AUTHSELECT
Section: \ \& (8)
Updated: 2018-03-18
Page Index
NAME
authselect - select system identity and authentication sources.
SYNOPSIS
authselect [--debug] [--trace] [--warn] command [command options]
DESCRIPTION
Authselect is a tool to configure system identity and authentication sources and providers by selecting a specific profile. Profile is a set of files that describes how the resulting system configuration will look like. When a profile is selected, authselect will create nsswitch.conf(5) and PAM(8) stack to use identity and authentication sources defined by the profile.
If the provided profile set is not sufficient, the administrator may create a custom profile by putting it in a special profile directory (/etc/authselect/custom). By doing so, the profile is immediately usable by authselect. See authselect-profiles(5) for more information on extending existing profiles.
OPT-IN TO AUTHSELECT
Authselect will not touch your existing configuration unless it has already been created by it. If you want to start using authselect to configure your system authentication, please call authselect select with --force parameter first (e.g. authselect select sssd --force). The --force parameter tells authselect that it is all right to overwrite existing non-authselect configuration (see description below). Using the --force parameter will automatically generate a backup of your current configuration so if you wish to go back you can restore it with authselect backup-restore command (see description below).
AVAILABLE COMMANDS
To list all available commands run authselect without any parameters. To print help for the selected command run authselect COMMAND --help.
select profile_id [features] [-f, --force] [-q, --quiet] [-b] [--backup=NAME]
-
Activate desired profile. See profile description with
show
command, to list profile specific optional features.
--force, -f
-
Write changes even if the previous configuration was not created by authselect but by other tool or by manual changes. This option will automatically backup system files before writing any change unless
--nobackup
option is set.
-b
-
Backup system files before activating the selected profile. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
-
Backup system files before activating the selected profile. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name if no value is provided.
--nobackup
-
Do not backup system configuration even if
--force
is set.
--quiet, -q
-
The command will not print any informational message such as additional profile requirements or backup location. Errors are still being print.
apply-changes [-b] [--backup=NAME]
-
Re-apply currently selected profile. If the profile templates were updated this command can be used to regenerate current system configuration in order to apply these changes on the system. This command will only re-apply the changes if the existing configuration is a valid authselect configuration, otherwise an error is returned.
-b
-
Backup system files before applying changes. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
-
Backup system files before applying changes. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name if no value is provided.
list
-
List available profiles.
list-features profile_id
-
List all features available in given profile.
Note:
This will only list the features without any description. Please, read the profile documentation with
show
to see what the features do.
show profile_id
-
Print information about the profile.
requirements profile_id [features]
-
Print information about profile requirements.
current [-r, --raw]
-
Print information about currently selected profiles. If
--raw
option is specified, the command will print raw parameters as they were passed to
select
command instead of formatted output.
check
-
Check if the current configuration is valid (it was either created by
authselect
or there are no leftovers from previous authselect configuration).
test profile_id [options] [features]
-
Print content of files generated by
authselect
without actually writing anything to system configuration.
-a, --all
-
Print content of all files.
-n, --nsswitch
-
Print nsswitch.conf content.
-s, --system-auth
-
Print system-auth content.
-p, --password-auth
-
Print password-auth content.
-c, --smartcard-auth
-
Print smartcard-auth content.
-f, --fingerprint-auth
-
Print fingerprint-auth content.
-o, --postlogin
-
Print postlogin content.
-d, --dconf-db
-
Print dconf database content.
-l, --dconf-lock
-
Print dconf lock content.
enable-feature feature [-b] [--backup=NAME] [-q, --quiet]
-
Enable feature in the currently selected profile.
-b
-
Backup system files before enabling feature. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
-
Backup system files before enabling feature. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name if no value is provided.
--quiet, -q
-
The command will not print any informational message such as additional profile requirements or backup location. Errors are still being print.
disable-feature feature [-b] [--backup=NAME]
-
Disable feature in the currently selected profile.
-b
-
Backup system files before disabling feature. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name of the backup. This is a shortcut for
--backup=.
--backup=NAME
-
Backup system files before disabling feature. The backup will be stored at /var/lib/authselect/backups/NAME. Current time with unique string is used as a name if no value is provided.
create-profile NAME [--custom,-c|--vendor,-v] [options]
-
Create a new custom profile named
NAME. The profile can be based on an existing profile in which case the new profile templates are either copied from the base profile or symbolic links to these files are created if such option is selected.
--vendor,-v
-
The new profile is a vendor profile instead of a custom profile. See
authselect-profiles(5)
for more information on profile types.
--base-on=BASE-ID, -b=BASE-ID
-
The new profile will be based on a profile named
BASE-ID. The base profile location is determined with these steps:
-
1.
If
BASE-ID
starts with prefix
custom/
it is a custom profile.
-
2.
Try if
BASE-ID
is found in vendor profiles.
-
3.
Try if
BASE-ID
is found in default profiles.
-
4.
Return an error.
--base-on-default
-
The base profile is a default profile even if it is found also within vendor profiles.
--symlink-meta
-
Meta files, such as
README
and
REQUIREMENTS
will be symbolic links to the origin profile files instead of their copy.
--symlink-nsswitch
-
nsswitch.conf
template will be symbolic link to the origin profile file instead of its copy.
--symlink-pam
-
PAM
templates will be symbolic links to the origin profile files instead of their copy.
--symlink-dconf
-
dconf
templates will be symbolic links to the origin profile files instead of their copy.
--symlink=FILE,-s=FILE
-
Create a symbolic link for a template file
FILE
instead of creating its copy. This option can be passed multiple times.
BACKUP COMMANDS
These commands can be used to manage backed up configurations.
backup-list [-r, --raw]
-
Print available backups. If
--raw
option is specified, the command will print only backup names without any formatting and additional information.
backup-remove BACKUP
-
Permanently delete backup named
BACKUP.
backup-restore BACKUP
-
Restore configuration from backup named
BACKUP.
Note:
this will overwrite current configuration.
COMMON OPTIONS
These options are available with all commands.
--debug
-
Print debugging information and error messages.
--trace
-
Print information about what the tool is doing.
--warn
-
Print information about unexpected situations that do not affect the program execution but may indicate some undesired situations (e.g. unexpected file in a profile directory).
NSSWITCH.CONF MANAGEMENT
Authselect generates /etc/nsswitch.conf and does not allow any user changes to this file. Such changes are detected and authselect will refuse to write any system configuration unless a --force option is provided to the select command. This mechanism prevents authselect from overwriting anything that does not match any available profile.
Any user changes to nsswitch maps must be done in file /etc/authselect/user-nsswitch.conf. When authselect generates new nsswitch.conf it reads this file and combines it with configuration from selected profile. The profile configuration takes always precedence. In other words, profiles do not have to set all nsswitch maps but can set only those that are relevant to the profile. If a map is set within a profile, it always overwrites the same map from user-nsswitch.conf.
Example 1.
-
# "sssd" profile
$ cat /usr/share/authselect/default/sssd/nsswitch.conf
passwd: sss files systemd
group: sss files systemd
netgroup: sss files
automount: sss files
services: sss files
sudoers: files sss {include if "with-sudo"}
$ cat /etc/authselect/user-nsswitch.conf
passwd: files sss
group: files sss
hosts: files dns myhostname
sudoers: files
$ authselect select sssd
# passwd and group maps from user-nsswitch.conf are ignored
$ cat /etc/nsswitch.conf
passwd: sss files systemd
group: sss files systemd
netgroup: sss files
automount: sss files
services: sss files
hosts: files dns myhostname
sudoers: files
$ authselect select sssd with-sudo
# passwd, group and sudoers maps from user-nsswitch.conf are ignored
$ cat /etc/nsswitch.conf
passwd: sss files systemd
group: sss files systemd
netgroup: sss files
automount: sss files
services: sss files
sudoers: files sss
hosts: files dns myhostname
TROUBLESHOOTING
How can I tell if my system is using authselect?
Use authselect check. The output will tell you if you have 1) configuration generated by authselect 2) non-authselect configuration or 3) configuration that was generated by authselect but modified manually at some point.
Is nsswitch.conf supposed to be a symbolic link now?
Authselect generates your system configuration from scratch and stores it at /etc/authselect. System files are then created as symbolic links to this directory. Symbolic links are used to make it clear that authselect is now owning your configuration and should be used instead of any manual modification.
Error: Unexpected changes to the configuration were detected.
For example:
-
[error] [/etc/authselect/nsswitch.conf] does not exist!
[error] [/etc/nsswitch.conf] is not a symbolic link!
[error] [/etc/nsswitch.conf] was not created by authselect!
[error] Unexpected changes to the configuration were detected.
[error] Refusing to activate profile unless those changes are removed or overwrite is requested.
This means that your configuration is unknown to authselect and as such it will not be modified. To fix this, please call authselect select with --force parameter to say that it is all right to overwrite it.
RETURN CODES
The authselect can return these exit codes:
-
•
0: Success.
-
•
1: Generic error.
-
•
2: Profile or configuration was not found or the system was not configured with authselect.
-
•
3: Current configuration is not valid, it was edited without authselect.
-
•
4: System configuration must be overwritten to activate an authselect profile, --force parameter is needed.
-
•
5: Executed command must be run as root.
GENERATED FILES
Authselect creates and maintains the following files to configure system identity and authentication providers properly.
/etc/nsswitch.conf
-
Name Service Switch configuration file.
/etc/pam.d/system-auth
-
PAM stack that is included from nearly all individual service configuration files.
/etc/pam.d/password-auth, smartcard-auth, fingerprint-auth
-
These PAM stacks are for applications which handle authentication from different types of devices via simultaneously running individual conversations instead of one aggregate conversation.
/etc/pam.d/postlogin
-
The purpose of this PAM stack is to provide a common place for all PAM modules which should be called after the stack configured in system-auth or the other common PAM configuration files. It is included from all individual service configuration files that provide login service with shell or file access.
NOTE: the modules in the postlogin configuration file are executed regardless of the success or failure of the modules in the system-auth configuration file.
/etc/dconf/db/distro.d/20-authselect
-
Changes to dconf database. The main uses case of this file is to set changes for gnome login screen in order to enable or disable smartcard and fingerprint authentication.
/etc/dconf/db/distro.d/locks/20-authselect
-
This file define locks on values set in dconf database.
SEE ALSO
authselect-profiles(5), authselect-migration(7), nsswitch.conf(5), PAM(8)