One of the most powerful configuration interfaces in the Curity Identity Server is the Command Line Interface (CLI). This is accessible directly from the Admin node using the bin/idsh command.
bin/idsh
The CLI mimics a Juniper CLI, which is a model driven style of CLI’s, which makes it very easy to navigate and work with. Administrators who are familiar with the XML structure of the Curity configuration model, will recognize the hierarchy in the CLI easily.
The CLI also works with standard Emacs commands as normal bash terminals do, such as Ctrl+A or Ctrl-E to reach beginning or end of line, as well as a command history using the up-arrow or Ctrl+R to do reverse search.
bash
Ctrl+A
Ctrl-E
up-arrow
Ctrl+R
On the admin node the CLI can be accessed directly via the bin/idsh command. The user needs to have privileged access to the machine running Curity, to be able to access the command. This is suitable for setup tasks, and for automation tasks.
$ /opt/idsvr/bin/idsh admin connected from 127.0.0.1 using console on prod-curity1 admin@prod-curity1>
Note
The bin/idsh command is a root shell (CLI) accessible on the admin machine. Users with execute access on the admin node can run the command.
There is no difference between the CLI over SSH or via the command, except that the bin/idsh command is root access. Treat it the same way as configuration files on the node would be treated.
The CLI operates in two modes. The view mode and the configuration mode. When in view mode it’s possible to show configuration, and running status of the cluster. In the configuration mode a transaction is created where the admin can change configuration and then commit it to move the system to a new running state.
view
configuration
The view mode is identified by the > character in the prompt:
>
admin@prod-curity1>
The configuration mode is identified by the % character in the prompt. To enter configuration mode simply type configure and hit enter.
%
configure
admin@prod-curity1>configure Entering configuration mode private [ok][2017-05-18 12:02:15] [edit] admin@prod-curity1%
Configuration mode private means that a private transaction now has started, where the admin can safely work with the configuration without interfering with other administrators using REST, the WebUI or another session in the CLI. Any change made in the CLI will not take effect until the commit command is used. More on that later.
commit
The CLI is built using a command hierarchy. Each command either has a sub command or accepts arguments directly. You’ve already used the configure command which is available in the view mode.
To see the available commands in any state in the CLI simply hit TAB
TAB
admin@prod-curity1% Possible completions: annotate - Add a comment to a statement commit - Commit current set of changes compare - Show configuration differences copy - Copy a list entry delete - Delete a data element describe - Display transparent command information edit - Edit a sub-element exit - Exit from this level help - Provide help information insert - Insert a parameter load - Load configuration from an ASCII file move - Move a parameter quit - Exit from this level rename - Rename an identifier request - Make system-level requests resolved - Conflicts have been resolved revert - Copy configuration from running rollback - Roll back database to last committed version run - Run an operational-mode command save - Save configuration to an ASCII file set - Set a parameter show - Show a parameter status - Display users currently editing the configuration tag - Manipulate statement tags top - Exit to top level and optionally run command up - Exit one level of configuration validate - Validate current configuration admin@prod-curity1%
To view the configuration in the transaction we are currently working in, we use the show command followed by the sub-tree of the configuration that we’d like to view. If the sub-tree is omitted the show command simply shows all configuration from the current location and onward.
show
admin@prod-curity1% show aaa { authentication { users { user admin { uid 9000; gid 20; password $1$YXZ; ssh_keydir /var/confd/homes/admin/.ssh; homedir /var/confd/homes/admin; } user jacob { uid 7126; gid 20; password $1$ABC; ssh_keydir /var/confd/homes/jacob/.ssh; homedir /var/confd/homes/jacob/.ssh; } } ...
The pager more is used to be able to page through the results. Hit q to quit the more pager and go back to the CLI.
more
q
It is usually necessary to be more specific in what to show. By passing configuration elements as arguments to the show command you can display a subtree of the configuration.
Tip
Remember, the TAB key can be used at any time to see the available completions for the command structure.
admin@prod-curity1% show environments environment Possible completions: admin-service - The administration service configuration base-url - The external base URL used to contact this machine localization - The localization settings for this environment name - The name of the organization running the services in an environment (Entity ID) services - Settings of physical daemon instances static-resource-root-path - The root path under the base-url from which static resources should be served white-listed-proxies - A list of proxies that are allowed to be in the middle of the requestor and this server. admin@prod-curity1% show environments environment services service-role Possible completions: admin - A given name of the service Possible match completions: disabled - Enable or disable the entire daemon instance enabled - Enable or disable the entire daemon instance endpoints - A list of endpoints deployed on this service instance, no order implied jvm-options - Options to be passed to the JVM on start up listening-host - IP used for listening host listening-port - The port the service listens on location - Where the service is located, physically protocol - Which protocol to use, almost always, https should be used thread-count - zone - The zone that the service is in (which, if not set, will be the default zone) admin@prod-curity1% show environments environment services service-role admin location Curity.io; protocol https; ssl-server-keystore server-key-1; endpoints [ authn-authenticate authn-info authn-register oauth-assisted-token oauth-authorize oauth-introspection oauth-meta oauth-revoke oauth-token ]; [ok][2017-05-18 13:04:25] [edit] admin@prod-curity1%
As you can see, in the second step, the tab completion shows both other nodes that can be accessed such as endpoints but also the available entries in the service list namely admin. When showing admin we can se the values that are set for that node currently. Default values are omitted.
endpoints
service
admin
To change the configuration the set command is used. It sets a new value or modifies an existing value. But the change is not applied to the system until the configuration is committed.
set
admin@prod-curity1% set environments environment base-url https://demo.curity.io [ok][2017-05-18 13:16:59] [edit]
Often we do more complex operations, such as creating a new runtime node in the configuration. This involves creating a new list entry in the service-role section, and populating it with the values we like. This can be done in a single line, or by setting each value separately. If mandatory values are omitted, the CLI will prompt the user to enter values for those before completing the operation.
service-role
admin@prod-curity1% set environments environment services service-role runtime2 protocol https \ ssl-server-keystore server-key-1 location "My Lab" \ endpoints [ oauth-authorize authn-authenticate authn-register authn-info ] [ok][2017-05-18 13:20:26] [edit] admin@prod-curity1%
Tab completion helps showing relevant values. For ssl-server-keystore this element only accepts values from the crypto section, so if it doesn’t tab complete, that means there are not values to choose from. Then one must add a server key before this configuration can be committed.
ssl-server-keystore
crypto
The endpoints element is a multivalue element. To set all at once simply use the [ to start list input and end with ].
[
]
Now we have prepared some new configuration. To know what will happen when committing we can view the current changes.
admin@prod-curity1% compare running brief environments { environment { - base-url https://login.curity.io; + base-url https://demo.curity.io; services { + service-role runtime2 { + location "My Lab"; + protocol https; + ssl-server-keystore server-key-1; + endpoints [ authn-authenticate authn-info authn-register oauth-authorize ]; + } } } } [ok][2017-05-18 13:23:31] [edit] admin@prod-curity1%
compare running shows a diff between the current running configuration and the prepared configuration in the transaction. By adding the brief command it only shows the relevant elements which usually is handy.
compare running
running
brief
All current changes are now displayed, but the base-url and the service change that is prepared. The transaction will treat these as a single update when the configuration is committed.
To apply the configuration the commit command is used. This will apply all the pending changes in the transaction and update the current running configuration to the new state.
admin@prod-curity1% commit Commit complete. [ok][2017-05-18 13:38:44] [edit] admin@prod-curity1%
When committing a few things happened.
Sometimes the applied configuration needs to be undone. Perhaps it was deployed prematurely or it contained incorrect value. Using the rollback history it is very easy to move back and forward in the configuration history.
To show the current history use the rollback command followed by a TAB.
rollback
admin@prod-curity1% rollback Possible completions: 0 - 2017-05-18 13:51:21 by admin via cli 1 - 2017-05-18 13:38:44 by admin via cli selective - Apply a single rollback delta
This lists the current history of commits. 0 is always the latest change made. So to undo the last commit two things are needed.
admin@prod-curity1% rollback 0 [ok][2017-05-18 13:55:39]
Now the changes in the rollback are available in the current transaction. This can easily be reviewed by using the compare command again.
compare
admin@prod-curity1% compare running brief environments { environment { - base-url https://demo.curity.io; + base-url https://old-url.io; services { - service-role runtime2 { - location "My Lab"; - protocol https; - ssl-server-keystore server-key-1; - endpoints [ authn-authenticate authn-info authn-register oauth-authorize ]; - } } } }
Either commit the changes as they are, or modify them before committing.
admin@prod-curity1% commit Commit complete. [ok][2017-05-18 13:58:21]
Now, a new rollback file is created, since we changed the configuration again. This means that we can also rollback the rollback. Use the rollback command followed by a TAB.
admin@prod-curity1% rollback Possible completions: 0 - 2017-05-18 13:58:21 by admin via cli 1 - 2017-05-18 13:51:21 by admin via cli 2 - 2017-05-18 13:38:44 by admin via cli selective - Apply a single rollback delta
As you can see there is a new timestamp for rollback 0. This is the new latest change.
To rollback further into the history simply rollback to a greater number. rollback 2 will apply rollbacks 0,1,2 in the correct order and move the system back to the state it was before the commit that caused rollback 2.
rollback 2
When working with the configuration it is often a bit clumsy to work from the root of the configuration. The edit command works similarly to cd in a regular shell.
edit
cd
To edit a sub-tree of the configuration use the edit command to navigate.
admin@prod-curity1% edit environments environment services service-role admin [ok][2017-05-18 14:07:01] [edit environments environment services service-role admin] admin@prod-curity1%
Notice how the text above the last prompt changed. It now indicates that the current element is the admin list entry in the service-role list.
Type show and see what happens
admin@prod-curity1% show location Curity.io; protocol http; endpoints [ authn-authenticate authn-info authn-register oauth-assisted-token oauth-authorize oauth-introspection oauth-meta oauth-revoke oauth-token um-admin ]; [ok][2017-05-18 14:08:19] [edit environments environment services service-role admin] admin@prod-curity1%
Now you didn’t have to give a sub-tree command to the show command, but instead the node’s config is available directly. All commands now operate in this part of the configuration.
To go back, use up to move up one level or top to go all the way up to the root.
up
top
The edit command is especially handy when working with the profile configuration, since those are nested deeper it makes sense to navigate to the profile configuration section before making changes.
admin@prod-curity1% edit profiles profile oauth oauth-service settings \ authorization-server client-store config-backed [ok][2017-05-18 14:10:56] [edit profiles profile oauth oauth-service settings authorization-server client-store config-backed] admin@prod-curity1%
It is possible to display only parts of the configuration. Since we just navigated to the OAuth clients section in one of our OAuth profiles we might want to show the available clients and their capabilities.
[edit profiles profile oauth oauth-service settings authorization-server client-store config-backed] admin@prod-curity1% show client | select capabilities client api-client { capabilities { introspection; } } client curity-customer-web { capabilities { code; } } ...
Many users want to store the configuration in a source control system (SCM), or use it as XML init files when deploying Curity in new environments. The CLI can be used to produce such files.
It is also possible to store the configuration as CLI data, which is recommended if the configuration is not to be used as factory init configuration, but instead being loaded in runtime.
It is possible to dump the entire configuration on the root level in the CLI. But more interesting is perhaps to dump a subsection to a file.
If we continue with the edit mode that we had, and say that we’d like to dump the clients to XML. We can use the save command together with the display command.
save
display
Lets start with display. Any part of the configuration can be viewed in various formats.
[edit profiles profile oauth oauth-service settings authorization-server client-store config-backed] admin@prod-curity1% show | display xml <config xmlns="http://tail-f.com/ns/config/1.0"> <profiles xmlns="https://curity.se/ns/conf/base"> <profile> <id>oauth</id> <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type> <settings> <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth"> <client-store> <config-backed> <client> <id>api-client</id> ...
It gives a complete XML tree for this subsection, which means it starts from the XML root but only selects this sub-section.
To save this, we simply pipe the command further to the save command.
[edit profiles profile oauth oauth-service settings authorization-server client-store config-backed] admin@prod-curity1% show | display xml | save /tmp/clients.xml [ok][2017-05-18 14:43:48]
Now the output of the command is saved in /tmp/clients.xml on the harddrive of the admin node.
/tmp/clients.xml
To save it as CLI data instead, simply omit the display part.
[edit profiles profile oauth oauth-service settings authorization-server client-store config-backed] admin@prod-curity1% show | save /tmp/clients.cli [ok][2017-05-18 14:44:50]
To load saved configuration back to the active transaction we use the load command.
load
admin@prod-curity1% load merge /tmp/clients.xml [ok][2017-05-18 14:53:08]
To make it more interesting, we changed a line in the clients.xml file before loading. Which now is visible in the transaction.
admin@prod-curity1% compare running brief profiles { profile oauth-dev oauth-service { settings { authorization-server { client-store { config-backed { client assisted-token-example { - scope [ read write ]; + scope [ delete read write ]; } } } } } } }
Even though we loaded a large chuck of data, Curity detected that one item was the only change. To apply simply do commit and the new configuration is active. This creates a rollback file as normal so it’s possible to revert.
Try changing something in the saved file before loading it back. Run compare running brief after loading and notice that Curity finds the minimal diff between the loaded configuration and the current running configuration.
compare running brief
The CLI accepts commands one line at a time. For some input, for example, a long procedure or PEM-encoded certificate, this isn’t ideal. In such cases, it is easier to enter the configuration using multi-line mode. When in configuration mode, you can enter this mode by typing Esc-m whenever input is expected. Once entered, it is possible to type any number of lines of input. When finished, you can exit multi-line mode by hitting Ctrl-d.
Warning
There must be a carriage return at the end of the last line of input. Hitting Ctrl-d on the same line as input has been entered will not cause the CLI to exit multi-line mode.
An example of this can be seen in Listing 317:
1 2 3 4 5 6 7 8
admin@localhost% set processing procedures token-procedure my-good-script oauth-authorize-implicit script (<string>): [Entering multiline mode, exit with ctrl-D.] > function result(context) { > // ... > } > [ok][2020-12-08 13:44:33]
In this example, multi-line mode was entered by striking Esc-m on line 3. It was exited by hitting Ctrl-d on line 8.
Using the bin/idsh command it’s possible to script against the CLI. This is very useful when working with automatic deployment tools, that can use the command to update the configuration of a running system.
1 2 3 4 5 6 7 8 9 10 11 12
#!/bin/sh PORT=9876 SERVER=TestServer1 /opt/idsvr/bin/idsh << EOF configure set environments environment services service-role $SERVER listening-port $PORT commit exit no-confirm exit EOF
A more common use-case is to apply a base configuration first with common configuration for all environments. Then apply changes needed for the specific environment.
The benefit of doing this in a CLI script is that all changes will take place in the same transaction. I.e. the system will never be in an inconsistent or insecure state.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
#!/bin/sh LABEL=some-label COMMENT="Set node config with specific port" PORT=9876 SERVICE=TestServer1 /opt/idsvr/bin/idsh << EOF configure load replace conf.xml set environments environment services service-role $SERVICE listening-port $PORT commit label $LABEL comment "$COMMENT" exit no-confirm exit EOF
As the highlighted line shows, the command loads conf.xml first, which can be a dump of the configuration from another environment (idsvr -d or in the cli save conf.xml xml). After the initial configuration is loaded, the script updates the listening-port of the node TestServer1. Then it applies the configuration with a label and a comment so it can be referenced later.
conf.xml
idsvr -d
save conf.xml xml
listening-port
TestServer1