SUBAUTH(1)


Table of Contents

1. NAME
2. SYNOPSIS
3. DESCRIPTION
4. OPERATIONS
5. OPTIONS
6. SEE ALSO

1. NAME

subauth - A client to the sub-authentication service

2. SYNOPSIS

subauth options operation

3. DESCRIPTION

The sub-authentication service lets local users define sub-accounts with different authentication tokens for specific services.

The system administrator defines one or more authentication zones, each corresponding to a set of system services. You can use subauth --zones to list all existing zones.

Each zone can contain an account for each system user. Depending on the configuration of the zone, accounts can be manager manually by the administrator, or they can be created automatically when the user sets an authentication token for the zone.

Every account can be endowed with one of more authentication tokens of the following types. Depending on the configuration, all types need not be available in all zones.

  • Password: a user-specified string, usually easy to remember, but hard to guess. This is useful when authenticating manually. Please note that the password must not contain a "-" (minus) character, because it is used as a separator in other token types. There may be at most one password per account. You can use subauth --passwd to set a password and subauth --delete-passwd to remove it.
  • Regular token: such tokens are generated automatically. They consist of a public identifier (4 hexadecimal digits) and a random secret string. Multiple tokens can be defined for the same account, their public identifiers and optional comments can be listed by the user. This can be useful if you want to let multiple programs remember your credentials: each program can get a unique token and when it ceases to be trusted, the token can be simply removed. Use subauth --create-token to have a token generated and subauth --delete-token to have it removed.
  • Temporary token: this is a randomly generated cryptographically signed string, allowing access to the given user in the given zone for a limited time. Temporary tokens can be useful for services which are used so scarcely that it does not make sense to remember permanent credentials of any kind. Use subauth --temp-token to obtain a temporary token. You can set how long will the token be valid up to a limit configured by the administrator for the given zone.

The sub-accounts are managed by the subauthd(8) daemon. The subauth(1) command is a front-end to this daemon, through which accounts and tokens can be managed from the shell.

4. OPERATIONS

User commands

--zones
List all known authentication zones.
-l, --list
List all accounts of the current user (this can be the user running the command, or a different user given as --user if ran by the super-user).
--passwd
Set or replace a password for the given account. Requires --zone.
--delete-passwd
Delete password for the given account. Requires --zone.
--create-token
Create a new token for the given account. Requires --zone. Optionally, a --comment can be given.
--delete-token
Delete a given token. Requires --zone and --ident.
--change-token
Change parameters of an existing token. Currently, only the comment can be changed; setting to an empty string removes the comment. Requires --zone and --ident.
--temp-token
Create a temporary token. Requires --zone. Optionally, token validity can be set with --expire (otherwise, a default of 5 minutes will be used).
--login
Test if a given password or token (read from standard input) is valid in the given zone. Requires --zone. Optionally, you can specify a --user to test somebody else’s credentials.

Administrator commands

--create-acct
Create an account for the current user in the given zone. Requires --zone and --user.
--delete-acct
Delete an account for the current user in the given zone. Requires --zone and --user.
--delete-user
Deletes all accounts of the current user. Requires --user.

5. OPTIONS

-u, --user=login
Operate on the given user instead of the user running the command. Only the super-user can operate on somebody else.
-z, --zone=zone
Specify authentication zone. This is required by most operations.
-i, --ident=id
Specify token identifier. An asterisk can be used for "all tokens".
-c, --comment=text
When creating a token, remember this comment with the token. Comments make it easier to recognize the intentions behind different tokens.
-x, --expire=time
Set lifetime of a temporary token. The time is followed by a unit, which is either "h", "m", or "s". Maximum lifetime can be limited by zone configuration.
--socket=path
Communicate with the subauth daemon through the given socket instead of the default one.
--debug
For wizards: Dump raw communication with the daemon.

6. SEE ALSO

subauthd(8)