AUTHSELECT(8)

📦
version 1.7.1 · 2 versions
, in centos-stream 10, fedora 43, fedora 44

💖 AUTHSELECT 💖 — the authselect(8) page, bestie edition 🎀

okay so you opened the manual for authselect and it's giving a lot of words, so let me just walk you through it like we're texting. no cap, this tool is lowkey the main character of your system's login setup. ✨

🌸 NAME 🌸

authselect — pick your system identity and authentication sources, bestie. that's the whole vibe. 💅

✨ SYNOPSIS ✨

authselect [--debug] [--trace] [--warn] command [command options]

like, that's it. command goes brrr, options are optional, we move. 🦋

🫶 DESCRIPTION 🫶

so authselect is the tool that configures your system's identity and authentication sources and providers by selecting a specific profile. and a profile is literally just a set of files that describes how the resulting system configuration is gonna look. that's it. that's the profile. 📁

when you select a profile, authselect will create the nsswitch.conf(5) and PAM(8) stack for you, using the identity and authentication sources that the profile defines. slay. 👑

and here's the thing — if the provided profile set is not enough for you (iconic of you to want more tbh), the administrator can create a custom profile by putting it in a special profile directory: /etc/authselect/custom. and the moment you do that, boom, the profile is immediately usable by authselect. no restart, no nothing. obsessed. 🌈

want the deep lore on extending existing profiles? go read authselect-profiles(5). iykyk. 📚

💜 OPT-IN TO AUTHSELECT 💜

listen, authselect will not touch your existing configuration unless it was already created by it. it's respectful like that. 🧚

so if you wanna start using authselect to configure your system authentication, please call authselect select with the --force parameter first, like:

authselect select sssd --force

the --force parameter is basically you telling authselect "yeah bestie, it's all right to overwrite existing non-authselect configuration" (see the description below for the details 👇).

and the best part? using --force will automatically generate a backup of your current configuration, so if you ever wanna go back you can just restore it with the authselect backup-restore command (also described below 👇). it's giving safety net. 🕸️💖

🙈 OPT-OUT FROM AUTHSELECT 🙈

want authselect to stop managing your configuration? totally valid, boundaries are healthy. just run:

authselect opt-out

this will remove all authselect configuration from your system, and then you can go modify your configuration manually like it's 2010. do your thing. 💅

👑 AVAILABLE COMMANDS 👑

to list all available commands, just run authselect without any parameters. and to print help for a specific command, run authselect COMMAND --help. easy. ✨

🔥 select profile_id [features] [-f, --force] [-q, --quiet] [-b] [--backup=NAME]

Activate the profile you desire, bestie. 🎀 see the profile description with the show command to list all the profile-specific optional features, because there might be more than you think.

  • --force, -f — Write changes even if the previous configuration was not created by authselect but by some other tool or by manual changes. this option will automatically backup system files before writing any change, unless the --nobackup option is set. (so like, it's a "yes overwrite it but also save me" situation 🫶)
  • -b — Backup system files before activating the selected profile. the backup will be stored at /var/lib/authselect/backups/NAME. the current time with a unique string is used as the 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. living dangerously, respect. 💀
  • --quiet, -q — the command will not print any informational message, such as additional profile requirements or backup location. errors are still being print though, so don't think you can hide from them. 😭

🔥 apply-changes [-b] [--backup=NAME]

Re-apply the currently selected profile. if the profile templates were updated, this command can be used to regenerate the current system configuration so those changes actually apply on the system. 🦋

heads up: this command will only re-apply the changes if the existing configuration is a valid authselect configuration, otherwise an error is returned. no shortcuts. 🙅♀️
  • -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. that's it, that's the command. short and sweet. 🍓

🔥 list-features profile_id

List all features available in the given profile. 💅

Note: this will only list the features without any description. please read the profile documentation with show to see what the features actually do. don't guess, bestie. 🧚

🔥 show profile_id

Print information about the profile. the lore drop. 📖

🔥 requirements profile_id [features]

Print information about profile requirements. ✅

🔥 current [-r, --raw]

Print information about currently selected profiles. if the --raw option is specified, the command will print raw parameters as they were passed to the select command instead of formatted output. raw, unfiltered, no makeup. 💅

🔥 check

Check if the current configuration is valid — meaning it was either created by authselect, or there are no leftovers from previous authselect configuration. vibe check, but for your config. 🌈

🔥 test profile_id [options] [features]

Print the content of files generated by authselect without actually writing anything to system configuration. it's a preview. a sneak peek. a trailer. 👀

  • -a, --all — Print content of all files. all of them. every single one. ✨
  • -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 a feature in the currently selected profile. glow up. ✨

  • -b — Backup system files before enabling the 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 the 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 a feature in the currently selected profile. we love a good declutter. 🧹

  • -b — Backup system files before disabling the 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 the 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. 📦

🔥 is-feature-enabled feature

Check if a feature is currently enabled in the selected profile. yes or no, no in-between. 🎯

🔥 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 an option is selected. pick your fighter. 🥊

  • --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 the 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. default wins, periodt. 💅
  • --symlink-meta — Meta files, such as README and REQUIREMENTS, will be symbolic links to the origin profile files instead of their copy. 🔗
  • --symlink-nsswitch — the nsswitch.conf template will be a 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. your little time capsules. ⏳

backup-list [-r, --raw]

Print available backups. if the --raw option is specified, the command will print only backup names without any formatting and additional information. no frills. 💅

backup-remove BACKUP

Permanently delete the backup named BACKUP. permanently. forever. no undo, bestie. 💀

backup-restore BACKUP

Restore configuration from the backup named BACKUP.

Note: this will overwrite current configuration. like, gone. be sure. 😭

🌟 OTHER COMMANDS 🌟

opt-out

Remove authselect configuration. this will restore the nsswitch and PAM configuration under its system location, and authselect will no longer manage it. run authselect select to opt-in again whenever you're ready to come back. it's giving "we were on a break". 🦋

🎀 COMMON OPTIONS 🎀

these options are available with all commands. universal besties. 🫶

  • --debug — Print debugging information and error messages. when things are weird, this is the flashlight. 🔦
  • --trace — Print information about what the tool is doing. like a little narrator for your commands. 🎙️
  • --warn — Print information about unexpected situations that do not affect the program execution but may indicate some undesired situations (e.g. an unexpected file in a profile directory). not fatal, just sus. 👀

(part 1 done, more coming bestie — don't go anywhere 💖)

🔧 TROUBLESHOOTING 🔧

Okay bestie, something's giving "my config is broken" energy and you need answers. Let's go question by question, iykyk. 💅

💭 How can I tell if my system is using authselect?

Run authselect check, periodt. The output will tell you if you have 1) a configuration generated by authselect, 2) a non-authselect configuration, or 3) a configuration that was generated by authselect but got modified manually at some point. Three moods, three outcomes, no guessing. ✨

Yes bestie, and it's iconic. Authselect generates your system configuration from scratch and stores it at /etc/authselect. Your actual system files are then created as symbolic links pointing into that directory. Why symlinks? So it's crystal clear that authselect owns your configuration now and should be used instead of any manual modification. She's the main character of your config, fr fr. 👑

😭 Error: Unexpected changes to the configuration were detected.

So when you see something like this:

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

…that means your configuration is unknown to authselect, and because of that, authselect will not touch it. It's not being rude, it's being careful. 🫶

To fix it, call authselect select with the --force parameter — that's you saying "yeah it's all right to overwrite it." Consent matters, even with config files. 💖

🚦 RETURN CODES 🚦

The authselect can return these exit codes, and each one is basically a vibe check on what just happened:

  • 0 — Success. Slay. ✨
  • 1 — Generic error. The "something went wrong but idk what" of exit codes. 💀
  • 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. (Not me editing files by hand… 🙈)
  • 4 — System configuration must be overwritten to activate an authselect profile; the --force parameter is needed.
  • 5 — The executed command must be run as root. 👑
  • 6 — No configuration was detected.

🗂️ GENERATED FILES 🗂️

Authselect creates and maintains the following files to configure system identity and authentication providers properly. These are her children and she loves them all equally. 🌸

  • /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. Like, she does not care how that went. She runs anyway. 💅
  • /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 👀

Go read these next, bestie, they're literally the rest of the lore:

And that's a wrap on the whole page, no cap. This one's from authselect, dated 2018-03-18, and you just finished reading AUTHSELECT(8) in all her glory. Go forth, run authselect check, and stan a well-managed configuration. 🦋💜🎀

📦 where this page comes from