s9s-user

Manage users.

Usage

s9s user {command} {options}

Command

Options

Creating the First User

To use the s9s command line tool a Cmon User Account is needed to authenticate on the Cmon Controller. These user accounts can be created using the s9s program itself by either authenticating with a pre-existing user account or bootstrapping the user management to create the very first user. The following section describes the authentication and the creation of the first user in detail.

If there is a username specified either in the command line using the --cmon-user (or -u) options or in the configuration file (either the ~/.s9s/s9s.conf or the /etc/s9s.conf file using the cmon_user variable name) the program will try to authenticate with this username. Creating the very first user account is of course not possible this way. The --cmon-user option and the cmon_user the variable is not for specifying what user we want to create, it is for setting what user we want to use for the connection.

If no user name is set for the authentication and user creation is requested the s9s will try to send a request to the controller through a named pipe. This is the only way a user account can be created without authenticating with an existing user account, this is the only way the very first user can be created. Here is an example:

$ s9s user --create \
       --group=admins \
       --generate-key \
       --controller=https://192.168.1.127:9501 \
       --new-password="MyS3cr3tpass" \
       --email-address="[email protected]" \
       admin

Please consider the following:

1. There is no --cmon-user specified, this is the first user we create, we do not have any pre-existing user account. This command line is for creating the very first user. Please check out the Examples section to see how to create additional users.
2. This is the first run, so we assume no ~/.s9s/s9s.conf configuration file exists, there is no user name there either.
3. In the example, we create the user with the username “admin”, and it is the command-line argument of the program.
4. The command specifies the controller to be at https://192.168.1.127:9501. The HTTPS protocol will be used later, but to create this first user the s9s will try to use SSH and sudo to access the controller’s named pipe on the specified host. For this, to work the UNIX user running this command has to have a passwordless SSH and sudo set up to the remote host. If the specified host is the local host the user does not need SSH access, but still needs to be root or have a passwordless sudo access because of course, the named pipe is not accessible for anyone.
5. Since the UNIX user has no s9s configuration file it will be created. The controller URL and the user name will be stored in it under ~/.s9s/s9s.conf. The next time this user runs the program, it will use this “admin” user unless another user name is set in the command line and will try to connect this controller unless another controller is set in the command line.
6. The password will be set for the user on the controller, but the password will never be stored in the configuration file.
7. The --generate-key the option is provided, so a new private/public key pair will be generated, then stored in the ~/s9s/ directory and the public key will be registered on the controller for the new user. The next time the program runs it will find the username in the configuration file, find the private key in place for the user, and will automatically authenticate without a password. The command-line options will always have precedence, so this automatic authentication is simply the default way, the password authentication is always available.
8. The group for the new user is set to “admins”, so this user will have special privileges. It is always a good idea to create the very first user with special privileges, then other users can be created by this administrator account.

User List

Using the --list and --long command-line options a detailed list of the users can be printed. Here is an example of such a list:

$ s9s user --list --long worf jadzia
A ID UNAME  GNAME EMAIL           REALNAME
- 11 jadzia ds9   [email protected]     Lt. Jadzia Dax
A 12 worf   ds9   [email protected] Lt. Worf
Total: 12

Please note that there are a total of 12 users defined on the system, but only two of those are printed because we filtered the list with the command line arguments.

The list contains the following fields:

User Formatting

When this command-line option is used the specified information will be printed instead of the default columns. The format string uses the % character to mark variable fields and flag characters as they are specified in the standard printf() C library functions. The ‘%’ specifiers are ended by field name letters to refer to various properties of the users.

The %+12I format string for example has the +12 flag characters in it with the standard meaning: the field will be 12 characters wide and the + or - the sign will always be printed with the number. The properties of the user are encoded by letters. For example, the letter N encodes the username field, so username of the user will be substituted. Standard \ the notation is also available, \n for example, encodes a new-line character. The %16N for example, the letter N encodes the username field, so username of the user will be substituted. Standard \ notation is also available, \n for example, encodes a new-line character.

The s9s-tools support the following fields:

Examples

Create a remote s9s user and generate an SSH key for the user:

$ s9s user --create \
        --generate-key \
        --cmon-user=dba \
        --controller="https://10.0.1.12:9501"

List out all users:

$ s9s user --list --long
A ID UNAME      GNAME  EMAIL REALNAME
-  1 system     admins -     System User
-  2 nobody     nobody -     -
A  3 dba        users  -     -
-  4 remote_dba users  -     -

List users that have at least one of the tags set.

$ s9s user \
        --list \
        --long \
        --with-tags="ds9;tng"

Register a new public key for the active user:

$ s9s user \
        --add-key \
        --public-key-file=/home/pipas/.ssh/id_rsa.pub \
        --public-key-name=The_SSH_key

Add user “myuser” into group “admins”:

$ s9s user \
        --add-to-group \
        --group=admins \
        myuser

Set a new password for user “pipas”:

$ s9s user \
        --change-password \
        --new-password="MyS3cr3tpass" \
        pipas

Create a new user called “john” under group “dba”:

$ s9s user \
        --create \
        --group=dba \
        --create-group \
        --generate-key \
        --new-password=s3cr3tP455 \
        [email protected] \
        --first-name=John \
        --last-name=Doe \
        --batch \
        john

Delete an existing user called “mydba”:

$ s9s user \
        --delete \
        mydba

Disable user nobody:

$ s9s user \
        --cmon-user=system \
        --password=secret \
        --disable \
        nobody

Enable user nobody:

$ s9s user \
        --cmon-user=system \
        --password=secret \
        --enable \
        nobody

Reset the password for a user called “dba”. One has to obtain the one-time token which will be sent to the registered email address of the corresponding user, followed by the actual password modification command with --token and --new-password parameters:

$ s9s user \
        --password-reset \
        dba
$ ## check the mail inbox of the respective user
$ s9s user \
        --password-reset \
        --token="98197ee4b5584cedba88ef1f583a1258" \
        --new-password="newp455w0rd"
        dba

Set a primary group for user “dba”:

$ s9s user \
        --set-group \
        --group=admins \
        dba

To add/set/delete the preferences for a given --cmon-user.

$ s9s user --cmon-user=s9s --password=***** --preferences --preferences-to-set="key1=value1;key2=value2;key3=value3"
$ s9s user --cmon-user=s9s --password=***** --preferences --preferences-to-set="key2=QWERTY"
$ s9s user --cmon-user=s9s --password=***** --preferences --preferences-to-delete="key1;key2"

To get the preferences for a given --cmon-user.

$ s9s user --cmon-user=s9s --password=***** --get-preferences