restauth-service.py¶
restauth-service.py
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.
Usage¶
restauth-service.py [-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.py --help
If you want more information on a specific comannd, do:
restauth-service.py command --help
... or see the Available commands section below.
Examples¶
restauth-service.py add example.com - Add the service example.com and prompt for a password.
restauth-service.py add --gen-password example.com - Add the service example.com and print a generated password to stdout.
restauth-service.py ls - List all available services.
restauth-service.py view example.com - View all details of the service example.com.
restauth-service.py set-password --password=foobar example.com - Set the password of the service example.com (which must already exist) to foobar.
restauth-service.py 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.py set-permissions example.com user* - Specify that the service example.com is allowed to perform all user operations.
restauth-service.py rm-permissions example.com user_delete - Specify that the service example.com is not allowed to delete users.
restauth-service.py 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.py add example.net restauth-service.py set-hosts 127.0.0.1 ::1 restauth-service.py 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.