Command Line Interface

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.

Listing 287 Access the CLI using SSH
$ /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.

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:

Listing 288 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.

Listing 289 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

Listing 290 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.

Listing 291 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.

Tip

Remember, the TAB key can be used at any time to see the available completions for the command structure.

Listing 292 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.

Listing 293 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.

Listing 294 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.

Listing 295 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.

Note

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.

Listing 296 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.

  1. The changes are applied to the running configuration
  2. The transaction is closed
  3. A rollback file is created
  4. 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.

Listing 297 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 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.

  1. Load the rollback into the transaction
  2. Commit the rollback
Listing 298 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.

Listing 299 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.

Listing 300 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.

Listing 301 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 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.

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.

Listing 302 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

Listing 303 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.

Listing 304 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.

Listing 305 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.

Listing 306 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.

Listing 307 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 harddrive of the admin node.

To save it as CLI data instead, simply omit the display part.

Listing 308 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.

Listing 309 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.

Listing 310 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.

Tip

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.

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 311:

Listing 311 An example of multi-line mode
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.

Scripting and automation

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.

Listing 312 A CLI script for changing configuration
 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.

Listing 313 CLI script for loading a default config and overriding with specifics
 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.