Smarter by Design.Simpler for Business
Pipe Commands
Pipe Commands are the commands that carry the output a command prints on the screen to the next command with the | sign in the WEB-CLI. The output is filtered, counted, sorted and formatted line by line, or is written to a temporary file with to-file. The pipe is used not only after the sys-cmd tools but also after the API commands such as lb service list and after the built-in commands such as help and history.
14 commands
grep · wc · sort · to-file…
Line filtering, counting, sorting, field cutting, JSON processing and writing to a file.
At most 8 pipes
On a single line
At most eight
| are used on a command line. Runs on the device
Independent of the context
Whatever the selected v-device and route table are, the filtering is done on the device itself.
to-file
Temporary file
The output of the chain is written to a downloadable file.
Short syntax:
<command> | <pipe-command> [parameters] [ | <pipe-command> [parameters] … ]Command Summary
# type | after the command and press Tab: the pipe commands
admin@TR7LBWAF01> sys-cmd ss -tan |
column cut grep head jq nl paste
sort tac tail to-file tr uniq wc
# the same list comes after the API commands too
admin@TR7LBWAF01> lb service list |
column cut grep head jq nl paste
sort tac tail to-file tr uniq wc
admin@TR7LBWAF01>
| Command | What it does | Writing |
|---|---|---|
grep | Passes the lines matching the pattern | Takes a single pattern; does not take parameters |
wc | Counts lines, words and characters | Free parameter |
sort | Sorts the lines | Free parameter |
head | Shows the first lines | Free parameter |
tail | Shows the last lines | Free parameter |
uniq | Reduces the consecutively repeated lines to one | Free parameter |
cut | Cuts a field or a character from the lines | Free parameter |
tr | Translates or deletes characters | Free parameter |
paste | Merges the lines side by side | Free parameter |
jq | Processes and filters the JSON output | Free parameter; a filter starting with . is rejected |
column | Lays the output out in aligned columns | Free parameter |
nl | Adds numbers to the lines | Free parameter |
tac | Reverses the line order | Free parameter |
to-file | Writes the output to a temporary file | The file name is mandatory; --append, --stdout; at the end of the chain |
In the pipe commands with a free parameter, what is written after the command name is carried to the tool as it is; Tab only shows the place of the next parameter in the form <wc-parameter-1>.
How It Works
| Subject | Behavior |
|---|---|
| After which commands | After every command that prints output: the sys-cmd tools, the API commands (lb service list, settings dns show…) and the built-in commands such as help and history. |
| Order | The chain works from left to right; the output of every command is the input of the next one. Only the output of the last command appears on the screen. |
| Where it works | The pipe commands always work on the device itself. Even though the sys-cmd tool on the left works from within the selected v-device and route table, the filtering and the writing to a file are done on the device. |
| Limit | At most 8 pipes are used on a line; more than that gives the error Maximum pipe exceeded: 9>8 (Pipe limiti aşıldı: 9>8 in the Turkish interface). |
| Early ending | When the command on the right closes, the commands on the left are stopped. For example, sys-cmd ping 10.20.0.15 | head -n 3 ends the ping as well after three lines. |
| Stopping | Ctrl+C stops the chain. |
| Error output | The error messages of the pipe commands are written in red. The own error output of the sys-cmd tool on the left is not carried to the pipe and does not come to the screen. |
| Interactive commands | The pipe cannot be used after telnet, frr-console and extend-data-disk: "Pipe" operator is not allowed after interactive commands. |
| Record | The lines starting with sys-cmd are written to the user logs together with their pipe parts as System command executed. |
Writing Rules and Limits
| Rule | Description | Example |
|---|---|---|
No | inside quotes | The line is split at the | signs before the quotes; a | inside quotes is also counted as a pipe. | — |
| Parameter with a space | It is taken inside single or double quotes. | tr -s ' ' · grep "GET /health" |
| File path ban | In the pipe commands other than grep and to-file, a parameter that contains / or .. or that starts with ~ or . is rejected: File path arguments are not allowed in pipe commands. The pipe commands are for processing the output coming from the left. | jq '(.status)' |
to-file at the very end | to-file must be the last command of the chain; otherwise it gives the error to-file must be the last pipe process. | … | grep 443 | to-file connections.txt |
| No shell operators | >, >>, ;, && cannot be used (Invalid command); to-file is used to write to a file. | | to-file output.txt --append |
grep
Passes only the lines matching the pattern from the output coming from the left. On live streams (tcpdump, ping) the lines are filtered as they arrive.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | Pattern | Required | The text or the regular expression to be searched; it is written directly, without the field name being written. If it contains a space, it is taken inside quotes. Tab shows its place as <grep-pattern> |
| Subject | Behavior |
|---|---|
| A single pattern | grep takes only one pattern, it does not accept parameters such as -i, -v and -c. The line grep -i estab gives the error Command not found: estab. |
A pattern starting with - | It is rejected: FIX: invalid grep pattern. If a pattern is not written, FIX: no grep pattern. |
| Upper / lower case | A distinction is made. To catch both writings, a character set is used: grep '[Ee]stab'. |
| Regular expression | The pattern is interpreted as a regular expression; . matches every character. grep 10.20 passes both the line that contains 10.20 and the line that contains 10120. |
| Color | The matching part is marked in color. The color codes also pass to the next pipe commands and to the file written with to-file. |
admin@TR7LBWAF01> sys-cmd ss -tan | grep ESTAB
admin@TR7LBWAF01> sys-cmd tcpdump -nn -i any port 53 | grep example.com
admin@TR7LBWAF01> lb service list | grep <vservice-name>
admin@TR7LBWAF01> help | grep file
admin@TR7LBWAF01>
to-file
Writes the output of the chain to the temporary file area of the device. The files are seen with sys-cmd file list, are downloaded from the Link column and are deleted with sys-cmd file delete.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | File name | Required | It contains only letters, digits, -, _ and .; it cannot contain .. or a directory, otherwise Invalid filename. It is written directly, without the field name being written. Tab shows its place as <file-name> |
| Field | What it does | What is written after it |
|---|---|---|
--append | If a file with the same name exists, it appends to its end instead of overwriting it | No value is written |
--stdout | While writing to the file, it also shows the output on the screen | No value is written |
| Subject | Behavior |
|---|---|
| Default | The output is written only to the file, nothing comes to the screen. If a file with the same name exists, it is overwritten. |
With tcpdump | On the sys-cmd tcpdump … | to-file <name>.pcap line, the packets are written in the pcap format that can be opened in Wireshark. In this case --stdout is not used; binary data is not read on the screen. Detail: tcpdump. |
| If the area fills up | The size and the fullness of the temporary area are seen with sys-cmd file disk show; space is freed with file delete or the area is enlarged with file disk change-size. |
# only to the file
admin@TR7LBWAF01> sys-cmd dig app.example.com A +short | to-file dig-app.txt
# both show on the screen and save
admin@TR7LBWAF01> sys-cmd ss -tan state established | to-file connections.txt --stdout
# append to the end on every run
admin@TR7LBWAF01> sys-cmd ss -tan state established | grep 10.20.0.30 | to-file backend-connections.txt --append
# save the output of the API command
admin@TR7LBWAF01> settings dns show | to-file dns-settings.txt
admin@TR7LBWAF01>
jq
Processes the output of a command that produces JSON: it selects fields, counts and formats.
| Subject | Behavior |
|---|---|
A filter starting with . | It is caught by the file path ban and is rejected: the line jq '.status' gives the error File path arguments are not allowed in pipe commands. The filter is written by being taken inside parentheses: jq '(.status)'. |
A filter containing / or .. | It cannot be written because of the same rule. |
| Parameters | -r writes the text without quotes, -c compresses every result into a single line. |
admin@TR7LBWAF01> sys-cmd curl -s http://10.20.0.30/api/status | jq '(.status)'
admin@TR7LBWAF01> sys-cmd curl -s http://10.20.0.30/api/status | jq -r '(.version)'
admin@TR7LBWAF01>
Filtering and Formatting Commands
| Command | Frequently used parameters | Example |
|---|---|---|
wc | -l line · -w word · -c byte count | … | wc -l |
sort | -n numeric · -r reverse · -k <n> according to the nth field · -t <separator> field separator · -u without repetition | … | sort -rn |
head | -n <number> the number of first lines | … | head -n 20 |
tail | -n <number> the number of last lines | … | tail -n 5 |
uniq | -c writes the repeat count at the beginning · -d only the ones that repeat · -u only the ones that occur once. It merges only the consecutive repetitions; for this reason sort is used first | … | sort | uniq -c |
cut | -d <separator> field separator · -f <n> field number · -c <range> character range | … | cut -d ':' -f 1 |
tr | -s <set> reduces the repeated character to one · -d <set> deletes · <set1> <set2> translates | … | tr -s ' ' |
paste | -s merges all the lines into a single line · -d <separator> merging separator · - - lays the lines out side by side two by two | … | paste - - |
column | -t aligns the fields separated by a space like a table · -s <separator> field separator | … | column -t |
nl | Without a parameter it adds numbers to the lines; -b a numbers the empty lines too | … | nl |
tac | It does not take a parameter; the last line comes to the beginning | … | tac |
The table summarizes the frequently used parameters; the full list and the behavior depend on the version of the tool on the device.
Example Chains
admin@TR7LBWAF01> sys-cmd ss -tn state established dst 10.20.0.30 | wc -l
admin@TR7LBWAF01>
admin@TR7LBWAF01> sys-cmd ss -tn state established | tr -s ' ' | cut -d ' ' -f 4 | cut -d ':' -f 1 | sort | uniq -c | sort -rn | head -n 10
admin@TR7LBWAF01>
admin@TR7LBWAF01> sys-cmd ping -c 50 10.20.0.15 | tail -n 2
admin@TR7LBWAF01>
# when 20 lines arrive, tcpdump is stopped as well
admin@TR7LBWAF01> sys-cmd tcpdump -nn -i any port 53 | head -n 20
admin@TR7LBWAF01>
admin@TR7LBWAF01> lb service list | grep <vservice-name>
admin@TR7LBWAF01> history | tail -n 10 | nl
admin@TR7LBWAF01>
admin@TR7LBWAF01> sys-cmd ss -tn state established | grep 10.20.0.30 | to-file backend-connections.txt --append
admin@TR7LBWAF01> sys-cmd file list
admin@TR7LBWAF01>
Things to Know
- The pipe commands are for processing the output coming from the left. Parameters containing a file path are rejected; the content of a file in the temporary file area is seen with
sys-cmd file content. - The heading also enters the line count. On the commands that give output in the table format,
wc -lcounts the heading lines too. - Colored output. The color codes of
grepand of the commands that produce colored output are also written to the file; when the file is opened in a text editor, these codes can appear. - Tool versions. The parameters of the pipe commands with a free parameter depend on the version of the tool on the device.
- For the system commands and the context, the System Commands page, and for the output formats of the API commands, the API Commands page can be looked at.
