Command Line Interface#
Overview#
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.
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.
Connect to the CLI#
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.
Access the CLI using SSH
$ /opt/idsvr/bin/idsh
admin connected from 127.0.0.1 using console on prod-curity1
admin@prod-curity1>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.
Modes in the CLI#
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 mode#
The view mode is identified by the > character in the prompt:
View mode
admin@prod-curity1>Configuration mode#
The configuration mode is identified by the % character in the prompt. To enter configuration mode simply type configure and hit enter.
Entering the Configuration mode
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.
Basic Usage#
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
List the commands in the configuration mode
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%Viewing the configuration#
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 all configuration
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.
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.
Remember, the TAB key can be used at any time to see the available completions for the command structure.
Show configuration for a sub-tree using the TAB auto-completion
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.
Changing the configuration#
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.
Setting a value
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.
Creating a new runtime node
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.
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.
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.
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.
Applying the configuration#
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.
Commit the changes
admin@prod-curity1% commit
Commit complete.
[ok][2017-05-18 13:38:44]
[edit]
admin@prod-curity1%When committing a few things happened.
- The changes are applied to the running configuration
- The transaction is closed
- A rollback file is created
- A new transaction is opened
Rollback changes#
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.
Viewing rollbacks
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 deltaThis lists the current history of commits. 0 is always the latest change made. So to undo the last commit two things are needed.
- Load the rollback into the transaction
- Commit the rollback
Loading rollbacks
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.
View rollback changes
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.
Commit the rollback
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.
View rollbacks again
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 deltaAs 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.
Advanced Usage#
Moving through the configuration using Edit#
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.
To edit a sub-tree of the configuration use the edit command to navigate.
Navigate to the admin service-role section
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
Show a sub-tree when in edit mode
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.
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.
Edit OAuth clients in the OAuth profile
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%Showing selected values only#
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.
Show only the client ids 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;
}
}
...Exporting configuration#
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.
Lets start with display. Any part of the configuration can be viewed in various formats.
Show configuration as XML
[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.
Save configuration as XML
[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 hard drive of the admin node.
To save it as CLI data instead, simply omit the display part.
Save configuration as CLI data
[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]Loading configuration#
To load saved configuration back to the active transaction we use the load command.
Load XML configuration
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.
Compare the loaded changes
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.
Multiline Edit Mode#
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.
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 below:
An example of multi-line mode
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.