CLI Contexts
A central principle in the CLI is the context in which commands are executed. The context dictates which elements of the system can be managed and which commands are available. Contexts have a tree structure in which contexts may themselves contain nested contexts and the structure generally mirrors that of the views in the BUI.
The initial context upon login is the root context, and serves as the parent or ancestor of all contexts. To navigate to a context, execute the name of the context as a command. For example, the functionality available in the Configuration view in the browser is available in the configuration context of the CLI. From the root context, this can be accessed by typing it directly:
hostname:> configuration
hostname:configuration>Note that the prompt changes to reflect the context, with the context provided between the colon and the greater-than sign in the prompt.
The show command shows child contexts. For example, from the configuration context:
hostname:configuration> show
Children:
net => Configure networking
services => Configure services
version => Display system version
users => Configure administrative users
roles => Configure administrative roles
preferences => Configure user preferences
alerts => Configure alerts
storage => Configure StorageThese child contexts correspond to the views available under the Configuration view in the browser, including Network, Services, Users, Preferences, and so on. To select one of these child contexts, type its name:
hostname:configuration> preferences
hostname:configuration preferences>Navigate to a descendant context directly from an ancestor by specifying the intermediate contexts separated with spaces. For example, to navigate directly to configuration preferences from the root context, simply type it:
hostname:> configuration preferences
hostname:configuration preferences>Some child contexts are dynamic in that they correspond not to fixed views in the browser, but rather to dynamic entities that have been created by either the user or the system. There are two ways to navigate to these contexts: You can use the select command followed by the name of the dynamic context, or surround the name of the dynamic context with double quotes. The names of the dynamic contexts contained within a given context are shown using the list command. For example, the users context is a static context, but each user is its own dynamic context.
hostname:> configuration users hostname:configuration users> list NAME USERNAME UID TYPE Pat M Doe pmd 12345 Dir Super-User root 0 Loc
To select the user named pmd, issue the command select pmd or "pmd":
hostname:configuration users> "pmd"
hostname:configuration users pmdAlternately, double quotes, select and destroy can in some contexts be used to select an entity based on its properties. For example, one could select log entries issued by the reboot module in the maintenance logs system context by issuing the following command:
hostname:maintenance logs system> select module=reboot hostname:maintenance logs system entry-034> show Properties: timestamp = 2022-10-14 06:24:41 module = reboot priority = crit text = initiated by root on /dev/console syslogd: going down on signal 15
As with other commands, select or double quotes may be appended to a context-changing command. For example, to select the user named pmd from the root context:
hostname:> configuration users select pmd
hostname:configuration users pmd>Use the last command to navigate to a previously selected or
created context. The following example creates a replication action, and then uses the
last and get id commands to retrieve the
replication action ID. Then a different action is selected, and the
last and get id commands are used to retrieve
the ID of the last-visited replication action.
Using last, you can return to the last-visited node:
hostname:configuration net interfaces> "igb4" hostname:configuration net interfaces igb4> done hostname:configuration net interfaces> last hostname:configuration net interfaces igb4>
The last command is also useful to retrieve values that have been
automatically set by the appliance during the creation of a dynamic node. For example,
each replication action is assigned an ID by the appliance when it is created. Using the
last command with the get id command, you can
retrieve the ID without using the name of the replication action:
hostname:shares p1/share replication> create hostname:shares p1/share action (uncommitted)> set target=hostname target = hostname (uncommitted) hostname:shares p1/share action (uncommitted)> set pool=p0 pool = p0 (uncommitted) hostname:shares p1/share action (uncommitted)> commit hostname:shares p1/share replication> last get id id = 7034367a-d4d8-e26f-fa93-c3b454e3b595 hostname:shares p1/share replication>
Note that when last is combined with another command (in this case,
get id), the command is run in the context of the last-visited
node, but the current node remains unchanged.
Because last allows you to retrieve the last-visited node and its
values without specifying the name of the node, this command is particularly convenient
for scripting:
script
project = 'myproj';
target = 'mytarget';
target_pool = 'notmypool';
run('cd /');
run('shares select ' + project);
run('replication');
run('create');
set('target', target);
set('pool', target_pool);
run('commit');
run('last');
id = get('id');
printf("Sending update for replication action id %s ...", id);
run('sendupdate');
while (get('state') != 'idle') {
printf(".");
run('sleep 1');
}
printf("done\n");
.To return to the previous context, use the done command:
hostname:configuration> done
hostname:>This returns to the previous context, which is not necessarily the parent context, as follows:
hostname:> configuration users select pmd hostname:configuration users pmd> done hostname:>
The done command can be used multiple times to backtrack to earlier
contexts:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> done hostname:configuration users> done hostname:configuration> done hostname:>
To navigate to a parent context, use the cd command. Inspired by
the classic UNIX command, cd takes an argument of
".." to denote moving to the parent context:
hostname:> configuration users select pmd hostname:configuration users pmd> cd .. hostname:configuration users>
And as with the UNIX command, "cd /" moves to the root
context:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> cd / hostname:>
And as with its UNIX analogue, "cd ../.." may be used to navigate
to the grandparent context:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> cd ../.. hostname:configuration>
Note that the cd / and cd .. commands support
limited variations. For more versatility, use the top command and the
up command.
Use the top command to navigate to the root context:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> top hostname:>
Use the top command followed by a context name to directly navigate to the specified context relative to the root context. For example, to directly navigate from context configuration users to context configuration services, use the top configuration services command:
hostname:> configuration hostname:configuration> users hostname:configuration users> top configuration services hostname:configuration services>
When the top command is used in conjunction with a specific
context, the done command can be used to navigate back to the context
before the top command was executed. In the following example, the
first done command returns to the previous context. The second
done command returns to the context before the
top command. The third done command returns to
the context two nodes before the top command.
hostname:> maintenance system hostname:maintenance system> updates hostname:maintenance system updates> top configuration services hostname:configuration services> ftp hostname:configuration services ftp> done hostname:configuration services> done hostname:maintenance system updates> done hostname:>
Like the cd .. command, the up command can be
used to navigate to the parent context:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> up hostname:configuration users>
Additionally, you can go to a context n nodes up from the current
context by repeating the up command n
times:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> up up hostname:configuration>
To go back to a specific context relative to the current parent context, enter the context name after the up command. Likewise, use the up up command followed by a context name to go back to a specific context relative to the current grandparent context. For example, to go from context configuration users pmd to context configuration services, use the command up up services:
hostname:> configuration hostname:configuration> users hostname:configuration users> select pmd hostname:configuration users pmd> up up services hostname:configuration services>
When the up command is used in conjunction with a specific context,
the done command can be used to navigate back to the context before
the up command was executed. In the following example, the first
done command returns to the context before the
up command. The second done command returns to
the context two nodes before the up command, and the third
done command returns to the context three nodes before the
up command.
hostname:> configuration hostname:configuration> services hostname:configuration services> ftp hostname:configuration services ftp> up http hostname:configuration services http> done hostname:configuration services ftp> done hostname:configuration services> done hostname:configuration> done hostname:>
Context names will tab complete, be they static contexts (via normal command completion) or dynamic contexts (via command completion of the select command). Following is an example of selecting the user named pmd from the root context with just fifteen keystrokes, instead of the thirty-one that would be required without tab completion:
hostname:> configtab hostname:> configuration utab hostname:> configuration users setab hostname:> configuration users select tab pmd root hostname:> configuration users select ptab hostname:> configuration users select pmdenter hostname:configuration users pmd>
Once in a context, execute context-specific commands. For example, to get the current user's preferences, execute the get command from the configuration preferences context:
hostname:configuration preferences> get
locale = C
login_screen = status/dashboard
session_timeout = 15
session_annotation =
advanced_analytics = falseIf there is input following a command that changes context, that command will be
executed in the target context, but control will return to the calling context. For
example, to get preferences from the root context without changing context, append the
get command to the context navigation commands:
hostname:> configuration preferences get
locale = C
login_screen = status/dashboard
session_timeout = 15
session_annotation =
advanced_analytics = falseWhen creating a new entity in the system, the context associated with the new entity will often be created in an uncommitted state. For example, create a threshold alert by executing the create command from the configuration alerts threshold context:
hostname:> configuration alerts thresholds create
hostname:configuration alerts threshold (uncommitted)>The (uncommitted) in the prompt denotes that this an uncommitted context. An uncommitted entity is committed via the commit command; any attempt to navigate away from the uncommitted context will prompt for confirmation:
hostname:configuration alerts threshold (uncommitted)> cd /
Leaving will abort creation of "threshold". Are you sure? (Y/N)When committing an uncommitted entity, the properties associated with the new entity will be validated, and an error will be generated if the entity cannot be created. For example, the creation of a new threshold alert requires the specification of a statistic name; failure to set this name results in an error:
hostname:configuration alerts threshold (uncommitted)> commit
error: missing value for property "statname"To resolve the problem, address the error and reattempt the commit:
hostname:configuration alerts threshold (uncommitted)> set statname=cpu.utilization statname = cpu.utilization (uncommitted) hostname:configuration alerts threshold (uncommitted)> commit error: missing value for property "limit" hostname:configuration alerts threshold (uncommitted)> set limit=90 limit = 90 (uncommitted) hostname:configuration alerts threshold (uncommitted)> commit hostname:configuration alerts thresholds> list THRESHOLD LIMIT TYPE STATNAME threshold-000 90 normal cpu.utilization
Related Topics