AUTHSELECT(8)

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 [--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)