cw-switchctl

NAME

cw-switchctl -- Query and modify switches for the cluster.

Note

This command is similar to cw-nodectl but only applies to switches. A switch is a node with type=switch:<NOS>

USAGE

cw-switchctl

[-h] [-v] [-q] [[-c | --config] CONFIG] [--base-url URL] [[-u | --user] USER[:PASSWD]] [--human | --json | --csv | --table] [--pretty | --no-pretty] [--show-uids] [-a | -i SWITCHES] | --up | --down | --booting] {apply, clear, clone,cp, create,mk, diff, delete,rm, download, exec, get, hardware, join, leave, list,ls, ping, reboot, replace,re, revert, scp, script, set, shutdown, ssh, status, update,up, upload, waitfor}

OPTIONAL ARGUMENTS

-h, --help

Print usage message and exit. Ignore trailing args, parse and ignore preceding args.

-v, --verbose

Increase verbosity.

-q, --quiet

Decrease verbosity.

-c, --config CONFIG

Specify a client configuration file CONFIG.

--show-uids

Do not try to make the output more human readable. Must be used with the list action.

-i, --ids SWITCHES

A comma-separated list of switches or an admin-defined group of switches to act upon.

-a, --all

Interact with all switches (default for list).

--up

Interact with all "up" switches.

--down

Interact with all "down" switches.

--booting

Interact with all "booting" switches.

--selector TEXT, -s TEXT

Switch selection string.

ARGUMENTS TO OVERRIDE BASIC CONFIGURATION DETAILS

--base-url URL

Specify the base URL of the ClusterWare REST API.

-u, --user USER[:PASSWD]

Masquerade as user USER with optional colon-separated password PASSWD.

FORMATTING ARGUMENTS

--human

Format the output for readability (default).

--json

Format the output as JSON.

--csv

Format the output as CSV.

--table

Format the output as a table.

--pretty

Indent JSON or XML output, and substitute human readable output for other formats.

--no-pretty

Opposite of --pretty.

--fields FIELDS

Select individual fields in the result or error.

ACTIONS

apply

Apply the target configuration file or the optionally provided configuration file to the switch.

clear [-a | --all | NAME ... ]

Delete attribute name(s) and their value(s).

-a, --all

Delete all attributes.

clone (cp) [--content JSON | INI_FILE] [NAME=VALUE ...]

Copy switch with new NAME/VALUE identifier pairs.

--content JSON | INI_FILE

Overwrite fields in the cloned switch.

create (mk) [--content JSON | INI_FILE ] [NAME=VALUE ...]

Add a switch, commonly by specifying its MAC address (e.g., mac=MACaddr, that assigns the next available number and associated IP address), and type=<NOS> or type=switch:<NOS>. The type argument is required when creating a switch and possible values for <NOS> include "sonic", "cumulus", and "arista".

--content JSON | INI_FILE

Load this content into the database as a switch.

delete (rm)

Delete switch(es).

diff [--baseline (target | current)]

Compare switch configuration files.

--baseline target | current

Provide a baseline, either target or current configuration, to compare.

download (--all | --target | --current) filename

Download switch config file to specified filename. When multiple switches are selected, {} is required in the filename to output to multiple files based on the switch name.

--all

Download all configuration information.

--target

Download only the target configuration.

--reported

Download only the reported configuration.

exec [--grouped] [--in-order] [--label] [--stdin IN] [--binary] [--stdout OUT] [--stderr ERR] CMD

Execute the CMD (double-quotes are optional) on switch(es). The cw-switchctl exec command passes its current stdin, stdout, and stderr to the remote command, or uses the --stdin, --stdout, and/or --stderr arguments to override the default(s) with a file.

When run via an ssh command (e.g. ssh cwhead cw-switchctl --up exec uptime), that stdin should be provided and closed with Ctrl-d, or ssh should be passed the -t argument to force tty allocation. Otherwise the command detects stdin is a pipe and wait for end-of-file.

Commands executed on multiple switches execute in parallel. The degree of fan-out can be controlled through the ssh_runner.fanout configuration variable in base.ini. Because these commands execute in parallel, their output may be interleaved or not in switch index order. Override this with grouped or --in-order arguments.

For sshpass functionality, see _remote_pass in the Reserved Attributes section of the ClusterWare documentation.

--grouped

Results are locally buffered and printed grouped by switch.

--in-order

Output is printed in switch index order, implies --grouped.

--label

Force output labeling, even if a single switch is selected.

--stdin IN

Provide @file or input string as stdin for the CMD.

--binary

Treat CMD output as binary data.

--stdout OUT

Provide a filename OUT for the CMD stdout output. Any {} in the filename gets translated to the switch name (see EXAMPLES).

--stderr ERR

Provide a filename ERR for the CMD stderr output. Any {} in the filename gets translated to the switch name (see EXAMPLES). An ERR value consisting of the string STDOUT will merge stderr into stdout.

get

Get attribute values.

hardware

Show the "hardware" information subset of cw-switchctl ls -L.

join GROUP ...

Append GROUP(S) to the switch group lists.

leave [-a | --all | GROUP ...]

Remove GROUP(S) from the switch group lists.

-a, --all

Remove switch(es) from all groups (other than the global default).

list (ls) [--long | --long-long]

Show information about switches.

-l, --long

Show a subset of all optional information for each switch.

-L, --long-long

Show all optional information for each switch.

ping [COUNT]

ping the specified switch(es) with COUNT packets (default 1).

reboot [--force]

Soft reboot switch(es) using SSH to run the shutdown command. Ignore the reboot if the switch's _no_boot is set to true (or t, 1, yes, y) or if _busy is set to true (or t, 1, yes, y), unless an overriding --force argument is supplied.

--force

Override the switch's _no_reboot attribute value when set to 1.

revert

Revert the switch configuration file between the current and target file in the database.

set

Set attribute values.

scp

Copy files to or from switch(es). See cw-switchctl exec in EXAMPLES, below.

script SCRIPT

Execute the specified ClusterWare SCRIPT (distributed in the clusterware-node package) on the specified switch(es). The script name list (or ls) displays names of the available scripts, which generally execute automatically at boot time to facilitate various switch initializations and have limited usefulness for later execution by a cluster administrator. However, the scripts fetch_hosts (re-download the list of head nodes) and update_keys (update SSH keys) may be useful in rare circumstances for a booted switch.

set [--content JSON | INI_FILE ] [ NAME=VALUE ] ...

Set attribute value(s).

--content JSON | INI_FILE

Import the NAME/VALUE pairs from the file into the switch attributes.

shutdown [--force]

Soft shutdown switch(es) using ssh to run the shutdown command.

--force

Perform the shutdown action regardless of _no_boot.

ssh [--pubkey FILE]

Create an SSH connection to the specified switch as the user root. This is done using a local SSH key that is temporarily copied to the switch through the head node and removed after the command completes. The user can provide their own public key, or one will be generated and stored in ~/.scyldcw/tempauth.key.

--pubkey FILE

Specify a file containing a public key to use for this connection.

status [--long] [--long-long] [--health | --aim | --no-aim] [--refresh] [--counts]

Show switch status.

--health

Show status based on _health attribute.

--aim

Show status based on _aim_status attribute.

--no-aim

Opposite of --aim.

-l, --long

Show a subset of all optional information for each switch.

-L, --long-long

Show all optional information for each switch.

--refresh

Show basic switch states, refreshing for any state change.

--counts

Include switch counts.

update (up) [--content JSON | INI_FILE ] [ NAME=VALUE ] ...

Modify switch NAME field(s) with new value(s).

--content JSON | INI_FILE

Overwrite this content into the database for a switch.

upload (--target | --current) JSON_FILE

Upload switch configuration file as either the target or current configuration.

waitfor [Options] COND

Complete when one or more of the specified switches meet the condition COND, which is either an expression or a '@'-prefixed file name. If no switches are specified, then defaults to --all.

--failure COND

Also complete if the failure condition becomes true.

--timeout SECS

Complete after SECS seconds if condition(s) never become true.

--name NAME

Use the currently defined COND state known as NAME, or define a new COND and remember it as NAME.

--load

Save the state maps into the database.

--activate [SECS]

Activate a state map for SECS seconds (default=120)

--deactivate

Deactivate a state map.

--delete NAME

Delete an existing state map NAME.

--show [NAME]

Show a list of all state maps, or optionally just the details of one.

--stream

Stream back ongoing results instead of returning the first result and exiting.

--skip

Do not use or print the initial switch states.

--one-per

Stream switch state changes with one switch per line.

EXAMPLES

cw-switchctl list

List all switch names.

cw-switchctl status

Shows the basic state of each switch.

cw-switchctl -in5 status

Shows the basic state of switch n5.

cw-switchctl -i n5 ls -L

Shows full information available for switch n5.

cw-switchctl -i %groupx ls -l

Shows an expanded information available for each switch joined to the admin-defined group groupx.

cw-switchctl create mac=00:25:90:0C:D9:3C type=switch:sonic

Add a new switch to the end of the current list of switches.

cw-switchctl create mac=00:25:90:0C:D9:3C type=switch:sonic index=10

Add a new switch beyond the end of the current list of switches as switch n10.

cw-switchctl -i n3 update mac=40:25:88:0C:B9:2C

Replace the current MAC address for switch n3 with a new MAC address.

cw-switchctl -in2 ssh

Use ssh to open a shell on switch n2.

cw-switchctl -i n2 exec ls /var/log

Execute ls /var/log on switch n2, directing stdout and stderr to cw-switchctl's stdout and stderr, respectively.

cw-switchctl -i n2 exec --stdout /tmp/n2.var.log ls /var/log

Execute ls /var/log on switch n2, directing stdout to the head node file /tmp/n2.var.log.

cw-switchctl -i n[2-4] exec --stderr STDOUT --stdout /tmp/{}.var.log ls /var/log

Execute ls /var/log on switches n2, n3, and n4, directing both stderr and stdout to the head node files /tmp/n2.var.log, /tmp/n3.var.log, and /tmp/n4.var.log, respectively.

cw-switchctl --up exec --stderr STDOUT --stdout /tmp/{}.var.log ls /var/log

Perform the same action as above, although this time for all the "up" switches.

cw-switchctl -in5 exec --stdout /tmp/n5-log.tar.gz tar -czf- /var/log

Execute tar -czf- /var/log on switch n5, directing the stdout of the packed result into the head node file /tmp/n5-log.tar.gz.

cw-switchctl -in5 exec --stdin=@/tmp/n5-log.tar.gz tar -C /root -xzf-

Send the local file /tmp/n5-log.tar.gz as the stdin to switch n5 as it executes tar -C /root -xzf- to unpack the stdin contents at /root.

cw-switchctl -in3 scp check-health.sh r:/opt/scyld/clusterware-node/bin/check-health.sh

Copy the local check-health.sh file to switch n3 as file /opt/scyld/clusterware-node/bin/check-health.sh.

cw-switchctl -in3 scp check-health.sh r:/opt/scyld/clusterware-node/bin/

Copy the local check-health.sh file to switch n3 directory /opt/scyld/clusterware-node/bin/. The trailing / in the remote path is mandatory to differentiate copying a file vs. copying a directory.

cw-switchctl -in3 scp r:/opt/scyld/clusterware-node/bin/check-health.sh /tmp/

Copy the remote n3 check-health.sh file to the head node's /tmp/ directory.

cw-switchctl -in3 scp /opt/scyld/clusterware-tools/examples/ r:/tmp/

Copy the directory /opt/scyld/clusterware-tools/examples to switch n3 directory /tmp/. The trailing / in the remote path is mandatory to differentiate copying a file vs. copying a directory.

cw-switchctl -i n4 reboot then waitfor 's[state] == "up"'

Reboot switch n4, then wait until the switch returns to the "up" state.

cw-switchctl -i n4 reboot then waitfor up

Reboot switch n4, then wait until the switch returns to the "up" state. Another supported shorthand is the conditional "down".

cw-switchctl -i n0 waitfor @/opt/scyld/clusterware-tools/examples/node-states.ini

For switch n0 establish a waitfor state condition described in the specified examples file, in which the state condition is named status. If no -i <NODE(s) is specified, then defaults to --all.

cw-switchctl waitfor --name status

For all switches re-establish a waitfor state condition for the previously defined state named status. When the condition is true for any switch, write the state to stdout and exit.

cw-switchctl waitfor --name status --stream

For all switches re-establish a waitfor state condition for the previously defined state named status. When the condition is true for any switch, write the state change to stdout and continue executing.

cw-switchctl -i n0 reboot then waitfor up then exec uname -r

Initiate a reboot of switch n0, wait for the switch to return to an "up" state, and then execute uname -r on the switch.

cw-switchctl -i n0 ssh

Start a ssh session on switch n0 as user root (by default) or whatever user is specified in the switch's _remote_user attribute.

RETURN VALUES

Upon successful completion, cw-switchctl returns 0. On failure, an error message is printed to stderr and cw-switchctl returns 1.