User Service Properties

User Properties

Users can have the following properties. Some properties are available only for users of a particular type.

Table 16-2 User Properties

Property	Type	Description
`logname`	string	Unique username. The `logname` is immutable after the user is created.
`type`	string	Type of user: `local`, `directory`, `data`, `nologin`. The `type` is immutable after the user is created. Default: `local`.
`uid`	number	User ID. You can specify the user ID or allow the system to assign the user ID. If you specify the user ID, the user ID cannot be less than 100, cannot be greater than 2147483646, and cannot be equal to 60001, 60002, or 65534. The `uid` is immutable after the user is created.
`fullname`	string	Full name or real name for the user. In the BUI, the full name is shown to the left of the Logout button at the top of the dashboard, and might also be shown on the browser tab. Default: same as `logname`.
`initial_password`	string	Password for local and data users.
`require_annotation`	boolean	When true: BUI – Require the user to enter a comment prior to displaying the initial BUI page. CLI – Require the user to enter a comment prior to displaying the CLI prompt. REST – Requests fail as unauthorized. The session annotation appears in the audit log.
`roles`	list	The roles assigned to a directory or local user.
`kiosk_mode`	boolean	When true, this user is a kiosk user: BUI – The user is restricted to viewing only the screen that is the value of the `kiosk_screen` property. CLI – Login fails. REST – Requests fail as unauthorized.
`kiosk_screen`	string	The BUI screen that this user is restricted to if `kiosk_mode` is true. Default: `status/dashboard`.
`exceptions`	list	Additional authorizations assigned to a directory or local user, or limitations on authorizations that are assigned in a role.
`preferences`	list	User environment preferences such as locale, BUI start page, timeouts, SSH public keys, and REST login tokens.

For further descriptions of these properties, see the following documentation:

Understanding Users and Roles in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x
Managing User Properties in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x

User Roles and Exceptions

Use the roles property to assign existing roles to a user. To create a role, see RESTful API Role Service.

Use the exceptions property to add authorizations for a user. You can also use this mechanism to remove authorizations. For example, if the user is assigned a role that grants certain authorizations, you can set individual authorizations to false in the exceptions list, while keeping other authorizations that are included in the role.

The following request adds the authorization to restart the Kerberos service for user user1.

POST /api/user/v1/users/user1/exceptions HTTP/1.1

{
    "scope": "svc",
    "service": "kerberos",
    "allow_restart": true
}

The following result shows all authorizations that are available for the Kerberos service for user1. In this example, other authorizations still have their default value of false.

{
    "auth": {
        "href": "/api/user/v1/users/user1/exceptions/auth-001",
        "scope": "svc",
        "service": "kerberos",
        "allow_administer": false,
        "allow_configure": false,
        "allow_restart": true
    }
}

User Preferences Properties

You can set preferences for the user that you are logged in as or for any user for which you have the allow_changePreferences authorization. To gain the allow_changePreferences authorization, see User Roles and Exceptions.

Table 16-3 User Preferences Properties

Property	Type	Description
`locale`	string	Locality; default: C
`login_screen`	string	The BUI page that is presented upon successful login if a page is not specified in the URL. Default: `status/dashboard`.
`cli_idle_timeout`	integer	The length of time in seconds that the CLI can be idle before the session is killed. The default value, `-1`, means the CLI will not automatically close when idle.
`advanced_analytics`	string	Make available advanced analytics statistics
`keys`	list	RSA/DSA public keys
`tokens`	list	REST login tokens

See the following sections for more information about these properties:

CLI Timeout

By default, there is no limit on the length of time that the command-line interface (CLI) can be idle (the value of cli_idle_timeout is -1). To set a limit on the length of time that the CLI can be idle, set a positive integer value for cli_idle_timeout seconds. If the timeout limit is reached, the CLI is closed.

The following example sets the CLI timeout to 1 hour.

PUT /api/user/v1/users/user1/preferences HTTP/1.1

{ "cli_idle_timeout": 3600 }

{
    "preferences": {
        "href": "/api/user/v1/users/user1/preferences",
        "locale": "C",
        "login_screen": "configuration/preferences",
        "session_timeout": 15,
        "cli_idle_timeout": 3600,
        "advanced_analytics": false,
        "keys": [],
        "tokens": []
    }
}

To disable the timeout, set the value of cli_idle_timeout to -1 or use unset, as shown in the following example.

PUT /api/user/v1/users/user1/preferences HTTP/1.1

{ "<unset>": ["cli_idle_timeout"] }

Enclosing unset in angle brackets avoids the problem of having a property named unset.

SSH Keys

SSH public keys can be used to allow SSH connections without the use of passwords.

Table 16-4 SSH Key Properties

Property	Type	Description
`type`	string	The type of SSH key: either RSA or DSA
`key`	string	The contents of the SSH key
`comment`	string	A comment associated with this SSH key

REST Login Tokens

You can create a persistent or non-persistent REST login token, and access the token via its returned token value or token ID.

Table 16-5 REST Login Token Properties

Property	Type	Description
`name`	string	The token name
`token_username`	string	The name of the user that can use this login token; this value is set in the request path
`preserve`	boolean	If `false`, use the default `expiration` value. If `true`, set a custom `expiration` value. Default: `false`.
`expiration`	number	When creating a token, this value is seconds until the token expires. This property is required to be set if `preserve` is set to `true`. If `preserve` is set to `false`, the value of `expiration` is 900. When listing token properties, this value is the date and time that this token will expire.

REST Login Token Query Parameter

Use the token=token query parameter with the GET command to show the property values for that token. Use the token=token query parameter with the DELETE command to remove that token. The token is the value of X-Auth-Session in the create token response.

The token is displayed when the token is created and is not shown again. Be sure to copy and keep the token. See example "Creating a REST Login Token" in section Manage Tokens.