restauth-service

restauth-service may be used to manage services that connect to RestAuth. A service is a system that wants to use RestAuth to store users, preferences and groups.

RestAuth stores a name (which may not include a ‘:’) and a password that identify the service. A service has zero or more IPv4 or IPv6 addresses associated with it, a service can only authenticate from the given adresses, use the *-hosts subcommands to manage hosts of a given service. A service must have permissions to perform the respective actions, use the *-permissions subcommands to manage permissions for services.

Name of restauth-service

If you installed from source or with pip, the script is installed as restauth-service.py. If you installed RestAuth via your distributions package management system, the script is usually called restauth-service.

Usage

restauth-service [-h] {add,ls,rm,rename,view,set-hosts,add-hosts,rm-hosts,set-password,add-permissions,rm-permissions,set-permissions} ...

Use one of the commands (i.e. add, view, ls, ...) to perform the respective operation. Each command usually requires more arguments to it, see the respective section for arguments (and possible options) for each command.

Getting runtime help

To get an authoritative list of available commands, use:

restauth-service --help

If you want more information on a specific comannd, do:

restauth-service command --help

... or see the Available commands section below.

Examples

restauth-service add example.com
Add the service example.com and prompt for a password.
restauth-service add --gen-password example.com
Add the service example.com and print a generated password to stdout.
restauth-service ls
List all available services.
restauth-service view example.com
View all details of the service example.com.
restauth-service set-password --password=foobar example.com
Set the password of the service example.com (which must already exist) to foobar.
restauth-service set-hosts example.com 192.168.0.1 192.168.0.2
Enable the service example.com for the hosts 192.168.0.1 192.168.0.2. Note that this removes any previously configured hosts.
restauth-service set-permissions example.com user*
Specify that the service example.com is allowed to perform all user operations.
restauth-service rm-permissions example.com user_delete
Specify that the service example.com is not allowed to delete users.
restauth-service remove example.com
Remove the service example.com from RestAuth. This will also remove any groups defined for the service, see restauth-groups(1).

A typical workflow for adding a service is:

restauth-service add example.net
restauth-service set-hosts 127.0.0.1 ::1
restauth-service set-permissions user_verify_password user_change_password

Please see the available permissions below for a full reference on what permissions can be configured.

Available commands

The following subsections never document the ‘-h’ parameter for clarity.

add

add [-h] [--password PWD | --gen-password] SERVICE

Add a new service.

--password PWD

The password to use.

--gen-password

Generate a password and print it to stdout.

SERVICE

The name of the service.

add-hosts

add-hosts [-h] SERVICE HOST [HOST ...]

Add hosts that a service can connect from.

SERVICE

The name of the service.

HOST [HOST ...]

Add hosts that this service is able to connect from. Note: This must be an IPv4 or IPv6 address, NOT a hostname.

add-permissions

add-permissions [-h] SERVICE PERM [PERM ...]

Add permissions to a service. This command supports shell wildcard style expansions, so ‘user*’ will add all user permissions.

SERVICE

The name of the service.

PERM [PERM ...]

Permissions to add to the specified service.

ls

ls [-h]
List all available services.

rename

rename [-h] SERVICE NAME

Rename a service.

SERVICE

The name of the service.

NAME

The new name for the service.

rm

rm [-h] SERVICE

Completely remove a service. This will also remove any groups associated with that service.

SERVICE

The name of the service.

rm-hosts

rm-hosts [-h] SERVICE HOST [HOST ...]

Remove hosts that a service can connect from.

SERVICE

The name of the service.

HOST [HOST ...]

Remove hosts that this service is able to connect from. Note: This must be an IPv4 or IPv6 address, NOT a hostname.

rm-permissions

rm-permissions [-h] SERVICE PERM [PERM ...]

Remove permissions from a service. This command supports shellwildcard style expansions, so “user*” will remove all user permissions.

SERVICE

The name of the service.

PERM [PERM ...]

Permissions to remove from the specified service.

set-hosts

set-hosts [-h] SERVICE [HOST [HOST ...]]

Set hosts that a service can connect from.

SERVICE

The name of the service.

[HOST [HOST ...]]

Hosts that this service is able to connect from. Note: This must be an IPv4 or IPv6 address, NOT a hostname.

set-password

set-password [-h] [--password PWD | --gen-password] SERVICE

Set the password for a service.

--password PWD

The password to use.

--gen-password

Generate a password and print it to stdout.

SERVICE

The name of the service.

set-permissions

set-permissions [-h] SERVICE [PERM [PERM ...]]

Set permissions of a service, removes any previous permissions. This command supports shell wildcard style expansions, so “user*” will set all user permissions.

SERVICE

The name of the service.

[PERM [PERM ...]]

Set the permissions of the specified service.

view

view [-h] SERVICE

View details of a service.

SERVICE

The name of the service.

Available permissions

A service can have zero or more permissions. There is a permission available for each operation available via the RestAuth protocol. If a service has no permissions, you will not be able to perform any operations.

Handling users

permission description
users_list List all users
user_create Create a new user
user_exists Check if a user exists
user_delete Delete a user
user_verify_password Verify a users password
user_change_password Change a users password
user_delete_password Delete a user

Handling properties

permission description
props_list List all properties of a user
prop_create Create a new property
prop_get Get value of a property
prop_set Set or create a property
prop_delete Delete a property

Handling groups

permission description
groups_for_user List groups for a user
groups_list List all groups
group_create Create a new group
group_exists Verify that a group exists
group_delete Delete a group
group_users List users in a group
group_add_user Add a user to a group
group_user_in_group Verify that a user is in a group
group_remove_user Remove a user from a group
group_groups_list List subgroups of a group
group_add_group Add a subgroup to a group
group_remove_group Remove a subgroup from a group

Influential environment variables

DJANGO_SETTINGS_MODULE

The path to the Django settings module. If not set, RestAuth.settings is used, which should be fine in most cases. For more information, please read the Django documentation.

PYTHONPATH

A semi-colon (‘;’) seperated list of additional directories to search for python modules. The RestAuth installation must be in the module search path for any commands to work. For more information, please read the official python documentation.