Prepare pam_namespace Instance Directories with pam_namespace_helper

You will prepare the parent directories used by Linux-PAM polyinstantiation, check what the helper will create, and run it at the right point in the boot process. On this machine the command comes from libpam-modules-bin version 1.5.3-5ubuntu5.7. Allow about fifteen minutes for a read-only check and a controlled configuration change. The helper itself needs elevated privileges because it can create directories below paths named in the system configuration.

This guide covers preparation, not the whole PAM design. You need a working shell, systemd if you want the packaged boot integration, and a backup or version-controlled copy of any configuration you change.

1. Check the installed helper and service

Start with ordinary, read-only commands. They do not need sudo:

$ command -v pam_namespace_helper
/usr/sbin/pam_namespace_helper
$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules-bin
libpam-modules-bin 1.5.3-5ubuntu5.7
$ systemctl cat pam_namespace.service

The installed service is a oneshot unit. Its description says that it makes sure parent directories configured in /etc/security/namespace.conf exist, and its ExecStart points to /usr/sbin/pam_namespace_helper. The helper has no command-line options in its manual page. Do not add guessed flags or a configuration path to a script.

2. Understand what the helper reads

The related pam_namespace(8) manual identifies /etc/security/namespace.conf as the main configuration file and /etc/security/namespace.d as the directory for additional configuration files. It also documents /etc/security/namespace.init, which is a separate initialisation script for an instance after PAM mounts it.

The helper is narrower than the PAM module. It ensures that namespace mount points exist before they are used for polyinstantiated directories. Lines describing home directories with $HOME are deliberately not created by this helper. The PAM module handles those per-user paths when a session is established.

Inspect the configuration without changing it:

$ sudo sed -n '1,220p' /etc/security/namespace.conf
$ sudo find /etc/security/namespace.d -maxdepth 1 -type f -print 2>/dev/null

Read each active line as a policy, not as a shell command. A malformed line can affect session setup. The exact fields and supported methods belong to namespace.conf(5), so use that manual on your host before editing values. Do not uncomment an example merely to test the helper.

3. Identify the directories that may be created

Before running a filesystem-changing command, review the instance parent paths in the active configuration. The packaged service description calls these the parent directories configured for polyinstantiation. A helper run can create missing parent directories with mode 000; this is a security boundary, not a cosmetic directory setup.

$ sudo stat -c '%A %a %U:%G %n' /etc/security/namespace.conf
$ sudo ls -ld /path/to/instance-parent

Replace /path/to/instance-parent with a path you have actually found in your configuration. Never paste that placeholder into a production command. Check ownership, mount points and available space first. If the path is a symlink, stop and resolve where it leads before allowing a privileged helper to operate on it.

4. Apply a reviewed configuration

If you need to add or change a polyinstantiated directory, make a backup before editing. This changes system security behaviour, so schedule it away from active login testing:

$ sudo cp --preserve=mode,ownership,timestamps /etc/security/namespace.conf /etc/security/namespace.conf.bak
$ sudoedit /etc/security/namespace.conf

Validate the edited file with the namespace.conf(5) documentation and your change review. There is no helper option in the documented interface that performs a dry run. Before proceeding, inspect the diff if the file is tracked:

$ sudo diff -u /etc/security/namespace.conf.bak /etc/security/namespace.conf

Keep only the reviewed change. The backup gives you a recovery path if a later session test exposes a configuration error.

5. Run the helper once, as root

After defining the polyinstantiated directories and before enabling them for sessions, run the installed helper with no arguments:

$ sudo /usr/sbin/pam_namespace_helper
mkdir /path/to/instance-parent

The printed mkdir line is expected when a configured instance parent is missing. Existing paths normally produce no output. A successful exit status is the first check:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ sudo stat -c '%A %a %U:%G %n' /path/to/instance-parent
d--------- 0 root root /path/to/instance-parent

Output wording and the owner can vary with the path and host, but the important checks are that the intended directory now exists and that its permissions are restrictive. Do not loosen mode 000 just to make a manual test easier. The instance directories are intended to be mounted and managed by the namespace mechanism.

6. Use the systemd integration

The installed unit is intended to run the helper during startup, after local filesystems are available and before multi-user.target. If the unit is enabled on your host, inspect it before starting anything:

$ systemctl is-enabled pam_namespace.service
$ systemctl status pam_namespace.service --no-pager

Starting or enabling a system service changes host behaviour and may affect future logins. Do not use systemctl enable --now as a blind test. If your operational change requires enabling the unit, follow your service-change procedure, then check its result:

$ sudo systemctl enable pam_namespace.service
$ sudo systemctl start pam_namespace.service
$ systemctl status pam_namespace.service --no-pager

If the service fails after an edit, stop further login testing. Read its journal and restore the backup if the configuration change is not ready:

$ sudo journalctl -u pam_namespace.service -b --no-pager
$ sudo cp --preserve=mode,ownership,timestamps /etc/security/namespace.conf.bak /etc/security/namespace.conf

That restore replaces the active configuration, so use it only when the backup is the known-good version. Re-run the helper or service after restoring, then verify the directory state again.

7. Confirm the PAM side separately

pam_namespace_helper does not enable the PAM module. The related manual says that pam_namespace is a session module and is normally placed in the relevant /etc/pam.d/<service> session stack. Treat that as a separate, security-sensitive change. Confirm the service stack and test with a controlled account before relying on it for real users.

A helper run alone proves only that the configured parent paths can be prepared. It does not prove that a PAM session will mount the expected instance, that an SELinux context is correct, or that an $HOME path has been created. Check those behaviours through the service's normal login test and keep a recovery console available.