Skip to main content

Special Conventions in Command-Line Client Usage

This section describes some of the special conventions in command-line client usage, such as features involving special syntax.

Filtering by Modified Date​

When filtering hosts, user keys, and authorizations by modified date (date_modified field), you can specify filter values as time ranges.

note

When filtering by the date_modified field, the syntax and supported functionality differs from regular timestamp filtering. For more information about filtering by other timestamp fields, see Filtering by Timestamp Fields.

Defining the Time Range​

To define a time range, you must provide timestamps for signifying the beginning and/or the end of the time range. The function of the timestamps is defined using the operators <, >, <=, >=, =. The list-authorizations command also supports the time-range operator ..

Timestamps must be in the ISO 8601 format (YYYY-MM-DDTHH:MM:SS). The year (YYYY-) must be specified in all timestamps. Other parts of the timestamp are optional, and may be omitted. Omitted parts of the timestamp assume default values as follows:

  • For timestamps that define the beginning of the time range (>, >=), omitted parts default to the earliest possible value.

  • For timestamps that define the end of the time range (<, <=), omitted parts default to the latest possible value.

  • For timestamps that define the entire time range (=), omitted parts default to match all possible values.

  • Timestamps are assumed to be in the time zone configured for the command-line client user. If the time-zone setting for the command-line client is unavailable and timezone is left unspecified, then timestamps are assumed to be in UTC time.

You may specify a custom time-zone offset to overwrite this behavior. To do this, append the time-zone offset to the timestamp, in the +/-HH:MM format. If you specify a custom time-zone offset, then time (THH:MM:SS) must be specified in the timestamp as well.

The following examples illustrate the resulting time ranges when parts of timestamps are omitted:

date_modified=2014-09-15..2014-09-20
15.9.2014 00:00:00.00000 - 20.9.2014 23:59:59.99999

 date_modified=2014-09..2014-10
1.9.2014 00:00:00.00000 - 31.10.2014 23:59:59.99999

 date_modified=..2014-09-15
Earlier than or at 15.9.2014 23:59:59.99999

 date_modified=2014-09-15..
Later than or at 15.9.2014 00:00:00.00000

 date_modified=2014-09-15
15.9.2014 00:00:00.00000 - 15.9.2014 23:59:59.99999

 date_modified=2014-09
1.9.2014 00:00:00.00000 - 30.9.2014 23:59:59.99999

 date_modified>=2014-09-15&&date_modified<= 2014-09-20
15.9.2014 00:00:00.00000 - 20.9.2014 23:59:59.99999

 date_modified<2014-09-15
Earlier than 15.9.2014 23:59:59.99999

 date_modified>2014-09-15
Later than 15.9.2014 00:00:00.00000

 date_modified<=2014-09-15
Earlier than or at 15.9.2014 23:59:59.99999

 date_modified>=2014-09-15
Later than or at 15.9.2014 00:00:00.00000

When is a Host or Key Considered Modified?​

A key is considered modified if it has an audit event from the specified time range. Audit events are generated when the key is modified via Key Manager, or when Key Manager detects manual changes to the key.

A host is considered modified if any of the following host values has changed during the specified time range:

  • OS release (os_release)

  • Management state (state)

  • Host status (status)

  • Host name (hostname)

  • SELinux status

  • Tags and back-end tags (backend_tags, tags)

Examples​

For example, to list authorizations that were modified later than 2014-10-10T12:00:00 (in the time zone of the command-line client user):

$ ssh-mgr-client list-authorizations -F 'date_modified>2014-10-10T12:00:00'

Listing authorizations that are modified later than 2014-10-10T12:00:00+03:00 (EST):

$ ssh-mgr-client list-authorizations -F 'date_modified>2014-10-10T12:00:00+03:00'

Listing authorizations that were modified in October 2014:

$ ssh-mgr-client list-authorizations -F 'date_modified=2014-10'

Listing authorizations that were modified during the time from the beginning of September to the end of November 2014 (UTC):

$ ssh-mgr-client list-authorizations -F 'date_modified=2014-09T00:00:00+00:00..2014-11T23:59:59+00:00'

Listing authorizations that were modified between or at 1st of August 12:00 and 2nd of August 18:00 (CET):

$ ssh-mgr-client list-authorizations -F 'date_modified=2014-08-01T12:00+0100..2014-08-02T18:00+01:00'

Filtering by Relative Time Ranges​

In the command-line client it is possible to use relative time ranges in filters for columns that are defined as relative time. The exact filter columns that support this are as follows:

For filtering authorizations:

  • ak_key_age
  • pk_key_age

For filtering authorized keys:

  • key_age
  • last_used

For filtering private keys:

  • key_age

For filtering hosts:

  • time_since_last_key_activity_scan
  • time_since_last_scan

For filtering key activity:

  • time_since_last_login

When defining the relative time range, you must provide a timestamp consisting of a number appended with one of the time modifiers: y (years), m (months), w (weeks), d (days), H (hours), M (minutes), and S (seconds). Also, define the function of the timestamp using one of the operators: <, >, <=, >=.

The relative units can be used with any command-line client filter in place of an absolute date. The relative date format has an integer followed by the unit. You can use more than one units in the same specifier, for example key_age<1d1H. Negative integers are also allowed, for example key_age<1d-1H (equal to 23 hours). The units are relative to the time on the Key Manager Database.

For example, to list the hosts that have not been scanned in two days:

$ ssh-mgr-client list-hosts -F "time_since_last_scan>=2d"

To list the authorized keys that are more than 6 months old and less than 2 years old:

$ ssh-mgr-client list-authorized-keys -F "key_age>6m&&key_age<2y"

To create an authorization between the accounts in the managed environment that is valid after one hour and expires after two hours from issuing the command:

$ ssh-mgr-client add-authorizations -d from=root@example.com,to=root@example2.com,validity=1H..2H

You can also use calendar-based relative times, and relative times that are calculated from present time. Such relative times work with all date-type filter fields.

The following values can be used for specifying calendar-based (UTC) relative times:

  • today
  • this_week
  • this_month

Relative times calculated from present time can be specified using any of the following values:

  • last_hour: refers to the last hour
  • last_day: refers to the past 24 hours
  • last_week: refers to the last seven days
  • last_month: refers to the last 30 days

You can list jobs created during this week by running the following command:

$ ssh-mgr-client list-jobs -F date_created=this_week

You can list hosts deployed during last 30 days by running the following command:

$ ssh-mgr-client list-hosts -F date_deployed=last_month

Filtering by Timestamp Fields​

This section describes some points that are good to keep in mind when filtering by timestamp fields (other than date_modified).

note

When filtering by the date_modified field, the syntax and supported functionality differs from regular timestamp filtering. For more information about filtering by date_modified, see Filtering by Modified Date.

Timestamps are specified in ISO 8601 format. For example:

2014-10-15T11:56:00Z

You can match entries by providing the full timestamp. For example:

$ ssh-mgr-client list-authorized-keys -F "date_created=2014-10-15T11:56:00Z"

Alternatively, you can filter by just a part of the timestamp. For example, listing all authorized keys created on a certain date (note that wildcards are not needed):

$ ssh-mgr-client list-authorized-keys -F "date_created=2014-10-15"

Specifying the Key Algorithm​

The key_alg option is used to specify the key algorithm when generating new keys. The supported algorithms, and the ways in which they can be specified, are as follows:

  • RSA: rsa, ssh-rsa

  • DSA: dsa, dss, ssh-dss, ssh-dsa

  • ECDSA: ecdsa, ssh-ecdsa

  • ed25519: ed25519, ssh-ed25519

Each algorithm can be specified using any of its accepted aliases. For example, both of the following commands shall equivalently use RSA for generating new keys:

$ ssh-mgr-client renew-private-keys -i 12 -d key_alg=rsa
$ ssh-mgr-client renew-private-keys -i 12 -d key_alg=ssh-rsa
note

SSH products typically support a subset of the listed key algorithms. When specifying a key algorithm, make sure that it is also supported by the SSH product to which the target key(s) belong to.