Setting Up

Documentation / Contents - CyLogin

• Overview of CyLogin
  • What It Is
  • What It Is Not
  • The Programs
  • In This Book
• Setting Up
  • What You Need
  • Build and Install
  • Enable With the Helper
  • Linux SysV and systemd
  • NetBSD rc.d
  • PAM Service File
  • Xservers and VT
  • Headless and LXC
  • Competing Display Managers
  • Check That It Works
  • Disable and Rollback
  • Common Mistakes
• Using CyLogin
  • Logging In
  • Faces
  • noiconlogin
  • Session Lock
  • Autologin and Classroom
  • After Login (Session)
  • Failsafe
• Configuration
  • Master Conf
  • Appearance
  • Session Path
  • Unsafe Knobs
  • Autologin Knobs
  • Lock Timeout
  • Classroom Sample
• Enable and Disable Helpers
  • cylogin-enable
  • Every enable Flag
  • cylogin-disable
  • Examples
• Security and PAM
  • Defaults
  • PAM Stacks
  • Empty Password Gate
  • Auth Dir and Cookies
  • Vs XDM and login
  • Lab Matrix
• Command Line
  • cylogind
  • cylogin Greeter
  • cylogin-authcheck
  • cychooser
• Keys and Shortcuts
• Files and Paths
  • System Conf
  • Runtime
  • Share Install
  • Init and PAM
• Troubleshooting
  • Greeter Never Appears
  • No Screens Found
  • PAM Failures
  • Wrong Session After Login
  • Setuid and Nobody
• Copyright

Setting Up

You need built binaries under PREFIX (usually /usr/local), then cylogin-enable to seed conf/PAM/init and claim the seat. There is no GUI setup panel; enable is CLI on purpose so headless and classroom boxes work the same way.

Day-to-day greeter clicks are in Using CyLogin. Every helper flag is in Enable and Disable Helpers.

What You Need

• Binaries: cylogind, cylogin-greeter (cylogin), cylogin-authcheck, usually cychooser; helpers cylogin-enable and cylogin-disable.
• Xorg on the machine that will show the greeter (or Xorg dummy for headless/LXC lab seats).
• Root for full enable. --dry-run never needs root.
• On Linux: PAM samples under share/cylogin (Debian common-* or RHEL system-auth). NetBSD uses native master.passwd; no /etc/pam.d/cylogin.
• A snapshotted lab CT or a spare seat before you displace LightDM/xdm on a live console.

Build and Install

From a Blueprint tree:

./configure --prefix=/usr/local --with-pam
make
sudo make install

Confirm:

cylogind --version
cylogin-greeter --version
ls -l /usr/local/bin/cylogin-authcheck
which cylogin-enable

make install as root seeds missing /etc/cyanotype pieces and may install /etc/init.d/cylogind or /etc/rc.d/cylogind. It does not claim the seat or stop LightDM. That is what cylogin-enable --yes is for.

Enable With the Helper

Always dry-run first:

cylogin-enable --dry-run

Then as root:

sudo cylogin-enable --yes

That does, in order:

1. fix-privs (setuid authcheck; mkdir runtime dirs; check nobody) 2. install /etc/pam.d/cylogin if missing (Linux only; OS-picked sample) 3. seed /etc/cyanotype conf/Xservers/Xaccess/hooks when absent 4. install SysV or NetBSD rc.d; write default-display-manager on Linux 5. stop/disable competing DMs (lightdm, gdm, slim, xdm, sddm, kdm) 6. start cylogind when Xorg and a usable seat (or dummy) are present

Staged pieces without claiming the live seat:

sudo cylogin-enable --fix-privs
sudo cylogin-enable --install-pam
sudo cylogin-enable --seed-conf

See Enable and Disable Helpers for every flag.

Linux SysV and systemd

On Devuan/Debian/Ubuntu-style systems the helper installs:

/etc/init.d/cylogind
/etc/default/cylogind   (if missing)
update-rc.d cylogind defaults   (when available)

On systemd hosts the SysV unit is generated; systemctl enable/start cylogind still works through that compatibility path. RHEL-family uses chkconfig or systemctl when update-rc.d is absent. The init script uses portable start/stop (start-stop-daemon when present, else pidfile).

NetBSD rc.d

On NetBSD (wedge and friends):

/etc/rc.d/cylogind          mode 555
cylogind=YES in /etc/rc.conf   (helper appends if missing)

/etc/rc.d/cylogind onestart

No PAM zoo. Auth is native crypt against master.passwd. Xservers comes from Xservers.netbsd.sample (/usr/X11R7/bin/Xorg, no Linux vtN).

Full enable on a twin that already runs auto_login on :0 needs an explicit plan; prefer --dry-run there until you mean to displace Slim.

PAM Service File

Linux builds with --with-pam need:

/etc/pam.d/cylogin

Samples:

• share/cylogin/pam.d-cylogin -- Debian/Devuan/Ubuntu common-* includes
• share/cylogin/pam.d-cylogin.rhel -- RHEL/Rocky/Alma system-auth + pam_nologin

cylogin-enable picks by /etc/os-release. Never overwrites an existing file unless you pass --force-pam. Missing service fails closed when PAM was compiled in. Policy knobs in cylogin.conf still apply after PAM success. Details: Security and PAM.

Xservers and VT

/etc/cyanotype/Xservers

Do NOT put -auth on the server line; cylogind appends it. Enable seeds a live line from the real Xorg path when possible:

:0 local /usr/lib/xorg/Xorg :0 vt07

If /dev/tty0 (and tty7) are absent (typical container), vtN is omitted so Xorg is not handed a console that does not exist:

:0 local /usr/lib/xorg/Xorg :0

Stock samples remain under share for hand edits. --force-conf rewrites live Xservers from the helper's detected path.

Headless and LXC

Unprivileged LXCs often have Xorg installed but no /dev/dri, /dev/fb0, or /dev/tty0. Bare Xorg then exits with "no screens found" and an old cylogind would respawn forever.

Enable now:

• Skips start when there is no local seat and no dummy driver.
• If dummy_drv.so is present, seeds /etc/X11/xorg.conf.d/10-cylogin-dummy.conf from share/cylogin/xorg-dummy.conf.sample and starts.

Lab install of the driver (admin step, like installing Xorg itself):

# Debian/Ubuntu/Devuan
apt install xserver-xorg-video-dummy
# RHEL/Rocky/Alma
dnf install xorg-x11-drv-dummy

Then re-run enable (or --seed-conf --force-conf and start). Do not hard-require dummy on real consoles; Suggest/Recommend it for lab CTs in packaging. See Troubleshooting.

Competing Display Managers

On Linux, enable stops and disables slim, lightdm, gdm3, gdm, kdm, xdm, and sddm when present (SysV and/or systemd). It saves the previous /etc/X11/default-display-manager path under /var/lib/cyanotype/enable-state/ before pointing that file at cylogind.

On NetBSD it stops /etc/rc.d/xdm when present and warns if xdm=YES is still in rc.conf.

Check That It Works

pgrep -a cylogind
pgrep -a Xorg
pgrep -a cylogin-greeter
ls -ld /var/lib/cyanotype/authdir
ls -l /var/lib/cyanotype/authdir/
test -f /etc/pam.d/cylogin && echo pam_ok   # Linux

Greeter should run as nobody (or greeter_user). Cookies 0600; authdir 0711. On a real seat you should see the face grid (or typed login).

PAM matrix tool in the tree (lab):

tools/cylogin-pam-matrix.sh

Disable and Rollback

sudo cylogin-disable --dry-run
sudo cylogin-disable --yes

Stops cylogind and best-effort restores the previous default-display-manager path. Does not delete /etc/cyanotype conf or remove PAM. Lab CTs with a dated pct snapshot can roll the whole CT back instead.

Common Mistakes

• Running --yes on a twin live :0 without a plan (auto_login seat).
• Expecting greeter in an LXC without dummy or GPU devices.
• Putting -auth in Xservers (double-auth; leave it to cylogind).
• Forcing vt07 in a container with no /dev/tty0.
• Leaving cylogin-authcheck non-setuid (lock path and some auth fail).
• Overwriting a tuned pam.d/cylogin with --force-pam by accident.
• Setting session= unset on classroom desks so a leftover ~/.xsession (Slim/icewm) steals the desktop; use the classroom sample.