From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/fedora-40/man5/BUILDINFO.5 | 238 + upstream/fedora-40/man5/PKGBUILD.5 | 795 + upstream/fedora-40/man5/acct.5 | 161 + upstream/fedora-40/man5/aliases.sendmail.5 | 131 + upstream/fedora-40/man5/alpm-hooks.5 | 272 + upstream/fedora-40/man5/anacrontab.5 | 145 + upstream/fedora-40/man5/at.allow.5 | 40 + upstream/fedora-40/man5/binfmt.d.5 | 104 + upstream/fedora-40/man5/bootchart.conf.5 | 123 + upstream/fedora-40/man5/btrfs.5 | 2972 ++++ upstream/fedora-40/man5/charmap.5 | 105 + upstream/fedora-40/man5/core.5 | 684 + upstream/fedora-40/man5/coredump.conf.5 | 157 + upstream/fedora-40/man5/crontab.5 | 374 + upstream/fedora-40/man5/crypttab.5 | 1114 ++ upstream/fedora-40/man5/depmod.d.5 | 126 + upstream/fedora-40/man5/dir_colors.5 | 406 + upstream/fedora-40/man5/dnssec-trust-anchors.d.5 | 227 + upstream/fedora-40/man5/e2fsck.conf.5 | 501 + upstream/fedora-40/man5/elf.5 | 2213 +++ upstream/fedora-40/man5/environment.d.5 | 151 + upstream/fedora-40/man5/erofs.5 | 97 + upstream/fedora-40/man5/ethers.5 | 28 + upstream/fedora-40/man5/exports.5 | 678 + upstream/fedora-40/man5/ext2.5 | 815 + upstream/fedora-40/man5/ext3.5 | 815 + upstream/fedora-40/man5/ext4.5 | 815 + upstream/fedora-40/man5/filesystems.5 | 227 + upstream/fedora-40/man5/ftpusers.5 | 42 + upstream/fedora-40/man5/gai.conf.5 | 89 + upstream/fedora-40/man5/genisoimagerc.5 | 144 + upstream/fedora-40/man5/groff_font.5 | 1114 ++ upstream/fedora-40/man5/groff_out.5 | 1963 +++ upstream/fedora-40/man5/groff_tmac.5 | 1474 ++ upstream/fedora-40/man5/group.5 | 55 + upstream/fedora-40/man5/homed.conf.5 | 110 + upstream/fedora-40/man5/host.conf.5 | 204 + upstream/fedora-40/man5/hostname.5 | 130 + upstream/fedora-40/man5/hosts.5 | 122 + upstream/fedora-40/man5/hosts.equiv.5 | 212 + upstream/fedora-40/man5/icewm-env.5 | 128 + upstream/fedora-40/man5/icewm-focus_mode.5 | 117 + upstream/fedora-40/man5/icewm-keys.5 | 220 + upstream/fedora-40/man5/icewm-menu.5 | 210 + upstream/fedora-40/man5/icewm-preferences.5 | 1508 ++ upstream/fedora-40/man5/icewm-prefoverride.5 | 109 + upstream/fedora-40/man5/icewm-programs.5 | 262 + upstream/fedora-40/man5/icewm-shutdown.5 | 108 + upstream/fedora-40/man5/icewm-startup.5 | 121 + upstream/fedora-40/man5/icewm-theme.5 | 140 + upstream/fedora-40/man5/icewm-toolbar.5 | 167 + upstream/fedora-40/man5/icewm-winoptions.5 | 344 + upstream/fedora-40/man5/idmapd.conf.5 | 424 + upstream/fedora-40/man5/info.5 | 59 + upstream/fedora-40/man5/integritytab.5 | 189 + upstream/fedora-40/man5/intro.5 | 23 + upstream/fedora-40/man5/iocost.conf.5 | 96 + upstream/fedora-40/man5/issue.5 | 24 + upstream/fedora-40/man5/journal-remote.conf.5 | 140 + upstream/fedora-40/man5/journal-upload.conf.5 | 115 + upstream/fedora-40/man5/journald.conf.5 | 509 + upstream/fedora-40/man5/keymaps.5 | 439 + upstream/fedora-40/man5/lmhosts.5 | 123 + upstream/fedora-40/man5/locale.5 | 1316 ++ upstream/fedora-40/man5/locale.conf.5 | 115 + upstream/fedora-40/man5/localtime.5 | 67 + upstream/fedora-40/man5/logind.conf.5 | 370 + upstream/fedora-40/man5/machine-id.5 | 253 + upstream/fedora-40/man5/machine-info.5 | 157 + upstream/fedora-40/man5/makepkg.conf.5 | 548 + upstream/fedora-40/man5/mke2fs.conf.5 | 566 + upstream/fedora-40/man5/mlocate.db.5 | 131 + upstream/fedora-40/man5/modprobe.d.5 | 174 + upstream/fedora-40/man5/modules-load.d.5 | 90 + upstream/fedora-40/man5/modules.dep.5 | 70 + upstream/fedora-40/man5/moduli.5 | 126 + upstream/fedora-40/man5/motd.5 | 25 + upstream/fedora-40/man5/mtools.5 | 575 + upstream/fedora-40/man5/muttrc.5 | 8134 ++++++++++ upstream/fedora-40/man5/nanorc.5 | 1057 ++ upstream/fedora-40/man5/networkd.conf.5 | 269 + upstream/fedora-40/man5/networks.5 | 60 + upstream/fedora-40/man5/nfs.5 | 1968 +++ upstream/fedora-40/man5/nfs.conf.5 | 335 + upstream/fedora-40/man5/nfsmount.conf.5 | 132 + upstream/fedora-40/man5/nfsrahead.5 | 72 + upstream/fedora-40/man5/nologin.5 | 22 + upstream/fedora-40/man5/nscd.conf.5 | 342 + upstream/fedora-40/man5/nss.5 | 101 + upstream/fedora-40/man5/nsswitch.conf.5 | 427 + upstream/fedora-40/man5/oomd.conf.5 | 114 + .../fedora-40/man5/org.freedesktop.LogControl1.5 | 391 + upstream/fedora-40/man5/org.freedesktop.home1.5 | 508 + .../fedora-40/man5/org.freedesktop.hostname1.5 | 618 + upstream/fedora-40/man5/org.freedesktop.import1.5 | 347 + upstream/fedora-40/man5/org.freedesktop.locale1.5 | 202 + upstream/fedora-40/man5/org.freedesktop.login1.5 | 1649 ++ upstream/fedora-40/man5/org.freedesktop.machine1.5 | 587 + upstream/fedora-40/man5/org.freedesktop.network1.5 | 376 + upstream/fedora-40/man5/org.freedesktop.oom1.5 | 105 + .../fedora-40/man5/org.freedesktop.portable1.5 | 769 + upstream/fedora-40/man5/org.freedesktop.resolve1.5 | 935 ++ upstream/fedora-40/man5/org.freedesktop.systemd1.5 | 7603 ++++++++++ .../fedora-40/man5/org.freedesktop.timedate1.5 | 217 + upstream/fedora-40/man5/os-release.5 | 718 + upstream/fedora-40/man5/pacman.conf.5 | 595 + upstream/fedora-40/man5/pam.5 | 331 + upstream/fedora-40/man5/passwd.5 | 160 + upstream/fedora-40/man5/pbm.5 | 212 + upstream/fedora-40/man5/pfm.5 | 96 + upstream/fedora-40/man5/pgm.5 | 247 + upstream/fedora-40/man5/pnm.5 | 85 + upstream/fedora-40/man5/ppm.5 | 240 + upstream/fedora-40/man5/proc.5 | 259 + upstream/fedora-40/man5/proc_apm.5 | 17 + upstream/fedora-40/man5/proc_buddyinfo.5 | 58 + upstream/fedora-40/man5/proc_bus.5 | 35 + upstream/fedora-40/man5/proc_cgroups.5 | 16 + upstream/fedora-40/man5/proc_cmdline.5 | 22 + upstream/fedora-40/man5/proc_config.gz.5 | 40 + upstream/fedora-40/man5/proc_cpuinfo.5 | 24 + upstream/fedora-40/man5/proc_crypto.5 | 26 + upstream/fedora-40/man5/proc_devices.5 | 16 + upstream/fedora-40/man5/proc_diskstats.5 | 21 + upstream/fedora-40/man5/proc_dma.5 | 16 + upstream/fedora-40/man5/proc_driver.5 | 15 + upstream/fedora-40/man5/proc_execdomains.5 | 16 + upstream/fedora-40/man5/proc_fb.5 | 17 + upstream/fedora-40/man5/proc_filesystems.5 | 33 + upstream/fedora-40/man5/proc_fs.5 | 18 + upstream/fedora-40/man5/proc_ide.5 | 37 + upstream/fedora-40/man5/proc_interrupts.5 | 22 + upstream/fedora-40/man5/proc_iomem.5 | 15 + upstream/fedora-40/man5/proc_ioports.5 | 16 + upstream/fedora-40/man5/proc_kallsyms.5 | 25 + upstream/fedora-40/man5/proc_kcore.5 | 24 + upstream/fedora-40/man5/proc_keys.5 | 20 + upstream/fedora-40/man5/proc_kmsg.5 | 28 + upstream/fedora-40/man5/proc_kpagecgroup.5 | 25 + upstream/fedora-40/man5/proc_kpagecount.5 | 24 + upstream/fedora-40/man5/proc_kpageflags.5 | 75 + upstream/fedora-40/man5/proc_loadavg.5 | 27 + upstream/fedora-40/man5/proc_locks.5 | 122 + upstream/fedora-40/man5/proc_malloc.5 | 18 + upstream/fedora-40/man5/proc_meminfo.5 | 327 + upstream/fedora-40/man5/proc_modules.5 | 17 + upstream/fedora-40/man5/proc_mtrr.5 | 24 + upstream/fedora-40/man5/proc_partitions.5 | 16 + upstream/fedora-40/man5/proc_pci.5 | 28 + upstream/fedora-40/man5/proc_pid.5 | 73 + upstream/fedora-40/man5/proc_pid_attr.5 | 137 + upstream/fedora-40/man5/proc_pid_autogroup.5 | 17 + upstream/fedora-40/man5/proc_pid_auxv.5 | 27 + upstream/fedora-40/man5/proc_pid_cgroup.5 | 16 + upstream/fedora-40/man5/proc_pid_clear_refs.5 | 87 + upstream/fedora-40/man5/proc_pid_cmdline.5 | 49 + upstream/fedora-40/man5/proc_pid_comm.5 | 49 + upstream/fedora-40/man5/proc_pid_coredump_filter.5 | 16 + upstream/fedora-40/man5/proc_pid_cpuset.5 | 17 + upstream/fedora-40/man5/proc_pid_cwd.5 | 36 + upstream/fedora-40/man5/proc_pid_environ.5 | 48 + upstream/fedora-40/man5/proc_pid_exe.5 | 59 + upstream/fedora-40/man5/proc_pid_fd.5 | 161 + upstream/fedora-40/man5/proc_pid_fdinfo.5 | 300 + upstream/fedora-40/man5/proc_pid_io.5 | 98 + upstream/fedora-40/man5/proc_pid_limits.5 | 25 + upstream/fedora-40/man5/proc_pid_map_files.5 | 72 + upstream/fedora-40/man5/proc_pid_maps.5 | 156 + upstream/fedora-40/man5/proc_pid_mem.5 | 24 + upstream/fedora-40/man5/proc_pid_mountinfo.5 | 124 + upstream/fedora-40/man5/proc_pid_mounts.5 | 49 + upstream/fedora-40/man5/proc_pid_mountstats.5 | 46 + upstream/fedora-40/man5/proc_pid_net.5 | 298 + upstream/fedora-40/man5/proc_pid_ns.5 | 20 + upstream/fedora-40/man5/proc_pid_numa_maps.5 | 16 + upstream/fedora-40/man5/proc_pid_oom_score.5 | 58 + upstream/fedora-40/man5/proc_pid_oom_score_adj.5 | 117 + upstream/fedora-40/man5/proc_pid_pagemap.5 | 77 + upstream/fedora-40/man5/proc_pid_personality.5 | 23 + upstream/fedora-40/man5/proc_pid_projid_map.5 | 17 + upstream/fedora-40/man5/proc_pid_root.5 | 75 + upstream/fedora-40/man5/proc_pid_seccomp.5 | 36 + upstream/fedora-40/man5/proc_pid_setgroups.5 | 16 + upstream/fedora-40/man5/proc_pid_smaps.5 | 129 + upstream/fedora-40/man5/proc_pid_stack.5 | 25 + upstream/fedora-40/man5/proc_pid_stat.5 | 380 + upstream/fedora-40/man5/proc_pid_statm.5 | 46 + upstream/fedora-40/man5/proc_pid_status.5 | 384 + upstream/fedora-40/man5/proc_pid_syscall.5 | 33 + upstream/fedora-40/man5/proc_pid_task.5 | 97 + upstream/fedora-40/man5/proc_pid_timers.5 | 82 + upstream/fedora-40/man5/proc_pid_timerslack_ns.5 | 41 + upstream/fedora-40/man5/proc_pid_uid_map.5 | 20 + upstream/fedora-40/man5/proc_pid_wchan.5 | 21 + upstream/fedora-40/man5/proc_profile.5 | 24 + upstream/fedora-40/man5/proc_scsi.5 | 66 + upstream/fedora-40/man5/proc_slabinfo.5 | 18 + upstream/fedora-40/man5/proc_stat.5 | 140 + upstream/fedora-40/man5/proc_swaps.5 | 17 + upstream/fedora-40/man5/proc_sys.5 | 31 + upstream/fedora-40/man5/proc_sys_abi.5 | 24 + upstream/fedora-40/man5/proc_sys_debug.5 | 17 + upstream/fedora-40/man5/proc_sys_dev.5 | 20 + upstream/fedora-40/man5/proc_sys_fs.5 | 471 + upstream/fedora-40/man5/proc_sys_kernel.5 | 691 + upstream/fedora-40/man5/proc_sys_net.5 | 34 + upstream/fedora-40/man5/proc_sys_proc.5 | 17 + upstream/fedora-40/man5/proc_sys_sunrpc.5 | 19 + upstream/fedora-40/man5/proc_sys_user.5 | 18 + upstream/fedora-40/man5/proc_sys_vm.5 | 420 + upstream/fedora-40/man5/proc_sysrq-trigger.5 | 25 + upstream/fedora-40/man5/proc_sysvipc.5 | 25 + upstream/fedora-40/man5/proc_tid_children.5 | 37 + upstream/fedora-40/man5/proc_timer_list.5 | 18 + upstream/fedora-40/man5/proc_timer_stats.5 | 117 + upstream/fedora-40/man5/proc_tty.5 | 16 + upstream/fedora-40/man5/proc_uptime.5 | 17 + upstream/fedora-40/man5/proc_version.5 | 27 + upstream/fedora-40/man5/proc_vmstat.5 | 702 + upstream/fedora-40/man5/proc_zoneinfo.5 | 17 + upstream/fedora-40/man5/procmailex.5 | 568 + upstream/fedora-40/man5/procmailrc.5 | 929 ++ upstream/fedora-40/man5/procmailsc.5 | 324 + upstream/fedora-40/man5/projects.5 | 31 + upstream/fedora-40/man5/projid.5 | 29 + upstream/fedora-40/man5/protocols.5 | 66 + upstream/fedora-40/man5/pstore.conf.5 | 97 + upstream/fedora-40/man5/rcsfile.5 | 459 + upstream/fedora-40/man5/repart.d.5 | 1113 ++ upstream/fedora-40/man5/repertoiremap.5 | 58 + upstream/fedora-40/man5/resolv.conf.5 | 406 + upstream/fedora-40/man5/resolved.conf.5 | 389 + upstream/fedora-40/man5/rpc.5 | 83 + upstream/fedora-40/man5/rsyncd.conf.5 | 1313 ++ upstream/fedora-40/man5/sane-abaton.5 | 142 + upstream/fedora-40/man5/sane-agfafocus.5 | 188 + upstream/fedora-40/man5/sane-apple.5 | 277 + upstream/fedora-40/man5/sane-artec.5 | 179 + upstream/fedora-40/man5/sane-artec_eplus48u.5 | 162 + upstream/fedora-40/man5/sane-as6e.5 | 49 + upstream/fedora-40/man5/sane-avision.5 | 187 + upstream/fedora-40/man5/sane-bh.5 | 581 + upstream/fedora-40/man5/sane-canon.5 | 111 + upstream/fedora-40/man5/sane-canon630u.5 | 123 + upstream/fedora-40/man5/sane-canon_dr.5 | 232 + upstream/fedora-40/man5/sane-canon_lide70.5 | 104 + upstream/fedora-40/man5/sane-canon_pp.5 | 237 + upstream/fedora-40/man5/sane-cardscan.5 | 117 + upstream/fedora-40/man5/sane-coolscan.5 | 111 + upstream/fedora-40/man5/sane-coolscan2.5 | 206 + upstream/fedora-40/man5/sane-coolscan3.5 | 204 + upstream/fedora-40/man5/sane-dc210.5 | 121 + upstream/fedora-40/man5/sane-dc240.5 | 131 + upstream/fedora-40/man5/sane-dc25.5 | 109 + upstream/fedora-40/man5/sane-dll.5 | 183 + upstream/fedora-40/man5/sane-dmc.5 | 153 + upstream/fedora-40/man5/sane-epjitsu.5 | 124 + upstream/fedora-40/man5/sane-epson.5 | 327 + upstream/fedora-40/man5/sane-epson2.5 | 380 + upstream/fedora-40/man5/sane-epsonds.5 | 114 + upstream/fedora-40/man5/sane-fujitsu.5 | 273 + upstream/fedora-40/man5/sane-genesys.5 | 306 + upstream/fedora-40/man5/sane-gphoto2.5 | 147 + upstream/fedora-40/man5/sane-gt68xx.5 | 232 + upstream/fedora-40/man5/sane-hp.5 | 304 + upstream/fedora-40/man5/sane-hp3500.5 | 53 + upstream/fedora-40/man5/sane-hp3900.5 | 124 + upstream/fedora-40/man5/sane-hp4200.5 | 115 + upstream/fedora-40/man5/sane-hp5400.5 | 113 + upstream/fedora-40/man5/sane-hp5590.5 | 343 + upstream/fedora-40/man5/sane-hpljm1005.5 | 50 + upstream/fedora-40/man5/sane-hpsj5s.5 | 121 + upstream/fedora-40/man5/sane-hs2p.5 | 131 + upstream/fedora-40/man5/sane-ibm.5 | 96 + upstream/fedora-40/man5/sane-kodak.5 | 154 + upstream/fedora-40/man5/sane-kodakaio.5 | 49 + upstream/fedora-40/man5/sane-kvs1025.5 | 32 + upstream/fedora-40/man5/sane-kvs20xx.5 | 31 + upstream/fedora-40/man5/sane-kvs40xx.5 | 33 + upstream/fedora-40/man5/sane-leo.5 | 167 + upstream/fedora-40/man5/sane-lexmark.5 | 172 + upstream/fedora-40/man5/sane-ma1509.5 | 142 + upstream/fedora-40/man5/sane-magicolor.5 | 90 + upstream/fedora-40/man5/sane-matsushita.5 | 176 + upstream/fedora-40/man5/sane-microtek.5 | 205 + upstream/fedora-40/man5/sane-microtek2.5 | 321 + upstream/fedora-40/man5/sane-mustek.5 | 421 + upstream/fedora-40/man5/sane-mustek_pp.5 | 524 + upstream/fedora-40/man5/sane-mustek_usb.5 | 213 + upstream/fedora-40/man5/sane-mustek_usb2.5 | 82 + upstream/fedora-40/man5/sane-nec.5 | 65 + upstream/fedora-40/man5/sane-net.5 | 167 + upstream/fedora-40/man5/sane-niash.5 | 81 + upstream/fedora-40/man5/sane-p5.5 | 162 + upstream/fedora-40/man5/sane-pie.5 | 59 + upstream/fedora-40/man5/sane-pieusb.5 | 120 + upstream/fedora-40/man5/sane-pixma.5 | 493 + upstream/fedora-40/man5/sane-plustek.5 | 529 + upstream/fedora-40/man5/sane-plustek_pp.5 | 350 + upstream/fedora-40/man5/sane-qcam.5 | 101 + upstream/fedora-40/man5/sane-ricoh.5 | 89 + upstream/fedora-40/man5/sane-ricoh2.5 | 68 + upstream/fedora-40/man5/sane-rts8891.5 | 171 + upstream/fedora-40/man5/sane-s9036.5 | 81 + upstream/fedora-40/man5/sane-sceptre.5 | 184 + upstream/fedora-40/man5/sane-scsi.5 | 355 + upstream/fedora-40/man5/sane-sharp.5 | 443 + upstream/fedora-40/man5/sane-sm3600.5 | 92 + upstream/fedora-40/man5/sane-sm3840.5 | 106 + upstream/fedora-40/man5/sane-snapscan.5 | 122 + upstream/fedora-40/man5/sane-sp15c.5 | 83 + upstream/fedora-40/man5/sane-st400.5 | 162 + upstream/fedora-40/man5/sane-stv680.5 | 180 + upstream/fedora-40/man5/sane-tamarack.5 | 91 + upstream/fedora-40/man5/sane-teco1.5 | 201 + upstream/fedora-40/man5/sane-teco2.5 | 257 + upstream/fedora-40/man5/sane-teco3.5 | 168 + upstream/fedora-40/man5/sane-test.5 | 351 + upstream/fedora-40/man5/sane-u12.5 | 192 + upstream/fedora-40/man5/sane-umax.5 | 284 + upstream/fedora-40/man5/sane-umax1220u.5 | 120 + upstream/fedora-40/man5/sane-umax_pp.5 | 332 + upstream/fedora-40/man5/sane-usb.5 | 186 + upstream/fedora-40/man5/sane-v4l.5 | 100 + upstream/fedora-40/man5/sane-xerox_mfp.5 | 76 + upstream/fedora-40/man5/scr_dump.5 | 476 + upstream/fedora-40/man5/securetty.5 | 35 + upstream/fedora-40/man5/services.5 | 199 + upstream/fedora-40/man5/shells.5 | 40 + upstream/fedora-40/man5/slabinfo.5 | 220 + upstream/fedora-40/man5/smb.conf.5 | 14930 +++++++++++++++++++ upstream/fedora-40/man5/smbpasswd.5 | 175 + upstream/fedora-40/man5/ssh_config.5 | 2400 +++ upstream/fedora-40/man5/sshd_config.5 | 2110 +++ upstream/fedora-40/man5/sysctl.d.5 | 245 + upstream/fedora-40/man5/sysfs.5 | 275 + upstream/fedora-40/man5/sysstat.5 | 176 + upstream/fedora-40/man5/systemd-sleep.conf.5 | 236 + upstream/fedora-40/man5/systemd-system.conf.5 | 837 ++ upstream/fedora-40/man5/systemd.automount.5 | 192 + upstream/fedora-40/man5/systemd.device.5 | 138 + upstream/fedora-40/man5/systemd.dnssd.5 | 336 + upstream/fedora-40/man5/systemd.exec.5 | 5667 +++++++ upstream/fedora-40/man5/systemd.kill.5 | 225 + upstream/fedora-40/man5/systemd.link.5 | 2045 +++ upstream/fedora-40/man5/systemd.mount.5 | 671 + upstream/fedora-40/man5/systemd.netdev.5 | 2746 ++++ upstream/fedora-40/man5/systemd.network.5 | 6230 ++++++++ upstream/fedora-40/man5/systemd.nspawn.5 | 592 + upstream/fedora-40/man5/systemd.path.5 | 211 + upstream/fedora-40/man5/systemd.pcrlock.5 | 276 + upstream/fedora-40/man5/systemd.preset.5 | 220 + upstream/fedora-40/man5/systemd.resource-control.5 | 1826 +++ upstream/fedora-40/man5/systemd.scope.5 | 170 + upstream/fedora-40/man5/systemd.service.5 | 2205 +++ upstream/fedora-40/man5/systemd.slice.5 | 120 + upstream/fedora-40/man5/systemd.socket.5 | 915 ++ upstream/fedora-40/man5/systemd.swap.5 | 247 + upstream/fedora-40/man5/systemd.target.5 | 177 + upstream/fedora-40/man5/systemd.timer.5 | 388 + upstream/fedora-40/man5/systemd.unit.5 | 3015 ++++ upstream/fedora-40/man5/sysupdate.d.5 | 1340 ++ upstream/fedora-40/man5/sysusers.d.5 | 377 + upstream/fedora-40/man5/term.5 | 452 + upstream/fedora-40/man5/termcap.5 | 466 + upstream/fedora-40/man5/terminfo.5 | 4345 ++++++ upstream/fedora-40/man5/texinfo.5 | 50 + upstream/fedora-40/man5/thinkfan.conf.5 | 420 + upstream/fedora-40/man5/thinkfan.conf.legacy.5 | 253 + upstream/fedora-40/man5/timesyncd.conf.5 | 140 + upstream/fedora-40/man5/tmpfiles.d.5 | 1051 ++ upstream/fedora-40/man5/tmpfs.5 | 281 + upstream/fedora-40/man5/ttytype.5 | 56 + upstream/fedora-40/man5/tzfile.5 | 496 + upstream/fedora-40/man5/udev.conf.5 | 112 + upstream/fedora-40/man5/updatedb.conf.5 | 138 + upstream/fedora-40/man5/user@.service.5 | 197 + upstream/fedora-40/man5/user_caps.5 | 464 + upstream/fedora-40/man5/utmp.5 | 348 + upstream/fedora-40/man5/uuencode.5 | 140 + upstream/fedora-40/man5/vconsole.conf.5 | 127 + upstream/fedora-40/man5/veritytab.5 | 275 + upstream/fedora-40/man5/whois.conf.5 | 50 + upstream/fedora-40/man5/xfs.5 | 370 + 384 files changed, 154091 insertions(+) create mode 100644 upstream/fedora-40/man5/BUILDINFO.5 create mode 100644 upstream/fedora-40/man5/PKGBUILD.5 create mode 100644 upstream/fedora-40/man5/acct.5 create mode 100644 upstream/fedora-40/man5/aliases.sendmail.5 create mode 100644 upstream/fedora-40/man5/alpm-hooks.5 create mode 100644 upstream/fedora-40/man5/anacrontab.5 create mode 100644 upstream/fedora-40/man5/at.allow.5 create mode 100644 upstream/fedora-40/man5/binfmt.d.5 create mode 100644 upstream/fedora-40/man5/bootchart.conf.5 create mode 100644 upstream/fedora-40/man5/btrfs.5 create mode 100644 upstream/fedora-40/man5/charmap.5 create mode 100644 upstream/fedora-40/man5/core.5 create mode 100644 upstream/fedora-40/man5/coredump.conf.5 create mode 100644 upstream/fedora-40/man5/crontab.5 create mode 100644 upstream/fedora-40/man5/crypttab.5 create mode 100644 upstream/fedora-40/man5/depmod.d.5 create mode 100644 upstream/fedora-40/man5/dir_colors.5 create mode 100644 upstream/fedora-40/man5/dnssec-trust-anchors.d.5 create mode 100644 upstream/fedora-40/man5/e2fsck.conf.5 create mode 100644 upstream/fedora-40/man5/elf.5 create mode 100644 upstream/fedora-40/man5/environment.d.5 create mode 100644 upstream/fedora-40/man5/erofs.5 create mode 100644 upstream/fedora-40/man5/ethers.5 create mode 100644 upstream/fedora-40/man5/exports.5 create mode 100644 upstream/fedora-40/man5/ext2.5 create mode 100644 upstream/fedora-40/man5/ext3.5 create mode 100644 upstream/fedora-40/man5/ext4.5 create mode 100644 upstream/fedora-40/man5/filesystems.5 create mode 100644 upstream/fedora-40/man5/ftpusers.5 create mode 100644 upstream/fedora-40/man5/gai.conf.5 create mode 100644 upstream/fedora-40/man5/genisoimagerc.5 create mode 100644 upstream/fedora-40/man5/groff_font.5 create mode 100644 upstream/fedora-40/man5/groff_out.5 create mode 100644 upstream/fedora-40/man5/groff_tmac.5 create mode 100644 upstream/fedora-40/man5/group.5 create mode 100644 upstream/fedora-40/man5/homed.conf.5 create mode 100644 upstream/fedora-40/man5/host.conf.5 create mode 100644 upstream/fedora-40/man5/hostname.5 create mode 100644 upstream/fedora-40/man5/hosts.5 create mode 100644 upstream/fedora-40/man5/hosts.equiv.5 create mode 100644 upstream/fedora-40/man5/icewm-env.5 create mode 100644 upstream/fedora-40/man5/icewm-focus_mode.5 create mode 100644 upstream/fedora-40/man5/icewm-keys.5 create mode 100644 upstream/fedora-40/man5/icewm-menu.5 create mode 100644 upstream/fedora-40/man5/icewm-preferences.5 create mode 100644 upstream/fedora-40/man5/icewm-prefoverride.5 create mode 100644 upstream/fedora-40/man5/icewm-programs.5 create mode 100644 upstream/fedora-40/man5/icewm-shutdown.5 create mode 100644 upstream/fedora-40/man5/icewm-startup.5 create mode 100644 upstream/fedora-40/man5/icewm-theme.5 create mode 100644 upstream/fedora-40/man5/icewm-toolbar.5 create mode 100644 upstream/fedora-40/man5/icewm-winoptions.5 create mode 100644 upstream/fedora-40/man5/idmapd.conf.5 create mode 100644 upstream/fedora-40/man5/info.5 create mode 100644 upstream/fedora-40/man5/integritytab.5 create mode 100644 upstream/fedora-40/man5/intro.5 create mode 100644 upstream/fedora-40/man5/iocost.conf.5 create mode 100644 upstream/fedora-40/man5/issue.5 create mode 100644 upstream/fedora-40/man5/journal-remote.conf.5 create mode 100644 upstream/fedora-40/man5/journal-upload.conf.5 create mode 100644 upstream/fedora-40/man5/journald.conf.5 create mode 100644 upstream/fedora-40/man5/keymaps.5 create mode 100644 upstream/fedora-40/man5/lmhosts.5 create mode 100644 upstream/fedora-40/man5/locale.5 create mode 100644 upstream/fedora-40/man5/locale.conf.5 create mode 100644 upstream/fedora-40/man5/localtime.5 create mode 100644 upstream/fedora-40/man5/logind.conf.5 create mode 100644 upstream/fedora-40/man5/machine-id.5 create mode 100644 upstream/fedora-40/man5/machine-info.5 create mode 100644 upstream/fedora-40/man5/makepkg.conf.5 create mode 100644 upstream/fedora-40/man5/mke2fs.conf.5 create mode 100644 upstream/fedora-40/man5/mlocate.db.5 create mode 100644 upstream/fedora-40/man5/modprobe.d.5 create mode 100644 upstream/fedora-40/man5/modules-load.d.5 create mode 100644 upstream/fedora-40/man5/modules.dep.5 create mode 100644 upstream/fedora-40/man5/moduli.5 create mode 100644 upstream/fedora-40/man5/motd.5 create mode 100644 upstream/fedora-40/man5/mtools.5 create mode 100644 upstream/fedora-40/man5/muttrc.5 create mode 100644 upstream/fedora-40/man5/nanorc.5 create mode 100644 upstream/fedora-40/man5/networkd.conf.5 create mode 100644 upstream/fedora-40/man5/networks.5 create mode 100644 upstream/fedora-40/man5/nfs.5 create mode 100644 upstream/fedora-40/man5/nfs.conf.5 create mode 100644 upstream/fedora-40/man5/nfsmount.conf.5 create mode 100644 upstream/fedora-40/man5/nfsrahead.5 create mode 100644 upstream/fedora-40/man5/nologin.5 create mode 100644 upstream/fedora-40/man5/nscd.conf.5 create mode 100644 upstream/fedora-40/man5/nss.5 create mode 100644 upstream/fedora-40/man5/nsswitch.conf.5 create mode 100644 upstream/fedora-40/man5/oomd.conf.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.LogControl1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.home1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.hostname1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.import1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.locale1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.login1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.machine1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.network1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.oom1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.portable1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.resolve1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.systemd1.5 create mode 100644 upstream/fedora-40/man5/org.freedesktop.timedate1.5 create mode 100644 upstream/fedora-40/man5/os-release.5 create mode 100644 upstream/fedora-40/man5/pacman.conf.5 create mode 100644 upstream/fedora-40/man5/pam.5 create mode 100644 upstream/fedora-40/man5/passwd.5 create mode 100644 upstream/fedora-40/man5/pbm.5 create mode 100644 upstream/fedora-40/man5/pfm.5 create mode 100644 upstream/fedora-40/man5/pgm.5 create mode 100644 upstream/fedora-40/man5/pnm.5 create mode 100644 upstream/fedora-40/man5/ppm.5 create mode 100644 upstream/fedora-40/man5/proc.5 create mode 100644 upstream/fedora-40/man5/proc_apm.5 create mode 100644 upstream/fedora-40/man5/proc_buddyinfo.5 create mode 100644 upstream/fedora-40/man5/proc_bus.5 create mode 100644 upstream/fedora-40/man5/proc_cgroups.5 create mode 100644 upstream/fedora-40/man5/proc_cmdline.5 create mode 100644 upstream/fedora-40/man5/proc_config.gz.5 create mode 100644 upstream/fedora-40/man5/proc_cpuinfo.5 create mode 100644 upstream/fedora-40/man5/proc_crypto.5 create mode 100644 upstream/fedora-40/man5/proc_devices.5 create mode 100644 upstream/fedora-40/man5/proc_diskstats.5 create mode 100644 upstream/fedora-40/man5/proc_dma.5 create mode 100644 upstream/fedora-40/man5/proc_driver.5 create mode 100644 upstream/fedora-40/man5/proc_execdomains.5 create mode 100644 upstream/fedora-40/man5/proc_fb.5 create mode 100644 upstream/fedora-40/man5/proc_filesystems.5 create mode 100644 upstream/fedora-40/man5/proc_fs.5 create mode 100644 upstream/fedora-40/man5/proc_ide.5 create mode 100644 upstream/fedora-40/man5/proc_interrupts.5 create mode 100644 upstream/fedora-40/man5/proc_iomem.5 create mode 100644 upstream/fedora-40/man5/proc_ioports.5 create mode 100644 upstream/fedora-40/man5/proc_kallsyms.5 create mode 100644 upstream/fedora-40/man5/proc_kcore.5 create mode 100644 upstream/fedora-40/man5/proc_keys.5 create mode 100644 upstream/fedora-40/man5/proc_kmsg.5 create mode 100644 upstream/fedora-40/man5/proc_kpagecgroup.5 create mode 100644 upstream/fedora-40/man5/proc_kpagecount.5 create mode 100644 upstream/fedora-40/man5/proc_kpageflags.5 create mode 100644 upstream/fedora-40/man5/proc_loadavg.5 create mode 100644 upstream/fedora-40/man5/proc_locks.5 create mode 100644 upstream/fedora-40/man5/proc_malloc.5 create mode 100644 upstream/fedora-40/man5/proc_meminfo.5 create mode 100644 upstream/fedora-40/man5/proc_modules.5 create mode 100644 upstream/fedora-40/man5/proc_mtrr.5 create mode 100644 upstream/fedora-40/man5/proc_partitions.5 create mode 100644 upstream/fedora-40/man5/proc_pci.5 create mode 100644 upstream/fedora-40/man5/proc_pid.5 create mode 100644 upstream/fedora-40/man5/proc_pid_attr.5 create mode 100644 upstream/fedora-40/man5/proc_pid_autogroup.5 create mode 100644 upstream/fedora-40/man5/proc_pid_auxv.5 create mode 100644 upstream/fedora-40/man5/proc_pid_cgroup.5 create mode 100644 upstream/fedora-40/man5/proc_pid_clear_refs.5 create mode 100644 upstream/fedora-40/man5/proc_pid_cmdline.5 create mode 100644 upstream/fedora-40/man5/proc_pid_comm.5 create mode 100644 upstream/fedora-40/man5/proc_pid_coredump_filter.5 create mode 100644 upstream/fedora-40/man5/proc_pid_cpuset.5 create mode 100644 upstream/fedora-40/man5/proc_pid_cwd.5 create mode 100644 upstream/fedora-40/man5/proc_pid_environ.5 create mode 100644 upstream/fedora-40/man5/proc_pid_exe.5 create mode 100644 upstream/fedora-40/man5/proc_pid_fd.5 create mode 100644 upstream/fedora-40/man5/proc_pid_fdinfo.5 create mode 100644 upstream/fedora-40/man5/proc_pid_io.5 create mode 100644 upstream/fedora-40/man5/proc_pid_limits.5 create mode 100644 upstream/fedora-40/man5/proc_pid_map_files.5 create mode 100644 upstream/fedora-40/man5/proc_pid_maps.5 create mode 100644 upstream/fedora-40/man5/proc_pid_mem.5 create mode 100644 upstream/fedora-40/man5/proc_pid_mountinfo.5 create mode 100644 upstream/fedora-40/man5/proc_pid_mounts.5 create mode 100644 upstream/fedora-40/man5/proc_pid_mountstats.5 create mode 100644 upstream/fedora-40/man5/proc_pid_net.5 create mode 100644 upstream/fedora-40/man5/proc_pid_ns.5 create mode 100644 upstream/fedora-40/man5/proc_pid_numa_maps.5 create mode 100644 upstream/fedora-40/man5/proc_pid_oom_score.5 create mode 100644 upstream/fedora-40/man5/proc_pid_oom_score_adj.5 create mode 100644 upstream/fedora-40/man5/proc_pid_pagemap.5 create mode 100644 upstream/fedora-40/man5/proc_pid_personality.5 create mode 100644 upstream/fedora-40/man5/proc_pid_projid_map.5 create mode 100644 upstream/fedora-40/man5/proc_pid_root.5 create mode 100644 upstream/fedora-40/man5/proc_pid_seccomp.5 create mode 100644 upstream/fedora-40/man5/proc_pid_setgroups.5 create mode 100644 upstream/fedora-40/man5/proc_pid_smaps.5 create mode 100644 upstream/fedora-40/man5/proc_pid_stack.5 create mode 100644 upstream/fedora-40/man5/proc_pid_stat.5 create mode 100644 upstream/fedora-40/man5/proc_pid_statm.5 create mode 100644 upstream/fedora-40/man5/proc_pid_status.5 create mode 100644 upstream/fedora-40/man5/proc_pid_syscall.5 create mode 100644 upstream/fedora-40/man5/proc_pid_task.5 create mode 100644 upstream/fedora-40/man5/proc_pid_timers.5 create mode 100644 upstream/fedora-40/man5/proc_pid_timerslack_ns.5 create mode 100644 upstream/fedora-40/man5/proc_pid_uid_map.5 create mode 100644 upstream/fedora-40/man5/proc_pid_wchan.5 create mode 100644 upstream/fedora-40/man5/proc_profile.5 create mode 100644 upstream/fedora-40/man5/proc_scsi.5 create mode 100644 upstream/fedora-40/man5/proc_slabinfo.5 create mode 100644 upstream/fedora-40/man5/proc_stat.5 create mode 100644 upstream/fedora-40/man5/proc_swaps.5 create mode 100644 upstream/fedora-40/man5/proc_sys.5 create mode 100644 upstream/fedora-40/man5/proc_sys_abi.5 create mode 100644 upstream/fedora-40/man5/proc_sys_debug.5 create mode 100644 upstream/fedora-40/man5/proc_sys_dev.5 create mode 100644 upstream/fedora-40/man5/proc_sys_fs.5 create mode 100644 upstream/fedora-40/man5/proc_sys_kernel.5 create mode 100644 upstream/fedora-40/man5/proc_sys_net.5 create mode 100644 upstream/fedora-40/man5/proc_sys_proc.5 create mode 100644 upstream/fedora-40/man5/proc_sys_sunrpc.5 create mode 100644 upstream/fedora-40/man5/proc_sys_user.5 create mode 100644 upstream/fedora-40/man5/proc_sys_vm.5 create mode 100644 upstream/fedora-40/man5/proc_sysrq-trigger.5 create mode 100644 upstream/fedora-40/man5/proc_sysvipc.5 create mode 100644 upstream/fedora-40/man5/proc_tid_children.5 create mode 100644 upstream/fedora-40/man5/proc_timer_list.5 create mode 100644 upstream/fedora-40/man5/proc_timer_stats.5 create mode 100644 upstream/fedora-40/man5/proc_tty.5 create mode 100644 upstream/fedora-40/man5/proc_uptime.5 create mode 100644 upstream/fedora-40/man5/proc_version.5 create mode 100644 upstream/fedora-40/man5/proc_vmstat.5 create mode 100644 upstream/fedora-40/man5/proc_zoneinfo.5 create mode 100644 upstream/fedora-40/man5/procmailex.5 create mode 100644 upstream/fedora-40/man5/procmailrc.5 create mode 100644 upstream/fedora-40/man5/procmailsc.5 create mode 100644 upstream/fedora-40/man5/projects.5 create mode 100644 upstream/fedora-40/man5/projid.5 create mode 100644 upstream/fedora-40/man5/protocols.5 create mode 100644 upstream/fedora-40/man5/pstore.conf.5 create mode 100644 upstream/fedora-40/man5/rcsfile.5 create mode 100644 upstream/fedora-40/man5/repart.d.5 create mode 100644 upstream/fedora-40/man5/repertoiremap.5 create mode 100644 upstream/fedora-40/man5/resolv.conf.5 create mode 100644 upstream/fedora-40/man5/resolved.conf.5 create mode 100644 upstream/fedora-40/man5/rpc.5 create mode 100644 upstream/fedora-40/man5/rsyncd.conf.5 create mode 100644 upstream/fedora-40/man5/sane-abaton.5 create mode 100644 upstream/fedora-40/man5/sane-agfafocus.5 create mode 100644 upstream/fedora-40/man5/sane-apple.5 create mode 100644 upstream/fedora-40/man5/sane-artec.5 create mode 100644 upstream/fedora-40/man5/sane-artec_eplus48u.5 create mode 100644 upstream/fedora-40/man5/sane-as6e.5 create mode 100644 upstream/fedora-40/man5/sane-avision.5 create mode 100644 upstream/fedora-40/man5/sane-bh.5 create mode 100644 upstream/fedora-40/man5/sane-canon.5 create mode 100644 upstream/fedora-40/man5/sane-canon630u.5 create mode 100644 upstream/fedora-40/man5/sane-canon_dr.5 create mode 100644 upstream/fedora-40/man5/sane-canon_lide70.5 create mode 100644 upstream/fedora-40/man5/sane-canon_pp.5 create mode 100644 upstream/fedora-40/man5/sane-cardscan.5 create mode 100644 upstream/fedora-40/man5/sane-coolscan.5 create mode 100644 upstream/fedora-40/man5/sane-coolscan2.5 create mode 100644 upstream/fedora-40/man5/sane-coolscan3.5 create mode 100644 upstream/fedora-40/man5/sane-dc210.5 create mode 100644 upstream/fedora-40/man5/sane-dc240.5 create mode 100644 upstream/fedora-40/man5/sane-dc25.5 create mode 100644 upstream/fedora-40/man5/sane-dll.5 create mode 100644 upstream/fedora-40/man5/sane-dmc.5 create mode 100644 upstream/fedora-40/man5/sane-epjitsu.5 create mode 100644 upstream/fedora-40/man5/sane-epson.5 create mode 100644 upstream/fedora-40/man5/sane-epson2.5 create mode 100644 upstream/fedora-40/man5/sane-epsonds.5 create mode 100644 upstream/fedora-40/man5/sane-fujitsu.5 create mode 100644 upstream/fedora-40/man5/sane-genesys.5 create mode 100644 upstream/fedora-40/man5/sane-gphoto2.5 create mode 100644 upstream/fedora-40/man5/sane-gt68xx.5 create mode 100644 upstream/fedora-40/man5/sane-hp.5 create mode 100644 upstream/fedora-40/man5/sane-hp3500.5 create mode 100644 upstream/fedora-40/man5/sane-hp3900.5 create mode 100644 upstream/fedora-40/man5/sane-hp4200.5 create mode 100644 upstream/fedora-40/man5/sane-hp5400.5 create mode 100644 upstream/fedora-40/man5/sane-hp5590.5 create mode 100644 upstream/fedora-40/man5/sane-hpljm1005.5 create mode 100644 upstream/fedora-40/man5/sane-hpsj5s.5 create mode 100644 upstream/fedora-40/man5/sane-hs2p.5 create mode 100644 upstream/fedora-40/man5/sane-ibm.5 create mode 100644 upstream/fedora-40/man5/sane-kodak.5 create mode 100644 upstream/fedora-40/man5/sane-kodakaio.5 create mode 100644 upstream/fedora-40/man5/sane-kvs1025.5 create mode 100644 upstream/fedora-40/man5/sane-kvs20xx.5 create mode 100644 upstream/fedora-40/man5/sane-kvs40xx.5 create mode 100644 upstream/fedora-40/man5/sane-leo.5 create mode 100644 upstream/fedora-40/man5/sane-lexmark.5 create mode 100644 upstream/fedora-40/man5/sane-ma1509.5 create mode 100644 upstream/fedora-40/man5/sane-magicolor.5 create mode 100644 upstream/fedora-40/man5/sane-matsushita.5 create mode 100644 upstream/fedora-40/man5/sane-microtek.5 create mode 100644 upstream/fedora-40/man5/sane-microtek2.5 create mode 100644 upstream/fedora-40/man5/sane-mustek.5 create mode 100644 upstream/fedora-40/man5/sane-mustek_pp.5 create mode 100644 upstream/fedora-40/man5/sane-mustek_usb.5 create mode 100644 upstream/fedora-40/man5/sane-mustek_usb2.5 create mode 100644 upstream/fedora-40/man5/sane-nec.5 create mode 100644 upstream/fedora-40/man5/sane-net.5 create mode 100644 upstream/fedora-40/man5/sane-niash.5 create mode 100644 upstream/fedora-40/man5/sane-p5.5 create mode 100644 upstream/fedora-40/man5/sane-pie.5 create mode 100644 upstream/fedora-40/man5/sane-pieusb.5 create mode 100644 upstream/fedora-40/man5/sane-pixma.5 create mode 100644 upstream/fedora-40/man5/sane-plustek.5 create mode 100644 upstream/fedora-40/man5/sane-plustek_pp.5 create mode 100644 upstream/fedora-40/man5/sane-qcam.5 create mode 100644 upstream/fedora-40/man5/sane-ricoh.5 create mode 100644 upstream/fedora-40/man5/sane-ricoh2.5 create mode 100644 upstream/fedora-40/man5/sane-rts8891.5 create mode 100644 upstream/fedora-40/man5/sane-s9036.5 create mode 100644 upstream/fedora-40/man5/sane-sceptre.5 create mode 100644 upstream/fedora-40/man5/sane-scsi.5 create mode 100644 upstream/fedora-40/man5/sane-sharp.5 create mode 100644 upstream/fedora-40/man5/sane-sm3600.5 create mode 100644 upstream/fedora-40/man5/sane-sm3840.5 create mode 100644 upstream/fedora-40/man5/sane-snapscan.5 create mode 100644 upstream/fedora-40/man5/sane-sp15c.5 create mode 100644 upstream/fedora-40/man5/sane-st400.5 create mode 100644 upstream/fedora-40/man5/sane-stv680.5 create mode 100644 upstream/fedora-40/man5/sane-tamarack.5 create mode 100644 upstream/fedora-40/man5/sane-teco1.5 create mode 100644 upstream/fedora-40/man5/sane-teco2.5 create mode 100644 upstream/fedora-40/man5/sane-teco3.5 create mode 100644 upstream/fedora-40/man5/sane-test.5 create mode 100644 upstream/fedora-40/man5/sane-u12.5 create mode 100644 upstream/fedora-40/man5/sane-umax.5 create mode 100644 upstream/fedora-40/man5/sane-umax1220u.5 create mode 100644 upstream/fedora-40/man5/sane-umax_pp.5 create mode 100644 upstream/fedora-40/man5/sane-usb.5 create mode 100644 upstream/fedora-40/man5/sane-v4l.5 create mode 100644 upstream/fedora-40/man5/sane-xerox_mfp.5 create mode 100644 upstream/fedora-40/man5/scr_dump.5 create mode 100644 upstream/fedora-40/man5/securetty.5 create mode 100644 upstream/fedora-40/man5/services.5 create mode 100644 upstream/fedora-40/man5/shells.5 create mode 100644 upstream/fedora-40/man5/slabinfo.5 create mode 100644 upstream/fedora-40/man5/smb.conf.5 create mode 100644 upstream/fedora-40/man5/smbpasswd.5 create mode 100644 upstream/fedora-40/man5/ssh_config.5 create mode 100644 upstream/fedora-40/man5/sshd_config.5 create mode 100644 upstream/fedora-40/man5/sysctl.d.5 create mode 100644 upstream/fedora-40/man5/sysfs.5 create mode 100644 upstream/fedora-40/man5/sysstat.5 create mode 100644 upstream/fedora-40/man5/systemd-sleep.conf.5 create mode 100644 upstream/fedora-40/man5/systemd-system.conf.5 create mode 100644 upstream/fedora-40/man5/systemd.automount.5 create mode 100644 upstream/fedora-40/man5/systemd.device.5 create mode 100644 upstream/fedora-40/man5/systemd.dnssd.5 create mode 100644 upstream/fedora-40/man5/systemd.exec.5 create mode 100644 upstream/fedora-40/man5/systemd.kill.5 create mode 100644 upstream/fedora-40/man5/systemd.link.5 create mode 100644 upstream/fedora-40/man5/systemd.mount.5 create mode 100644 upstream/fedora-40/man5/systemd.netdev.5 create mode 100644 upstream/fedora-40/man5/systemd.network.5 create mode 100644 upstream/fedora-40/man5/systemd.nspawn.5 create mode 100644 upstream/fedora-40/man5/systemd.path.5 create mode 100644 upstream/fedora-40/man5/systemd.pcrlock.5 create mode 100644 upstream/fedora-40/man5/systemd.preset.5 create mode 100644 upstream/fedora-40/man5/systemd.resource-control.5 create mode 100644 upstream/fedora-40/man5/systemd.scope.5 create mode 100644 upstream/fedora-40/man5/systemd.service.5 create mode 100644 upstream/fedora-40/man5/systemd.slice.5 create mode 100644 upstream/fedora-40/man5/systemd.socket.5 create mode 100644 upstream/fedora-40/man5/systemd.swap.5 create mode 100644 upstream/fedora-40/man5/systemd.target.5 create mode 100644 upstream/fedora-40/man5/systemd.timer.5 create mode 100644 upstream/fedora-40/man5/systemd.unit.5 create mode 100644 upstream/fedora-40/man5/sysupdate.d.5 create mode 100644 upstream/fedora-40/man5/sysusers.d.5 create mode 100644 upstream/fedora-40/man5/term.5 create mode 100644 upstream/fedora-40/man5/termcap.5 create mode 100644 upstream/fedora-40/man5/terminfo.5 create mode 100644 upstream/fedora-40/man5/texinfo.5 create mode 100644 upstream/fedora-40/man5/thinkfan.conf.5 create mode 100644 upstream/fedora-40/man5/thinkfan.conf.legacy.5 create mode 100644 upstream/fedora-40/man5/timesyncd.conf.5 create mode 100644 upstream/fedora-40/man5/tmpfiles.d.5 create mode 100644 upstream/fedora-40/man5/tmpfs.5 create mode 100644 upstream/fedora-40/man5/ttytype.5 create mode 100644 upstream/fedora-40/man5/tzfile.5 create mode 100644 upstream/fedora-40/man5/udev.conf.5 create mode 100644 upstream/fedora-40/man5/updatedb.conf.5 create mode 100644 upstream/fedora-40/man5/user@.service.5 create mode 100644 upstream/fedora-40/man5/user_caps.5 create mode 100644 upstream/fedora-40/man5/utmp.5 create mode 100644 upstream/fedora-40/man5/uuencode.5 create mode 100644 upstream/fedora-40/man5/vconsole.conf.5 create mode 100644 upstream/fedora-40/man5/veritytab.5 create mode 100644 upstream/fedora-40/man5/whois.conf.5 create mode 100644 upstream/fedora-40/man5/xfs.5 (limited to 'upstream/fedora-40/man5') diff --git a/upstream/fedora-40/man5/BUILDINFO.5 b/upstream/fedora-40/man5/BUILDINFO.5 new file mode 100644 index 00000000..13f1ccde --- /dev/null +++ b/upstream/fedora-40/man5/BUILDINFO.5 @@ -0,0 +1,238 @@ +'\" t +.\" Title: buildinfo +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2024-01-25 +.\" Manual: Pacman Manual +.\" Source: Pacman 6.0.2 +.\" Language: English +.\" +.TH "BUILDINFO" "5" "2024\-01\-25" "Pacman 6\&.0\&.2" "Pacman Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +BUILDINFO \- Makepkg package build information file +.SH "SYNOPSIS" +.sp +This manual page describes the format of a BUILDINFO file found in the root of a package created by makepkg\&. The file contains a description of the package\(cqs build environment\&. The information is formatted in key\-value pairs separated by a \fI=\fR, one value per line\&. Arrays are represented multiple keys with the same value\&. +.SH "DESCRIPTION" +.sp +This is a description of the contents of version \fI1\fR of the BUILDINFO file format\&. +.PP +\fBformat\fR +.RS 4 +Denotes the file format version, represented by a plain positive integer\&. +.RE +.PP +\fBpkgname\fR +.RS 4 +The name of the package\&. +.RE +.PP +\fBpkgbase\fR +.RS 4 +The base name of a package, usually the same as the pkgname except for split packages\&. +.RE +.PP +\fBpkgver\fR +.RS 4 +The version of the package including pkgrel and epoch\&. +.RE +.PP +\fBpkgarch\fR +.RS 4 +The architecture of the package\&. +.RE +.PP +\fBpkgbuild_sha256sum\fR +.RS 4 +The sha256sum in hex format of the PKGBUILD used to build the package\&. +.RE +.PP +\fBpackager\fR +.RS 4 +The details of the packager that built the package\&. +.RE +.PP +\fBbuilddate\fR +.RS 4 +The build date of the package in epoch\&. +.RE +.PP +\fBbuilddir\fR +.RS 4 +The directory where the package was built\&. +.RE +.PP +\fBstartdir\fR +.RS 4 +The directory from which makepkg was executed\&. +.RE +.PP +\fBbuildenv (array)\fR +.RS 4 +The build environment specified in makepkg\&.conf\&. +.RE +.PP +\fBoptions (array)\fR +.RS 4 +The options set specified when building the package\&. +.RE +.PP +\fBinstalled (array)\fR +.RS 4 +The installed packages at build time including the version information of the package\&. Formatted as "$pkgname\-$pkgver\-$pkgrel\-$pkgarch"\&. +.RE +.SH "SEE ALSO" +.sp +\fBmakepkg\fR(8), \fBpacman\fR(8), \fBmakepkg.conf\fR(5) +.sp +See the pacman website at https://archlinux\&.org/pacman/ for current information on pacman and its related tools\&. +.SH "BUGS" +.sp +Bugs? You must be kidding; there are no bugs in this software\&. But if we happen to be wrong, submit a bug report with as much detail as possible at the Arch Linux Bug Tracker in the Pacman section\&. +.SH "AUTHORS" +.sp +Current maintainers: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Allan McRae +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Andrew Gregory +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Eli Schwartz +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Morgan Adamiec +.RE +.sp +Past major contributors: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Judd Vinet +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aurelien Foret +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aaron Griffin +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dan McGee +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Xavier Chantry +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Nagy Gabor +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dave Reisner +.RE +.sp +For additional contributors, use git shortlog \-s on the pacman\&.git repository\&. diff --git a/upstream/fedora-40/man5/PKGBUILD.5 b/upstream/fedora-40/man5/PKGBUILD.5 new file mode 100644 index 00000000..c320a1e5 --- /dev/null +++ b/upstream/fedora-40/man5/PKGBUILD.5 @@ -0,0 +1,795 @@ +'\" t +.\" Title: pkgbuild +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2024-01-25 +.\" Manual: Pacman Manual +.\" Source: Pacman 6.0.2 +.\" Language: English +.\" +.TH "PKGBUILD" "5" "2024\-01\-25" "Pacman 6\&.0\&.2" "Pacman Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +PKGBUILD \- Arch Linux package build description file +.SH "SYNOPSIS" +.sp +PKGBUILD +.SH "DESCRIPTION" +.sp +This manual page describes general rules about PKGBUILDs\&. Once a PKGBUILD is written, the actual package is built using makepkg and installed with pacman\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +An example PKGBUILD, useful for reference, is located in \fI/usr/share/pacman\fR along with other example files such as an install script\&. You can copy the provided PKGBUILD\&.proto file to a new package build directory and make customizations to suit your needs\&. +.sp .5v +.RE +.SH "OPTIONS AND DIRECTIVES" +.sp +The following is a list of standard options and directives available for use in a PKGBUILD\&. These are all understood and interpreted by makepkg, and most of them will be directly transferred to the built package\&. The mandatory fields for a minimally functional PKGBUILD are \fBpkgname\fR, \fBpkgver\fR, \fBpkgrel\fR and \fBarch\fR\&. +.sp +If you need to create any custom variables for use in your build process, it is recommended to prefix their name with an \fI_\fR (underscore)\&. This will prevent any possible name clashes with internal makepkg variables\&. For example, to store the base kernel version in a variable, use something similar to $_basekernver\&. +.PP +\fBpkgname (array)\fR +.RS 4 +Either the name of the package or an array of names for split packages\&. Valid characters for members of this array are alphanumerics, and any of the following characters: \(lq@ \&. _ + \-\(rq\&. Additionally, names are not allowed to start with hyphens or dots\&. +.RE +.PP +\fBpkgver\fR +.RS 4 +The version of the software as released from the author (e\&.g\&., +\fI2\&.7\&.1\fR)\&. The variable is not allowed to contain colons, forward slashes, hyphens or whitespace\&. +.sp +The +pkgver +variable can be automatically updated by providing a +pkgver() +function in the PKGBUILD that outputs the new package version\&. This is run after downloading and extracting the sources and running the +prepare() +function (if present), so it can use those files in determining the new +pkgver\&. This is most useful when used with sources from version control systems (see below)\&. +.RE +.PP +\fBpkgrel\fR +.RS 4 +This is the release number specific to the distribution\&. This allows package maintainers to make updates to the package\(cqs configure flags, for example\&. This is typically set to +\fI1\fR +for each new upstream software release and incremented for intermediate PKGBUILD updates\&. The variable is a positive integer, with an optional subrelease level specified by adding another positive integer separated by a period (i\&.e\&. in the form x\&.y)\&. +.RE +.PP +\fBepoch\fR +.RS 4 +Used to force the package to be seen as newer than any previous versions with a lower epoch, even if the version number would normally not trigger such an upgrade\&. This value is required to be a positive integer; the default value if left unspecified is +\fI0\fR\&. This is useful when the version numbering scheme of a package changes (or is alphanumeric), breaking normal version comparison logic\&. See +\fBpacman\fR(8) +for more information on version comparisons\&. +.RE +.PP +\fBpkgdesc\fR +.RS 4 +This should be a brief description of the package and its functionality\&. Try to keep the description to one line of text and to not use the package\(cqs name\&. +.RE +.PP +\fBurl\fR +.RS 4 +This field contains a URL that is associated with the software being packaged\&. This is typically the project\(cqs web site\&. +.RE +.PP +\fBlicense (array)\fR +.RS 4 +This field specifies the license(s) that apply to the package\&. Commonly used licenses can be found in +\fI/usr/share/licenses/common\fR\&. If you see the package\(cqs license there, simply reference it in the license field (e\&.g\&., +license=(\*(AqGPL\*(Aq))\&. If the package provides a license not available in +\fI/usr/share/licenses/common\fR, then you should include it in the package itself and set +license=(\*(Aqcustom\*(Aq) +or +license=(\*(Aqcustom:LicenseName\*(Aq)\&. The license should be placed in +\fI$pkgdir/usr/share/licenses/$pkgname/\fR +when building the package\&. If multiple licenses are applicable, list all of them: +license=(\*(AqGPL\*(Aq \*(AqFDL\*(Aq)\&. +.RE +.PP +\fBinstall\fR +.RS 4 +Specifies a special install script that is to be included in the package\&. This file should reside in the same directory as the PKGBUILD and will be copied into the package by makepkg\&. It does not need to be included in the source array (e\&.g\&., +install=$pkgname\&.install)\&. +.RE +.PP +\fBchangelog\fR +.RS 4 +Specifies a changelog file that is to be included in the package\&. The changelog file should end in a single newline\&. This file should reside in the same directory as the PKGBUILD and will be copied into the package by makepkg\&. It does not need to be included in the source array (e\&.g\&., +changelog=$pkgname\&.changelog)\&. +.RE +.PP +\fBsource (array)\fR +.RS 4 +An array of source files required to build the package\&. Source files must either reside in the same directory as the PKGBUILD, or be a fully\-qualified URL that makepkg can use to download the file\&. To simplify the maintenance of PKGBUILDs, use the +$pkgname +and +$pkgver +variables when specifying the download location, if possible\&. Compressed files will be extracted automatically unless found in the noextract array described below\&. +.sp +Additional architecture\-specific sources can be added by appending an underscore and the architecture name e\&.g\&., +\fIsource_x86_64=()\fR\&. There must be a corresponding integrity array with checksums, e\&.g\&. +\fIcksums_x86_64=()\fR\&. +.sp +It is also possible to change the name of the downloaded file, which is helpful with weird URLs and for handling multiple source files with the same name\&. The syntax is: +source=(\*(Aqfilename::url\*(Aq)\&. +.sp +makepkg also supports building developmental versions of packages using sources downloaded from version control systems (VCS)\&. For more information, see +Using VCS Sources +below\&. +.sp +Files in the source array with extensions +\&.sig, +\&.sign +or, +\&.asc +are recognized by makepkg as PGP signatures and will be automatically used to verify the integrity of the corresponding source file\&. +.RE +.PP +\fBvalidpgpkeys (array)\fR +.RS 4 +An array of PGP fingerprints\&. If this array is non\-empty, makepkg will only accept signatures from the keys listed here and will ignore the trust values from the keyring\&. If the source file was signed with a subkey, makepkg will still use the primary key for comparison\&. +.sp +Only full fingerprints are accepted\&. They must be uppercase and must not contain whitespace characters\&. +.RE +.PP +\fBnoextract (array)\fR +.RS 4 +An array of file names corresponding to those from the source array\&. Files listed here will not be extracted with the rest of the source files\&. This is useful for packages that use compressed data directly\&. +.RE +.PP +\fBcksums (array)\fR +.RS 4 +This array contains CRC checksums for every source file specified in the source array (in the same order)\&. makepkg will use this to verify source file integrity during subsequent builds\&. If +\fISKIP\fR +is put in the array in place of a normal hash, the integrity check for that source file will be skipped\&. To easily generate cksums, run \(lqmakepkg \-g >> PKGBUILD\(rq\&. If desired, move the cksums line to an appropriate location\&. Note that checksums generated by "makepkg \-g" should be verified using checksum values provided by the software developer\&. +.RE +.PP +\fBmd5sums, sha1sums, sha224sums, sha256sums, sha384sums, sha512sums, b2sums (arrays)\fR +.RS 4 +Alternative integrity checks that makepkg supports; these all behave similar to the cksums option described above\&. To enable use and generation of these checksums, be sure to set up the +INTEGRITY_CHECK +option in +\fBmakepkg.conf\fR(5)\&. +.RE +.PP +\fBgroups (array)\fR +.RS 4 +An array of symbolic names that represent groups of packages, allowing you to install multiple packages by requesting a single target\&. For example, one could install all KDE packages by installing the +\fIkde\fR +group\&. +.RE +.PP +\fBarch (array)\fR +.RS 4 +Defines on which architectures the given package is available (e\&.g\&., +arch=(\*(Aqi686\*(Aq \*(Aqx86_64\*(Aq))\&. Packages that contain no architecture specific files should use +arch=(\*(Aqany\*(Aq)\&. Valid characters for members of this array are alphanumerics and \(lq_\(rq\&. +.RE +.PP +\fBbackup (array)\fR +.RS 4 +An array of file names, without preceding slashes, that should be backed up if the package is removed or upgraded\&. This is commonly used for packages placing configuration files in +\fI/etc\fR\&. See +"Handling Config Files" +in +\fBpacman\fR(8) +for more information\&. +.RE +.PP +\fBdepends (array)\fR +.RS 4 +An array of packages this package depends on to run\&. Entries in this list should be surrounded with single quotes and contain at least the package name\&. Entries can also include a version requirement of the form +\fIname<>version\fR, where +<> +is one of five comparisons: +>= +(greater than or equal to), +<= +(less than or equal to), += +(equal to), +> +(greater than), or +< +(less than)\&. +.sp +If the dependency name appears to be a library (ends with \&.so), makepkg will try to find a binary that depends on the library in the built package and append the version needed by the binary\&. Appending the version yourself disables automatic detection\&. +.sp +Additional architecture\-specific depends can be added by appending an underscore and the architecture name e\&.g\&., +\fIdepends_x86_64=()\fR\&. +.RE +.PP +\fBmakedepends (array)\fR +.RS 4 +An array of packages this package depends on to build but are not needed at runtime\&. Packages in this list follow the same format as depends\&. +.sp +Additional architecture\-specific makedepends can be added by appending an underscore and the architecture name e\&.g\&., +\fImakedepends_x86_64=()\fR\&. +.RE +.PP +\fBcheckdepends (array)\fR +.RS 4 +An array of packages this package depends on to run its test suite but are not needed at runtime\&. Packages in this list follow the same format as depends\&. These dependencies are only considered when the check() function is present and is to be run by makepkg\&. +.sp +Additional architecture\-specific checkdepends can be added by appending an underscore and the architecture name e\&.g\&., +\fIcheckdepends_x86_64=()\fR\&. +.RE +.PP +\fBoptdepends (array)\fR +.RS 4 +An array of packages (and accompanying reasons) that are not essential for base functionality, but may be necessary to make full use of the contents of this package\&. optdepends are currently for informational purposes only and are not utilized by pacman during dependency resolution\&. Packages in this list follow the same format as depends, with an optional description appended\&. The format for specifying optdepends descriptions is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +optdepends=(\*(Aqpython: for library bindings\*(Aq) +.fi +.if n \{\ +.RE +.\} +.sp +Additional architecture\-specific optdepends can be added by appending an underscore and the architecture name e\&.g\&., +\fIoptdepends_x86_64=()\fR\&. +.RE +.PP +\fBconflicts (array)\fR +.RS 4 +An array of packages that will conflict with this package (i\&.e\&. they cannot both be installed at the same time)\&. This directive follows the same format as depends\&. Versioned conflicts are supported using the operators as described in +depends\&. +.sp +Additional architecture\-specific conflicts can be added by appending an underscore and the architecture name e\&.g\&., +\fIconflicts_x86_64=()\fR\&. +.RE +.PP +\fBprovides (array)\fR +.RS 4 +An array of \(lqvirtual provisions\(rq this package provides\&. This allows a package to provide dependencies other than its own package name\&. For example, the dcron package can provide +\fIcron\fR, which allows packages to depend on +\fIcron\fR +rather than +\fIdcron OR fcron\fR\&. +.sp +Versioned provisions are also possible, in the +\fIname=version\fR +format\&. For example, dcron can provide +\fIcron=2\&.0\fR +to satisfy the +\fIcron>=2\&.0\fR +dependency of other packages\&. Provisions involving the +> +and +< +operators are invalid as only specific versions of a package may be provided\&. +.sp +If the provision name appears to be a library (ends with \&.so), makepkg will try to find the library in the built package and append the correct version\&. Appending the version yourself disables automatic detection\&. +.sp +Additional architecture\-specific provides can be added by appending an underscore and the architecture name e\&.g\&., +\fIprovides_x86_64=()\fR\&. +.RE +.PP +\fBreplaces (array)\fR +.RS 4 +An array of packages this package should replace\&. This can be used to handle renamed/combined packages\&. For example, if the +\fIj2re\fR +package is renamed to +\fIjre\fR, this directive allows future upgrades to continue as expected even though the package has moved\&. Versioned replaces are supported using the operators as described in +depends\&. +.sp +Sysupgrade is currently the only pacman operation that utilizes this field\&. A normal sync or upgrade will not use its value\&. +.sp +Additional architecture\-specific replaces can be added by appending an underscore and the architecture name e\&.g\&., +\fIreplaces_x86_64=()\fR\&. +.RE +.PP +\fBoptions (array)\fR +.RS 4 +This array allows you to override some of makepkg\(cqs default behavior when building packages\&. To set an option, just include the option name in the options array\&. To reverse the default behavior, place an \(lq!\(rq at the front of the option\&. Only specify the options you specifically want to override, the rest will be taken from +\fBmakepkg.conf\fR(5)\&. +\fBNOTE:\fR +\fIforce\fR +is a now\-removed option in favor of the top level +\fIepoch\fR +variable\&. +.PP +\fBstrip\fR +.RS 4 +Strip symbols from binaries and libraries\&. If you frequently use a debugger on programs or libraries, it may be helpful to disable this option\&. +.RE +.PP +\fBdocs\fR +.RS 4 +Save doc directories\&. If you wish to delete doc directories, specify +!docs +in the array\&. +.RE +.PP +\fBlibtool\fR +.RS 4 +Leave libtool (\&.la) files in packages\&. Specify +!libtool +to remove them\&. +.RE +.PP +\fBstaticlibs\fR +.RS 4 +Leave static library (\&.a) files in packages\&. Specify +!staticlibs +to remove them (if they have a shared counterpart)\&. +.RE +.PP +\fBemptydirs\fR +.RS 4 +Leave empty directories in packages\&. +.RE +.PP +\fBzipman\fR +.RS 4 +Compress man and info pages with gzip\&. +.RE +.PP +\fBccache\fR +.RS 4 +Allow the use of ccache during +build()\&. More useful in its negative form +!ccache +with select packages that have problems building with ccache\&. +.RE +.PP +\fBdistcc\fR +.RS 4 +Allow the use of distcc during +build()\&. More useful in its negative form +!distcc +with select packages that have problems building with distcc\&. +.RE +.PP +\fBbuildflags\fR +.RS 4 +Allow the use of user\-specific buildflags (CPPFLAGS, CFLAGS, CXXFLAGS, LDFLAGS) during +build() +as specified in +\fBmakepkg.conf\fR(5)\&. More useful in its negative form +!buildflags +with select packages that have problems building with custom buildflags\&. +.RE +.PP +\fBmakeflags\fR +.RS 4 +Allow the use of user\-specific makeflags during +build() +as specified in +\fBmakepkg.conf\fR(5)\&. More useful in its negative form +!makeflags +with select packages that have problems building with custom makeflags such as +\-j2 +(or higher)\&. +.RE +.PP +\fBdebug\fR +.RS 4 +Add the user\-specified debug flags (DEBUG_CFLAGS, DEBUG_CXXFLAGS) to their counterpart buildflags as specified in +\fBmakepkg.conf\fR(5)\&. When used in combination with the \(oqstrip\(cq option, a separate package containing the debug symbols is created\&. +.RE +.PP +\fBlto\fR +.RS 4 +Enable building packages using link time optimization\&. Adds +\fI\-flto\fR +to both CFLAGS and CXXFLAGS\&. +.RE +.RE +.SH "PACKAGING FUNCTIONS" +.sp +In addition to the above directives, PKGBUILDs require a set of functions that provide instructions to build and install the package\&. As a minimum, the PKGBUILD must contain a package() function which installs all the package\(cqs files into the packaging directory, with optional prepare(), build(), and check() functions being used to create those files from source\&. +.sp +This is directly sourced and executed by makepkg, so anything that Bash or the system has available is available for use here\&. Be sure any exotic commands used are covered by the makedepends array\&. +.sp +If you create any variables of your own in any of these functions, it is recommended to use the Bash local keyword to scope the variable to inside the function\&. +.PP +\fBpackage() Function\fR +.RS 4 +The +package() +function is used to install files into the directory that will become the root directory of the built package and is run after all the optional functions listed below\&. The packaging stage is run using fakeroot to ensure correct file permissions in the resulting package\&. All other functions will be run as the user calling makepkg\&. +.RE +.PP +\fBprepare() Function\fR +.RS 4 +An optional +prepare() +function can be specified in which operations to prepare the sources for building, such as patching, are performed\&. This function is run after the source extraction and before the +build() +function\&. The +prepare() +function is skipped when source extraction is skipped\&. +.RE +.PP +\fBbuild() Function\fR +.RS 4 +The optional +build() +function is used to compile and/or adjust the source files in preparation to be installed by the +package() +function\&. +.RE +.PP +\fBcheck() Function\fR +.RS 4 +An optional +check() +function can be specified in which a package\(cqs test\-suite may be run\&. This function is run between the +build() +and +package() +functions\&. Be sure any exotic commands used are covered by the +checkdepends +array\&. +.RE +.sp +All of the above variables such as $pkgname and $pkgver are available for use in the packaging functions\&. In addition, makepkg defines the following variables: +.PP +\fBsrcdir\fR +.RS 4 +This contains the directory where makepkg extracts, or copies, all source files\&. +.sp +All of the packaging functions defined above are run starting inside +$srcdir +.RE +.PP +\fBpkgdir\fR +.RS 4 +This contains the directory where makepkg bundles the installed package\&. This directory will become the root directory of your built package\&. This variable should only be used in the +package() +function\&. +.RE +.PP +\fBstartdir\fR +.RS 4 +This contains the absolute path to the directory where the PKGBUILD is located, which is usually the output of +$(pwd) +when makepkg is started\&. Use of this variable is deprecated and strongly discouraged\&. +.RE +.SH "PACKAGE SPLITTING" +.sp +makepkg supports building multiple packages from a single PKGBUILD\&. This is achieved by assigning an array of package names to the pkgname directive\&. Each split package uses a corresponding packaging function with name package_foo(), where foo is the name of the split package\&. +.sp +All options and directives for the split packages default to the global values given in the PKGBUILD\&. Nevertheless, the following ones can be overridden within each split package\(cqs packaging function: pkgdesc, arch, url, license, groups, depends, optdepends, provides, conflicts, replaces, backup, options, install, and changelog\&. +.sp +Note that makepkg does not consider split package depends when checking if dependencies are installed before package building and with \-\-syncdeps\&. All packages required to make the package are required to be specified in the global depends and makedepends arrays\&. +.sp +An optional global directive is available when building a split package: +.PP +\fBpkgbase\fR +.RS 4 +The name used to refer to the group of packages in the output of makepkg and in the naming of source\-only tarballs\&. If not specified, the first element in the +pkgname +array is used\&. Valid characters for this variable are alphanumerics, and any of the following characters: \(lq@ \&. _ + \-\(rq\&. Additionally, the variable is not allowed to start with hyphens or dots\&. +.RE +.SH "INSTALL/UPGRADE/REMOVE SCRIPTING" +.sp +Pacman has the ability to store and execute a package\-specific script when it installs, removes, or upgrades a package\&. This allows a package to configure itself after installation and perform an opposite action upon removal\&. +.sp +The exact time the script is run varies with each operation, and should be self\-explanatory\&. Note that during an upgrade operation, none of the install or remove functions will be called\&. +.sp +Scripts are passed either one or two \(lqfull version strings\(rq, where a full version string is either \fIpkgver\-pkgrel\fR or \fIepoch:pkgver\-pkgrel\fR, if epoch is non\-zero\&. +.PP +\fBpre_install\fR +.RS 4 +Run right before files are extracted\&. One argument is passed: new package full version string\&. +.RE +.PP +\fBpost_install\fR +.RS 4 +Run right after files are extracted\&. One argument is passed: new package full version string\&. +.RE +.PP +\fBpre_upgrade\fR +.RS 4 +Run right before files are extracted\&. Two arguments are passed in this order: new package full version string, old package full version string\&. +.RE +.PP +\fBpost_upgrade\fR +.RS 4 +Run after files are extracted\&. Two arguments are passed in this order: new package full version string, old package full version string\&. +.RE +.PP +\fBpre_remove\fR +.RS 4 +Run right before files are removed\&. One argument is passed: old package full version string\&. +.RE +.PP +\fBpost_remove\fR +.RS 4 +Run right after files are removed\&. One argument is passed: old package full version string\&. +.RE +.sp +To use this feature, create a file such as \fIpkgname\&.install\fR and put it in the same directory as the PKGBUILD script\&. Then use the install directive: +.sp +.if n \{\ +.RS 4 +.\} +.nf +install=pkgname\&.install +.fi +.if n \{\ +.RE +.\} +.sp +The install script does not need to be specified in the source array\&. A template install file is available in \fI/usr/share/pacman\fR as \fIproto\&.install\fR for reference with all of the available functions defined\&. +.SH "USING VCS SOURCES" +.sp +Building a developmental version of a package using sources from a version control system (VCS) is enabled by specifying the source in the form: +.sp +.if n \{\ +.RS 4 +.\} +.nf +source=(\*(Aqdirectory::url#fragment?query\*(Aq) +.fi +.if n \{\ +.RE +.\} +.sp +Currently makepkg supports the Bazaar, Git, Subversion, Fossil and Mercurial version control systems\&. For other version control systems, manual cloning of upstream repositories must be done in the prepare() function\&. +.sp +The source URL is divided into four components: +.PP +\fBdirectory\fR +.RS 4 +(optional) Specifies an alternate directory name for makepkg to download the VCS source into\&. +.RE +.PP +\fBurl\fR +.RS 4 +The URL to the VCS repository\&. This must include the VCS in the URL protocol for makepkg to recognize this as a VCS source\&. If the protocol does not include the VCS name, it can be added by prefixing the URL with +vcs+\&. For example, using a Git repository over HTTPS would have a source URL in the form: +git+https://\&.\&.\&.\&. +.RE +.PP +\fBfragment\fR +.RS 4 +(optional) Allows specifying a revision number or branch for makepkg to checkout from the VCS\&. A fragment has the form +type=value, for example to checkout a given revision the source line would be +source=(url#revision=123)\&. The available types depends on the VCS being used: +.PP +\fBbzr\fR +.RS 4 +revision (see +\*(Aqbzr help revisionspec\*(Aq +for details) +.RE +.PP +\fBfossil\fR +.RS 4 +branch, commit, tag +.RE +.PP +\fBgit\fR +.RS 4 +branch, commit, tag +.RE +.PP +\fBhg\fR +.RS 4 +branch, revision, tag +.RE +.PP +\fBsvn\fR +.RS 4 +revision +.RE +.RE +.PP +\fBquery\fR +.RS 4 +(optional) Allows specifying whether a VCS checkout should be checked for PGP\-signed revisions\&. The source line should have the format +source=(url#fragment?signed) +or +source=(url?signed#fragment)\&. Currently only supported by Git\&. +.RE +.SH "EXAMPLE" +.sp +The following is an example PKGBUILD for the \fIpatch\fR package\&. For more examples, look through the build files of your distribution\(cqs packages\&. For those using Arch Linux, consult the Arch Build System (ABS) tree\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Maintainer: Joe User + +pkgname=patch +pkgver=2\&.7\&.1 +pkgrel=1 +pkgdesc="A utility to apply patch files to original sources" +arch=(\*(Aqi686\*(Aq \*(Aqx86_64\*(Aq) +url="https://www\&.gnu\&.org/software/patch/patch\&.html" +license=(\*(AqGPL\*(Aq) +groups=(\*(Aqbase\-devel\*(Aq) +depends=(\*(Aqglibc\*(Aq) +makedepends=(\*(Aqed\*(Aq) +optdepends=(\*(Aqed: for "patch \-e" functionality\*(Aq) +source=("ftp://ftp\&.gnu\&.org/gnu/$pkgname/$pkgname\-$pkgver\&.tar\&.xz"{,\&.sig}) +md5sums=(\*(Aqe9ae5393426d3ad783a300a338c09b72\*(Aq + \*(AqSKIP\*(Aq) + +build() { + cd "$srcdir/$pkgname\-$pkgver" + \&./configure \-\-prefix=/usr + make +} + +package() { + cd "$srcdir/$pkgname\-$pkgver" + make DESTDIR="$pkgdir/" install +} +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.sp +\fBmakepkg\fR(8), \fBpacman\fR(8), \fBmakepkg.conf\fR(5) +.sp +See the pacman website at https://archlinux\&.org/pacman/ for current information on pacman and its related tools\&. +.SH "BUGS" +.sp +Bugs? You must be kidding; there are no bugs in this software\&. But if we happen to be wrong, submit a bug report with as much detail as possible at the Arch Linux Bug Tracker in the Pacman section\&. +.SH "AUTHORS" +.sp +Current maintainers: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Allan McRae +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Andrew Gregory +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Eli Schwartz +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Morgan Adamiec +.RE +.sp +Past major contributors: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Judd Vinet +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aurelien Foret +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aaron Griffin +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dan McGee +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Xavier Chantry +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Nagy Gabor +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dave Reisner +.RE +.sp +For additional contributors, use git shortlog \-s on the pacman\&.git repository\&. diff --git a/upstream/fedora-40/man5/acct.5 b/upstream/fedora-40/man5/acct.5 new file mode 100644 index 00000000..18d458e6 --- /dev/null +++ b/upstream/fedora-40/man5/acct.5 @@ -0,0 +1,161 @@ +.\" Copyright (C) 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH acct 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +acct \- process accounting file +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +If the kernel is built with the process accounting option enabled +.RB ( CONFIG_BSD_PROCESS_ACCT ), +then calling +.BR acct (2) +starts process accounting, for example: +.P +.in +4n +acct("/var/log/pacct"); +.in +.P +When process accounting is enabled, the kernel writes a record +to the accounting file as each process on the system terminates. +This record contains information about the terminated process, +and is defined in +.I +as follows: +.P +.in +4n +.EX +#define ACCT_COMM 16 +\& +typedef u_int16_t comp_t; +\& +struct acct { + char ac_flag; /* Accounting flags */ + u_int16_t ac_uid; /* Accounting user ID */ + u_int16_t ac_gid; /* Accounting group ID */ + u_int16_t ac_tty; /* Controlling terminal */ + u_int32_t ac_btime; /* Process creation time + (seconds since the Epoch) */ + comp_t ac_utime; /* User CPU time */ + comp_t ac_stime; /* System CPU time */ + comp_t ac_etime; /* Elapsed time */ + comp_t ac_mem; /* Average memory usage (kB) */ + comp_t ac_io; /* Characters transferred (unused) */ + comp_t ac_rw; /* Blocks read or written (unused) */ + comp_t ac_minflt; /* Minor page faults */ + comp_t ac_majflt; /* Major page faults */ + comp_t ac_swaps; /* Number of swaps (unused) */ + u_int32_t ac_exitcode; /* Process termination status + (see wait(2)) */ + char ac_comm[ACCT_COMM+1]; + /* Command name (basename of last + executed command; null\-terminated) */ + char ac_pad[\fIX\fP]; /* padding bytes */ +}; +\& +enum { /* Bits that may be set in ac_flag field */ + AFORK = 0x01, /* Has executed fork, but no exec */ + ASU = 0x02, /* Used superuser privileges */ + ACORE = 0x08, /* Dumped core */ + AXSIG = 0x10 /* Killed by a signal */ +}; +.EE +.in +.P +The +.I comp_t +data type is a floating-point value consisting of a 3-bit, base-8 exponent, +and a 13-bit mantissa. +A value, +.IR c , +of this type can be converted to a (long) integer as follows: +.P +.nf + v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3); +.fi +.P +The +.IR ac_utime , +.IR ac_stime , +and +.I ac_etime +fields measure time in "clock ticks"; divide these values by +.I sysconf(_SC_CLK_TCK) +to convert them to seconds. +.SS Version 3 accounting file format +Since Linux 2.6.8, +an optional alternative version of the accounting file can be produced +if the +.B CONFIG_BSD_PROCESS_ACCT_V3 +option is set when building the kernel. +With this option is set, +the records written to the accounting file contain additional fields, +and the width of +.I c_uid +and +.I ac_gid +fields is widened from 16 to 32 bits +(in line with the increased size of UID and GIDs in Linux 2.4 and later). +The records are defined as follows: +.P +.in +4n +.EX +struct acct_v3 { + char ac_flag; /* Flags */ + char ac_version; /* Always set to ACCT_VERSION (3) */ + u_int16_t ac_tty; /* Controlling terminal */ + u_int32_t ac_exitcode; /* Process termination status */ + u_int32_t ac_uid; /* Real user ID */ + u_int32_t ac_gid; /* Real group ID */ + u_int32_t ac_pid; /* Process ID */ + u_int32_t ac_ppid; /* Parent process ID */ + u_int32_t ac_btime; /* Process creation time */ + float ac_etime; /* Elapsed time */ + comp_t ac_utime; /* User CPU time */ + comp_t ac_stime; /* System time */ + comp_t ac_mem; /* Average memory usage (kB) */ + comp_t ac_io; /* Characters transferred (unused) */ + comp_t ac_rw; /* Blocks read or written + (unused) */ + comp_t ac_minflt; /* Minor page faults */ + comp_t ac_majflt; /* Major page faults */ + comp_t ac_swaps; /* Number of swaps (unused) */ + char ac_comm[ACCT_COMM]; /* Command name */ +}; +.EE +.in +.SH VERSIONS +Although it is present on most systems, it is not standardized, +and the details vary somewhat between systems. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.6. +.P +Process accounting originated on BSD. +.SH NOTES +Records in the accounting file are ordered by termination time of +the process. +.P +Up to and including Linux 2.6.9, +a separate accounting record is written for each thread created using +the NPTL threading library; +since Linux 2.6.10, +a single accounting record is written for the entire process +on termination of the last thread in the process. +.P +The +.I /proc/sys/kernel/acct +file, described in +.BR proc (5), +defines settings that control the behavior of process accounting +when disk space runs low. +.SH SEE ALSO +.BR lastcomm (1), +.BR acct (2), +.BR accton (8), +.BR sa (8) diff --git a/upstream/fedora-40/man5/aliases.sendmail.5 b/upstream/fedora-40/man5/aliases.sendmail.5 new file mode 100644 index 00000000..52e5124c --- /dev/null +++ b/upstream/fedora-40/man5/aliases.sendmail.5 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1998-2000 Proofpoint, Inc. and its suppliers. +.\" All rights reserved. +.\" Copyright (c) 1983, 1997 Eric P. Allman. All rights reserved. +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" By using this file, you agree to the terms and conditions set +.\" forth in the LICENSE file which can be found at the top level of +.\" the sendmail distribution. +.\" +.\" +.\" $Id: aliases.5,v 8.20 2013-11-22 20:51:55 ca Exp $ +.\" +.TH ALIASES 5 "$Date: 2013-11-22 20:51:55 $" +.SH NAME +aliases +\- aliases file for sendmail +.SH SYNOPSIS +.B aliases +.SH DESCRIPTION +This file describes user +ID +aliases used by +sendmail. +The file resides in +/etc +and +is formatted as a series of lines of the form +.IP +name: addr_1, addr_2, addr_3, . . . +.PP +The +.I name +is the name to alias, and the +.I addr_n +are the aliases for that name. +.I addr_n +can be another alias, a local username, a local filename, +a command, +an include file, +or an external address. +.TP +.B Local Username +username +.IP +The username must be available via getpwnam(3). +.TP +.B Local Filename +/path/name +.IP +Messages are appended to the file specified by the full pathname +(starting with a slash (/)) +.TP +.B Command +|command +.IP +A command starts with a pipe symbol (|), +it receives messages via standard input. +.TP +.B Include File +:include: /path/name +.IP +The aliases in pathname are added to the aliases for +.I name. +.TP +.B E-Mail Address +user@domain +.IP +An e-mail address in RFC 822 format. +.PP +Lines beginning with white space are continuation lines. +Another way to continue lines is by placing a backslash +directly before a newline. +Lines beginning with +# +are comments. +.PP +Aliasing occurs only on local names. +Loops can not occur, since no message will be sent to any person more than once. +.PP +If an alias is found for +.IR name , +sendmail then checks for an alias for +.IR owner-name . +If it is found and the result of the lookup expands to a single +address, the envelope sender address of the message is rewritten to +that address. +If it is found and the result expands to more than one address, the +envelope sender address is changed to +.IR owner-name . +.PP +After aliasing has been done, local and valid recipients who have a +``.forward'' +file in their home directory have messages forwarded to the +list of users defined in that file. +.PP +This is only the raw data file; the actual aliasing information is +placed into a binary format in the file +/etc/aliases.db +using the program +newaliases(1). +A +newaliases +command should be executed each time the aliases file is changed for the +change to take effect. +.SH SEE ALSO +newaliases(1), +dbm(3), +dbopen(3), +db_open(3), +sendmail(8) +.PP +.I +SENDMAIL Installation and Operation Guide. +.PP +.I +SENDMAIL An Internetwork Mail Router. +.SH BUGS +If you have compiled +sendmail +with DBM support instead of NEWDB, +you may have encountered problems in +dbm(3) +restricting a single alias to about 1000 bytes of information. +You can get longer aliases by ``chaining''; that is, make the last name in +the alias be a dummy name which is a continuation alias. +.SH HISTORY +The +.B aliases +file format appeared in +4.0BSD. diff --git a/upstream/fedora-40/man5/alpm-hooks.5 b/upstream/fedora-40/man5/alpm-hooks.5 new file mode 100644 index 00000000..f82c1e8a --- /dev/null +++ b/upstream/fedora-40/man5/alpm-hooks.5 @@ -0,0 +1,272 @@ +'\" t +.\" Title: alpm-hooks +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2024-01-25 +.\" Manual: Pacman Manual +.\" Source: Pacman 6.0.2 +.\" Language: English +.\" +.TH "ALPM\-HOOKS" "5" "2024\-01\-25" "Pacman 6\&.0\&.2" "Pacman Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +alpm-hooks \- alpm hook file format +.SH "SYNOPSIS" +.sp +.nf +[Trigger] (Required, Repeatable) +Operation = Install|Upgrade|Remove (Required, Repeatable) +Type = Path|Package (Required) +Target = (Required, Repeatable) + +[Action] (Required) +Description = \&.\&.\&. (Optional) +When = PreTransaction|PostTransaction (Required) +Exec = (Required) +Depends = (Optional) +AbortOnFail (Optional, PreTransaction only) +NeedsTargets (Optional) +.fi +.SH "DESCRIPTION" +.sp +libalpm provides the ability to specify hooks to run before or after transactions based on the packages and/or files being modified\&. Hooks consist of a single \fI[Action]\fR section describing the action to be run and one or more \fI[Trigger]\fR section describing which transactions it should be run for\&. +.sp +Hooks are read from files located in the system hook directory /usr/share/libalpm/hooks, and additional custom directories specified in \fBpacman.conf\fR(5) (the default is /etc/pacman\&.d/hooks)\&. The file names are required to have the suffix "\&.hook"\&. Hooks are run in alphabetical order of their file name, where the ordering ignores the suffix\&. +.SH "TRIGGERS" +.sp +Hooks must contain at least one \fI[Trigger]\fR section that determines which transactions will cause the hook to run\&. If multiple trigger sections are defined the hook will run if the transaction matches \fBany\fR of the triggers\&. +.PP +\fBOperation =\fR Install|Upgrade|Remove +.RS 4 +Select the type of operation to match targets against\&. May be specified multiple times\&. Installations are considered an upgrade if the package or file is already present on the system regardless of whether the new package version is actually greater than the currently installed version\&. For Path triggers, this is true even if the file changes ownership from one package to another\&. Required\&. +.RE +.PP +\fBType =\fR Path|Package +.RS 4 +Select whether targets are matched against transaction packages or files\&. See CAVEATS for special notes regarding Path triggers\&. +\fIFile\fR +is a deprecated alias for +\fIPath\fR +and will be removed in a future release\&. Required\&. +.RE +.PP +\fBTarget =\fR +.RS 4 +The path or package name to match against the active transaction\&. Paths refer to the files in the package archive; the installation root should +\fBnot\fR +be included in the path\&. Shell\-style glob patterns are allowed\&. It is possible to invert matches by prepending a target with an exclamation mark\&. May be specified multiple times\&. Required\&. +.RE +.SH "ACTIONS" +.PP +\fBDescription =\fR \&... +.RS 4 +An optional description that describes the action being taken by the hook for use in front\-end output\&. +.RE +.PP +\fBExec =\fR +.RS 4 +Command to run\&. Command arguments are split on whitespace\&. Values containing whitespace should be enclosed in quotes\&. Required\&. +.RE +.PP +\fBWhen =\fR PreTransaction|PostTransaction +.RS 4 +When to run the hook\&. Required\&. +.RE +.PP +\fBDepends =\fR +.RS 4 +Packages that must be installed for the hook to run\&. May be specified multiple times\&. +.RE +.PP +\fBAbortOnFail\fR +.RS 4 +Causes the transaction to be aborted if the hook exits non\-zero\&. Only applies to PreTransaction hooks\&. +.RE +.PP +\fBNeedsTargets\fR +.RS 4 +Causes the list of matched trigger targets to be passed to the running hook on +\fIstdin\fR\&. +.RE +.SH "OVERRIDING HOOKS" +.sp +Hooks may be overridden by placing a file with the same name in a higher priority hook directory\&. Hooks may be disabled by overriding them with a symlink to \fI/dev/null\fR\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Force disks to sync to reduce the risk of data corruption + +[Trigger] +Operation = Install +Operation = Upgrade +Operation = Remove +Type = Package +Target = * + +[Action] +Depends = coreutils +When = PostTransaction +Exec = /usr/bin/sync +.fi +.if n \{\ +.RE +.\} +.SH "CAVEATS" +.sp +There are situations when path triggers may act in unexpected ways\&. Hooks are triggered using the file list of the installed, upgraded, or removed package\&. When installing or upgrading a file that is extracted with a \fI\&.pacnew\fR extension, the original file name is used in triggering the hook\&. When removing a package, all files owned by that package can trigger a hook whether or not they were actually present on the file system before package removal\&. +.sp +PostTransaction hooks will \fBnot\fR run if the transaction fails to complete for any reason\&. +.sp +See the pacman website at https://archlinux\&.org/pacman/ for current information on pacman and its related tools\&. +.SH "BUGS" +.sp +Bugs? You must be kidding; there are no bugs in this software\&. But if we happen to be wrong, submit a bug report with as much detail as possible at the Arch Linux Bug Tracker in the Pacman section\&. +.SH "AUTHORS" +.sp +Current maintainers: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Allan McRae +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Andrew Gregory +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Eli Schwartz +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Morgan Adamiec +.RE +.sp +Past major contributors: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Judd Vinet +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aurelien Foret +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aaron Griffin +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dan McGee +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Xavier Chantry +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Nagy Gabor +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dave Reisner +.RE +.sp +For additional contributors, use git shortlog \-s on the pacman\&.git repository\&. diff --git a/upstream/fedora-40/man5/anacrontab.5 b/upstream/fedora-40/man5/anacrontab.5 new file mode 100644 index 00000000..f7ca5c00 --- /dev/null +++ b/upstream/fedora-40/man5/anacrontab.5 @@ -0,0 +1,145 @@ +.TH ANACRONTAB 5 2012-11-22 "cronie" "File Formats" +.SH NAME +/etc/anacrontab \- configuration file for Anacron +.SH DESCRIPTION +The +.I /etc/anacrontab +configuration file describes the jobs controlled by +.BR anacron (8). +It can contain three types of lines: job-description lines, environment +assignments, or empty lines. +.PP +Job-description lines can have the following format: +.PP + period in days delay in minutes job-identifier command +.PP +The +.I period in days +variable specifies the frequency of execution of a job in days. This +variable can be represented by an integer or a macro (@daily, @weekly, +@monthly), where @daily denotes the same value as the integer 1, @weekly +the same as 7, and @monthly specifies that the job is run once a month, +independent on the length of the month. +.PP +The +.I delay in minutes +variable specifies the number of minutes anacron waits, if necessary, +before executing a job. This variable is represented by an integer where +0 means no delay. +.PP +The +.I job-identifier +variable specifies a unique name of a job which is used in the log files. +.PP +The +.I command +variable specifies the command to execute. The command can either be a +command such as +.B ls /proc >> /tmp/proc +or a command to execute a custom script. +.PP +Environment assignment lines can have the following format: +.PP + VAR=VALUE +.PP +Any spaces around +.I VAR +are removed. No spaces around +.I VALUE +are allowed (unless you want them to be part of the value). The +specified assignment takes effect from the next line until the end of the +file, or to the next assignment of the same variable. +.PP +The +.I START_HOURS_RANGE +variable defines an interval (in hours) when scheduled jobs can be run. +In case this time interval is missed, for example, due to a power down, +then scheduled jobs are not executed that day. +.PP +The +.I RANDOM_DELAY +variable denotes the maximum number of minutes that will be added to the +delay in minutes variable which is specified for each job. A +.I RANDOM_DELAY +set to 12 would therefore add, randomly, between 0 and 12 minutes to the +delay in minutes for each job in that particular anacrontab. When set to +0, no random delay is added. +.PP +If +.I MAILTO +is defined (and non-empty), mail is sent to the specified address, +otherwise, system user is used. +.PP +If +.I MAILFROM +is defined (and non-empty), it is used as the envelope sender address, +otherwise, system user is used. +.PP +(Note: Both +.I MAILFROM +and +.I MAILTO +variables are expanded, so setting them as in the following example works as expected: MAILFROM=cron-$USER@cron.com ($USER is replaced by the system user) ) +.PP +If +.I NO_MAIL_OUTPUT +is defined (and non-empty), the standard output and error descriptors of job processes are not redirected and e-mailed. +.PP +.PP +Empty lines are either blank lines, line containing white spaces only, or +lines with white spaces followed by a '#' followed by an arbitrary +comment. +.PP +You can continue a line onto the next line by adding a '\\' at the end of it. +.PP +In case you want to disable Anacron, add a line with +.I 0anacron +which is the name of the script running the Anacron into the +.I /etc/cron.hourly/jobs.deny +file. +.SH EXAMPLE +This example shows how to set up an Anacron job similar in functionality to +.I /etc/crontab +which starts all regular jobs +between 6:00 and 8:00 +.I only. +A +.I RANDOM_DELAY +which can be 30 minutes at the most is specified. Jobs will run +serialized in a queue where each job is started only after the previous +one is finished. +.PP +.nf +# environment variables +SHELL=/bin/sh +PATH=/sbin:/bin:/usr/sbin:/usr/bin +MAILTO=root +RANDOM_DELAY=30 +# Anacron jobs will start between 6am and 8am. +START_HOURS_RANGE=6-8 +# delay will be 5 minutes + RANDOM_DELAY for cron.daily +1 5 cron.daily nice run-parts /etc/cron.daily +7 0 cron.weekly nice run-parts /etc/cron.weekly +@monthly 0 cron.monthly nice run-parts /etc/cron.monthly +.fi +.SH "SEE ALSO" +.BR anacron (8), +.BR crontab (1) +.PP +The Anacron +.I README +file. +.SH AUTHOR +.MT itzur@\:actcom.\:co.\:il +Itai Tzur +.ME +.PP +Currently maintained by +.MT pasc@\:(debian.\:org|\:redellipse.\:net) +Pascal Hakim +.ME . +.PP +For Fedora, maintained by +.MT mmaslano@redhat.com +Marcela Mašláňová +.ME . diff --git a/upstream/fedora-40/man5/at.allow.5 b/upstream/fedora-40/man5/at.allow.5 new file mode 100644 index 00000000..ece2f507 --- /dev/null +++ b/upstream/fedora-40/man5/at.allow.5 @@ -0,0 +1,40 @@ +.TH AT.ALLOW 5 "Sep 1997" "" "Linux Programmer's Manual" +.SH NAME +at.allow, at.deny \- determine who can submit jobs via at or batch +.SH DESCRIPTION +The +.I /etc/at.allow +and +.I /etc/at.deny +files determine which user can submit commands for later execution via +.BR at (1) +or +.BR batch (1) . +.PP +The format of the files is a list of usernames, one on each line. Whitespace +is not permitted. +.PP +If the file +.I /etc/at.allow +exists, only usernames mentioned in it are allowed to use +.BR at . +.PP +If +.I /etc/at.allow +does not exist, +.I /etc/at.deny +is checked, every username not mentioned in it is then allowed +to use +.BR at . +.PP +An empty +.I /etc/at.deny +means that every user may use +.BR at . +.PP +If neither exists, only the superuser is allowed to use at. +.SH "SEE ALSO" +.BR at (1), +.BR cron (8), +.BR crontab (1), +.BR atd (8). diff --git a/upstream/fedora-40/man5/binfmt.d.5 b/upstream/fedora-40/man5/binfmt.d.5 new file mode 100644 index 00000000..f03a5a39 --- /dev/null +++ b/upstream/fedora-40/man5/binfmt.d.5 @@ -0,0 +1,104 @@ +'\" t +.TH "BINFMT\&.D" "5" "" "systemd 255" "binfmt.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +binfmt.d \- Configure additional binary formats for executables at boot +.SH "SYNOPSIS" +.PP +/etc/binfmt\&.d/*\&.conf +.PP +/run/binfmt\&.d/*\&.conf +.PP +/usr/lib/binfmt\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +At boot, +\fBsystemd-binfmt.service\fR(8) +reads configuration files from the above directories to register in the kernel additional binary formats for executables\&. +.SH "CONFIGURATION FORMAT" +.PP +Each file contains a list of binfmt_misc kernel binary format rules\&. Consult the kernel\*(Aqs +\m[blue]\fBKernel Support for miscellaneous Binary Formats (binfmt_misc)\fR\m[]\&\s-2\u[1]\d\s+2 +documentation file for more information on registration of additional binary formats and how to write rules\&. +.PP +Empty lines and lines beginning with +";" +and +"#" +are ignored\&. Note that this means you may not use those symbols as the delimiter in binary format rules\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +Configuration files are read from directories in +/etc/, +/run/, +/usr/local/lib/, and +/usr/lib/, in order of precedence, as listed in the SYNOPSIS section above\&. Files must have the +"\&.conf" +extension\&. Files in +/etc/ +override files with the same name in +/run/, +/usr/local/lib/, and +/usr/lib/\&. Files in +/run/ +override files with the same name under +/usr/\&. +.PP +All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence\&. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later)\&. +.PP +Packages should install their configuration files in +/usr/lib/ +(distribution packages) or +/usr/local/lib/ +(local installs)\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. It is recommended to prefix all filenames with a two\-digit number and a dash, to simplify the ordering of the files\&. +.PP +If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. If the vendor configuration file is included in the initrd image, the image has to be regenerated\&. +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&/etc/binfmt\&.d/wine\&.conf example:\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Start WINE on Windows executables +:DOSWin:M::MZ::/usr/bin/wine: +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-binfmt.service\fR(8), +\fBsystemd-delta\fR(1), +\fBwine\fR(8) +.SH "NOTES" +.IP " 1." 4 +Kernel Support for miscellaneous Binary Formats (binfmt_misc) +.RS 4 +\%https://docs.kernel.org/admin-guide/binfmt-misc.html +.RE diff --git a/upstream/fedora-40/man5/bootchart.conf.5 b/upstream/fedora-40/man5/bootchart.conf.5 new file mode 100644 index 00000000..3a29f5d8 --- /dev/null +++ b/upstream/fedora-40/man5/bootchart.conf.5 @@ -0,0 +1,123 @@ +'\" t +.TH "BOOTCHART\&.CONF" "5" "" "systemd 234" "bootchart.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +bootchart.conf, bootchart.conf.d \- Boot performance analysis graphing tool configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/bootchart\&.conf +.PP +/etc/systemd/bootchart\&.conf\&.d/*\&.conf +.PP +/run/systemd/bootchart\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/bootchart\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +When starting, systemd\-bootchart will read the configuration file +/etc/systemd/bootchart\&.conf, followed by the files in the +bootchart\&.conf\&.d +directories\&. These configuration files determine logging parameters and graph output\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is defined during compilation, so a configuration file is only needed when it is necessary to deviate from those defaults\&. By default, the configuration file in +/etc/systemd/ +contains commented out entries showing the defaults as a guide to the administrator\&. This file can be edited to create local overrides\&. +.PP +When packages need to customize the configuration, they can install configuration snippets in +/usr/lib/systemd/*\&.conf\&.d/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. The main configuration file is read before any of the configuration directories, and has the lowest precedence; entries in a file in any configuration directory override entries in the single configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of which of the subdirectories they reside in\&. If multiple files specify the same option, the entry in the file with the lexicographically latest name takes precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +\fISamples=500\fR +.RS 4 +Configure the amount of samples to record in total before bootchart exits\&. Each sample will record at intervals defined by Frequency=\&. +.RE +.PP +\fIFrequency=25\fR +.RS 4 +Configure the sample log frequency\&. This can be a fractional number, but must be larger than 0\&.0\&. Most systems can cope with values under 25\-50 without impacting boot time severely\&. +.RE +.PP +\fIRelative=no\fR +.RS 4 +Configures whether the left axis of the output graph equals time=0\&.0 (\fBCLOCK_MONOTONIC\fR +start)\&. This is useful for using bootchart at post\-boot time to profile an already booted system, otherwise the graph would become extremely large\&. If set to yes, the horizontal axis starts at the first recorded sample instead of time=0\&.0\&. +.RE +.PP +\fIFilter=no\fR +.RS 4 +Configures whether the resulting graph should omit tasks that did not contribute significantly to the boot\&. Processes that are too short\-lived (only seen in one sample) or that do not consume any significant CPU time (less than 0\&.001sec) will not be displayed in the output graph\&. +.RE +.PP +\fIOutput=[path]\fR +.RS 4 +Configures the output directory for writing the graphs\&. By default, bootchart writes the graphs to +/run/log\&. +.RE +.PP +\fIInit=[path]\fR +.RS 4 +Configures bootchart to run a non\-standard binary instead of +/usr/lib/systemd/systemd\&. This option is only relevant if bootchart was invoked from the kernel command line with init=/usr/lib/systemd/systemd\-bootchart\&. +.RE +.PP +\fIPlotMemoryUsage=no\fR +.RS 4 +If set to yes, enables logging and graphing of processes\*(Aq PSS memory consumption\&. +.RE +.PP +\fIPlotEntropyGraph=no\fR +.RS 4 +If set to yes, enables logging and graphing of the kernel random entropy pool size\&. +.RE +.PP +\fIScaleX=100\fR +.RS 4 +Horizontal scaling factor for all variable graph components\&. +.RE +.PP +\fIScaleY=20\fR +.RS 4 +Vertical scaling factor for all variable graph components\&. +.RE +.PP +\fIControlGroup=no\fR +.RS 4 +Display process control group\&. +.RE +.PP +\fICmdline=no\fR +.RS 4 +Display the full command line of each process\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd-bootchart\fR(1), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/btrfs.5 b/upstream/fedora-40/man5/btrfs.5 new file mode 100644 index 00000000..208aa24b --- /dev/null +++ b/upstream/fedora-40/man5/btrfs.5 @@ -0,0 +1,2972 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BTRFS" "5" "Feb 14, 2024" "6.7.1" "BTRFS" +.SH NAME +btrfs \- topics about the BTRFS filesystem (mount options, supported file attributes and other) +.SH DESCRIPTION +.sp +This document describes topics related to BTRFS that are not specific to the +tools. Currently covers: +.INDENT 0.0 +.IP 1. 4 +mount options +.IP 2. 4 +filesystem features +.IP 3. 4 +checksum algorithms +.IP 4. 4 +compression +.IP 5. 4 +sysfs interface +.IP 6. 4 +filesystem exclusive operations +.IP 7. 4 +filesystem limits +.IP 8. 4 +bootloader support +.IP 9. 4 +file attributes +.IP 10. 4 +zoned mode +.IP 11. 4 +control device +.IP 12. 4 +filesystems with multiple block group profiles +.IP 13. 4 +seeding device +.IP 14. 4 +RAID56 status and recommended practices +.IP 15. 4 +storage model, hardware considerations +.UNINDENT +.SH MOUNT OPTIONS +.SS BTRFS SPECIFIC MOUNT OPTIONS +.sp +This section describes mount options specific to BTRFS. For the generic mount +options please refer to \fBmount(8)\fP manual page. The options are sorted alphabetically +(discarding the \fIno\fP prefix). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Most mount options apply to the whole filesystem and only options in the +first mounted subvolume will take effect. This is due to lack of implementation +and may change in the future. This means that (for example) you can\(aqt set +per\-subvolume \fInodatacow\fP, \fInodatasum\fP, or \fIcompress\fP using mount options. This +should eventually be fixed, but it has proved to be difficult to implement +correctly within the Linux VFS framework. +.UNINDENT +.UNINDENT +.sp +Mount options are processed in order, only the last occurrence of an option +takes effect and may disable other options due to constraints (see e.g. +\fInodatacow\fP and \fIcompress\fP). The output of \fBmount\fP command shows which options +have been applied. +.INDENT 0.0 +.TP +.B acl, noacl +(default: on) +.sp +Enable/disable support for POSIX Access Control Lists (ACLs). See the +\fBacl(5)\fP manual page for more information about ACLs. +.sp +The support for ACL is build\-time configurable (BTRFS_FS_POSIX_ACL) and +mount fails if \fIacl\fP is requested but the feature is not compiled in. +.UNINDENT +.INDENT 0.0 +.TP +.B autodefrag, noautodefrag +(since: 3.0, default: off) +.sp +Enable automatic file defragmentation. +When enabled, small random writes into files (in a range of tens of kilobytes, +currently it\(aqs 64KiB) are detected and queued up for the defragmentation process. +May not be well suited for large database workloads. +.sp +The read latency may increase due to reading the adjacent blocks that make up the +range for defragmentation, successive write will merge the blocks in the new +location. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14\-rc2 as +well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or +≥ 3.13.4 will break up the reflinks of COW data (for example files +copied with \fBcp \-\-reflink\fP, snapshots or de\-duplicated data). +This may cause considerable increase of space usage depending on the +broken up reflinks. +.UNINDENT +.UNINDENT +.TP +.B barrier, nobarrier +(default: on) +.sp +Ensure that all IO write operations make it through the device cache and are stored +permanently when the filesystem is at its consistency checkpoint. This +typically means that a flush command is sent to the device that will +synchronize all pending data and ordinary metadata blocks, then writes the +superblock and issues another flush. +.sp +The write flushes incur a slight hit and also prevent the IO block +scheduler to reorder requests in a more effective way. Disabling barriers gets +rid of that penalty but will most certainly lead to a corrupted filesystem in +case of a crash or power loss. The ordinary metadata blocks could be yet +unwritten at the time the new superblock is stored permanently, expecting that +the block pointers to metadata were stored permanently before. +.sp +On a device with a volatile battery\-backed write\-back cache, the \fInobarrier\fP +option will not lead to filesystem corruption as the pending blocks are +supposed to make it to the permanent storage. +.TP +.B check_int, check_int_data, check_int_print_mask= +(since: 3.0, default: off) +.sp +These debugging options control the behavior of the integrity checking +module (the BTRFS_FS_CHECK_INTEGRITY config option required). The main goal is +to verify that all blocks from a given transaction period are properly linked. +.sp +\fIcheck_int\fP enables the integrity checker module, which examines all +block write requests to ensure on\-disk consistency, at a large +memory and CPU cost. +.sp +\fIcheck_int_data\fP includes extent data in the integrity checks, and +implies the \fIcheck_int\fP option. +.sp +\fIcheck_int_print_mask\fP takes a bitmask of BTRFSIC_PRINT_MASK_* values +as defined in \fIfs/btrfs/check\-integrity.c\fP, to control the integrity +checker module behavior. +.sp +See comments at the top of \fIfs/btrfs/check\-integrity.c\fP +for more information. +.TP +.B clear_cache +Force clearing and rebuilding of the free space cache if something +has gone wrong. +.sp +For free space cache \fIv1\fP, this only clears (and, unless \fInospace_cache\fP is +used, rebuilds) the free space cache for block groups that are modified while +the filesystem is mounted with that option. To actually clear an entire free +space cache \fIv1\fP, see \fBbtrfs check \-\-clear\-space\-cache v1\fP\&. +.sp +For free space cache \fIv2\fP, this clears the entire free space cache. +To do so without requiring to mounting the filesystem, see +\fBbtrfs check \-\-clear\-space\-cache v2\fP\&. +.sp +See also: \fIspace_cache\fP\&. +.TP +.B commit= +(since: 3.12, default: 30) +.sp +Set the interval of periodic transaction commit when data are synchronized +to permanent storage. Higher interval values lead to larger amount of unwritten +data, which has obvious consequences when the system crashes. +The upper bound is not forced, but a warning is printed if it\(aqs more than 300 +seconds (5 minutes). Use with care. +.TP +.B compress, compress=, compress\-force, compress\-force= +(default: off, level support since: 5.1) +.sp +Control BTRFS file data compression. Type may be specified as \fIzlib\fP, +\fIlzo\fP, \fIzstd\fP or \fIno\fP (for no compression, used for remounting). If no type +is specified, \fIzlib\fP is used. If \fIcompress\-force\fP is specified, +then compression will always be attempted, but the data may end up uncompressed +if the compression would make them larger. +.sp +Both \fIzlib\fP and \fIzstd\fP (since version 5.1) expose the compression level as a +tunable knob with higher levels trading speed and memory (\fIzstd\fP) for higher +compression ratios. This can be set by appending a colon and the desired level. +ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. If no level is set, +both currently use a default level of 3. The value 0 is an alias for the +default level. +.sp +Otherwise some simple heuristics are applied to detect an incompressible file. +If the first blocks written to a file are not compressible, the whole file is +permanently marked to skip compression. As this is too simple, the +\fIcompress\-force\fP is a workaround that will compress most of the files at the +cost of some wasted CPU cycles on failed attempts. +Since kernel 4.15, a set of heuristic algorithms have been improved by using +frequency sampling, repeated pattern detection and Shannon entropy calculation +to avoid that. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If compression is enabled, \fInodatacow\fP and \fInodatasum\fP are disabled. +.UNINDENT +.UNINDENT +.TP +.B datacow, nodatacow +(default: on) +.sp +Enable data copy\-on\-write for newly created files. +\fINodatacow\fP implies \fInodatasum\fP, and disables \fIcompression\fP\&. All files created +under \fInodatacow\fP are also set the NOCOW file attribute (see \fBchattr(1)\fP). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If \fInodatacow\fP or \fInodatasum\fP are enabled, compression is disabled. +.UNINDENT +.UNINDENT +.sp +Updates in\-place improve performance for workloads that do frequent overwrites, +at the cost of potential partial writes, in case the write is interrupted +(system crash, device failure). +.TP +.B datasum, nodatasum +(default: on) +.sp +Enable data checksumming for newly created files. +\fIDatasum\fP implies \fIdatacow\fP, i.e. the normal mode of operation. All files created +under \fInodatasum\fP inherit the \(dqno checksums\(dq property, however there\(aqs no +corresponding file attribute (see \fBchattr(1)\fP). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If \fInodatacow\fP or \fInodatasum\fP are enabled, compression is disabled. +.UNINDENT +.UNINDENT +.sp +There is a slight performance gain when checksums are turned off, the +corresponding metadata blocks holding the checksums do not need to updated. +The cost of checksumming of the blocks in memory is much lower than the IO, +modern CPUs feature hardware support of the checksumming algorithm. +.UNINDENT +.INDENT 0.0 +.TP +.B degraded +(default: off) +.sp +Allow mounts with fewer devices than the RAID profile constraints +require. A read\-write mount (or remount) may fail when there are too many devices +missing, for example if a stripe member is completely missing from RAID0. +.sp +Since 4.14, the constraint checks have been improved and are verified on the +chunk level, not at the device level. This allows degraded mounts of +filesystems with mixed RAID profiles for data and metadata, even if the +device number constraints would not be satisfied for some of the profiles. +.sp +Example: metadata \-\- raid1, data \-\- single, devices \-\- \fB/dev/sda\fP, \fB/dev/sdb\fP +.sp +Suppose the data are completely stored on \fIsda\fP, then missing \fIsdb\fP will not +prevent the mount, even if 1 missing device would normally prevent (any) +\fIsingle\fP profile to mount. In case some of the data chunks are stored on \fIsdb\fP, +then the constraint of single/data is not satisfied and the filesystem +cannot be mounted. +.UNINDENT +.INDENT 0.0 +.TP +.B device= +Specify a path to a device that will be scanned for BTRFS filesystem during +mount. This is usually done automatically by a device manager (like udev) or +using the \fBbtrfs device scan\fP command (e.g. run from the initial ramdisk). In +cases where this is not possible the \fIdevice\fP mount option can help. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Booting e.g. a RAID1 system may fail even if all filesystem\(aqs \fIdevice\fP +paths are provided as the actual device nodes may not be discovered by the +system at that point. +.UNINDENT +.UNINDENT +.TP +.B discard, discard=sync, discard=async, nodiscard +(default: async when devices support it since 6.2, async support since: 5.6) +.sp +Enable discarding of freed file blocks. This is useful for SSD devices, thinly +provisioned LUNs, or virtual machine images; however, every storage layer must +support discard for it to work. +.sp +In the synchronous mode (\fIsync\fP or without option value), lack of asynchronous +queued TRIM on the backing device TRIM can severely degrade performance, +because a synchronous TRIM operation will be attempted instead. Queued TRIM +requires newer than SATA revision 3.1 chipsets and devices. +.sp +The asynchronous mode (\fIasync\fP) gathers extents in larger chunks before sending +them to the devices for TRIM. The overhead and performance impact should be +negligible compared to the previous mode and it\(aqs supposed to be the preferred +mode if needed. +.sp +If it is not necessary to immediately discard freed blocks, then the \fBfstrim\fP +tool can be used to discard all free blocks in a batch. Scheduling a TRIM +during a period of low system activity will prevent latent interference with +the performance of other operations. Also, a device may ignore the TRIM command +if the range is too small, so running a batch discard has a greater probability +of actually discarding the blocks. +.TP +.B enospc_debug, noenospc_debug +(default: off) +.sp +Enable verbose output for some ENOSPC conditions. It\(aqs safe to use but can +be noisy if the system reaches near\-full state. +.TP +.B fatal_errors= +(since: 3.4, default: bug) +.sp +Action to take when encountering a fatal error. +.INDENT 7.0 +.TP +.B bug +\fIBUG()\fP on a fatal error, the system will stay in the crashed state and may be +still partially usable, but reboot is required for full operation +.TP +.B panic +\fIpanic()\fP on a fatal error, depending on other system configuration, this may +be followed by a reboot. Please refer to the documentation of kernel boot +parameters, e.g. \fIpanic\fP, \fIoops\fP or \fIcrashkernel\fP\&. +.UNINDENT +.TP +.B flushoncommit, noflushoncommit +(default: off) +.sp +This option forces any data dirtied by a write in a prior transaction to commit +as part of the current commit, effectively a full filesystem sync. +.sp +This makes the committed state a fully consistent view of the file system from +the application\(aqs perspective (i.e. it includes all completed file system +operations). This was previously the behavior only when a snapshot was +created. +.sp +When off, the filesystem is consistent but buffered writes may last more than +one transaction commit. +.TP +.B fragment= +(depends on compile\-time option CONFIG_BTRFS_DEBUG, since: 4.4, default: off) +.sp +A debugging helper to intentionally fragment given \fItype\fP of block groups. The +type can be \fIdata\fP, \fImetadata\fP or \fIall\fP\&. This mount option should not be used +outside of debugging environments and is not recognized if the kernel config +option \fICONFIG_BTRFS_DEBUG\fP is not enabled. +.TP +.B nologreplay +(default: off, even read\-only) +.sp +The tree\-log contains pending updates to the filesystem until the full commit. +The log is replayed on next mount, this can be disabled by this option. See +also \fItreelog\fP\&. Note that \fInologreplay\fP is the same as \fInorecovery\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Currently, the tree log is replayed even with a read\-only mount! To +disable that behaviour, mount also with \fInologreplay\fP\&. +.UNINDENT +.UNINDENT +.TP +.B max_inline= +(default: min(2048, page size) ) +.sp +Specify the maximum amount of space, that can be inlined in +a metadata b\-tree leaf. The value is specified in bytes, optionally +with a K suffix (case insensitive). In practice, this value +is limited by the filesystem block size (named \fIsectorsize\fP at mkfs time), +and memory page size of the system. In case of sectorsize limit, there\(aqs +some space unavailable due to b\-tree leaf headers. For example, a 4KiB +sectorsize, maximum size of inline data is about 3900 bytes. +.sp +Inlining can be completely turned off by specifying 0. This will increase data +block slack if file sizes are much smaller than block size but will reduce +metadata consumption in return. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The default value has changed to 2048 in kernel 4.6. +.UNINDENT +.UNINDENT +.TP +.B metadata_ratio= +(default: 0, internal logic) +.sp +Specifies that 1 metadata chunk should be allocated after every \fIvalue\fP data +chunks. Default behaviour depends on internal logic, some percent of unused +metadata space is attempted to be maintained but is not always possible if +there\(aqs not enough space left for chunk allocation. The option could be useful to +override the internal logic in favor of the metadata allocation if the expected +workload is supposed to be metadata intense (snapshots, reflinks, xattrs, +inlined files). +.TP +.B norecovery +(since: 4.5, default: off) +.sp +Do not attempt any data recovery at mount time. This will disable \fIlogreplay\fP +and avoids other write operations. Note that this option is the same as +\fInologreplay\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The opposite option \fIrecovery\fP used to have different meaning but was +changed for consistency with other filesystems, where \fInorecovery\fP is used for +skipping log replay. BTRFS does the same and in general will try to avoid any +write operations. +.UNINDENT +.UNINDENT +.TP +.B rescan_uuid_tree +(since: 3.12, default: off) +.sp +Force check and rebuild procedure of the UUID tree. This should not +normally be needed. +.TP +.B rescue +(since: 5.9) +.sp +Modes allowing mount with damaged filesystem structures. +.INDENT 7.0 +.IP \(bu 2 +\fIusebackuproot\fP (since: 5.9, replaces standalone option \fIusebackuproot\fP) +.IP \(bu 2 +\fInologreplay\fP (since: 5.9, replaces standalone option \fInologreplay\fP) +.IP \(bu 2 +\fIignorebadroots\fP, \fIibadroots\fP (since: 5.11) +.IP \(bu 2 +\fIignoredatacsums\fP, \fIidatacsums\fP (since: 5.11) +.IP \(bu 2 +\fIall\fP (since: 5.9) +.UNINDENT +.TP +.B skip_balance +(since: 3.3, default: off) +.sp +Skip automatic resume of an interrupted balance operation. The operation can +later be resumed with \fBbtrfs balance resume\fP, or the paused state can be +removed with \fBbtrfs balance cancel\fP\&. The default behaviour is to resume an +interrupted balance immediately after a volume is mounted. +.TP +.B space_cache, space_cache=, nospace_cache +(\fInospace_cache\fP since: 3.2, \fIspace_cache=v1\fP and \fIspace_cache=v2\fP since 4.5, default: \fIspace_cache=v2\fP) +.sp +Options to control the free space cache. The free space cache greatly improves +performance when reading block group free space into memory. However, managing +the space cache consumes some resources, including a small amount of disk +space. +.sp +There are two implementations of the free space cache. The original +one, referred to as \fIv1\fP, used to be a safe default but has been +superseded by \fIv2\fP\&. The \fIv1\fP space cache can be disabled at mount time +with \fInospace_cache\fP without clearing. +.sp +On very large filesystems (many terabytes) and certain workloads, the +performance of the \fIv1\fP space cache may degrade drastically. The \fIv2\fP +implementation, which adds a new b\-tree called the free space tree, addresses +this issue. Once enabled, the \fIv2\fP space cache will always be used and cannot +be disabled unless it is cleared. Use \fIclear_cache,space_cache=v1\fP or +\fIclear_cache,nospace_cache\fP to do so. If \fIv2\fP is enabled, and \fIv1\fP space +cache will be cleared (at the first mount) and kernels without \fIv2\fP +support will only be able to mount the filesystem in read\-only mode. +On an unmounted filesystem the caches (both versions) can be cleared by +\(dqbtrfs check \-\-clear\-space\-cache\(dq. +.sp +The \fI\%btrfs\-check(8)\fP and \fI:doc:\(gamkfs.btrfs\fP commands have full \fIv2\fP free space +cache support since v4.19. +.sp +If a version is not explicitly specified, the default implementation will be +chosen, which is \fIv2\fP\&. +.TP +.B ssd, ssd_spread, nossd, nossd_spread +(default: SSD autodetected) +.sp +Options to control SSD allocation schemes. By default, BTRFS will +enable or disable SSD optimizations depending on status of a device with +respect to rotational or non\-rotational type. This is determined by the +contents of \fI/sys/block/DEV/queue/rotational\fP). If it is 0, the \fIssd\fP option is +turned on. The option \fInossd\fP will disable the autodetection. +.sp +The optimizations make use of the absence of the seek penalty that\(aqs inherent +for the rotational devices. The blocks can be typically written faster and +are not offloaded to separate threads. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Since 4.14, the block layout optimizations have been dropped. This used +to help with first generations of SSD devices. Their FTL (flash translation +layer) was not effective and the optimization was supposed to improve the wear +by better aligning blocks. This is no longer true with modern SSD devices and +the optimization had no real benefit. Furthermore it caused increased +fragmentation. The layout tuning has been kept intact for the option +\fIssd_spread\fP\&. +.UNINDENT +.UNINDENT +.sp +The \fIssd_spread\fP mount option attempts to allocate into bigger and aligned +chunks of unused space, and may perform better on low\-end SSDs. \fIssd_spread\fP +implies \fIssd\fP, enabling all other SSD heuristics as well. The option \fInossd\fP +will disable all SSD options while \fInossd_spread\fP only disables \fIssd_spread\fP\&. +.TP +.B subvol= +Mount subvolume from \fIpath\fP rather than the toplevel subvolume. The +\fIpath\fP is always treated as relative to the toplevel subvolume. +This mount option overrides the default subvolume set for the given filesystem. +.TP +.B subvolid= +Mount subvolume specified by a \fIsubvolid\fP number rather than the toplevel +subvolume. You can use \fBbtrfs subvolume list\fP of \fBbtrfs subvolume show\fP to see +subvolume ID numbers. +This mount option overrides the default subvolume set for the given filesystem. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If both \fIsubvolid\fP and \fIsubvol\fP are specified, they must point at the +same subvolume, otherwise the mount will fail. +.UNINDENT +.UNINDENT +.TP +.B thread_pool= +(default: min(NRCPUS + 2, 8) ) +.sp +The number of worker threads to start. NRCPUS is number of on\-line CPUs +detected at the time of mount. Small number leads to less parallelism in +processing data and metadata, higher numbers could lead to a performance hit +due to increased locking contention, process scheduling, cache\-line bouncing or +costly data transfers between local CPU memories. +.TP +.B treelog, notreelog +(default: on) +.sp +Enable the tree logging used for \fIfsync\fP and \fIO_SYNC\fP writes. The tree log +stores changes without the need of a full filesystem sync. The log operations +are flushed at sync and transaction commit. If the system crashes between two +such syncs, the pending tree log operations are replayed during mount. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Currently, the tree log is replayed even with a read\-only mount! To +disable that behaviour, also mount with \fInologreplay\fP\&. +.UNINDENT +.UNINDENT +.sp +The tree log could contain new files/directories, these would not exist on +a mounted filesystem if the log is not replayed. +.TP +.B usebackuproot +(since: 4.6, default: off) +.sp +Enable autorecovery attempts if a bad tree root is found at mount time. +Currently this scans a backup list of several previous tree roots and tries to +use the first readable. This can be used with read\-only mounts as well. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This option has replaced \fIrecovery\fP\&. +.UNINDENT +.UNINDENT +.TP +.B user_subvol_rm_allowed +(default: off) +.sp +Allow subvolumes to be deleted by their respective owner. Otherwise, only the +root user can do that. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Historically, any user could create a snapshot even if he was not owner +of the source subvolume, the subvolume deletion has been restricted for that +reason. The subvolume creation has been restricted but this mount option is +still required. This is a usability issue. +Since 4.18, the \fBrmdir(2)\fP syscall can delete an empty subvolume just like an +ordinary directory. Whether this is possible can be detected at runtime, see +\fIrmdir_subvol\fP feature in \fIFILESYSTEM FEATURES\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.SS DEPRECATED MOUNT OPTIONS +.sp +List of mount options that have been removed, kept for backward compatibility. +.INDENT 0.0 +.TP +.B recovery +(since: 3.2, default: off, deprecated since: 4.5) +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This option has been replaced by \fIusebackuproot\fP and should not be used +but will work on 4.5+ kernels. +.UNINDENT +.UNINDENT +.TP +.B inode_cache, noinode_cache +(removed in: 5.11, since: 3.0, default: off) +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The functionality has been removed in 5.11, any stale data created by +previous use of the \fIinode_cache\fP option can be removed by +\fI\%btrfs rescue clear\-ino\-cache\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.SS NOTES ON GENERIC MOUNT OPTIONS +.sp +Some of the general mount options from \fBmount(8)\fP that affect BTRFS and are +worth mentioning. +.INDENT 0.0 +.TP +.B noatime +under read intensive work\-loads, specifying \fInoatime\fP significantly improves +performance because no new access time information needs to be written. Without +this option, the default is \fIrelatime\fP, which only reduces the number of +inode atime updates in comparison to the traditional \fIstrictatime\fP\&. The worst +case for atime updates under \fIrelatime\fP occurs when many files are read whose +atime is older than 24 h and which are freshly snapshotted. In that case the +atime is updated and COW happens \- for each file \- in bulk. See also +\fI\%https://lwn.net/Articles/499293/\fP \- \fIAtime and btrfs: a bad combination? (LWN, 2012\-05\-31)\fP\&. +.sp +Note that \fInoatime\fP may break applications that rely on atime uptimes like +the venerable Mutt (unless you use maildir mailboxes). +.UNINDENT +.SH FILESYSTEM FEATURES +.sp +The basic set of filesystem features gets extended over time. The backward +compatibility is maintained and the features are optional, need to be +explicitly asked for so accidental use will not create incompatibilities. +.sp +There are several classes and the respective tools to manage the features: +.INDENT 0.0 +.TP +.B at mkfs time only +This is namely for core structures, like the b\-tree nodesize or checksum +algorithm, see \fI\%mkfs.btrfs(8)\fP for more details. +.TP +.B after mkfs, on an unmounted filesystem +Features that may optimize internal structures or add new structures to support +new functionality, see \fI\%btrfstune(8)\fP\&. The command +\fBbtrfs inspect\-internal dump\-super /dev/sdx\fP +will dump a superblock, you can map the value of +\fIincompat_flags\fP to the features listed below +.TP +.B after mkfs, on a mounted filesystem +The features of a filesystem (with a given UUID) are listed in +\fB/sys/fs/btrfs/UUID/features/\fP, one file per feature. The status is stored +inside the file. The value \fI1\fP is for enabled and active, while \fI0\fP means the +feature was enabled at mount time but turned off afterwards. +.sp +Whether a particular feature can be turned on a mounted filesystem can be found +in the directory \fB/sys/fs/btrfs/features/\fP, one file per feature. The value \fI1\fP +means the feature can be enabled. +.UNINDENT +.sp +List of features (see also \fI\%mkfs.btrfs(8)\fP section +\fI\%FILESYSTEM FEATURES\fP): +.INDENT 0.0 +.TP +.B big_metadata +(since: 3.4) +.sp +the filesystem uses \fInodesize\fP for metadata blocks, this can be bigger than the +page size +.TP +.B block_group_tree +(since: 6.1) +.sp +block group item representation using a dedicated b\-tree, this can greatly +reduce mount time for large filesystems +.TP +.B compress_lzo +(since: 2.6.38) +.sp +the \fIlzo\fP compression has been used on the filesystem, either as a mount option +or via \fBbtrfs filesystem defrag\fP\&. +.TP +.B compress_zstd +(since: 4.14) +.sp +the \fIzstd\fP compression has been used on the filesystem, either as a mount option +or via \fBbtrfs filesystem defrag\fP\&. +.TP +.B default_subvol +(since: 2.6.34) +.sp +the default subvolume has been set on the filesystem +.TP +.B extended_iref +(since: 3.7) +.sp +increased hardlink limit per file in a directory to 65536, older kernels +supported a varying number of hardlinks depending on the sum of all file name +sizes that can be stored into one metadata block +.TP +.B free_space_tree +(since: 4.5) +.sp +free space representation using a dedicated b\-tree, successor of v1 space cache +.TP +.B metadata_uuid +(since: 5.0) +.sp +the main filesystem UUID is the metadata_uuid, which stores the new UUID only +in the superblock while all metadata blocks still have the UUID set at mkfs +time, see \fI\%btrfstune(8)\fP for more +.TP +.B mixed_backref +(since: 2.6.31) +.sp +the last major disk format change, improved backreferences, now default +.TP +.B mixed_groups +(since: 2.6.37) +.sp +mixed data and metadata block groups, i.e. the data and metadata are not +separated and occupy the same block groups, this mode is suitable for small +volumes as there are no constraints how the remaining space should be used +(compared to the split mode, where empty metadata space cannot be used for data +and vice versa) +.sp +on the other hand, the final layout is quite unpredictable and possibly highly +fragmented, which means worse performance +.TP +.B no_holes +(since: 3.14) +.sp +improved representation of file extents where holes are not explicitly +stored as an extent, saves a few percent of metadata if sparse files are used +.TP +.B raid1c34 +(since: 5.5) +.sp +extended RAID1 mode with copies on 3 or 4 devices respectively +.TP +.B RAID56 +(since: 3.9) +.sp +the filesystem contains or contained a RAID56 profile of block groups +.TP +.B rmdir_subvol +(since: 4.18) +.sp +indicate that \fBrmdir(2)\fP syscall can delete an empty subvolume just like an +ordinary directory. Note that this feature only depends on the kernel version. +.TP +.B skinny_metadata +(since: 3.10) +.sp +reduced\-size metadata for extent references, saves a few percent of metadata +.TP +.B send_stream_version +(since: 5.10) +.sp +number of the highest supported send stream version +.TP +.B supported_checksums +(since: 5.5) +.sp +list of checksum algorithms supported by the kernel module, the respective +modules or built\-in implementing the algorithms need to be present to mount +the filesystem, see section \fI\%CHECKSUM ALGORITHMS\fP\&. +.TP +.B supported_sectorsizes +(since: 5.13) +.sp +list of values that are accepted as sector sizes (\fBmkfs.btrfs \-\-sectorsize\fP) by +the running kernel +.TP +.B supported_rescue_options +(since: 5.11) +.sp +list of values for the mount option \fIrescue\fP that are supported by the running +kernel, see \fI\%btrfs(5)\fP +.TP +.B zoned +(since: 5.12) +.sp +zoned mode is allocation/write friendly to host\-managed zoned devices, +allocation space is partitioned into fixed\-size zones that must be updated +sequentially, see section \fI\%ZONED MODE\fP +.UNINDENT +.SH SWAPFILE SUPPORT +.sp +A swapfile, when active, is a file\-backed swap area. It is supported since kernel 5.0. +Use \fBswapon(8)\fP to activate it, until then (respectively again after deactivating it +with \fBswapoff(8)\fP) it\(aqs just a normal file (with NODATACOW set), for which the special +restrictions for active swapfiles don\(aqt apply. +.sp +There are some limitations of the implementation in BTRFS and Linux swap +subsystem: +.INDENT 0.0 +.IP \(bu 2 +filesystem \- must be only single device +.IP \(bu 2 +filesystem \- must have only \fIsingle\fP data profile +.IP \(bu 2 +subvolume \- cannot be snapshotted if it contains any active swapfiles +.IP \(bu 2 +swapfile \- must be preallocated (i.e. no holes) +.IP \(bu 2 +swapfile \- must be NODATACOW (i.e. also NODATASUM, no compression) +.UNINDENT +.sp +The limitations come namely from the COW\-based design and mapping layer of +blocks that allows the advanced features like relocation and multi\-device +filesystems. However, the swap subsystem expects simpler mapping and no +background changes of the file block location once they\(aqve been assigned to +swap. +.sp +With active swapfiles, the following whole\-filesystem operations will skip +swapfile extents or may fail: +.INDENT 0.0 +.IP \(bu 2 +balance \- block groups with extents of any active swapfiles are skipped and +reported, the rest will be processed normally +.IP \(bu 2 +resize grow \- unaffected +.IP \(bu 2 +resize shrink \- works as long as the extents of any active swapfiles are +outside of the shrunk range +.IP \(bu 2 +device add \- if the new devices do not interfere with any already active swapfiles +this operation will work, though no new swapfile can be activated +afterwards +.IP \(bu 2 +device delete \- if the device has been added as above, it can be also deleted +.IP \(bu 2 +device replace \- ditto +.UNINDENT +.sp +When there are no active swapfiles and a whole\-filesystem exclusive operation +is running (e.g. balance, device delete, shrink), the swapfiles cannot be +temporarily activated. The operation must finish first. +.sp +To create and activate a swapfile run the following commands: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# truncate \-s 0 swapfile +# chattr +C swapfile +# fallocate \-l 2G swapfile +# chmod 0600 swapfile +# mkswap swapfile +# swapon swapfile +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Since version 6.1 it\(aqs possible to create the swapfile in a single command +(except the activation): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs filesystem mkswapfile \-\-size 2G swapfile +# swapon swapfile +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Please note that the UUID returned by the \fImkswap\fP utility identifies the swap +\(dqfilesystem\(dq and because it\(aqs stored in a file, it\(aqs not generally visible and +usable as an identifier unlike if it was on a block device. +.sp +Once activated the file will appear in \fB/proc/swaps\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# cat /proc/swaps +Filename Type Size Used Priority +/path/swapfile file 2097152 0 \-2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The swapfile can be created as one\-time operation or, once properly created, +activated on each boot by the \fBswapon \-a\fP command (usually started by the +service manager). Add the following entry to \fI/etc/fstab\fP, assuming the +filesystem that provides the \fI/path\fP has been already mounted at this point. +Additional mount options relevant for the swapfile can be set too (like +priority, not the BTRFS mount options). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +/path/swapfile none swap defaults 0 0 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +From now on the subvolume with the active swapfile cannot be snapshotted until +the swapfile is deactivated again by \fBswapoff\fP\&. Then the swapfile is a +regular file and the subvolume can be snapshotted again, though this would prevent +another activation any swapfile that has been snapshotted. New swapfiles (not +snapshotted) can be created and activated. +.sp +Otherwise, an inactive swapfile does not affect the containing subvolume. Activation +creates a temporary in\-memory status and prevents some file operations, but is +not stored permanently. +.SH HIBERNATION +.sp +A swapfile can be used for hibernation but it\(aqs not straightforward. Before +hibernation a resume offset must be written to file \fI/sys/power/resume_offset\fP +or the kernel command line parameter \fIresume_offset\fP must be set. +.sp +The value is the physical offset on the device. Note that \fBthis is not the same +value that\fP \fBfilefrag\fP \fBprints as physical offset!\fP +.sp +Btrfs filesystem uses mapping between logical and physical addresses but here +the physical can still map to one or more device\-specific physical block +addresses. It\(aqs the device\-specific physical offset that is suitable as resume +offset. +.sp +Since version 6.1 there\(aqs a command \fI\%btrfs inspect\-internal map\-swapfile\fP +that will print the device physical offset and the adjusted value for +\fB/sys/power/resume_offset\fP\&. Note that the value is divided by page size, i.e. +it\(aqs not the offset itself. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs filesystem mkswapfile swapfile +# btrfs inspect\-internal map\-swapfile swapfile +Physical start: 811511726080 +Resume offset: 198122980 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For scripting and convenience the option \fI\-r\fP will print just the offset: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs inspect\-internal map\-swapfile \-r swapfile +198122980 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The command \fBmap\-swapfile\fP also verifies all the requirements, i.e. no holes, +single device, etc. +.SH TROUBLESHOOTING +.sp +If the swapfile activation fails please verify that you followed all the steps +above or check the system log (e.g. \fBdmesg\fP or \fBjournalctl\fP) for more +information. +.sp +Notably, the \fBswapon\fP utility exits with a message that does not say what +failed: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# swapon /path/swapfile +swapon: /path/swapfile: swapon failed: Invalid argument +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The specific reason is likely to be printed to the system log by the btrfs +module: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# journalctl \-t kernel | grep swapfile +kernel: BTRFS warning (device sda): swapfile must have single data profile +.ft P +.fi +.UNINDENT +.UNINDENT +.SH CHECKSUM ALGORITHMS +.sp +Data and metadata are checksummed by default, the checksum is calculated before +write and verified after reading the blocks from devices. The whole metadata +block has a checksum stored inline in the b\-tree node header, each data block +has a detached checksum stored in the checksum tree. +.sp +There are several checksum algorithms supported. The default and backward +compatible is \fIcrc32c\fP\&. Since kernel 5.5 there are three more with different +characteristics and trade\-offs regarding speed and strength. The following list +may help you to decide which one to select. +.INDENT 0.0 +.TP +.B CRC32C (32bit digest) +default, best backward compatibility, very fast, modern CPUs have +instruction\-level support, not collision\-resistant but still good error +detection capabilities +.TP +.B XXHASH (64bit digest) +can be used as CRC32C successor, very fast, optimized for modern CPUs utilizing +instruction pipelining, good collision resistance and error detection +.TP +.B SHA256 (256bit digest) +a cryptographic\-strength hash, relatively slow but with possible CPU +instruction acceleration or specialized hardware cards, FIPS certified and +in wide use +.TP +.B BLAKE2b (256bit digest) +a cryptographic\-strength hash, relatively fast with possible CPU acceleration +using SIMD extensions, not standardized but based on BLAKE which was a SHA3 +finalist, in wide use, the algorithm used is BLAKE2b\-256 that\(aqs optimized for +64bit platforms +.UNINDENT +.sp +The \fIdigest size\fP affects overall size of data block checksums stored in the +filesystem. The metadata blocks have a fixed area up to 256 bits (32 bytes), so +there\(aqs no increase. Each data block has a separate checksum stored, with +additional overhead of the b\-tree leaves. +.sp +Approximate relative performance of the algorithms, measured against CRC32C +using implementations on a 11th gen 3.6GHz intel CPU: +.TS +center; +|l|l|l|l|. +_ +T{ +Digest +T} T{ +Cycles/4KiB +T} T{ +Ratio +T} T{ +Implementation +T} +_ +T{ +CRC32C +T} T{ +470 +T} T{ +1.00 +T} T{ +CPU instruction, PCL combination +T} +_ +T{ +XXHASH +T} T{ +870 +T} T{ +1.9 +T} T{ +reference impl. +T} +_ +T{ +SHA256 +T} T{ +7600 +T} T{ +16 +T} T{ +libgcrypt +T} +_ +T{ +SHA256 +T} T{ +8500 +T} T{ +18 +T} T{ +openssl +T} +_ +T{ +SHA256 +T} T{ +8700 +T} T{ +18 +T} T{ +botan +T} +_ +T{ +SHA256 +T} T{ +32000 +T} T{ +68 +T} T{ +builtin, CPU instruction +T} +_ +T{ +SHA256 +T} T{ +37000 +T} T{ +78 +T} T{ +libsodium +T} +_ +T{ +SHA256 +T} T{ +78000 +T} T{ +166 +T} T{ +builtin, reference impl. +T} +_ +T{ +BLAKE2b +T} T{ +10000 +T} T{ +21 +T} T{ +builtin/AVX2 +T} +_ +T{ +BLAKE2b +T} T{ +10900 +T} T{ +23 +T} T{ +libgcrypt +T} +_ +T{ +BLAKE2b +T} T{ +13500 +T} T{ +29 +T} T{ +builtin/SSE41 +T} +_ +T{ +BLAKE2b +T} T{ +13700 +T} T{ +29 +T} T{ +libsodium +T} +_ +T{ +BLAKE2b +T} T{ +14100 +T} T{ +30 +T} T{ +openssl +T} +_ +T{ +BLAKE2b +T} T{ +14500 +T} T{ +31 +T} T{ +kcapi +T} +_ +T{ +BLAKE2b +T} T{ +14500 +T} T{ +34 +T} T{ +builtin, reference impl. +T} +_ +.TE +.sp +Many kernels are configured with SHA256 as built\-in and not as a module. +The accelerated versions are however provided by the modules and must be loaded +explicitly (\fBmodprobe sha256\fP) before mounting the filesystem to make use of +them. You can check in \fB/sys/fs/btrfs/FSID/checksum\fP which one is used. If you +see \fIsha256\-generic\fP, then you may want to unmount and mount the filesystem +again, changing that on a mounted filesystem is not possible. +Check the file \fB/proc/crypto\fP, when the implementation is built\-in, you\(aqd find +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +name : sha256 +driver : sha256\-generic +module : kernel +priority : 100 +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +while accelerated implementation is e.g. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +name : sha256 +driver : sha256\-avx2 +module : sha256_ssse3 +priority : 170 +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.SH COMPRESSION +.sp +Btrfs supports transparent file compression. There are three algorithms +available: ZLIB, LZO and ZSTD (since v4.14), with various levels. +The compression happens on the level of file extents and the algorithm is +selected by file property, mount option or by a defrag command. +You can have a single btrfs mount point that has some files that are +uncompressed, some that are compressed with LZO, some with ZLIB, for instance +(though you may not want it that way, it is supported). +.sp +Once the compression is set, all newly written data will be compressed, i.e. +existing data are untouched. Data are split into smaller chunks (128KiB) before +compression to make random rewrites possible without a high performance hit. Due +to the increased number of extents the metadata consumption is higher. The +chunks are compressed in parallel. +.sp +The algorithms can be characterized as follows regarding the speed/ratio +trade\-offs: +.INDENT 0.0 +.TP +.B ZLIB +.INDENT 7.0 +.IP \(bu 2 +slower, higher compression ratio +.IP \(bu 2 +levels: 1 to 9, mapped directly, default level is 3 +.IP \(bu 2 +good backward compatibility +.UNINDENT +.TP +.B LZO +.INDENT 7.0 +.IP \(bu 2 +faster compression and decompression than ZLIB, worse compression ratio, designed to be fast +.IP \(bu 2 +no levels +.IP \(bu 2 +good backward compatibility +.UNINDENT +.TP +.B ZSTD +.INDENT 7.0 +.IP \(bu 2 +compression comparable to ZLIB with higher compression/decompression speeds and different ratio +.IP \(bu 2 +levels: 1 to 15, mapped directly (higher levels are not available) +.IP \(bu 2 +since 4.14, levels since 5.1 +.UNINDENT +.UNINDENT +.sp +The differences depend on the actual data set and cannot be expressed by a +single number or recommendation. Higher levels consume more CPU time and may +not bring a significant improvement, lower levels are close to real time. +.SH HOW TO ENABLE COMPRESSION +.sp +Typically the compression can be enabled on the whole filesystem, specified for +the mount point. Note that the compression mount options are shared among all +mounts of the same filesystem, either bind mounts or subvolume mounts. +Please refer to \fI\%btrfs(5)\fP section +\fI\%MOUNT OPTIONS\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ mount \-o compress=zstd /dev/sdx /mnt +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will enable the \fBzstd\fP algorithm on the default level (which is 3). +The level can be specified manually too like \fBzstd:3\fP\&. Higher levels compress +better at the cost of time. This in turn may cause increased write latency, low +levels are suitable for real\-time compression and on reasonably fast CPU don\(aqt +cause noticeable performance drops. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ btrfs filesystem defrag \-czstd file +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The command above will start defragmentation of the whole \fIfile\fP and apply +the compression, regardless of the mount option. (Note: specifying level is not +yet implemented). The compression algorithm is not persistent and applies only +to the defragmentation command, for any other writes other compression settings +apply. +.sp +Persistent settings on a per\-file basis can be set in two ways: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ chattr +c file +$ btrfs property set file compression zstd +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The first command is using legacy interface of file attributes inherited from +ext2 filesystem and is not flexible, so by default the \fIzlib\fP compression is +set. The other command sets a property on the file with the given algorithm. +(Note: setting level that way is not yet implemented.) +.SH COMPRESSION LEVELS +.sp +The level support of ZLIB has been added in v4.14, LZO does not support levels +(the kernel implementation provides only one), ZSTD level support has been added +in v5.1. +.sp +There are 9 levels of ZLIB supported (1 to 9), mapping 1:1 from the mount option +to the algorithm defined level. The default is level 3, which provides the +reasonably good compression ratio and is still reasonably fast. The difference +in compression gain of levels 7, 8 and 9 is comparable but the higher levels +take longer. +.sp +The ZSTD support includes levels 1 to 15, a subset of full range of what ZSTD +provides. Levels 1\-3 are real\-time, 4\-8 slower with improved compression and +9\-15 try even harder though the resulting size may not be significantly improved. +.sp +Level 0 always maps to the default. The compression level does not affect +compatibility. +.SH INCOMPRESSIBLE DATA +.sp +Files with already compressed data or with data that won\(aqt compress well with +the CPU and memory constraints of the kernel implementations are using a simple +decision logic. If the first portion of data being compressed is not smaller +than the original, the compression of the file is disabled \-\- unless the +filesystem is mounted with \fIcompress\-force\fP\&. In that case compression will +always be attempted on the file only to be later discarded. This is not optimal +and subject to optimizations and further development. +.sp +If a file is identified as incompressible, a flag is set (\fINOCOMPRESS\fP) and it\(aqs +sticky. On that file compression won\(aqt be performed unless forced. The flag +can be also set by \fBchattr +m\fP (since e2fsprogs 1.46.2) or by properties with +value \fIno\fP or \fInone\fP\&. Empty value will reset it to the default that\(aqs currently +applicable on the mounted filesystem. +.sp +There are two ways to detect incompressible data: +.INDENT 0.0 +.IP \(bu 2 +actual compression attempt \- data are compressed, if the result is not smaller, +it\(aqs discarded, so this depends on the algorithm and level +.IP \(bu 2 +pre\-compression heuristics \- a quick statistical evaluation on the data is +performed and based on the result either compression is performed or skipped, +the NOCOMPRESS bit is not set just by the heuristic, only if the compression +algorithm does not make an improvement +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ lsattr file +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-m file +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Using the forcing compression is not recommended, the heuristics are +supposed to decide that and compression algorithms internally detect +incompressible data too. +.SH PRE-COMPRESSION HEURISTICS +.sp +The heuristics aim to do a few quick statistical tests on the compressed data +in order to avoid probably costly compression that would turn out to be +inefficient. Compression algorithms could have internal detection of +incompressible data too but this leads to more overhead as the compression is +done in another thread and has to write the data anyway. The heuristic is +read\-only and can utilize cached memory. +.sp +The tests performed based on the following: data sampling, long repeated +pattern detection, byte frequency, Shannon entropy. +.SH COMPATIBILITY +.sp +Compression is done using the COW mechanism so it\(aqs incompatible with +\fInodatacow\fP\&. Direct IO works on compressed files but will fall back to buffered +writes and leads to recompression. Currently \fInodatasum\fP and compression don\(aqt +work together. +.sp +The compression algorithms have been added over time so the version +compatibility should be also considered, together with other tools that may +access the compressed data like bootloaders. +.SH SYSFS INTERFACE +.sp +Btrfs has a sysfs interface to provide extra knobs. +.sp +The top level path is \fB/sys/fs/btrfs/\fP, and the main directory layout is the following: +.TS +center; +|l|l|l|. +_ +T{ +Relative Path +T} T{ +Description +T} T{ +Version +T} +_ +T{ +features/ +T} T{ +All supported features +T} T{ +3.14+ +T} +_ +T{ +/ +T} T{ +Mounted fs UUID +T} T{ +3.14+ +T} +_ +T{ +/allocation/ +T} T{ +Space allocation info +T} T{ +3.14+ +T} +_ +T{ +/features/ +T} T{ +Features of the filesystem +T} T{ +3.14+ +T} +_ +T{ +/devices// +T} T{ +Symlink to each block device sysfs +T} T{ +5.6+ +T} +_ +T{ +/devinfo// +T} T{ +Btrfs specific info for each device +T} T{ +5.6+ +T} +_ +T{ +/qgroups/ +T} T{ +Global qgroup info +T} T{ +5.9+ +T} +_ +T{ +/qgroups/_/ +T} T{ +Info for each qgroup +T} T{ +5.9+ +T} +_ +T{ +/discard/ +T} T{ +Discard stats and tunables +T} T{ +6.1+ +T} +_ +.TE +.sp +For \fB/sys/fs/btrfs/features/\fP directory, each file means a supported feature +for the current kernel. +.sp +For \fB/sys/fs/btrfs//features/\fP directory, each file means an enabled +feature for the mounted filesystem. +.sp +The features shares the same name in section +\fI\%FILESYSTEM FEATURES\fP\&. +.sp +Files in \fB/sys/fs/btrfs//\fP directory are: +.INDENT 0.0 +.TP +.B bg_reclaim_threshold +(RW, since: 5.19) +.sp +Used space percentage of total device space to start auto block group claim. +Mostly for zoned devices. +.TP +.B checksum +(RO, since: 5.5) +.sp +The checksum used for the mounted filesystem. +This includes both the checksum type (see section +\fI\%CHECKSUM ALGORITHMS\fP) +and the implemented driver (mostly shows if it\(aqs hardware accelerated). +.TP +.B clone_alignment +(RO, since: 3.16) +.sp +The bytes alignment for \fIclone\fP and \fIdedupe\fP ioctls. +.TP +.B commit_stats +(RW, since: 6.0) +.sp +The performance statistics for btrfs transaction commit. +Mostly for debug purposes. +.sp +Writing into this file will reset the maximum commit duration to +the input value. +.TP +.B exclusive_operation +(RO, since: 5.10) +.sp +Shows the running exclusive operation. +Check section +\fI\%FILESYSTEM EXCLUSIVE OPERATIONS\fP +for details. +.TP +.B generation +(RO, since: 5.11) +.sp +Show the generation of the mounted filesystem. +.TP +.B label +(RW, since: 3.14) +.sp +Show the current label of the mounted filesystem. +.TP +.B metadata_uuid +(RO, since: 5.0) +.sp +Shows the metadata uuid of the mounted filesystem. +Check \fImetadata_uuid\fP feature for more details. +.TP +.B nodesize +(RO, since: 3.14) +.sp +Show the nodesize of the mounted filesystem. +.TP +.B quota_override +(RW, since: 4.13) +.sp +Shows the current quota override status. +0 means no quota override. +1 means quota override, quota can ignore the existing limit settings. +.TP +.B read_policy +(RW, since: 5.11) +.sp +Shows the current balance policy for reads. +Currently only \(dqpid\(dq (balance using pid value) is supported. +.TP +.B sectorsize +(RO, since: 3.14) +.sp +Shows the sectorsize of the mounted filesystem. +.UNINDENT +.sp +Files and directories in \fB/sys/fs/btrfs//allocations\fP directory are: +.INDENT 0.0 +.TP +.B global_rsv_reserved +(RO, since: 3.14) +.sp +The used bytes of the global reservation. +.TP +.B global_rsv_size +(RO, since: 3.14) +.sp +The total size of the global reservation. +.TP +.B \fIdata/\fP, \fImetadata/\fP and \fIsystem/\fP directories +(RO, since: 5.14) +.sp +Space info accounting for the 3 chunk types. +Mostly for debug purposes. +.UNINDENT +.sp +Files in \fB/sys/fs/btrfs//allocations/\fP\fIdata,metadata,system\fP directory are: +.INDENT 0.0 +.TP +.B bg_reclaim_threshold +(RW, since: 5.19) +.sp +Reclaimable space percentage of block group\(aqs size (excluding +permanently unusable space) to reclaim the block group. +Can be used on regular or zoned devices. +.TP +.B chunk_size +(RW, since: 6.0) +.sp +Shows the chunk size. Can be changed for data and metadata. +Cannot be set for zoned devices. +.UNINDENT +.sp +Files in \fB/sys/fs/btrfs//devinfo/\fP directory are: +.INDENT 0.0 +.TP +.B error_stats: +(RO, since: 5.14) +.sp +Shows all the history error numbers of the device. +.TP +.B fsid: +(RO, since: 5.17) +.sp +Shows the fsid which the device belongs to. +It can be different than the \fI\fP if it\(aqs a seed device. +.TP +.B in_fs_metadata +(RO, since: 5.6) +.sp +Shows whether we have found the device. +Should always be 1, as if this turns to 0, the \fI\fP directory +would get removed automatically. +.TP +.B missing +(RO, since: 5.6) +.sp +Shows whether the device is missing. +.TP +.B replace_target +(RO, since: 5.6) +.sp +Shows whether the device is the replace target. +If no dev\-replace is running, this value should be 0. +.TP +.B scrub_speed_max +(RW, since: 5.14) +.sp +Shows the scrub speed limit for this device. The unit is Bytes/s. +0 means no limit. +.TP +.B writeable +(RO, since: 5.6) +.sp +Show if the device is writeable. +.UNINDENT +.sp +Files in \fB/sys/fs/btrfs//qgroups/\fP directory are: +.INDENT 0.0 +.TP +.B enabled +(RO, since: 6.1) +.sp +Shows if qgroup is enabled. +Also, if qgroup is disabled, the \fIqgroups\fP directory would +be removed automatically. +.TP +.B inconsistent +(RO, since: 6.1) +.sp +Shows if the qgroup numbers are inconsistent. +If 1, it\(aqs recommended to do a qgroup rescan. +.TP +.B drop_subtree_threshold +(RW, since: 6.1) +.sp +Shows the subtree drop threshold to automatically mark qgroup inconsistent. +.sp +When dropping large subvolumes with qgroup enabled, there would be a huge +load for qgroup accounting. +If we have a subtree whose level is larger than or equal to this value, +we will not trigger qgroup account at all, but mark qgroup inconsistent to +avoid the huge workload. +.sp +Default value is 8, where no subtree drop can trigger qgroup. +.sp +Lower value can reduce qgroup workload, at the cost of extra qgroup rescan +to re\-calculate the numbers. +.UNINDENT +.sp +Files in \fB/sys/fs/btrfs//_/\fP directory are: +.INDENT 0.0 +.TP +.B exclusive +(RO, since: 5.9) +.sp +Shows the exclusively owned bytes of the qgroup. +.TP +.B limit_flags +(RO, since: 5.9) +.sp +Shows the numeric value of the limit flags. +If 0, means no limit implied. +.TP +.B max_exclusive +(RO, since: 5.9) +.sp +Shows the limits on exclusively owned bytes. +.TP +.B max_referenced +(RO, since: 5.9) +.sp +Shows the limits on referenced bytes. +.TP +.B referenced +(RO, since: 5.9) +.sp +Shows the referenced bytes of the qgroup. +.TP +.B rsv_data +(RO, since: 5.9) +.sp +Shows the reserved bytes for data. +.TP +.B rsv_meta_pertrans +(RO, since: 5.9) +.sp +Shows the reserved bytes for per transaction metadata. +.TP +.B rsv_meta_prealloc +(RO, since: 5.9) +.sp +Shows the reserved bytes for preallocated metadata. +.UNINDENT +.sp +Files in \fB/sys/fs/btrfs//discard/\fP directory are: +.INDENT 0.0 +.TP +.B discardable_bytes +(RO, since: 6.1) +.sp +Shows amount of bytes that can be discarded in the async discard and +nodiscard mode. +.TP +.B discardable_extents +(RO, since: 6.1) +.sp +Shows number of extents to be discarded in the async discard and +nodiscard mode. +.TP +.B discard_bitmap_bytes +(RO, since: 6.1) +.sp +Shows amount of discarded bytes from data tracked as bitmaps. +.TP +.B discard_extent_bytes +(RO, since: 6.1) +.sp +Shows amount of discarded extents from data tracked as bitmaps. +.TP +.B discard_bytes_saved +(RO, since: 6.1) +.sp +Shows the amount of bytes that were reallocated without being discarded. +.TP +.B kbps_limit +(RW, since: 6.1) +.sp +Tunable limit of kilobytes per second issued as discard IO in the async +discard mode. +.TP +.B iops_limit +(RW, since: 6.1) +.sp +Tunable limit of number of discard IO operations to be issued in the +async discard mode. +.TP +.B max_discard_size +(RW, since: 6.1) +.sp +Tunable limit for size of one IO discard request. +.UNINDENT +.SH FILESYSTEM EXCLUSIVE OPERATIONS +.sp +There are several operations that affect the whole filesystem and cannot be run +in parallel. Attempt to start one while another is running will fail (see +exceptions below). +.sp +Since kernel 5.10 the currently running operation can be obtained from +\fB/sys/fs/UUID/exclusive_operation\fP with following values and operations: +.INDENT 0.0 +.IP \(bu 2 +balance +.IP \(bu 2 +balance paused (since 5.17) +.IP \(bu 2 +device add +.IP \(bu 2 +device delete +.IP \(bu 2 +device replace +.IP \(bu 2 +resize +.IP \(bu 2 +swapfile activate +.IP \(bu 2 +none +.UNINDENT +.sp +Enqueuing is supported for several btrfs subcommands so they can be started +at once and then serialized. +.sp +There\(aqs an exception when a paused balance allows to start a device add +operation as they don\(aqt really collide and this can be used to add more space +for the balance to finish. +.SH FILESYSTEM LIMITS +.INDENT 0.0 +.TP +.B maximum file name length +255 +.sp +This limit is imposed by Linux VFS, the structures of BTRFS could store +larger file names. +.TP +.B maximum symlink target length +depends on the \fInodesize\fP value, for 4KiB it\(aqs 3949 bytes, for larger nodesize +it\(aqs 4095 due to the system limit PATH_MAX +.sp +The symlink target may not be a valid path, i.e. the path name components +can exceed the limits (NAME_MAX), there\(aqs no content validation at \fBsymlink(3)\fP +creation. +.TP +.B maximum number of inodes +2\s-2\u64\d\s0 but depends on the available metadata space as the inodes are created +dynamically +.sp +Each subvolume is an independent namespace of inodes and thus their +numbers, so the limit is per subvolume, not for the whole filesystem. +.TP +.B inode numbers +minimum number: 256 (for subvolumes), regular files and directories: 257, +maximum number: (2\s-2\u64\d\s0 \- 256) +.sp +The inode numbers that can be assigned to user created files are from +the whole 64bit space except first 256 and last 256 in that range that +are reserved for internal b\-tree identifiers. +.TP +.B maximum file length +inherent limit of BTRFS is 2\s-2\u64\d\s0 (16 EiB) but the practical +limit of Linux VFS is 2\s-2\u63\d\s0 (8 EiB) +.TP +.B maximum number of subvolumes +the subvolume ids can go up to 2\s-2\u48\d\s0 but the number of actual subvolumes +depends on the available metadata space +.sp +The space consumed by all subvolume metadata includes bookkeeping of +shared extents can be large (MiB, GiB). The range is not the full 64bit +range because of qgroups that use the upper 16 bits for another +purposes. +.TP +.B maximum number of hardlinks of a file in a directory +65536 when the \fIextref\fP feature is turned on during mkfs (default), roughly +100 otherwise and depends on file name length that fits into one metadata node +.TP +.B minimum filesystem size +the minimal size of each device depends on the \fImixed\-bg\fP feature, without that +(the default) it\(aqs about 109MiB, with mixed\-bg it\(aqs is 16MiB +.UNINDENT +.SH BOOTLOADER SUPPORT +.sp +GRUB2 (\fI\%https://www.gnu.org/software/grub\fP) has the most advanced support of +booting from BTRFS with respect to features. +.sp +U\-Boot (\fI\%https://www.denx.de/wiki/U\-Boot/\fP) has decent support for booting but +not all BTRFS features are implemented, check the documentation. +.sp +In general, the first 1MiB on each device is unused with the exception of +primary superblock that is on the offset 64KiB and spans 4KiB. The rest can be +freely used by bootloaders or for other system information. Note that booting +from a filesystem on \fI\%zoned device\fP is not supported. +.SH FILE ATTRIBUTES +.sp +The btrfs filesystem supports setting file attributes or flags. Note there are +old and new interfaces, with confusing names. The following list should clarify +that: +.INDENT 0.0 +.IP \(bu 2 +\fIattributes\fP: \fBchattr(1)\fP or \fBlsattr(1)\fP utilities (the ioctls are +FS_IOC_GETFLAGS and FS_IOC_SETFLAGS), due to the ioctl names the attributes +are also called flags +.IP \(bu 2 +\fIxflags\fP: to distinguish from the previous, it\(aqs extended flags, with tunable +bits similar to the attributes but extensible and new bits will be added in +the future (the ioctls are FS_IOC_FSGETXATTR and FS_IOC_FSSETXATTR but they +are not related to extended attributes that are also called xattrs), there\(aqs +no standard tool to change the bits, there\(aqs support in \fBxfs_io(8)\fP as +command \fBxfs_io \-c chattr\fP +.UNINDENT +.SS Attributes +.INDENT 0.0 +.TP +.B a +\fIappend only\fP, new writes are always written at the end of the file +.TP +.B A +\fIno atime updates\fP +.TP +.B c +\fIcompress data\fP, all data written after this attribute is set will be compressed. +Please note that compression is also affected by the mount options or the parent +directory attributes. +.sp +When set on a directory, all newly created files will inherit this attribute. +This attribute cannot be set with \(aqm\(aq at the same time. +.TP +.B C +\fIno copy\-on\-write\fP, file data modifications are done in\-place +.sp +When set on a directory, all newly created files will inherit this attribute. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Due to implementation limitations, this flag can be set/unset only on +empty files. +.UNINDENT +.UNINDENT +.TP +.B d +\fIno dump\fP, makes sense with 3rd party tools like \fBdump(8)\fP, on BTRFS the +attribute can be set/unset but no other special handling is done +.TP +.B D +\fIsynchronous directory updates\fP, for more details search \fBopen(2)\fP for \fIO_SYNC\fP +and \fIO_DSYNC\fP +.TP +.B i +\fIimmutable\fP, no file data and metadata changes allowed even to the root user as +long as this attribute is set (obviously the exception is unsetting the attribute) +.TP +.B m +\fIno compression\fP, permanently turn off compression on the given file. Any +compression mount options will not affect this file. (\fBchattr\fP support added in +1.46.2) +.sp +When set on a directory, all newly created files will inherit this attribute. +This attribute cannot be set with \fIc\fP at the same time. +.TP +.B S +\fIsynchronous updates\fP, for more details search \fBopen(2)\fP for \fIO_SYNC\fP and +\fIO_DSYNC\fP +.UNINDENT +.sp +No other attributes are supported. For the complete list please refer to the +\fBchattr(1)\fP manual page. +.SS XFLAGS +.sp +There\(aqs an overlap of letters assigned to the bits with the attributes, this list +refers to what \fBxfs_io(8)\fP provides: +.INDENT 0.0 +.TP +.B i +\fIimmutable\fP, same as the attribute +.TP +.B a +\fIappend only\fP, same as the attribute +.TP +.B s +\fIsynchronous updates\fP, same as the attribute \fIS\fP +.TP +.B A +\fIno atime updates\fP, same as the attribute +.TP +.B d +\fIno dump\fP, same as the attribute +.UNINDENT +.SH ZONED MODE +.sp +Since version 5.12 btrfs supports so called \fIzoned mode\fP\&. This is a special +on\-disk format and allocation/write strategy that\(aqs friendly to zoned devices. +In short, a device is partitioned into fixed\-size zones and each zone can be +updated by append\-only manner, or reset. As btrfs has no fixed data structures, +except the super blocks, the zoned mode only requires block placement that +follows the device constraints. You can learn about the whole architecture at +\fI\%https://zonedstorage.io\fP . +.sp +The devices are also called SMR/ZBC/ZNS, in \fIhost\-managed\fP mode. Note that +there are devices that appear as non\-zoned but actually are, this is +\fIdrive\-managed\fP and using zoned mode won\(aqt help. +.sp +The zone size depends on the device, typical sizes are 256MiB or 1GiB. In +general it must be a power of two. Emulated zoned devices like \fInull_blk\fP allow +to set various zone sizes. +.SS Requirements, limitations +.INDENT 0.0 +.IP \(bu 2 +all devices must have the same zone size +.IP \(bu 2 +maximum zone size is 8GiB +.IP \(bu 2 +minimum zone size is 4MiB +.IP \(bu 2 +mixing zoned and non\-zoned devices is possible, the zone writes are emulated, +but this is namely for testing +.IP \(bu 2 +the super block is handled in a special way and is at different locations than on a non\-zoned filesystem: +.INDENT 2.0 +.IP \(bu 2 +primary: 0B (and the next two zones) +.IP \(bu 2 +secondary: 512GiB (and the next two zones) +.IP \(bu 2 +tertiary: 4TiB (4096GiB, and the next two zones) +.UNINDENT +.UNINDENT +.SS Incompatible features +.sp +The main constraint of the zoned devices is lack of in\-place update of the data. +This is inherently incompatible with some features: +.INDENT 0.0 +.IP \(bu 2 +NODATACOW \- overwrite in\-place, cannot create such files +.IP \(bu 2 +fallocate \- preallocating space for in\-place first write +.IP \(bu 2 +mixed\-bg \- unordered writes to data and metadata, fixing that means using +separate data and metadata block groups +.IP \(bu 2 +booting \- the zone at offset 0 contains superblock, resetting the zone would +destroy the bootloader data +.UNINDENT +.sp +Initial support lacks some features but they\(aqre planned: +.INDENT 0.0 +.IP \(bu 2 +only single (data, metadata) and DUP (metadata) profile is supported +.IP \(bu 2 +fstrim \- due to dependency on free space cache v1 +.UNINDENT +.SS Super block +.sp +As said above, super block is handled in a special way. In order to be crash +safe, at least one zone in a known location must contain a valid superblock. +This is implemented as a ring buffer in two consecutive zones, starting from +known offsets 0B, 512GiB and 4TiB. +.sp +The values are different than on non\-zoned devices. Each new super block is +appended to the end of the zone, once it\(aqs filled, the zone is reset and writes +continue to the next one. Looking up the latest super block needs to read +offsets of both zones and determine the last written version. +.sp +The amount of space reserved for super block depends on the zone size. The +secondary and tertiary copies are at distant offsets as the capacity of the +devices is expected to be large, tens of terabytes. Maximum zone size supported +is 8GiB, which would mean that e.g. offset 0\-16GiB would be reserved just for +the super block on a hypothetical device of that zone size. This is wasteful +but required to guarantee crash safety. +.SS Devices +.SS Real hardware +.sp +The WD Ultrastar series 600 advertises HM\-SMR, i.e. the host\-managed zoned +mode. There are two more: DA (device managed, no zoned information exported to +the system), HA (host aware, can be used as regular disk but zoned writes +improve performance). There are not many devices available at the moment, the +information about exact zoned mode is hard to find, check data sheets or +community sources gathering information from real devices. +.sp +Note: zoned mode won\(aqt work with DM\-SMR disks. +.INDENT 0.0 +.IP \(bu 2 +Ultrastar® DC ZN540 NVMe ZNS SSD (\fI\%product +brief\fP) +.UNINDENT +.SS Emulated: null_blk +.sp +The driver \fInull_blk\fP provides memory backed device and is suitable for +testing. There are some quirks setting up the devices. The module must be +loaded with \fInr_devices=0\fP or the numbering of device nodes will be offset. The +\fIconfigfs\fP must be mounted at \fI/sys/kernel/config\fP and the administration of +the null_blk devices is done in \fI/sys/kernel/config/nullb\fP\&. The device nodes +are named like \fB/dev/nullb0\fP and are numbered sequentially. NOTE: the device +name may be different than the named directory in sysfs! +.sp +Setup: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +modprobe\ configfs +modprobe\ null_blk\ nr_devices=0 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Create a device \fImydev\fP, assuming no other previously created devices, size is +2048MiB, zone size 256MiB. There are more tunable parameters, this is a minimal +example taking defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cd\ /sys/kernel/config/nullb/ +mkdir\ mydev +cd\ mydev +echo\ 2048\ >\ size +echo\ 1\ >\ zoned +echo\ 1\ >\ memory_backed +echo\ 256\ >\ zone_size +echo\ 1\ >\ power +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will create a device \fB/dev/nullb0\fP and the value of file \fIindex\fP will +match the ending number of the device node. +.sp +Remove the device: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +rmdir\ /sys/kernel/config/nullb/mydev +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then continue with \fBmkfs.btrfs /dev/nullb0\fP, the zoned mode is auto\-detected. +.sp +For convenience, there\(aqs a script wrapping the basic null_blk management operations +\fI\%https://github.com/kdave/nullb.git\fP, the above commands become: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nullb setup +nullb create \-s 2g \-z 256 +mkfs.btrfs /dev/nullb0 +\&... +nullb rm nullb0 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Emulated: TCMU runner +.sp +TCMU is a framework to emulate SCSI devices in userspace, providing various +backends for the storage, with zoned support as well. A file\-backed zoned +device can provide more options for larger storage and zone size. Please follow +the instructions at \fI\%https://zonedstorage.io/projects/tcmu\-runner/\fP . +.SS Compatibility, incompatibility +.INDENT 0.0 +.IP \(bu 2 +the feature sets an incompat bit and requires new kernel to access the +filesystem (for both read and write) +.IP \(bu 2 +superblock needs to be handled in a special way, there are still 3 copies +but at different offsets (0, 512GiB, 4TiB) and the 2 consecutive zones are a +ring buffer of the superblocks, finding the latest one needs reading it from +the write pointer or do a full scan of the zones +.IP \(bu 2 +mixing zoned and non zoned devices is possible (zones are emulated) but is +recommended only for testing +.IP \(bu 2 +mixing zoned devices with different zone sizes is not possible +.IP \(bu 2 +zone sizes must be power of two, zone sizes of real devices are e.g. 256MiB +or 1GiB, larger size is expected, maximum zone size supported by btrfs is +8GiB +.UNINDENT +.SS Status, stability, reporting bugs +.sp +The zoned mode has been released in 5.12 and there are still some rough edges +and corner cases one can hit during testing. Please report bugs to +\fI\%https://github.com/naota/linux/issues/\fP . +.SS References +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://zonedstorage.io\fP +.INDENT 2.0 +.IP \(bu 2 +\fI\%https://zonedstorage.io/projects/libzbc/\fP \-\- \fIlibzbc\fP is library and set +of tools to directly manipulate devices with ZBC/ZAC support +.IP \(bu 2 +\fI\%https://zonedstorage.io/projects/libzbd/\fP \-\- \fIlibzbd\fP uses the kernel +provided zoned block device interface based on the ioctl() system calls +.UNINDENT +.IP \(bu 2 +\fI\%https://hddscan.com/blog/2020/hdd\-wd\-smr.html\fP \-\- some details about exact device types +.IP \(bu 2 +\fI\%https://lwn.net/Articles/853308/\fP \-\- \fIBtrfs on zoned block devices\fP +.IP \(bu 2 +\fI\%https://www.usenix.org/conference/vault20/presentation/bjorling\fP \-\- Zone +Append: A New Way of Writing to Zoned Storage +.UNINDENT +.SH CONTROL DEVICE +.sp +There\(aqs a character special device \fB/dev/btrfs\-control\fP with major and minor +numbers 10 and 234 (the device can be found under the \fImisc\fP category). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ls \-l /dev/btrfs\-control +crw\-\-\-\-\-\-\- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs\-control +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The device accepts some ioctl calls that can perform following actions on the +filesystem module: +.INDENT 0.0 +.IP \(bu 2 +scan devices for btrfs filesystem (i.e. to let multi\-device filesystems mount +automatically) and register them with the kernel module +.IP \(bu 2 +similar to scan, but also wait until the device scanning process is finished +for a given filesystem +.IP \(bu 2 +get the supported features (can be also found under \fB/sys/fs/btrfs/features\fP) +.UNINDENT +.sp +The device is created when btrfs is initialized, either as a module or a +built\-in functionality and makes sense only in connection with that. Running +e.g. mkfs without the module loaded will not register the device and will +probably warn about that. +.sp +In rare cases when the module is loaded but the device is not present (most +likely accidentally deleted), it\(aqs possible to recreate it by +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# mknod \-\-mode=600 /dev/btrfs\-control c 10 234 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +or (since 5.11) by a convenience command +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs rescue create\-control\-device +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The control device is not strictly required but the device scanning will not +work and a workaround would need to be used to mount a multi\-device filesystem. +The mount option \fIdevice\fP can trigger the device scanning during mount, see +also \fBbtrfs device scan\fP\&. +.SH FILESYSTEM WITH MULTIPLE PROFILES +.sp +It is possible that a btrfs filesystem contains multiple block group profiles +of the same type. This could happen when a profile conversion using balance +filters is interrupted (see \fI\%btrfs\-balance(8)\fP). Some +\fBbtrfs\fP commands perform +a test to detect this kind of condition and print a warning like this: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +WARNING: Multiple block group profiles detected, see \(aqman btrfs(5)\(aq. +WARNING: Data: single, raid1 +WARNING: Metadata: single, raid1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The corresponding output of \fBbtrfs filesystem df\fP might look like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +WARNING: Multiple block group profiles detected, see \(aqman btrfs(5)\(aq. +WARNING: Data: single, raid1 +WARNING: Metadata: single, raid1 +Data, RAID1: total=832.00MiB, used=0.00B +Data, single: total=1.63GiB, used=0.00B +System, single: total=4.00MiB, used=16.00KiB +Metadata, single: total=8.00MiB, used=112.00KiB +Metadata, RAID1: total=64.00MiB, used=32.00KiB +GlobalReserve, single: total=16.25MiB, used=0.00B +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +There\(aqs more than one line for type \fIData\fP and \fIMetadata\fP, while the profiles +are \fIsingle\fP and \fIRAID1\fP\&. +.sp +This state of the filesystem OK but most likely needs the user/administrator to +take an action and finish the interrupted tasks. This cannot be easily done +automatically, also the user knows the expected final profiles. +.sp +In the example above, the filesystem started as a single device and \fIsingle\fP +block group profile. Then another device was added, followed by balance with +\fIconvert=raid1\fP but for some reason hasn\(aqt finished. Restarting the balance +with \fIconvert=raid1\fP will continue and end up with filesystem with all block +group profiles \fIRAID1\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you\(aqre familiar with balance filters, you can use +\fIconvert=raid1,profiles=single,soft\fP, which will take only the unconverted +\fIsingle\fP profiles and convert them to \fIraid1\fP\&. This may speed up the conversion +as it would not try to rewrite the already convert \fIraid1\fP profiles. +.UNINDENT +.UNINDENT +.sp +Having just one profile is desired as this also clearly defines the profile of +newly allocated block groups, otherwise this depends on internal allocation +policy. When there are multiple profiles present, the order of selection is +RAID56, RAID10, RAID1, RAID0 as long as the device number constraints are +satisfied. +.sp +Commands that print the warning were chosen so they\(aqre brought to user +attention when the filesystem state is being changed in that regard. This is: +\fBdevice add\fP, \fBdevice delete\fP, \fBbalance cancel\fP, \fBbalance pause\fP\&. Commands +that report space usage: \fBfilesystem df\fP, \fBdevice usage\fP\&. The command +\fBfilesystem usage\fP provides a line in the overall summary: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Multiple profiles: yes (data, metadata) +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEEDING DEVICE +.sp +The COW mechanism and multiple devices under one hood enable an interesting +concept, called a seeding device: extending a read\-only filesystem on a +device with another device that captures all writes. For example +imagine an immutable golden image of an operating system enhanced with another +device that allows to use the data from the golden image and normal operation. +This idea originated on CD\-ROMs with base OS and allowing to use them for live +systems, but this became obsolete. There are technologies providing similar +functionality, like \fI\%unionmount\fP, +\fI\%overlayfs\fP or +\fI\%qcow2\fP image snapshot. +.sp +The seeding device starts as a normal filesystem, once the contents is ready, +\fBbtrfstune \-S 1\fP is used to flag it as a seeding device. Mounting such device +will not allow any writes, except adding a new device by \fBbtrfs device add\fP\&. +Then the filesystem can be remounted as read\-write. +.sp +Given that the filesystem on the seeding device is always recognized as +read\-only, it can be used to seed multiple filesystems from one device at the +same time. The UUID that is normally attached to a device is automatically +changed to a random UUID on each mount. +.sp +Once the seeding device is mounted, it needs the writable device. After adding +it, unmounting and mounting with \fBumount /path; mount /dev/writable +/path\fP or remounting read\-write with \fBremount \-o remount,rw\fP makes the +filesystem at \fB/path\fP ready for use. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +There is a known bug with using remount to make the mount writeable: +remount will leave the filesystem in a state where it is unable to +clean deleted snapshots, so it will leak space until it is unmounted +and mounted properly. +.UNINDENT +.UNINDENT +.sp +Furthermore, deleting the seeding device from the filesystem can turn it into +a normal filesystem, provided that the writable device can also contain all the +data from the seeding device. +.sp +The seeding device flag can be cleared again by \fBbtrfstune \-f \-S 0\fP, e.g. +allowing to update with newer data but please note that this will invalidate +all existing filesystems that use this particular seeding device. This works +for some use cases, not for others, and the forcing flag to the command is +mandatory to avoid accidental mistakes. +.sp +Example how to create and use one seeding device: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# mkfs.btrfs /dev/sda +# mount /dev/sda /mnt/mnt1 +\&... fill mnt1 with data +# umount /mnt/mnt1 + +# btrfstune \-S 1 /dev/sda + +# mount /dev/sda /mnt/mnt1 +# btrfs device add /dev/sdb /mnt/mnt1 +# umount /mnt/mnt1 +# mount /dev/sdb /mnt/mnt1 +\&... /mnt/mnt1 is now writable +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now \fB/mnt/mnt1\fP can be used normally. The device \fB/dev/sda\fP can be mounted +again with a another writable device: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# mount /dev/sda /mnt/mnt2 +# btrfs device add /dev/sdc /mnt/mnt2 +# umount /mnt/mnt2 +# mount /dev/sdc /mnt/mnt2 +\&... /mnt/mnt2 is now writable +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The writable device (file:\fI/dev/sdb\fP) can be decoupled from the seeding device and +used independently: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs device delete /dev/sda /mnt/mnt1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +As the contents originated in the seeding device, it\(aqs possible to turn +\fB/dev/sdb\fP to a seeding device again and repeat the whole process. +.sp +A few things to note: +.INDENT 0.0 +.IP \(bu 2 +it\(aqs recommended to use only single device for the seeding device, it works +for multiple devices but the \fIsingle\fP profile must be used in order to make +the seeding device deletion work +.IP \(bu 2 +block group profiles \fIsingle\fP and \fIdup\fP support the use cases above +.IP \(bu 2 +the label is copied from the seeding device and can be changed by \fBbtrfs filesystem label\fP +.IP \(bu 2 +each new mount of the seeding device gets a new random UUID +.IP \(bu 2 +\fBumount /path; mount /dev/writable /path\fP can be replaced with +\fBmount \-o remount,rw /path\fP +but it won\(aqt reclaim space of deleted subvolumes until the seeding device +is mounted read\-write again before making it seeding again +.UNINDENT +.SS Chained seeding devices +.sp +Though it\(aqs not recommended and is rather an obscure and untested use case, +chaining seeding devices is possible. In the first example, the writable device +\fB/dev/sdb\fP can be turned onto another seeding device again, depending on the +unchanged seeding device \fB/dev/sda\fP\&. Then using \fB/dev/sdb\fP as the primary +seeding device it can be extended with another writable device, say \fB/dev/sdd\fP, +and it continues as before as a simple tree structure on devices. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# mkfs.btrfs /dev/sda +# mount /dev/sda /mnt/mnt1 +\&... fill mnt1 with data +# umount /mnt/mnt1 + +# btrfstune \-S 1 /dev/sda + +# mount /dev/sda /mnt/mnt1 +# btrfs device add /dev/sdb /mnt/mnt1 +# mount \-o remount,rw /mnt/mnt1 +\&... /mnt/mnt1 is now writable +# umount /mnt/mnt1 + +# btrfstune \-S 1 /dev/sdb + +# mount /dev/sdb /mnt/mnt1 +# btrfs device add /dev/sdc /mnt +# mount \-o remount,rw /mnt/mnt1 +\&... /mnt/mnt1 is now writable +# umount /mnt/mnt1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +As a result we have: +.INDENT 0.0 +.IP \(bu 2 +\fIsda\fP is a single seeding device, with its initial contents +.IP \(bu 2 +\fIsdb\fP is a seeding device but requires \fIsda\fP, the contents are from the time +when \fIsdb\fP is made seeding, i.e. contents of \fIsda\fP with any later changes +.IP \(bu 2 +\fIsdc\fP last writable, can be made a seeding one the same way as was \fIsdb\fP, +preserving its contents and depending on \fIsda\fP and \fIsdb\fP +.UNINDENT +.sp +As long as the seeding devices are unmodified and available, they can be used +to start another branch. +.SH RAID56 STATUS AND RECOMMENDED PRACTICES +.sp +The RAID56 feature provides striping and parity over several devices, same as +the traditional RAID5/6. There are some implementation and design deficiencies +that make it unreliable for some corner cases and the feature \fBshould not be +used in production, only for evaluation or testing\fP\&. The power failure safety +for metadata with RAID56 is not 100%. +.SS Metadata +.sp +Do not use \fIraid5\fP nor \fIraid6\fP for metadata. Use \fIraid1\fP or \fIraid1c3\fP +respectively. +.sp +The substitute profiles provide the same guarantees against loss of 1 or 2 +devices, and in some respect can be an improvement. Recovering from one +missing device will only need to access the remaining 1st or 2nd copy, that in +general may be stored on some other devices due to the way RAID1 works on +btrfs, unlike on a striped profile (similar to \fIraid0\fP) that would need all +devices all the time. +.sp +The space allocation pattern and consumption is different (e.g. on N devices): +for \fIraid5\fP as an example, a 1GiB chunk is reserved on each device, while with +\fIraid1\fP there\(aqs each 1GiB chunk stored on 2 devices. The consumption of each +1GiB of used metadata is then \fIN * 1GiB\fP for vs \fI2 * 1GiB\fP\&. Using \fIraid1\fP +is also more convenient for balancing/converting to other profile due to lower +requirement on the available chunk space. +.SS Missing/incomplete support +.sp +When RAID56 is on the same filesystem with different raid profiles, the space +reporting is inaccurate, e.g. \fBdf\fP, \fBbtrfs filesystem df\fP or +\fBbtrfs filesystem usage\fP\&. When there\(aqs only a one profile per block +group type (e.g. RAID5 for data) the reporting is accurate. +.sp +When scrub is started on a RAID56 filesystem, it\(aqs started on all devices that +degrade the performance. The workaround is to start it on each device +separately. Due to that the device stats may not match the actual state and +some errors might get reported multiple times. +.sp +The \fIwrite hole\fP problem. An unclean shutdown could leave a partially written +stripe in a state where the some stripe ranges and the parity are from the old +writes and some are new. The information which is which is not tracked. Write +journal is not implemented. Alternatively a full read\-modify\-write would make +sure that a full stripe is always written, avoiding the write hole completely, +but performance in that case turned out to be too bad for use. +.sp +The striping happens on all available devices (at the time the chunks were +allocated), so in case a new device is added it may not be utilized +immediately and would require a rebalance. A fixed configured stripe width is +not implemented. +.SH STORAGE MODEL, HARDWARE CONSIDERATIONS +.SS Storage model +.sp +\fIA storage model is a model that captures key physical aspects of data +structure in a data store. A filesystem is the logical structure organizing +data on top of the storage device.\fP +.sp +The filesystem assumes several features or limitations of the storage device +and utilizes them or applies measures to guarantee reliability. BTRFS in +particular is based on a COW (copy on write) mode of writing, i.e. not updating +data in place but rather writing a new copy to a different location and then +atomically switching the pointers. +.sp +In an ideal world, the device does what it promises. The filesystem assumes +that this may not be true so additional mechanisms are applied to either detect +misbehaving hardware or get valid data by other means. The devices may (and do) +apply their own detection and repair mechanisms but we won\(aqt assume any. +.sp +The following assumptions about storage devices are considered (sorted by +importance, numbers are for further reference): +.INDENT 0.0 +.IP 1. 3 +atomicity of reads and writes of blocks/sectors (the smallest unit of data +the device presents to the upper layers) +.IP 2. 3 +there\(aqs a flush command that instructs the device to forcibly order writes +before and after the command; alternatively there\(aqs a barrier command that +facilitates the ordering but may not flush the data +.IP 3. 3 +data sent to write to a given device offset will be written without further +changes to the data and to the offset +.IP 4. 3 +writes can be reordered by the device, unless explicitly serialized by the +flush command +.IP 5. 3 +reads and writes can be freely reordered and interleaved +.UNINDENT +.sp +The consistency model of BTRFS builds on these assumptions. The logical data +updates are grouped, into a generation, written on the device, serialized by +the flush command and then the super block is written ending the generation. +All logical links among metadata comprising a consistent view of the data may +not cross the generation boundary. +.SS When things go wrong +.sp +\fBNo or partial atomicity of block reads/writes (1)\fP +.INDENT 0.0 +.IP \(bu 2 +\fIProblem\fP: a partial block contents is written (\fItorn write\fP), e.g. due to a +power glitch or other electronics failure during the read/write +.IP \(bu 2 +\fIDetection\fP: checksum mismatch on read +.IP \(bu 2 +\fIRepair\fP: use another copy or rebuild from multiple blocks using some encoding +scheme +.UNINDENT +.sp +\fBThe flush command does not flush (2)\fP +.sp +This is perhaps the most serious problem and impossible to mitigate by +filesystem without limitations and design restrictions. What could happen in +the worst case is that writes from one generation bleed to another one, while +still letting the filesystem consider the generations isolated. Crash at any +point would leave data on the device in an inconsistent state without any hint +what exactly got written, what is missing and leading to stale metadata link +information. +.sp +Devices usually honor the flush command, but for performance reasons may do +internal caching, where the flushed data are not yet persistently stored. A +power failure could lead to a similar scenario as above, although it\(aqs less +likely that later writes would be written before the cached ones. This is +beyond what a filesystem can take into account. Devices or controllers are +usually equipped with batteries or capacitors to write the cache contents even +after power is cut. (\fIBattery backed write cache\fP) +.sp +\fBData get silently changed on write (3)\fP +.sp +Such thing should not happen frequently, but still can happen spuriously due +the complex internal workings of devices or physical effects of the storage +media itself. +.INDENT 0.0 +.IP \(bu 2 +\fIProblem\fP: while the data are written atomically, the contents get changed +.IP \(bu 2 +\fIDetection\fP: checksum mismatch on read +.IP \(bu 2 +\fIRepair\fP: use another copy or rebuild from multiple blocks using some +encoding scheme +.UNINDENT +.sp +\fBData get silently written to another offset (3)\fP +.sp +This would be another serious problem as the filesystem has no information +when it happens. For that reason the measures have to be done ahead of time. +This problem is also commonly called \fIghost write\fP\&. +.sp +The metadata blocks have the checksum embedded in the blocks, so a correct +atomic write would not corrupt the checksum. It\(aqs likely that after reading +such block the data inside would not be consistent with the rest. To rule that +out there\(aqs embedded block number in the metadata block. It\(aqs the logical +block number because this is what the logical structure expects and verifies. +.sp +The following is based on information publicly available, user feedback, +community discussions or bug report analyses. It\(aqs not complete and further +research is encouraged when in doubt. +.SS Main memory +.sp +The data structures and raw data blocks are temporarily stored in computer +memory before they get written to the device. It is critical that memory is +reliable because even simple bit flips can have vast consequences and lead to +damaged structures, not only in the filesystem but in the whole operating +system. +.sp +Based on experience in the community, memory bit flips are more common than one +would think. When it happens, it\(aqs reported by the tree\-checker or by a checksum +mismatch after reading blocks. There are some very obvious instances of bit +flips that happen, e.g. in an ordered sequence of keys in metadata blocks. We can +easily infer from the other data what values get damaged and how. However, fixing +that is not straightforward and would require cross\-referencing data from the +entire filesystem to see the scope. +.sp +If available, ECC memory should lower the chances of bit flips, but this +type of memory is not available in all cases. A memory test should be performed +in case there\(aqs a visible bit flip pattern, though this may not detect a faulty +memory module because the actual load of the system could be the factor making +the problems appear. In recent years attacks on how the memory modules operate +have been demonstrated (\fIrowhammer\fP) achieving specific bits to be flipped. +While these were targeted, this shows that a series of reads or writes can +affect unrelated parts of memory. +.sp +Further reading: +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://en.wikipedia.org/wiki/Row_hammer\fP +.UNINDENT +.sp +What to do: +.INDENT 0.0 +.IP \(bu 2 +run \fImemtest\fP, note that sometimes memory errors happen only when the system +is under heavy load that the default memtest cannot trigger +.IP \(bu 2 +memory errors may appear as filesystem going read\-only due to \(dqpre write\(dq +check, that verify meta data before they get written but fail some basic +consistency checks +.UNINDENT +.SS Direct memory access (DMA) +.sp +Another class of errors is related to DMA (direct memory access) performed +by device drivers. While this could be considered a software error, the +data transfers that happen without CPU assistance may accidentally corrupt +other pages. Storage devices utilize DMA for performance reasons, the +filesystem structures and data pages are passed back and forth, making +errors possible in case page life time is not properly tracked. +.sp +There are lots of quirks (device\-specific workarounds) in Linux kernel +drivers (regarding not only DMA) that are added when found. The quirks +may avoid specific errors or disable some features to avoid worse problems. +.sp +What to do: +.INDENT 0.0 +.IP \(bu 2 +use up\-to\-date kernel (recent releases or maintained long term support versions) +.IP \(bu 2 +as this may be caused by faulty drivers, keep the systems up\-to\-date +.UNINDENT +.SS Rotational disks (HDD) +.sp +Rotational HDDs typically fail at the level of individual sectors or small clusters. +Read failures are caught on the levels below the filesystem and are returned to +the user as \fIEIO \- Input/output error\fP\&. Reading the blocks repeatedly may +return the data eventually, but this is better done by specialized tools and +filesystem takes the result of the lower layers. Rewriting the sectors may +trigger internal remapping but this inevitably leads to data loss. +.sp +Disk firmware is technically software but from the filesystem perspective is +part of the hardware. IO requests are processed, and caching or various +other optimizations are performed, which may lead to bugs under high load or +unexpected physical conditions or unsupported use cases. +.sp +Disks are connected by cables with two ends, both of which can cause problems +when not attached properly. Data transfers are protected by checksums and the +lower layers try hard to transfer the data correctly or not at all. The errors +from badly\-connecting cables may manifest as large amount of failed read or +write requests, or as short error bursts depending on physical conditions. +.sp +What to do: +.INDENT 0.0 +.IP \(bu 2 +check \fBsmartctl\fP for potential issues +.UNINDENT +.SS Solid state drives (SSD) +.sp +The mechanism of information storage is different from HDDs and this affects +the failure mode as well. The data are stored in cells grouped in large blocks +with limited number of resets and other write constraints. The firmware tries +to avoid unnecessary resets and performs optimizations to maximize the storage +media lifetime. The known techniques are deduplication (blocks with same +fingerprint/hash are mapped to same physical block), compression or internal +remapping and garbage collection of used memory cells. Due to the additional +processing there are measures to verity the data e.g. by ECC codes. +.sp +The observations of failing SSDs show that the whole electronic fails at once +or affects a lot of data (e.g. stored on one chip). Recovering such data +may need specialized equipment and reading data repeatedly does not help as +it\(aqs possible with HDDs. +.sp +There are several technologies of the memory cells with different +characteristics and price. The lifetime is directly affected by the type and +frequency of data written. Writing \(dqtoo much\(dq distinct data (e.g. encrypted) +may render the internal deduplication ineffective and lead to a lot of rewrites +and increased wear of the memory cells. +.sp +There are several technologies and manufacturers so it\(aqs hard to describe them +but there are some that exhibit similar behaviour: +.INDENT 0.0 +.IP \(bu 2 +expensive SSD will use more durable memory cells and is optimized for +reliability and high load +.IP \(bu 2 +cheap SSD is projected for a lower load (\(dqdesktop user\(dq) and is optimized for +cost, it may employ the optimizations and/or extended error reporting +partially or not at all +.UNINDENT +.sp +It\(aqs not possible to reliably determine the expected lifetime of an SSD due to +lack of information about how it works or due to lack of reliable stats provided +by the device. +.sp +Metadata writes tend to be the biggest component of lifetime writes to a SSD, +so there is some value in reducing them. Depending on the device class (high +end/low end) the features like DUP block group profiles may affect the +reliability in both ways: +.INDENT 0.0 +.IP \(bu 2 +\fIhigh end\fP are typically more reliable and using \fIsingle\fP for data and +metadata could be suitable to reduce device wear +.IP \(bu 2 +\fIlow end\fP could lack ability to identify errors so an additional redundancy +at the filesystem level (checksums, \fIDUP\fP) could help +.UNINDENT +.sp +Only users who consume 50 to 100% of the SSD\(aqs actual lifetime writes need to be +concerned by the write amplification of btrfs DUP metadata. Most users will be +far below 50% of the actual lifetime, or will write the drive to death and +discover how many writes 100% of the actual lifetime was. SSD firmware often +adds its own write multipliers that can be arbitrary and unpredictable and +dependent on application behavior, and these will typically have far greater +effect on SSD lifespan than DUP metadata. It\(aqs more or less impossible to +predict when a SSD will run out of lifetime writes to within a factor of two, so +it\(aqs hard to justify wear reduction as a benefit. +.sp +Further reading: +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://www.snia.org/educational\-library/ssd\-and\-deduplication\-end\-spinning\-disk\-2012\fP +.IP \(bu 2 +\fI\%https://www.snia.org/educational\-library/realities\-solid\-state\-storage\-2013\-2013\fP +.IP \(bu 2 +\fI\%https://www.snia.org/educational\-library/ssd\-performance\-primer\-2013\fP +.IP \(bu 2 +\fI\%https://www.snia.org/educational\-library/how\-controllers\-maximize\-ssd\-life\-2013\fP +.UNINDENT +.sp +What to do: +.INDENT 0.0 +.IP \(bu 2 +run \fBsmartctl\fP or self\-tests to look for potential issues +.IP \(bu 2 +keep the firmware up\-to\-date +.UNINDENT +.SS NVM express, non\-volatile memory (NVMe) +.sp +NVMe is a type of persistent memory usually connected over a system bus (PCIe) +or similar interface and the speeds are an order of magnitude faster than SSD. +It is also a non\-rotating type of storage, and is not typically connected by a +cable. It\(aqs not a SCSI type device either but rather a complete specification +for logical device interface. +.sp +In a way the errors could be compared to a combination of SSD class and regular +memory. Errors may exhibit as random bit flips or IO failures. There are tools +to access the internal log (\fBnvme log\fP and \fBnvme\-cli\fP) for a more detailed +analysis. +.sp +There are separate error detection and correction steps performed e.g. on the +bus level and in most cases never making in to the filesystem level. Once this +happens it could mean there\(aqs some systematic error like overheating or bad +physical connection of the device. You may want to run self\-tests (using +\fBsmartctl\fP). +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://en.wikipedia.org/wiki/NVM_Express\fP +.IP \(bu 2 +\fI\%https://www.smartmontools.org/wiki/NVMe_Support\fP +.UNINDENT +.SS Drive firmware +.sp +Firmware is technically still software but embedded into the hardware. As all +software has bugs, so does firmware. Storage devices can update the firmware +and fix known bugs. In some cases the it\(aqs possible to avoid certain bugs by +quirks (device\-specific workarounds) in Linux kernel. +.sp +A faulty firmware can cause wide range of corruptions from small and localized +to large affecting lots of data. Self\-repair capabilities may not be sufficient. +.sp +What to do: +.INDENT 0.0 +.IP \(bu 2 +check for firmware updates in case there are known problems, note that +updating firmware can be risky on itself +.IP \(bu 2 +use up\-to\-date kernel (recent releases or maintained long term support versions) +.UNINDENT +.SS SD flash cards +.sp +There are a lot of devices with low power consumption and thus using storage +media based on low power consumption too, typically flash memory stored on +a chip enclosed in a detachable card package. An improperly inserted card may be +damaged by electrical spikes when the device is turned on or off. The chips +storing data in turn may be damaged permanently. All types of flash memory +have a limited number of rewrites, so the data are internally translated by FTL +(flash translation layer). This is implemented in firmware (technically a +software) and prone to bugs that manifest as hardware errors. +.sp +Adding redundancy like using DUP profiles for both data and metadata can help +in some cases but a full backup might be the best option once problems appear +and replacing the card could be required as well. +.SS Hardware as the main source of filesystem corruptions +.sp +\fBIf you use unreliable hardware and don\(aqt know about that, don\(aqt blame the +filesystem when it tells you.\fP +.SH SEE ALSO +.sp +\fBacl(5)\fP, +\fI\%btrfs(8)\fP, +\fBchattr(1)\fP, +\fBfstrim(8)\fP, +\fBioctl(2)\fP, +\fI\%mkfs.btrfs(8)\fP, +\fBmount(8)\fP, +\fBswapon(8)\fP +.\" Generated by docutils manpage writer. +. diff --git a/upstream/fedora-40/man5/charmap.5 b/upstream/fedora-40/man5/charmap.5 new file mode 100644 index 00000000..1b66a63f --- /dev/null +++ b/upstream/fedora-40/man5/charmap.5 @@ -0,0 +1,105 @@ +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH charmap 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +charmap \- character set description file +.SH DESCRIPTION +A character set description (charmap) defines all available characters +and their encodings in a character set. +.BR localedef (1) +can use charmaps to create locale variants for different character sets. +.SS Syntax +The charmap file starts with a header that may consist of the +following keywords: +.TP +.RI < code_set_name > +is followed by the name of the character map. +.TP +.RI < comment_char > +is followed by a character that will be used as the comment character +for the rest of the file. +It defaults to the number sign (#). +.TP +.RI < escape_char > +is followed by a character that should be used as the escape character +for the rest of the file to mark characters that should be interpreted +in a special way. +It defaults to the backslash (\e). +.TP +.RI < mb_cur_max > +is followed by the maximum number of bytes for a character. +The default value is 1. +.TP +.RI < mb_cur_min > +is followed by the minimum number of bytes for a character. +This value must be less than or equal than +.RI < mb_cur_max >. +If not specified, it defaults to +.RI < mb_cur_max >. +.P +The character set definition section starts with the keyword +.I CHARMAP +in the first column. +.P +The following lines may have one of the two following forms to +define the character set: +.TP +.RI < character >\ byte-sequence\ comment +This form defines exactly one character and its byte sequence, +.I comment +being optional. +.TP +.RI < character >..< character >\ byte-sequence\ comment +This form defines a character range and its byte sequence, +.I comment +being optional. +.P +The character set definition section ends with the string +.IR "END CHARMAP" . +.P +The character set definition section may optionally be followed by a +section to define widths of characters. +.P +The +.I WIDTH_DEFAULT +keyword can be used to define the default width for all characters +not explicitly listed. +The default character width is 1. +.P +The width section for individual characters starts with the keyword +.I WIDTH +in the first column. +.P +The following lines may have one of the two following forms to +define the widths of the characters: +.TP +.RI < character >\ width +This form defines the width of exactly one character. +.TP +.RI < character >...< character >\ width +This form defines the width for all the characters in the range. +.P +The width definition section ends with the string +.IR "END WIDTH" . +.SH FILES +.TP +.I /usr/share/i18n/charmaps +Usual default character map path. +.SH STANDARDS +POSIX.2. +.SH EXAMPLES +The Euro sign is defined as follows in the +.I UTF\-8 +charmap: +.P +.nf + /xe2/x82/xac EURO SIGN +.fi +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR locale (5), +.BR charsets (7) diff --git a/upstream/fedora-40/man5/core.5 b/upstream/fedora-40/man5/core.5 new file mode 100644 index 00000000..73408b44 --- /dev/null +++ b/upstream/fedora-40/man5/core.5 @@ -0,0 +1,684 @@ +.\" Copyright (c) 2006, 2008 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH core 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +core \- core dump file +.SH DESCRIPTION +The default action of certain signals is to cause a process to terminate +and produce a +.IR "core dump file" , +a file containing an image of the process's memory at +the time of termination. +This image can be used in a debugger (e.g., +.BR gdb (1)) +to inspect the state of the program at the time that it terminated. +A list of the signals which cause a process to dump core can be found in +.BR signal (7). +.P +A process can set its soft +.B RLIMIT_CORE +resource limit to place an upper limit on the size of the core dump file +that will be produced if it receives a "core dump" signal; see +.BR getrlimit (2) +for details. +.P +There are various circumstances in which a core dump file is +not produced: +.IP \[bu] 3 +The process does not have permission to write the core file. +(By default, the core file is called +.I core +or +.IR core.pid , +where +.I pid +is the ID of the process that dumped core, +and is created in the current working directory. +See below for details on naming.) +Writing the core file fails if the directory in which +it is to be created is not writable, +or if a file with the same name exists and +is not writable +or is not a regular file +(e.g., it is a directory or a symbolic link). +.IP \[bu] +A (writable, regular) file with the same name as would be used for the +core dump already exists, but there is more than one hard link to that +file. +.IP \[bu] +The filesystem where the core dump file would be created is full; +or has run out of inodes; or is mounted read-only; +or the user has reached their quota for the filesystem. +.IP \[bu] +The directory in which the core dump file is to be created does +not exist. +.IP \[bu] +The +.B RLIMIT_CORE +(core file size) or +.B RLIMIT_FSIZE +(file size) resource limits for the process are set to zero; see +.BR getrlimit (2) +and the documentation of the shell's +.I ulimit +command +.RI ( limit +in +.BR csh (1)). +However, +.B RLIMIT_CORE +will be ignored if the system is configured to pipe core dumps to a program. +.IP \[bu] +The binary being executed by the process does not have read +permission enabled. +(This is a security measure to +ensure that an executable whose contents are not readable +does not produce a\[em]possibly readable\[em]core dump containing +an image of the executable.) +.IP \[bu] +The process is executing a set-user-ID (set-group-ID) program +that is owned by a user (group) other than the real user (group) +ID of the process, +or the process is executing a program that has file capabilities (see +.BR capabilities (7)). +(However, see the description of the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation, and the description of the +.I /proc/sys/fs/suid_dumpable +.\" FIXME . Perhaps relocate discussion of /proc/sys/fs/suid_dumpable +.\" and PR_SET_DUMPABLE to this page? +file in +.BR proc (5).) +.IP \[bu] +.I /proc/sys/kernel/core_pattern +is empty and +.I /proc/sys/kernel/core_uses_pid +contains the value 0. +(These files are described below.) +Note that if +.I /proc/sys/kernel/core_pattern +is empty and +.I /proc/sys/kernel/core_uses_pid +contains the value 1, +core dump files will have names of the form +.IR .pid , +and such files are hidden unless one uses the +.BR ls (1) +.I \-a +option. +.IP \[bu] +(Since Linux 3.7) +.\" commit 046d662f481830e652ac34cd112249adde16452a +The kernel was configured without the +.B CONFIG_COREDUMP +option. +.P +In addition, +a core dump may exclude part of the address space of the process if the +.BR madvise (2) +.B MADV_DONTDUMP +flag was employed. +.P +On systems that employ +.BR systemd (1) +as the +.I init +framework, core dumps may instead be placed in a location determined by +.BR systemd (1). +See below for further details. +.\" +.SS Naming of core dump files +By default, a core dump file is named +.IR core , +but the +.I /proc/sys/kernel/core_pattern +file (since Linux 2.6 and 2.4.21) +can be set to define a template that is used to name core dump files. +The template can contain % specifiers which are substituted +by the following values when a core file is created: +.P +.RS 4 +.PD 0 +.TP 4 +%% +A single % character. +.TP +%c +Core file size soft resource limit of crashing process (since Linux 2.6.24). +.TP +%d +.\" Added in git commit 12a2b4b2241e318b4f6df31228e4272d2c2968a1 +Dump mode\[em]same as value returned by +.BR prctl (2) +.B PR_GET_DUMPABLE +(since Linux 3.7). +.TP +%e +The process or thread's +.I comm +value, which typically is the same as the executable filename +(without path prefix, and truncated to a maximum of 15 characters), +but may have been modified to be something different; +see the discussion of +.IR /proc/ pid /comm +and +.IR /proc/ pid /task/ tid /comm +in +.BR proc (5). +.TP +%E +Pathname of executable, +with slashes (\[aq]/\[aq]) replaced by exclamation marks (\[aq]!\[aq]) +(since Linux 3.0). +.TP +%g +Numeric real GID of dumped process. +.TP +%h +Hostname (same as \fInodename\fP returned by \fBuname\fP(2)). +.TP +%i +TID of thread that triggered core dump, +as seen in the PID namespace in which the thread resides +.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 +(since Linux 3.18). +.TP +%I +TID of thread that triggered core dump, as seen in the initial PID namespace +.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 +(since Linux 3.18). +.TP +%p +PID of dumped process, +as seen in the PID namespace in which the process resides. +.TP +%P +.\" Added in git commit 65aafb1e7484b7434a0c1d4c593191ebe5776a2f +PID of dumped process, as seen in the initial PID namespace +(since Linux 3.12). +.TP +%s +Number of signal causing dump. +.TP +%t +Time of dump, expressed as seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.TP +%u +Numeric real UID of dumped process. +.PD +.RE +.P +A single % at the end of the template is dropped from the +core filename, as is the combination of a % followed by any +character other than those listed above. +All other characters in the template become a literal +part of the core filename. +The template may include \[aq]/\[aq] characters, which are interpreted +as delimiters for directory names. +The maximum size of the resulting core filename is 128 bytes (64 bytes +before Linux 2.6.19). +The default value in this file is "core". +For backward compatibility, if +.I /proc/sys/kernel/core_pattern +does not include +.I %p +and +.I /proc/sys/kernel/core_uses_pid +(see below) +is nonzero, then .PID will be appended to the core filename. +.P +Paths are interpreted according to the settings that are active for the +crashing process. +That means the crashing process's mount namespace (see +.BR mount_namespaces (7)), +its current working directory (found via +.BR getcwd (2)), +and its root directory (see +.BR chroot (2)). +.P +Since Linux 2.4, Linux has also provided +a more primitive method of controlling +the name of the core dump file. +If the +.I /proc/sys/kernel/core_uses_pid +file contains the value 0, then a core dump file is simply named +.IR core . +If this file contains a nonzero value, then the core dump file includes +the process ID in a name of the form +.IR core.PID . +.P +Since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +if +.I /proc/sys/fs/suid_dumpable +is set to 2 ("suidsafe"), the pattern must be either an absolute pathname +(starting with a leading \[aq]/\[aq] character) or a pipe, as defined below. +.SS Piping core dumps to a program +Since Linux 2.6.19, Linux supports an alternate syntax for the +.I /proc/sys/kernel/core_pattern +file. +If the first character of this file is a pipe symbol (\fB|\fP), +then the remainder of the line is interpreted as the command-line for +a user-space program (or script) that is to be executed. +.P +Since Linux 5.3.0, +.\" commit 315c69261dd3fa12dbc830d4fa00d1fad98d3b03 +the pipe template is split on spaces into an argument list +.I before +the template parameters are expanded. +In earlier kernels, the template parameters are expanded first and +the resulting string is split on spaces into an argument list. +This means that in earlier kernels executable names added by the +.I %e +and +.I %E +template parameters could get split into multiple arguments. +So the core dump handler needs to put the executable names as the last +argument and ensure it joins all parts of the executable name using spaces. +Executable names with multiple spaces in them are not correctly represented +in earlier kernels, +meaning that the core dump handler needs to use mechanisms to find +the executable name. +.P +Instead of being written to a file, the core dump is given as +standard input to the program. +Note the following points: +.IP \[bu] 3 +The program must be specified using an absolute pathname (or a +pathname relative to the root directory, \fI/\fP), +and must immediately follow the '|' character. +.IP \[bu] +The command-line arguments can include any of +the % specifiers listed above. +For example, to pass the PID of the process that is being dumped, specify +.I %p +in an argument. +.IP \[bu] +The process created to run the program runs as user and group +.IR root . +.IP \[bu] +Running as +.I root +does not confer any exceptional security bypasses. +Namely, LSMs (e.g., SELinux) are still active and may prevent the handler +from accessing details about the crashed process via +.IR /proc/ pid. +.IP \[bu] +The program pathname is interpreted with respect to the initial mount namespace +as it is always executed there. +It is not affected by the settings +(e.g., root directory, mount namespace, current working directory) +of the crashing process. +.IP \[bu] +The process runs in the initial namespaces +(PID, mount, user, and so on) +and not in the namespaces of the crashing process. +One can utilize specifiers such as +.I %P +to find the right +.IR /proc/ pid +directory and probe/enter the crashing process's namespaces if needed. +.IP \[bu] +The process starts with its current working directory +as the root directory. +If desired, it is possible change to the working directory of +the dumping process by employing the value provided by the +.I %P +specifier to change to the location of the dumping process via +.IR /proc/ pid /cwd . +.IP \[bu] +Command-line arguments can be supplied to the +program (since Linux 2.6.24), +delimited by white space (up to a total line length of 128 bytes). +.IP \[bu] +The +.B RLIMIT_CORE +limit is not enforced for core dumps that are piped to a program +via this mechanism. +.\" +.SS /proc/sys/kernel/core_pipe_limit +When collecting core dumps via a pipe to a user-space program, +it can be useful for the collecting program to gather data about +the crashing process from that process's +.IR /proc/ pid +directory. +In order to do this safely, +the kernel must wait for the program collecting the core dump to exit, +so as not to remove the crashing process's +.IR /proc/ pid +files prematurely. +This in turn creates the +possibility that a misbehaving collecting program can block +the reaping of a crashed process by simply never exiting. +.P +Since Linux 2.6.32, +.\" commit a293980c2e261bd5b0d2a77340dd04f684caff58 +the +.I /proc/sys/kernel/core_pipe_limit +can be used to defend against this possibility. +The value in this file defines how many concurrent crashing +processes may be piped to user-space programs in parallel. +If this value is exceeded, then those crashing processes above this value +are noted in the kernel log and their core dumps are skipped. +.P +A value of 0 in this file is special. +It indicates that unlimited processes may be captured in parallel, +but that no waiting will take place (i.e., the collecting +program is not guaranteed access to +.IR /proc/ ). +The default value for this file is 0. +.\" +.SS Controlling which mappings are written to the core dump +Since Linux 2.6.23, the Linux-specific +.IR /proc/ pid /coredump_filter +file can be used to control which memory segments are written to the +core dump file in the event that a core dump is performed for the +process with the corresponding process ID. +.P +The value in the file is a bit mask of memory mapping types (see +.BR mmap (2)). +If a bit is set in the mask, then memory mappings of the +corresponding type are dumped; otherwise they are not dumped. +The bits in this file have the following meanings: +.P +.PD 0 +.RS 4 +.TP +bit 0 +Dump anonymous private mappings. +.TP +bit 1 +Dump anonymous shared mappings. +.TP +bit 2 +Dump file-backed private mappings. +.TP +bit 3 +Dump file-backed shared mappings. +.\" file-backed shared mappings of course also update the underlying +.\" mapped file. +.TP +bit 4 (since Linux 2.6.24) +Dump ELF headers. +.TP +bit 5 (since Linux 2.6.28) +Dump private huge pages. +.TP +bit 6 (since Linux 2.6.28) +Dump shared huge pages. +.TP +bit 7 (since Linux 4.4) +.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 +Dump private DAX pages. +.TP +bit 8 (since Linux 4.4) +.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 +Dump shared DAX pages. +.RE +.PD +.P +By default, the following bits are set: 0, 1, 4 (if the +.B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS +kernel configuration option is enabled), and 5. +This default can be modified at boot time using the +.I coredump_filter +boot option. +.P +The value of this file is displayed in hexadecimal. +(The default value is thus displayed as 33.) +.P +Memory-mapped I/O pages such as frame buffer are never dumped, and +virtual DSO +.RB ( vdso (7)) +pages are always dumped, regardless of the +.I coredump_filter +value. +.P +A child process created via +.BR fork (2) +inherits its parent's +.I coredump_filter +value; +the +.I coredump_filter +value is preserved across an +.BR execve (2). +.P +It can be useful to set +.I coredump_filter +in the parent shell before running a program, for example: +.P +.in +4n +.EX +.RB "$" " echo 0x7 > /proc/self/coredump_filter" +.RB "$" " ./some_program" +.EE +.in +.P +This file is provided only if the kernel was built with the +.B CONFIG_ELF_CORE +configuration option. +.\" +.SS Core dumps and systemd +On systems using the +.BR systemd (1) +.I init +framework, core dumps may be placed in a location determined by +.BR systemd (1). +To do this, +.BR systemd (1) +employs the +.I core_pattern +feature that allows piping core dumps to a program. +One can verify this by checking whether core dumps are being piped to the +.BR systemd\-coredump (8) +program: +.P +.in +4n +.EX +$ \fBcat /proc/sys/kernel/core_pattern\fP +|/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e +.EE +.in +.P +In this case, core dumps will be placed in the location configured for +.BR systemd\-coredump (8), +typically as +.BR lz4 (1) +compressed files in the directory +.IR /var/lib/systemd/coredump/ . +One can list the core dumps that have been recorded by +.BR systemd\-coredump (8) +using +.BR coredumpctl (1): +.P +.EX +$ \fBcoredumpctl list | tail \-5\fP +Wed 2017\-10\-11 22:25:30 CEST 2748 1000 1000 3 present /usr/bin/sleep +Thu 2017\-10\-12 06:29:10 CEST 2716 1000 1000 3 present /usr/bin/sleep +Thu 2017\-10\-12 06:30:50 CEST 2767 1000 1000 3 present /usr/bin/sleep +Thu 2017\-10\-12 06:37:40 CEST 2918 1000 1000 3 present /usr/bin/cat +Thu 2017\-10\-12 08:13:07 CEST 2955 1000 1000 3 present /usr/bin/cat +.EE +.P +The information shown for each core dump includes the date and time +of the dump, the PID, UID, and GID of the dumping process, +the signal number that caused the core dump, +and the pathname of the executable that was being run by the dumped process. +Various options to +.BR coredumpctl (1) +allow a specified coredump file to be pulled from the +.BR systemd (1) +location into a specified file. +For example, to extract the core dump for PID 2955 shown above to a file named +.I core +in the current directory, one could use: +.P +.in +4n +.EX +$ \fBcoredumpctl dump 2955 \-o core\fP +.EE +.in +.P +For more extensive details, see the +.BR coredumpctl (1) +manual page. +.P +To (persistently) disable the +.BR systemd (1) +mechanism that archives core dumps, restoring to something more like +traditional Linux behavior, one can set an override for the +.BR systemd (1) +mechanism, using something like: +.P +.in +4n +.EX +# \fBecho "kernel.core_pattern=core.%p" > \e\fP +\fB /etc/sysctl.d/50\-coredump.conf\fP +# \fB/lib/systemd/systemd\-sysctl\fP +.EE +.in +.P +It is also possible to temporarily (i.e., until the next reboot) change the +.I core_pattern +setting using a command such as the following +(which causes the names of core dump files to include the executable name +as well as the number of the signal which triggered the core dump): +.P +.in +4n +.EX +# \fBsysctl \-w kernel.core_pattern="%e\-%s.core"\fP +.EE +.in +.\" +.SH NOTES +The +.BR gdb (1) +.I gcore +command can be used to obtain a core dump of a running process. +.P +In Linux versions up to and including 2.6.27, +.\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922 +if a multithreaded process (or, more precisely, a process that +shares its memory with another process by being created with the +.B CLONE_VM +flag of +.BR clone (2)) +dumps core, then the process ID is always appended to the core filename, +unless the process ID was already included elsewhere in the +filename via a +.I %p +specification in +.IR /proc/sys/kernel/core_pattern . +(This is primarily useful when employing the obsolete +LinuxThreads implementation, +where each thread of a process has a different PID.) +.\" Always including the PID in the name of the core file made +.\" sense for LinuxThreads, where each thread had a unique PID, +.\" but doesn't seem to serve any purpose with NPTL, where all the +.\" threads in a process share the same PID (as POSIX.1 requires). +.\" Probably the behavior is maintained so that applications using +.\" LinuxThreads continue appending the PID (the kernel has no easy +.\" way of telling which threading implementation the user-space +.\" application is using). -- mtk, April 2006 +.SH EXAMPLES +The program below can be used to demonstrate the use of the +pipe syntax in the +.I /proc/sys/kernel/core_pattern +file. +The following shell session demonstrates the use of this program +(compiled to create an executable named +.IR core_pattern_pipe_test ): +.P +.in +4n +.EX +.RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c" +.RB "$" " su" +Password: +.RB "#" " echo \[dq]|$PWD/core_pattern_pipe_test %p \ +UID=%u GID=%g sig=%s\[dq] > \e" +.B " /proc/sys/kernel/core_pattern" +.RB "#" " exit" +.RB "$" " sleep 100" +.BR "\[ha]\e" " # type control\-backslash" +Quit (core dumped) +.RB "$" " cat core.info" +argc=5 +argc[0]= +argc[1]=<20575> +argc[2]= +argc[3]= +argc[4]= +Total bytes in core dump: 282624 +.EE +.in +.SS Program source +\& +.EX +/* core_pattern_pipe_test.c */ +\& +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +#define BUF_SIZE 1024 +\& +int +main(int argc, char *argv[]) +{ + ssize_t nread, tot; + char buf[BUF_SIZE]; + FILE *fp; + char cwd[PATH_MAX]; +\& + /* Change our current working directory to that of the + crashing process. */ +\& + snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]); + chdir(cwd); +\& + /* Write output to file "core.info" in that directory. */ +\& + fp = fopen("core.info", "w+"); + if (fp == NULL) + exit(EXIT_FAILURE); +\& + /* Display command\-line arguments given to core_pattern + pipe program. */ +\& + fprintf(fp, "argc=%d\en", argc); + for (size_t j = 0; j < argc; j++) + fprintf(fp, "argc[%zu]=<%s>\en", j, argv[j]); +\& + /* Count bytes in standard input (the core dump). */ +\& + tot = 0; + while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0) + tot += nread; + fprintf(fp, "Total bytes in core dump: %zd\en", tot); +\& + fclose(fp); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bash (1), +.BR coredumpctl (1), +.BR gdb (1), +.BR getrlimit (2), +.BR mmap (2), +.BR prctl (2), +.BR sigaction (2), +.BR elf (5), +.BR proc (5), +.BR pthreads (7), +.BR signal (7), +.BR systemd\-coredump (8) diff --git a/upstream/fedora-40/man5/coredump.conf.5 b/upstream/fedora-40/man5/coredump.conf.5 new file mode 100644 index 00000000..10f56339 --- /dev/null +++ b/upstream/fedora-40/man5/coredump.conf.5 @@ -0,0 +1,157 @@ +'\" t +.TH "COREDUMP\&.CONF" "5" "" "systemd 255" "coredump.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +coredump.conf, coredump.conf.d \- Core dump storage configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/coredump\&.conf +.PP +/etc/systemd/coredump\&.conf\&.d/*\&.conf +.PP +/run/systemd/coredump\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/coredump\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These files configure the behavior of +\fBsystemd-coredump\fR(8), a handler for core dumps invoked by the kernel\&. Whether +\fBsystemd\-coredump\fR +is used is determined by the kernel\*(Aqs +\fIkernel\&.core_pattern\fR +\fBsysctl\fR(8) +setting\&. See +\fBsystemd-coredump\fR(8) +and +\fBcore\fR(5) +pages for the details\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [Coredump] section: +.PP +\fIStorage=\fR +.RS 4 +Controls where to store cores\&. One of +"none", +"external", and +"journal"\&. When +"none", the core dumps may be logged (including the backtrace if possible), but not stored permanently\&. When +"external" +(the default), cores will be stored in +/var/lib/systemd/coredump/\&. When +"journal", cores will be stored in the journal and rotated following normal journal rotation patterns\&. +.sp +When cores are stored in the journal, they might be compressed following journal compression settings, see +\fBjournald.conf\fR(5)\&. When cores are stored externally, they will be compressed by default, see below\&. +.sp +Note that in order to process a coredump (i\&.e\&. extract a stack trace) the core must be written to disk first\&. Thus, unless +\fIProcessSizeMax=\fR +is set to 0 (see below), the core will be written to +/var/lib/systemd/coredump/ +either way (under a temporary filename, or even in an unlinked file), +\fIStorage=\fR +thus only controls whether to leave it there even after it was processed\&. +.sp +Added in version 215\&. +.RE +.PP +\fICompress=\fR +.RS 4 +Controls compression for external storage\&. Takes a boolean argument, which defaults to +"yes"\&. +.sp +Added in version 215\&. +.RE +.PP +\fIProcessSizeMax=\fR +.RS 4 +The maximum size in bytes of a core which will be processed\&. Core dumps exceeding this size may be stored, but the stack trace will not be generated\&. Like other sizes in this same config file, the usual suffixes to the base of 1024 are allowed (B, K, M, G, T, P, and E)\&. Defaults to 1G on 32\-bit systems, 32G on 64\-bit systems\&. +.sp +Setting +\fIStorage=none\fR +and +\fIProcessSizeMax=0\fR +disables all coredump handling except for a log entry\&. +.sp +Added in version 215\&. +.RE +.PP +\fIExternalSizeMax=\fR, \fIJournalSizeMax=\fR +.RS 4 +The maximum (compressed or uncompressed) size in bytes of a coredump to be saved in separate files on disk (default: 1G on 32\-bit systems, 32G on 64\-bit systems) or in the journal (default: 767M)\&. Note that the journal service enforces a hard limit on journal log records of 767M, and will ignore larger submitted log records\&. Hence, +\fIJournalSizeMax=\fR +may be lowered relative to the default, but not increased\&. Unit suffixes are allowed just as in +\fBProcessSizeMax=\fR\&. +.sp +\fIExternalSizeMax=infinity\fR +sets the core size to unlimited\&. +.sp +Added in version 215\&. +.RE +.PP +\fIMaxUse=\fR, \fIKeepFree=\fR +.RS 4 +Enforce limits on the disk space, specified in bytes, taken up by externally stored core dumps\&. Unit suffixes are allowed just as in +\fBProcessSizeMax=\fR\&. +\fBMaxUse=\fR +makes sure that old core dumps are removed as soon as the total disk space taken up by core dumps grows beyond this limit (defaults to 10% of the total disk size)\&. +\fBKeepFree=\fR +controls how much disk space to keep free at least (defaults to 15% of the total disk size)\&. Note that the disk space used by core dumps might temporarily exceed these limits while core dumps are processed\&. Note that old core dumps are also removed based on time via +\fBsystemd-tmpfiles\fR(8)\&. Set either value to 0 to turn off size\-based cleanup\&. +.sp +Added in version 215\&. +.RE +.PP +The defaults for all values are listed as comments in the template +/etc/systemd/coredump\&.conf +file that is installed by default\&. +.SH "SEE ALSO" +.PP +\fBsystemd-journald.service\fR(8), +\fBcoredumpctl\fR(1), +\fBsystemd-tmpfiles\fR(8) diff --git a/upstream/fedora-40/man5/crontab.5 b/upstream/fedora-40/man5/crontab.5 new file mode 100644 index 00000000..0c6a300a --- /dev/null +++ b/upstream/fedora-40/man5/crontab.5 @@ -0,0 +1,374 @@ +.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie +.\" * All rights reserved +.\" */ +.\" +.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: crontab.5,v 1.6 2004/01/23 19:03:33 vixie Exp $ +.\" +.TH CRONTAB 5 2012-11-22 "cronie" "File Formats" +.SH NAME +crontab \- files used to schedule the execution of programs +.SH DESCRIPTION +A +.I crontab +file contains instructions for the +.BR cron (8) +daemon in the following simplified manner: "run this command at this time +on this date". Each user can define their own crontab. Commands defined +in any given crontab are executed under the user who owns that particular +crontab. Uucp and News usually have their own crontabs, eliminating the +need for explicitly running +.BR su (1) +as part of a cron command. +.PP +Blank lines, leading spaces, and tabs are ignored. Lines whose first +non-white space character is a pound-sign (#) are comments, and are not +processed. Note that comments are not allowed on the same line as cron +commands, since they are considered a part of the command. Similarly, +comments are not allowed on the same line as environment variable +settings. +.PP +An active line in a crontab is either an environment setting or a cron +command. An environment setting is of the form: +.PP + name = value +.PP +where the white spaces around the equal-sign (=) are optional, and any +subsequent non-leading white spaces in +.I value +is a part of the value assigned to +.IR name . +The +.I value +string may be placed in quotes (single or double, but matching) to +preserve leading or trailing white spaces. +.PP +Several environment variables are set up automatically by the +.BR cron (8) +daemon. +.I SHELL +is set to /bin/sh, and +.I LOGNAME +and +.I HOME +are set from the /etc/passwd line of the crontab\'s owner. +.I HOME +and +.I SHELL +can be overridden by settings in the crontab; LOGNAME can not. +.PP +(Note: the +.I LOGNAME +variable is sometimes called +.I USER +on BSD systems and is also automatically set). +.PP +In addition to +.IR LOGNAME , +.IR HOME , +and +.IR SHELL , +.BR cron (8) +looks at the +.I MAILTO +variable if a mail needs to be send as a result of running any commands +in that particular crontab. If +.I MAILTO +is defined (and non-empty), mail is sent to the specified address. If +.I MAILTO +is defined but empty +.RI ( MAILTO="" ), +no mail is sent. Otherwise, mail is sent to the owner of the crontab. +This option is useful if you decide to use /bin/mail instead of +/usr/lib/sendmail as your mailer. Note that /bin/mail does not provide +aliasing and UUCP usually does not read its mail. If +.I MAILFROM +is defined (and non-empty), it is used as the envelope sender address, +otherwise, ``root'' is used. +.PP +(Note: Both +.I MAILFROM +and +.I MAILTO +variables are expanded, so setting them as in the following example works as expected: MAILFROM=cron-$USER@cron.com ($USER is replaced by the system user) ) +.PP +By default, cron sends a mail using the 'Content-Type:' header +of 'text/plain' with the 'charset=' parameter set to the 'charmap/codeset' +of the locale in which +.BR crond (8) +is started up, i.e., either the default system locale, if no LC_* +environment variables are set, or the locale specified by the LC_* +environment variables (see +.BR locale (7)). +Different character encodings can be used for mailing cron job outputs by +setting the +.I CONTENT_TYPE +and +.I CONTENT_TRANSFER_ENCODING +variables in a crontab to the correct values of the mail headers of those +names. +.PP +The +.I CRON_TZ +variable specifies the time zone specific for the cron table. The user +should enter a time according to the specified time zone into the table. +The time used for writing into a log file is taken from the local time +zone, where the daemon is running. +.PP +The +.I MLS_LEVEL +environment variable provides support for multiple per-job SELinux +security contexts in the same crontab. By default, cron jobs execute +with the default SELinux security context of the user that created the +crontab file. When using multiple security levels and roles, this may +not be sufficient, because the same user may be running in different +roles or in different security levels. For more information about roles +and SELinux MLS/MCS, see +.BR selinux (8) +and the crontab example mentioned later on in this text. You can set the +.I MLS_LEVEL +variable to the SELinux security context string specifying the particular +SELinux security context in which you want jobs to be run. +.B crond +will then set the execution context of those jobs that meet the +specifications of the particular security context. For more information, +see +.BR crontab (1)\ -s\ option. +.PP +The +.I RANDOM_DELAY +variable allows delaying job startups by random amount of minutes with +upper limit specified by the variable. The random scaling factor is +determined during the cron daemon startup so it remains constant for +the whole run time of the daemon. +.PP +The format of a cron command is similar to the V7 standard, with a number +of upward-compatible extensions. Each line has five time-and-date fields +followed by a +.BR user name +(if this is the +.BR system +crontab file), and followed by a command. Commands are executed by +.BR cron (8) +when the 'minute', 'hour', and 'month of the year' fields match the +current time, +.I and +at least one of the two 'day' fields ('day of month', or 'day of week') +match the current time (see "Note" below). +.PP +Note that this means that non-existent times, such as the "missing hours" +during the daylight savings time conversion, will never match, causing +jobs scheduled during the "missing times" not to be run. Similarly, +times that occur more than once (again, during the daylight savings time +conversion) will cause matching jobs to be run twice. +.PP +.BR cron (8) +examines cron entries every minute. +.PP +The time and date fields are: +.IP +.ta 1.5i +field allowed values +.br +----- -------------- +.br +minute 0-59 +.br +hour 0-23 +.br +day of month 1-31 +.br +month 1-12 (or names, see below) +.br +day of week 0-7 (0 or 7 is Sunday, or use names) +.br +.PP +A field may contain an asterisk (*), which always stands for +"first\-last". +.PP +Ranges of numbers are allowed. Ranges are two numbers separated with a +hyphen. The specified range is inclusive. For example, 8-11 for +an 'hours' entry specifies execution at hours 8, 9, 10, and 11. The first +number must be less than or equal to the second one. +.PP +Randomization of the execution time within a range can be used. +A random number within a range specified as two numbers separated with +a tilde is picked. The specified range is inclusive. +For example, 6~15 for a 'minutes' entry picks a random minute +within 6 to 15 range. The random number is picked when crontab file is parsed. +The first number must be less than or equal to the second one. You might omit +one or both of the numbers specifying the range. For example, ~ for a 'minutes' +entry picks a random minute within 0 to 59 range. +.PP +Lists are allowed. A list is a set of numbers (or ranges) separated by +commas. Examples: "1,2,5,9", "0-4,8-12". +.PP +Step values can be used in conjunction with ranges. Following a range +with "/" specifies skips of the number's value through the range. +For example, "0-23/2" can be used in the 'hours' field to specify command +execution for every other hour (the alternative in the V7 standard is +"0,\:2,\:4,\:6,\:8,\:10,\:12,\:14,\:16,\:18,\:20,\:22"). Step values are +also permitted after an asterisk, so if specifying a job to be run every +two hours, you can use "*/2". Please note that steps are evaluated just +within the field they are applied to. For example "*/23" in hours field +means to execute the job on the hour 0 and the hour 23 within a calendar +day. See "NOTES" below for a workaround. +.PP +Names can also be used for the 'month' and 'day of week' fields. Use the +first three letters of the particular day or month (case does not +matter). Ranges and lists of names are allowed. Examples: "mon,wed,fri", +"jan-mar". +.PP +If the UID of the owner is 0 (root), the first character of a crontab +entry can be "-" character. This will prevent cron from writing a syslog +message about the command being executed. +.PP +The "sixth" field (the rest of the line) specifies the command to be run. +The entire command portion of the line, up to a newline or a "%" +character, will be executed by /bin/sh or by the shell specified in the +SHELL variable of the cronfile. A "%" character in the command, unless +escaped with a backslash (\\), will be changed into newline characters, +and all data after the first % will be sent to the command as standard +input. +.PP +Note: The day of a command's execution can be specified in the following +two fields \(em 'day of month', and 'day of week'. If both fields are +restricted (i.e., do not contain the "*" character), the command will be +run when +.I either +field matches the current time. For example, +.br +"30 4 1,15 * 5" would cause a command to be run at 4:30 am on the 1st and +15th of each month, plus every Friday. +.PP +A crontab file syntax can be tested before an install using the -T option. See +.BR crontab (1) +for details. +.SH EXAMPLE CRON FILE +.nf +# use /bin/sh to run commands, no matter what /etc/passwd says +SHELL=/bin/sh +# mail any output to `paul', no matter whose crontab this is +MAILTO=paul +# +CRON_TZ=Japan +# run five minutes after midnight, every day +5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 +# run at 2:15pm on the first of every month -- output mailed to paul +15 14 1 * * $HOME/bin/monthly +# run at 10 pm on weekdays, annoy Joe +0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% +23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" +5 4 * * sun echo "run at 5 after 4 every sunday" +.fi +.SH Jobs in /etc/cron.d/ +The jobs in +.I cron.d +and +.I /etc/crontab +are system jobs, which are used usually for more than one user, thus, +additionally the username is needed. MAILTO on the first line is +optional. +.SH EXAMPLE OF A JOB IN /etc/cron.d/job +.nf +#login as root +#create job with preferred editor (e.g. vim) +MAILTO=root +* * * * * root touch /tmp/file +.fi +.SH NOTES +As noted above, skip values only operate within the time period they\'re +attached to. For example, specifying "0/35" for the minute field of a +crontab entry won\'t cause that entry to be executed every 35 minutes; +instead, it will be executed twice every hour, at 0 and 35 minutes past. +For more fine-grained control you can do something like this: +.nf +* * * * * if [ $(expr \( $(date +\%s) / 60 \) \% 58) = 0 ]; then echo this runs every 58 minutes; fi +0 * * * * if [ $(expr \( $(date +\%s) / 3600 \) \% 23) = 0 ]; then echo this runs every 23 hours on the hour; fi +.fi +Adjust as needed if your +.BR date (1) +command does not accept "+%s" as the format string specifier to output +the current UNIX timestamp. +.SH SELinux with multi level security (MLS) +In a crontab, it is important to specify a security level by +.I crontab \-s +or specifying the required level on the first line of the crontab. Each +level is specified in +.IR /etc/selinux/targeted/seusers . +When using crontab in the MLS mode, it is especially important to: +.br +- check/change the actual role, +.br +- set correct +.I role for +.IR directory , +which is used for input/output. +.SH EXAMPLE FOR SELINUX MLS +.nf +# login as root +newrole -r sysadm_r +mkdir /tmp/SystemHigh +chcon -l SystemHigh /tmp/SystemHigh +crontab -e +# write in crontab file +MLS_LEVEL=SystemHigh +0-59 * * * * id -Z > /tmp/SystemHigh/crontest +.fi +.SH FILES +.I /etc/crontab +main system crontab file. +.I /var/spool/cron/ +a directory for storing crontabs defined by users. +.I /etc/cron.d/ +a directory for storing system crontabs. +.SH "SEE ALSO" +.BR cron (8), +.BR crontab (1) +.SH EXTENSIONS +These special time specification "nicknames" which replace the 5 initial +time and date fields, and are prefixed with the '@' character, are +supported: +.PP +.nf +@reboot : Run once after reboot. +@yearly : Run once a year, ie. "0 0 1 1 *". +@annually : Run once a year, ie. "0 0 1 1 *". +@monthly : Run once a month, ie. "0 0 1 * *". +@weekly : Run once a week, ie. "0 0 * * 0". +@daily : Run once a day, ie. "0 0 * * *". +@hourly : Run once an hour, ie. "0 * * * *". +.fi +.SH CAVEATS +.BR crontab +files have to be regular files or symlinks to regular files, they must +not be executable or writable for anyone else but the owner. This +requirement can be overridden by using the +.B \-p +option on the crond command line. If inotify support is in use, changes +in the symlinked crontabs are not automatically noticed by the cron +daemon. The cron daemon must receive a SIGHUP signal to reload the +crontabs. This is a limitation of the inotify API. +.PP +cron requires that each entry in a crontab end in a newline character. If the +last entry in a crontab is missing a newline (i.e.\& terminated by EOF), +cron will consider the crontab (at least partially) broken. +A warning will be written to syslog. +.SH AUTHOR +.MT vixie@isc.org +Paul Vixie +.ME diff --git a/upstream/fedora-40/man5/crypttab.5 b/upstream/fedora-40/man5/crypttab.5 new file mode 100644 index 00000000..1a621795 --- /dev/null +++ b/upstream/fedora-40/man5/crypttab.5 @@ -0,0 +1,1114 @@ +'\" t +.TH "CRYPTTAB" "5" "" "systemd 255" "crypttab" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +crypttab \- Configuration for encrypted block devices +.SH "SYNOPSIS" +.PP +/etc/crypttab +.SH "DESCRIPTION" +.PP +The +/etc/crypttab +file describes encrypted block devices that are set up during system boot\&. +.PP +Empty lines and lines starting with the +"#" +character are ignored\&. Each of the remaining lines describes one encrypted block device\&. Fields are delimited by white space\&. +.PP +Each line is in the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIvolume\-name\fR \fIencrypted\-device\fR \fIkey\-file\fR \fIoptions\fR +.fi +.if n \{\ +.RE +.\} +.sp +The first two fields are mandatory, the remaining two are optional\&. +.PP +Setting up encrypted block devices using this file supports four encryption modes: LUKS, TrueCrypt, BitLocker and plain\&. See +\fBcryptsetup\fR(8) +for more information about each mode\&. When no mode is specified in the options field and the block device contains a LUKS signature, it is opened as a LUKS device; otherwise, it is assumed to be in raw dm\-crypt (plain mode) format\&. +.PP +The four fields of +/etc/crypttab +are defined as follows: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +The first field contains the name of the resulting volume with decrypted data; its block device is set up below +/dev/mapper/\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +The second field contains a path to the underlying block device or file, or a specification of a block device via +"UUID=" +followed by the UUID\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +The third field specifies an absolute path to a file with the encryption key\&. Optionally, the path may be followed by +":" +and an +/etc/fstab +style device specification (e\&.g\&. starting with +"LABEL=" +or similar); in which case the path is taken relative to the specified device\*(Aqs file system root\&. If the field is not present or is +"none" +or +"\-", a key file named after the volume to unlock (i\&.e\&. the first column of the line), suffixed with +\&.key +is automatically loaded from the +/etc/cryptsetup\-keys\&.d/ +and +/run/cryptsetup\-keys\&.d/ +directories, if present\&. Otherwise, the password has to be manually entered during system boot\&. For swap encryption, +/dev/urandom +may be used as key file, resulting in a randomized key\&. +.sp +If the specified key file path refers to an +\fBAF_UNIX\fR +stream socket in the file system, the key is acquired by connecting to the socket and reading it from the connection\&. This allows the implementation of a service to provide key information dynamically, at the moment when it is needed\&. For details see below\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +The fourth field, if present, is a comma\-delimited list of options\&. The supported options are listed below\&. +.RE +.SH "KEY ACQUISITION" +.PP +Six different mechanisms for acquiring the decryption key or passphrase unlocking the encrypted volume are supported\&. Specifically: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Most prominently, the user may be queried interactively during volume activation (i\&.e\&. typically at boot), asking them to type in the necessary passphrases\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +The (unencrypted) key may be read from a file on disk, possibly on removable media\&. The third field of each line encodes the location, for details see above\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +The (unencrypted) key may be requested from another service, by specifying an +\fBAF_UNIX\fR +file system socket in place of a key file in the third field\&. For details see above and below\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +The key may be acquired via a PKCS#11 compatible hardware security token or smartcard\&. In this case an encrypted key is stored on disk/removable media, acquired via +\fBAF_UNIX\fR, or stored in the LUKS2 JSON token metadata header\&. The encrypted key is then decrypted by the PKCS#11 token with an RSA key stored on it, and then used to unlock the encrypted volume\&. Use the +\fBpkcs11\-uri=\fR +option described below to use this mechanism\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +Similarly, the key may be acquired via a FIDO2 compatible hardware security token (which must implement the "hmac\-secret" extension)\&. In this case a key generated randomly during enrollment is stored on disk/removable media, acquired via +\fBAF_UNIX\fR, or stored in the LUKS2 JSON token metadata header\&. The random key is hashed via a keyed hash function (HMAC) on the FIDO2 token, using a secret key stored on the token that never leaves it\&. The resulting hash value is then used as key to unlock the encrypted volume\&. Use the +\fBfido2\-device=\fR +option described below to use this mechanism\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +Similarly, the key may be acquired via a TPM2 security chip\&. In this case a (during enrollment) randomly generated key \(em encrypted by an asymmetric key derived from the TPM2 chip\*(Aqs seed key \(em is stored on disk/removable media, acquired via +\fBAF_UNIX\fR, or stored in the LUKS2 JSON token metadata header\&. Use the +\fBtpm2\-device=\fR +option described below to use this mechanism\&. +.RE +.PP +For the latter five mechanisms the source for the key material used for unlocking the volume is primarily configured in the third field of each +/etc/crypttab +line, but may also configured in +/etc/cryptsetup\-keys\&.d/ +and +/run/cryptsetup\-keys\&.d/ +(see above) or in the LUKS2 JSON token header (in case of the latter three)\&. Use the +\fBsystemd-cryptenroll\fR(1) +tool to enroll PKCS#11, FIDO2 and TPM2 devices in LUKS2 volumes\&. +.SH "SUPPORTED OPTIONS" +.PP +The following options may be used in the fourth field of each line: +.PP +\fBcipher=\fR +.RS 4 +Specifies the cipher to use\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. A cipher with unpredictable IV values, such as +"aes\-cbc\-essiv:sha256", is recommended\&. Embedded commas in the cipher specification need to be escaped by preceding them with a backslash, see example below\&. +.sp +Added in version 186\&. +.RE +.PP +\fBdiscard\fR +.RS 4 +Allow discard requests to be passed through the encrypted block device\&. This improves performance on SSD storage but has security implications\&. +.sp +Added in version 207\&. +.RE +.PP +\fBhash=\fR +.RS 4 +Specifies the hash to use for password hashing\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. +.sp +Added in version 186\&. +.RE +.PP +\fBheader=\fR +.RS 4 +Use a detached (separated) metadata device or file where the header containing the master key(s) is stored\&. This option is only relevant for LUKS and TrueCrypt/VeraCrypt devices\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. +.sp +Optionally, the path may be followed by +":" +and an +/etc/fstab +device specification (e\&.g\&. starting with +"UUID=" +or similar); in which case, the path is relative to the device file system root\&. The device gets mounted automatically for LUKS device activation duration only\&. +.sp +Added in version 219\&. +.RE +.PP +\fBkeyfile\-offset=\fR +.RS 4 +Specifies the number of bytes to skip at the start of the key file\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. +.sp +Added in version 187\&. +.RE +.PP +\fBkeyfile\-size=\fR +.RS 4 +Specifies the maximum number of bytes to read from the key file\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. This option is ignored in plain encryption mode, as the key file size is then given by the key size\&. +.sp +Added in version 188\&. +.RE +.PP +\fBkeyfile\-erase\fR +.RS 4 +If enabled, the specified key file is erased after the volume is activated or when activation fails\&. This is in particular useful when the key file is only acquired transiently before activation (e\&.g\&. via a file in +/run/, generated by a service running before activation), and shall be removed after use\&. Defaults to off\&. +.sp +Added in version 246\&. +.RE +.PP +\fBkey\-slot=\fR +.RS 4 +Specifies the key slot to compare the passphrase or key against\&. If the key slot does not match the given passphrase or key, but another would, the setup of the device will fail regardless\&. This option implies +\fBluks\fR\&. See +\fBcryptsetup\fR(8) +for possible values\&. The default is to try all key slots in sequential order\&. +.sp +Added in version 209\&. +.RE +.PP +\fBkeyfile\-timeout=\fR +.RS 4 +Specifies the timeout for the device on which the key file resides or the device used as the key file, and falls back to a password if it could not be accessed\&. See +\fBsystemd-cryptsetup-generator\fR(8) +for key files on external devices\&. +.sp +Added in version 243\&. +.RE +.PP +\fBluks\fR +.RS 4 +Force LUKS mode\&. When this mode is used, the following options are ignored since they are provided by the LUKS header on the device: +\fBcipher=\fR, +\fBhash=\fR, +\fBsize=\fR\&. +.sp +Added in version 186\&. +.RE +.PP +\fBbitlk\fR +.RS 4 +Decrypt BitLocker drive\&. Encryption parameters are deduced by cryptsetup from BitLocker header\&. +.sp +Added in version 246\&. +.RE +.PP +\fB_netdev\fR +.RS 4 +Marks this cryptsetup device as requiring network\&. It will be started after the network is available, similarly to +\fBsystemd.mount\fR(5) +units marked with +\fB_netdev\fR\&. The service unit to set up this device will be ordered between +remote\-fs\-pre\&.target +and +remote\-cryptsetup\&.target, instead of +cryptsetup\-pre\&.target +and +cryptsetup\&.target\&. +.sp +Hint: if this device is used for a mount point that is specified in +\fBfstab\fR(5), the +\fB_netdev\fR +option should also be used for the mount point\&. Otherwise, a dependency loop might be created where the mount point will be pulled in by +local\-fs\&.target, while the service to configure the network is usually only started +\fIafter\fR +the local file system has been mounted\&. +.sp +Added in version 235\&. +.RE +.PP +\fBnoauto\fR +.RS 4 +This device will not be added to +cryptsetup\&.target\&. This means that it will not be automatically unlocked on boot, unless something else pulls it in\&. In particular, if the device is used for a mount point, it\*(Aqll be unlocked automatically during boot, unless the mount point itself is also disabled with +\fBnoauto\fR\&. +.sp +Added in version 186\&. +.RE +.PP +\fBnofail\fR +.RS 4 +This device will not be a hard dependency of +cryptsetup\&.target\&. It\*(Aqll still be pulled in and started, but the system will not wait for the device to show up and be unlocked, and boot will not fail if this is unsuccessful\&. Note that other units that depend on the unlocked device may still fail\&. In particular, if the device is used for a mount point, the mount point itself also needs to have the +\fBnofail\fR +option, or the boot will fail if the device is not unlocked successfully\&. +.sp +Added in version 186\&. +.RE +.PP +\fBoffset=\fR +.RS 4 +Start offset in the backend device, in 512\-byte sectors\&. This option is only relevant for plain devices\&. +.sp +Added in version 220\&. +.RE +.PP +\fBplain\fR +.RS 4 +Force plain encryption mode\&. +.sp +Added in version 186\&. +.RE +.PP +\fBread\-only\fR, \fBreadonly\fR +.RS 4 +Set up the encrypted block device in read\-only mode\&. +.sp +Added in version 186\&. +.RE +.PP +\fBsame\-cpu\-crypt\fR +.RS 4 +Perform encryption using the same CPU that IO was submitted on\&. The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs\&. +.sp +This requires kernel 4\&.0 or newer\&. +.sp +Added in version 242\&. +.RE +.PP +\fBsubmit\-from\-crypt\-cpus\fR +.RS 4 +Disable offloading writes to a separate thread after encryption\&. There are some situations where offloading write requests from the encryption threads to a dedicated thread degrades performance significantly\&. The default is to offload write requests to a dedicated thread because it benefits the CFQ scheduler to have writes submitted using the same context\&. +.sp +This requires kernel 4\&.0 or newer\&. +.sp +Added in version 242\&. +.RE +.PP +\fBno\-read\-workqueue\fR +.RS 4 +Bypass dm\-crypt internal workqueue and process read requests synchronously\&. The default is to queue these requests and process them asynchronously\&. +.sp +This requires kernel 5\&.9 or newer\&. +.sp +Added in version 248\&. +.RE +.PP +\fBno\-write\-workqueue\fR +.RS 4 +Bypass dm\-crypt internal workqueue and process write requests synchronously\&. The default is to queue these requests and process them asynchronously\&. +.sp +This requires kernel 5\&.9 or newer\&. +.sp +Added in version 248\&. +.RE +.PP +\fBskip=\fR +.RS 4 +How many 512\-byte sectors of the encrypted data to skip at the beginning\&. This is different from the +\fBoffset=\fR +option with respect to the sector numbers used in initialization vector (IV) calculation\&. Using +\fBoffset=\fR +will shift the IV calculation by the same negative amount\&. Hence, if +\fBoffset=\fR\fB\fIn\fR\fR +is given, sector +\fIn\fR +will get a sector number of 0 for the IV calculation\&. Using +\fBskip=\fR +causes sector +\fIn\fR +to also be the first sector of the mapped device, but with its number for IV generation being +\fIn\fR\&. +.sp +This option is only relevant for plain devices\&. +.sp +Added in version 220\&. +.RE +.PP +\fBsize=\fR +.RS 4 +Specifies the key size in bits\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. +.sp +Added in version 186\&. +.RE +.PP +\fBsector\-size=\fR +.RS 4 +Specifies the sector size in bytes\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. +.sp +Added in version 240\&. +.RE +.PP +\fBswap\fR +.RS 4 +The encrypted block device will be used as a swap device, and will be formatted accordingly after setting up the encrypted block device, with +\fBmkswap\fR(8)\&. This option implies +\fBplain\fR\&. +.sp +WARNING: Using the +\fBswap\fR +option will destroy the contents of the named partition during every boot, so make sure the underlying block device is specified correctly\&. +.sp +Added in version 186\&. +.RE +.PP +\fBtcrypt\fR +.RS 4 +Use TrueCrypt encryption mode\&. When this mode is used, the following options are ignored since they are provided by the TrueCrypt header on the device or do not apply: +\fBcipher=\fR, +\fBhash=\fR, +\fBkeyfile\-offset=\fR, +\fBkeyfile\-size=\fR, +\fBsize=\fR\&. +.sp +When this mode is used, the passphrase is read from the key file given in the third field\&. Only the first line of this file is read, excluding the new line character\&. +.sp +Note that the TrueCrypt format uses both passphrase and key files to derive a password for the volume\&. Therefore, the passphrase and all key files need to be provided\&. Use +\fBtcrypt\-keyfile=\fR +to provide the absolute path to all key files\&. When using an empty passphrase in combination with one or more key files, use +"/dev/null" +as the password file in the third field\&. +.sp +Added in version 206\&. +.RE +.PP +\fBtcrypt\-hidden\fR +.RS 4 +Use the hidden TrueCrypt volume\&. This option implies +\fBtcrypt\fR\&. +.sp +This will map the hidden volume that is inside of the volume provided in the second field\&. Please note that there is no protection for the hidden volume if the outer volume is mounted instead\&. See +\fBcryptsetup\fR(8) +for more information on this limitation\&. +.sp +Added in version 206\&. +.RE +.PP +\fBtcrypt\-keyfile=\fR +.RS 4 +Specifies the absolute path to a key file to use for a TrueCrypt volume\&. This implies +\fBtcrypt\fR +and can be used more than once to provide several key files\&. +.sp +See the entry for +\fBtcrypt\fR +on the behavior of the passphrase and key files when using TrueCrypt encryption mode\&. +.sp +Added in version 206\&. +.RE +.PP +\fBtcrypt\-system\fR +.RS 4 +Use TrueCrypt in system encryption mode\&. This option implies +\fBtcrypt\fR\&. +.sp +Added in version 206\&. +.RE +.PP +\fBtcrypt\-veracrypt\fR +.RS 4 +Check for a VeraCrypt volume\&. VeraCrypt is a fork of TrueCrypt that is mostly compatible, but uses different, stronger key derivation algorithms that cannot be detected without this flag\&. Enabling this option could substantially slow down unlocking, because VeraCrypt\*(Aqs key derivation takes much longer than TrueCrypt\*(Aqs\&. This option implies +\fBtcrypt\fR\&. +.sp +Added in version 232\&. +.RE +.PP +\fBveracrypt\-pim=\fR +.RS 4 +Specifies a custom Personal Iteration Multiplier (PIM) value, which can range from 0\&.\&.2147468 for standard veracrypt volumes and 0\&.\&.65535 for veracrypt system volumes\&. A value of 0 will imply the VeraCrypt default\&. This option is only effective when +\fBtcrypt\-veracrypt\fR +is set\&. +.sp +Note that VeraCrypt enforces a minimal allowed PIM value depending on the password strength and the hash algorithm used for key derivation, however +\fBveracrypt\-pim=\fR +is not checked against these bounds\&. See +\m[blue]\fBVeracrypt Personal Iterations Multiplier\fR\m[]\&\s-2\u[1]\d\s+2 +documentation for more information\&. +.sp +Added in version 254\&. +.RE +.PP +\fBtimeout=\fR +.RS 4 +Specifies the timeout for querying for a password\&. If no unit is specified, seconds is used\&. Supported units are s, ms, us, min, h, d\&. A timeout of 0 waits indefinitely (which is the default)\&. +.sp +Added in version 186\&. +.RE +.PP +\fBtmp=\fR +.RS 4 +The encrypted block device will be prepared for using it as +/tmp/; it will be formatted using +\fBmkfs\fR(8)\&. Takes a file system type as argument, such as +"ext4", +"xfs" +or +"btrfs"\&. If no argument is specified defaults to +"ext4"\&. This option implies +\fBplain\fR\&. +.sp +WARNING: Using the +\fBtmp\fR +option will destroy the contents of the named partition during every boot, so make sure the underlying block device is specified correctly\&. +.sp +Added in version 186\&. +.RE +.PP +\fBtries=\fR +.RS 4 +Specifies the maximum number of times the user is queried for a password\&. The default is 3\&. If set to 0, the user is queried for a password indefinitely\&. +.sp +Added in version 186\&. +.RE +.PP +\fBheadless=\fR +.RS 4 +Takes a boolean argument, defaults to false\&. If true, never query interactively for the password/PIN\&. Useful for headless systems\&. +.sp +Added in version 249\&. +.RE +.PP +\fBverify\fR +.RS 4 +If the encryption password is read from console, it has to be entered twice to prevent typos\&. +.sp +Added in version 186\&. +.RE +.PP +\fBpassword\-echo=yes|no|masked\fR +.RS 4 +Controls whether to echo passwords or security token PINs that are read from console\&. Takes a boolean or the special string +"masked"\&. The default is +\fBpassword\-echo=masked\fR\&. +.sp +If enabled, the typed characters are echoed literally\&. If disabled, the typed characters are not echoed in any form, the user will not get feedback on their input\&. If set to +"masked", an asterisk ("*") is echoed for each character typed\&. Regardless of which mode is chosen, if the user hits the tabulator key ("↹") at any time, or the backspace key ("⌫") before any other data has been entered, then echo is turned off\&. +.sp +Added in version 249\&. +.RE +.PP +\fBpkcs11\-uri=\fR +.RS 4 +Takes either the special value +"auto" +or an +\m[blue]\fBRFC7512 PKCS#11 URI\fR\m[]\&\s-2\u[2]\d\s+2 +pointing to a private RSA key which is used to decrypt the encrypted key specified in the third column of the line\&. This is useful for unlocking encrypted volumes through PKCS#11 compatible security tokens or smartcards\&. See below for an example how to set up this mechanism for unlocking a LUKS2 volume with a YubiKey security token\&. +.sp +If specified as +"auto" +the volume must be of type LUKS2 and must carry PKCS#11 security token metadata in its LUKS2 JSON token section\&. In this mode the URI and the encrypted key are automatically read from the LUKS2 JSON token header\&. Use +\fBsystemd-cryptenroll\fR(1) +as simple tool for enrolling PKCS#11 security tokens or smartcards in a way compatible with +"auto"\&. In this mode the third column of the line should remain empty (that is, specified as +"\-")\&. +.sp +The specified URI can refer directly to a private RSA key stored on a token or alternatively just to a slot or token, in which case a search for a suitable private RSA key will be performed\&. In this case if multiple suitable objects are found the token is refused\&. The encrypted key configured in the third column of the line is passed as is (i\&.e\&. in binary form, unprocessed) to RSA decryption\&. The resulting decrypted key is then Base64 encoded before it is used to unlock the LUKS volume\&. +.sp +Use +\fBsystemd\-cryptenroll \-\-pkcs11\-token\-uri=list\fR +to list all suitable PKCS#11 security tokens currently plugged in, along with their URIs\&. +.sp +Note that many newer security tokens that may be used as PKCS#11 security token typically also implement the newer and simpler FIDO2 standard\&. Consider using +\fBfido2\-device=\fR +(described below) to enroll it via FIDO2 instead\&. Note that a security token enrolled via PKCS#11 cannot be used to unlock the volume via FIDO2, unless also enrolled via FIDO2, and vice versa\&. +.sp +Added in version 245\&. +.RE +.PP +\fBfido2\-device=\fR +.RS 4 +Takes either the special value +"auto" +or the path to a +"hidraw" +device node (e\&.g\&. +/dev/hidraw1) referring to a FIDO2 security token that implements the +"hmac\-secret" +extension (most current hardware security tokens do)\&. See below for an example how to set up this mechanism for unlocking an encrypted volume with a FIDO2 security token\&. +.sp +If specified as +"auto" +the FIDO2 token device is automatically discovered, as it is plugged in\&. +.sp +FIDO2 volume unlocking requires a client ID hash (CID) to be configured via +\fBfido2\-cid=\fR +(see below) and a key to pass to the security token\*(Aqs HMAC functionality (configured in the line\*(Aqs third column) to operate\&. If not configured and the volume is of type LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead\&. Use +\fBsystemd-cryptenroll\fR(1) +as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is only available for LUKS2 volumes\&. +.sp +Use +\fBsystemd\-cryptenroll \-\-fido2\-device=list\fR +to list all suitable FIDO2 security tokens currently plugged in, along with their device nodes\&. +.sp +This option implements the following mechanism: the configured key is hashed via they HMAC keyed hash function the FIDO2 device implements, keyed by a secret key embedded on the device\&. The resulting hash value is Base64 encoded and used to unlock the LUKS2 volume\&. As it should not be possible to extract the secret from the hardware token, it should not be possible to retrieve the hashed key given the configured key \(em without possessing the hardware token\&. +.sp +Note that many security tokens that implement FIDO2 also implement PKCS#11, suitable for unlocking volumes via the +\fBpkcs11\-uri=\fR +option described above\&. Typically the newer, simpler FIDO2 standard is preferable\&. +.sp +Added in version 248\&. +.RE +.PP +\fBfido2\-cid=\fR +.RS 4 +Takes a Base64 encoded FIDO2 client ID to use for the FIDO2 unlock operation\&. If specified, but +\fBfido2\-device=\fR +is not, +\fBfido2\-device=auto\fR +is implied\&. If +\fBfido2\-device=\fR +is used but +\fBfido2\-cid=\fR +is not, the volume must be of LUKS2 type, and the CID is read from the LUKS2 JSON token header\&. Use +\fBsystemd-cryptenroll\fR(1) +for enrolling a FIDO2 token in the LUKS2 header compatible with this automatic mode\&. +.sp +Added in version 248\&. +.RE +.PP +\fBfido2\-rp=\fR +.RS 4 +Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock operation\&. If not specified +"io\&.systemd\&.cryptsetup" +is used, except if the LUKS2 JSON token header contains a different value\&. It should normally not be necessary to override this\&. +.sp +Added in version 248\&. +.RE +.PP +\fBtpm2\-device=\fR +.RS 4 +Takes either the special value +"auto" +or the path to a device node (e\&.g\&. +/dev/tpmrm0) referring to a TPM2 security chip\&. See below for an example how to set up this mechanism for unlocking an encrypted volume with a TPM2 chip\&. +.sp +Use +\fBtpm2\-pcrs=\fR +(see below) to configure the set of TPM2 PCRs to bind the volume unlocking to\&. Use +\fBsystemd-cryptenroll\fR(1) +as simple tool for enrolling TPM2 security chips in LUKS2 volumes\&. +.sp +If specified as +"auto" +the TPM2 device is automatically discovered\&. Use +\fBsystemd\-cryptenroll \-\-tpm2\-device=list\fR +to list all suitable TPM2 devices currently available, along with their device nodes\&. +.sp +This option implements the following mechanism: when enrolling a TPM2 device via +\fBsystemd\-cryptenroll\fR +on a LUKS2 volume, a randomized key unlocking the volume is generated on the host and loaded into the TPM2 chip where it is encrypted with an asymmetric "primary" key pair derived from the TPM2\*(Aqs internal "seed" key\&. Neither the seed key nor the primary key are permitted to ever leave the TPM2 chip \(em however, the now encrypted randomized key may\&. It is saved in the LUKS2 volume JSON token header\&. When unlocking the encrypted volume, the primary key pair is generated on the TPM2 chip again (which works as long as the chip\*(Aqs seed key is correctly maintained by the TPM2 chip), which is then used to decrypt (on the TPM2 chip) the encrypted key from the LUKS2 volume JSON token header saved there during enrollment\&. The resulting decrypted key is then used to unlock the volume\&. When the randomized key is encrypted the current values of the selected PCRs (see below) are included in the operation, so that different PCR state results in different encrypted keys and the decrypted key can only be recovered if the same PCR state is reproduced\&. +.sp +Added in version 248\&. +.RE +.PP +\fBtpm2\-pcrs=\fR +.RS 4 +Takes a +"+" +separated list of numeric TPM2 PCR (i\&.e\&. "Platform Configuration Register") indexes to bind the TPM2 volume unlocking to\&. This option is only useful when TPM2 enrollment metadata is not available in the LUKS2 JSON token header already, the way +\fBsystemd\-cryptenroll\fR +writes it there\&. If not used (and no metadata in the LUKS2 JSON token header defines it), defaults to a list of a single entry: PCR 7\&. Assign an empty string to encode a policy that binds the key to no PCRs, making the key accessible to local programs regardless of the current PCR state\&. +.sp +Added in version 248\&. +.RE +.PP +\fBtpm2\-pin=\fR +.RS 4 +Takes a boolean argument, defaults to +"false"\&. Controls whether TPM2 volume unlocking is bound to a PIN in addition to PCRs\&. Similarly, this option is only useful when TPM2 enrollment metadata is not available\&. +.sp +Added in version 251\&. +.RE +.PP +\fBtpm2\-signature=\fR +.RS 4 +Takes an absolute path to a TPM2 PCR JSON signature file, as produced by the +\fBsystemd-measure\fR(1) +tool\&. This permits locking LUKS2 volumes to any PCR values for which a valid signature matching a public key specified at key enrollment time can be provided\&. See +\fBsystemd-cryptenroll\fR(1) +for details on enrolling TPM2 PCR public keys\&. If this option is not specified but it is attempted to unlock a LUKS2 volume with a signed TPM2 PCR enrollment a suitable signature file +tpm2\-pcr\-signature\&.json +is searched for in +/etc/systemd/, +/run/systemd/, +/usr/lib/systemd/ +(in this order)\&. +.sp +Added in version 252\&. +.RE +.PP +\fBtpm2\-pcrlock=\fR +.RS 4 +Takes an absolute path to a TPM2 pcrlock policy file, as produced by the +\fBsystemd-pcrlock\fR(1) +tool\&. This permits locking LUKS2 volumes to a local policy of allowed PCR values with variants\&. See +\fBsystemd-cryptenroll\fR(1) +for details on enrolling TPM2 pcrlock policies\&. If this option is not specified but it is attempted to unlock a LUKS2 volume with a TPM2 pcrlock enrollment a suitable signature file +pcrlock\&.json +is searched for in +/run/systemd/ +and +/var/lib/systemd/ +(in this order)\&. +.sp +Added in version 255\&. +.RE +.PP +\fBtpm2\-measure\-pcr=\fR +.RS 4 +Controls whether to measure the volume key of the encrypted volume to a TPM2 PCR\&. If set to "no" (which is the default) no PCR extension is done\&. If set to "yes" the volume key is measured into PCR 15\&. If set to a decimal integer in the range 0\&...23 the volume key is measured into the specified PCR\&. The volume key is measured along with the activated volume name and its UUID\&. This functionality is particularly useful for the encrypted volume backing the root file system, as it then allows later TPM objects to be securely bound to the root file system and hence the specific installation\&. +.sp +Added in version 253\&. +.RE +.PP +\fBtpm2\-measure\-bank=\fR +.RS 4 +Selects one or more TPM2 PCR banks to measure the volume key into, as configured with +\fBtpm2\-measure\-pcr=\fR +above\&. Multiple banks may be specified, separated by a colon character\&. If not specified automatically determines available and used banks\&. Expects a message digest name (e\&.g\&. +"sha1", +"sha256", \&...) as argument, to identify the bank\&. +.sp +Added in version 253\&. +.RE +.PP +\fBtoken\-timeout=\fR +.RS 4 +Specifies how long to wait at most for configured security devices (i\&.e\&. FIDO2, PKCS#11, TPM2) to show up\&. Takes a time value in seconds (but other time units may be specified too, see +\fBsystemd.time\fR(7) +for supported formats)\&. Defaults to 30s\&. Once the specified timeout elapsed authentication via password is attempted\&. Note that this timeout applies to waiting for the security device to show up \(em it does not apply to the PIN prompt for the device (should one be needed) or similar\&. Pass 0 to turn off the time\-out and wait forever\&. +.sp +Added in version 250\&. +.RE +.PP +\fBtry\-empty\-password=\fR +.RS 4 +Takes a boolean argument\&. If enabled, right before asking the user for a password it is first attempted to unlock the volume with an empty password\&. This is useful for systems that are initialized with an encrypted volume with only an empty password set, which shall be replaced with a suitable password during first boot, but after activation\&. +.sp +Added in version 246\&. +.RE +.PP +\fBx\-systemd\&.device\-timeout=\fR +.RS 4 +Specifies how long systemd should wait for a block device to show up before giving up on the entry\&. The argument is a time in seconds or explicitly specified units of +"s", +"min", +"h", +"ms"\&. +.sp +Added in version 216\&. +.RE +.PP +\fBx\-initrd\&.attach\fR +.RS 4 +Setup this encrypted block device in the initrd, similarly to +\fBsystemd.mount\fR(5) +units marked with +\fBx\-initrd\&.mount\fR\&. +.sp +Although it\*(Aqs not necessary to mark the mount entry for the root file system with +\fBx\-initrd\&.mount\fR, +\fBx\-initrd\&.attach\fR +is still recommended with the encrypted block device containing the root file system as otherwise systemd will attempt to detach the device during the regular system shutdown while it\*(Aqs still in use\&. With this option the device will still be detached but later after the root file system is unmounted\&. +.sp +All other encrypted block devices that contain file systems mounted in the initrd should use this option\&. +.sp +Added in version 245\&. +.RE +.PP +At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by +\fBsystemd-cryptsetup-generator\fR(8)\&. +.SH "AF_UNIX KEY FILES" +.PP +If the key file path (as specified in the third column of +/etc/crypttab +entries, see above) refers to an +\fBAF_UNIX\fR +stream socket in the file system, the key is acquired by connecting to the socket and reading the key from the connection\&. The connection is made from an +\fBAF_UNIX\fR +socket name in the abstract namespace, see +\fBunix\fR(7) +for details\&. The source socket name is chosen according the following format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBNUL\fR \fIRANDOM\fR /cryptsetup/ \fIVOLUME\fR +.fi +.if n \{\ +.RE +.\} +.PP +In other words: a +\fBNUL\fR +byte (as required for abstract namespace sockets), followed by a random string (consisting of alphanumeric characters only), followed by the literal string +"/cryptsetup/", followed by the name of the volume to acquire they key for\&. For example, for the volume +"myvol": +.sp +.if n \{\ +.RS 4 +.\} +.nf +\e0d7067f78d9827418/cryptsetup/myvol +.fi +.if n \{\ +.RE +.\} +.PP +Services listening on the +\fBAF_UNIX\fR +stream socket may query the source socket name with +\fBgetpeername\fR(2), and use this to determine which key to send, allowing a single listening socket to serve keys for multiple volumes\&. If the PKCS#11 logic is used (see above), the socket source name is picked in similar fashion, except that the literal string +"/cryptsetup\-pkcs11/" +is used\&. And similarly for FIDO2 ("/cryptsetup\-fido2/") and TPM2 ("/cryptsetup\-tpm2/")\&. A different path component is used so that services providing key material know that the secret key was not requested directly, but instead an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire the final secret key\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&/etc/crypttab example\fR +.PP +Set up four encrypted block devices\&. One using LUKS for normal storage, another one for usage as a swap device and two TrueCrypt volumes\&. For the fourth device, the option string is interpreted as two options +"cipher=xchacha12,aes\-adiantum\-plain64", +"keyfile\-timeout=10s"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +luks UUID=2505567a\-9e27\-4efe\-a4d5\-15ad146c258b +swap /dev/sda7 /dev/urandom swap +truecrypt /dev/sda2 /etc/container_password tcrypt +hidden /mnt/tc_hidden /dev/null tcrypt\-hidden,tcrypt\-keyfile=/etc/keyfile +external /dev/sda3 keyfile:LABEL=keydev keyfile\-timeout=10s,cipher=xchacha12\e,aes\-adiantum\-plain64 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Yubikey\-based PKCS#11 Volume Unlocking Example\fR +.PP +The PKCS#11 logic allows hooking up any compatible security token that is capable of storing RSA decryption keys for unlocking an encrypted volume\&. Here\*(Aqs an example how to set up a Yubikey security token for this purpose on a LUKS2 volume, using +\fBykmap\fR(1) +from the yubikey\-manager project to initialize the token and +\fBsystemd-cryptenroll\fR(1) +to add it in the LUKS2 volume: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# SPDX\-License\-Identifier: MIT\-0 + +# Destroy any old key on the Yubikey (careful!) +ykman piv reset + +# Generate a new private/public key pair on the device, store the public key in +# \*(Aqpubkey\&.pem\*(Aq\&. +ykman piv generate\-key \-a RSA2048 9d pubkey\&.pem + +# Create a self\-signed certificate from this public key, and store it on the +# device\&. The "subject" should be an arbitrary user\-chosen string to identify +# the token with\&. +ykman piv generate\-certificate \-\-subject "Knobelei" 9d pubkey\&.pem + +# We don\*(Aqt need the public key anymore, let\*(Aqs remove it\&. Since it is not +# security sensitive we just do a regular "rm" here\&. +rm pubkey\&.pem + +# Enroll the freshly initialized security token in the LUKS2 volume\&. Replace +# /dev/sdXn by the partition to use (e\&.g\&. /dev/sda1)\&. +sudo systemd\-cryptenroll \-\-pkcs11\-token\-uri=auto /dev/sdXn + +# Test: Let\*(Aqs run systemd\-cryptsetup to test if this all worked\&. +sudo systemd\-cryptsetup attach mytest /dev/sdXn \- pkcs11\-uri=auto + +# If that worked, let\*(Aqs now add the same line persistently to /etc/crypttab, +# for the future\&. We don\*(Aqt want to use the (unstable) /dev/sdX name, so let\*(Aqs +# figure out a stable link: +udevadm info \-q \-r symlink /dev/sdXn + +# Now add the line using the by\-uuid symlink to /etc/crypttab: +sudo bash \-c \*(Aqecho "mytest /dev/disk/by\-uuid/\&.\&.\&. \- pkcs11\-uri=auto" >>/etc/crypttab\*(Aq + +# Depending on your distribution and encryption setup, you may need to manually +# regenerate your initramfs to be able to use a Yubikey / PKCS#11 token to +# unlock the partition during early boot\&. +# More information at https://unix\&.stackexchange\&.com/a/705809\&. +# On Fedora based systems: +sudo dracut \-\-force +# On Debian based systems: +sudo update\-initramfs \-u +.fi +.if n \{\ +.RE +.\} +.PP +A few notes on the above: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +We use RSA2048, which is the longest key size current Yubikeys support +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +We use Yubikey key slot 9d, since that\*(Aqs apparently the keyslot to use for decryption purposes, see +\m[blue]\fBYubico PIV certificate slots\fR\m[]\&\s-2\u[3]\d\s+2\&. +.RE +.PP +\fBExample\ \&3.\ \&FIDO2 Volume Unlocking Example\fR +.PP +The FIDO2 logic allows using any compatible FIDO2 security token that implements the +"hmac\-secret" +extension for unlocking an encrypted volume\&. Here\*(Aqs an example how to set up a FIDO2 security token for this purpose for a LUKS2 volume, using +\fBsystemd-cryptenroll\fR(1): +.sp +.if n \{\ +.RS 4 +.\} +.nf +# SPDX\-License\-Identifier: MIT\-0 + +# Enroll the security token in the LUKS2 volume\&. Replace /dev/sdXn by the +# partition to use (e\&.g\&. /dev/sda1)\&. +sudo systemd\-cryptenroll \-\-fido2\-device=auto /dev/sdXn + +# Test: Let\*(Aqs run systemd\-cryptsetup to test if this worked\&. +sudo systemd\-cryptsetup attach mytest /dev/sdXn \- fido2\-device=auto + +# If that worked, let\*(Aqs now add the same line persistently to /etc/crypttab, +# for the future\&. We don\*(Aqt want to use the (unstable) /dev/sdX name, so let\*(Aqs +# figure out a stable link: +udevadm info \-q \-r symlink /dev/sdXn + +# Now add the line using the by\-uuid symlink to /etc/crypttab: +sudo bash \-c \*(Aqecho "mytest /dev/disk/by\-uuid/\&.\&.\&. \- fido2\-device=auto" >>/etc/crypttab\*(Aq + +# Depending on your distribution and encryption setup, you may need to manually +# regenerate your initramfs to be able to use a FIDO2 device to unlock the +# partition during early boot\&. +# More information at https://unix\&.stackexchange\&.com/a/705809\&. +# On Fedora based systems: +sudo dracut \-\-force +# On Debian based systems: +sudo update\-initramfs \-u +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&TPM2 Volume Unlocking Example\fR +.PP +The TPM2 logic allows using any TPM2 chip supported by the Linux kernel for unlocking an encrypted volume\&. Here\*(Aqs an example how to set up a TPM2 chip for this purpose for a LUKS2 volume, using +\fBsystemd-cryptenroll\fR(1): +.sp +.if n \{\ +.RS 4 +.\} +.nf +# SPDX\-License\-Identifier: MIT\-0 + +# Enroll the TPM2 security chip in the LUKS2 volume, and bind it to PCR 7 +# only\&. Replace /dev/sdXn by the partition to use (e\&.g\&. /dev/sda1)\&. +sudo systemd\-cryptenroll \-\-tpm2\-device=auto \-\-tpm2\-pcrs=7 /dev/sdXn + +# Test: Let\*(Aqs run systemd\-cryptsetup to test if this worked\&. +sudo systemd\-cryptsetup attach mytest /dev/sdXn \- tpm2\-device=auto + +# If that worked, let\*(Aqs now add the same line persistently to /etc/crypttab, +# for the future\&. We don\*(Aqt want to use the (unstable) /dev/sdX name, so let\*(Aqs +# figure out a stable link: +udevadm info \-q \-r symlink /dev/sdXn + +# Now add the line using the by\-uuid symlink to /etc/crypttab: +sudo bash \-c \*(Aqecho "mytest /dev/disk/by\-uuid/\&.\&.\&. \- tpm2\-device=auto" >>/etc/crypttab\*(Aq + +# And now let\*(Aqs check that automatic unlocking works: +sudo systemd\-cryptsetup detach mytest +sudo systemctl daemon\-reload +sudo systemctl start cryptsetup\&.target +systemctl is\-active systemd\-cryptsetup@mytest\&.service + +# Once we have the device which will be unlocked automatically, we can use it\&. +# Usually we would create a file system and add it to /etc/fstab: +sudo mkfs\&.ext4 /dev/mapper/mytest +# This prints a \*(AqFilesystem UUID\*(Aq, which we can use as a stable name: +sudo bash \-c \*(Aqecho "/dev/disk/by\-uuid/\&.\&.\&. /var/mytest ext4 defaults,x\-systemd\&.mkdir 0 2" >>/etc/fstab\*(Aq +# And now let\*(Aqs check that the mounting works: +sudo systemctl daemon\-reload +sudo systemctl start /var/mytest +systemctl status /var/mytest + +# Depending on your distribution and encryption setup, you may need to manually +# regenerate your initramfs to be able to use a TPM2 security chip to unlock +# the partition during early boot\&. +# More information at https://unix\&.stackexchange\&.com/a/705809\&. +# On Fedora based systems: +sudo dracut \-\-force +# On Debian based systems: +sudo update\-initramfs \-u +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-cryptsetup@.service\fR(8), +\fBsystemd-cryptsetup-generator\fR(8), +\fBsystemd-cryptenroll\fR(1), +\fBfstab\fR(5), +\fBcryptsetup\fR(8), +\fBmkswap\fR(8), +\fBmke2fs\fR(8) +.SH "NOTES" +.IP " 1." 4 +Veracrypt Personal Iterations Multiplier +.RS 4 +\%https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html +.RE +.IP " 2." 4 +RFC7512 PKCS#11 URI +.RS 4 +\%https://tools.ietf.org/html/rfc7512 +.RE +.IP " 3." 4 +Yubico PIV certificate slots +.RS 4 +\%https://developers.yubico.com/PIV/Introduction/Certificate_slots.html +.RE diff --git a/upstream/fedora-40/man5/depmod.d.5 b/upstream/fedora-40/man5/depmod.d.5 new file mode 100644 index 00000000..93bc5922 --- /dev/null +++ b/upstream/fedora-40/man5/depmod.d.5 @@ -0,0 +1,126 @@ +'\" t +.\" Title: depmod.d +.\" Author: Jon Masters +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 01/25/2024 +.\" Manual: depmod.d +.\" Source: kmod +.\" Language: English +.\" +.TH "DEPMOD\&.D" "5" "01/25/2024" "kmod" "depmod.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +depmod.d \- Configuration directory for depmod +.SH "SYNOPSIS" +.PP +/lib/depmod\&.d/*\&.conf +.PP +/usr/lib/depmod\&.d/*\&.conf +.PP +/usr/local/lib/depmod\&.d/*\&.conf +.PP +/run/depmod\&.d/*\&.conf +.PP +/etc/depmod\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +The order in which modules are processed by the +\fBdepmod\fR +command can be altered on a global or per\-module basis\&. This is typically useful in cases where built\-in kernel modules are complemented by custom built versions of the same and the user wishes to affect the priority of processing in order to override the module version supplied by the kernel\&. +.PP +The format of files under +depmod\&.d +is simple: one command per line, with blank lines and lines starting with \*(Aq#\*(Aq ignored (useful for adding comments)\&. A \*(Aq\e\*(Aq at the end of a line causes it to continue on the next line, which makes the files a bit neater\&. +.SH "COMMANDS" +.PP +search \fIsubdirectory\&.\&.\&.\fR +.RS 4 +This allows you to specify the order in which /lib/modules (or other configured module location) subdirectories will be processed by +\fBdepmod\fR\&. Directories are listed in order, with the highest priority given to the first listed directory and the lowest priority given to the last directory listed\&. The special keyword +\fBbuilt\-in\fR +refers to the standard module directories installed by the kernel\&. Another special keyword +\fBexternal\fR +refers to the list of external directories, defined by the +\fBexternal\fR +command\&. +.sp +By default, depmod will give a higher priority to a directory with the name +\fBupdates\fR +using this built\-in search string: "updates built\-in" but more complex arrangements are possible and are used in several popular distributions\&. +.RE +.PP +override \fImodulename\fR \fIkernelversion\fR \fImodulesubdirectory\fR +.RS 4 +This command allows you to override which version of a specific module will be used when more than one module sharing the same name is processed by the +\fBdepmod\fR +command\&. It is possible to specify one kernel or all kernels using the * wildcard\&. +\fImodulesubdirectory\fR +is the name of the subdirectory under /lib/modules (or other module location) where the target module is installed\&. +.sp +For example, it is possible to override the priority of an updated test module called +\fBkmod\fR +by specifying the following command: "override kmod * extra"\&. This will ensure that any matching module name installed under the +\fBextra\fR +subdirectory within /lib/modules (or other module location) will take priority over any likenamed module already provided by the kernel\&. +.RE +.PP +external \fIkernelversion\fR \fIabsolutemodulesdirectory\&.\&.\&.\fR +.RS 4 +This specifies a list of directories, which will be checked according to the priorities in the +\fBsearch\fR +command\&. The order matters also, the first directory has the higher priority\&. +.sp +The +\fIkernelversion\fR +is a POSIX regular expression or * wildcard, like in the +\fBoverride\fR\&. +.RE +.PP +exclude \fIexcludedir\fR +.RS 4 +This specifies the trailing directories that will be excluded during the search for kernel modules\&. +.sp +The +\fIexcludedir\fR +is the trailing directory to exclude +.RE +.SH "COPYRIGHT" +.PP +This manual page Copyright 2006\-2010, Jon Masters, Red Hat, Inc\&. +.SH "SEE ALSO" +.PP +\fBdepmod\fR(8) +.SH "AUTHORS" +.PP +\fBJon Masters\fR <\&jcm@jonmasters\&.org\&> +.RS 4 +Developer +.RE +.PP +\fBRobby Workman\fR <\&rworkman@slackware\&.com\&> +.RS 4 +Developer +.RE +.PP +\fBLucas De Marchi\fR <\&lucas\&.de\&.marchi@gmail\&.com\&> +.RS 4 +Developer +.RE diff --git a/upstream/fedora-40/man5/dir_colors.5 b/upstream/fedora-40/man5/dir_colors.5 new file mode 100644 index 00000000..a492f644 --- /dev/null +++ b/upstream/fedora-40/man5/dir_colors.5 @@ -0,0 +1,406 @@ +'\" t +.\" Copyright (c) 2001 Martin Schulze +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH dir_colors 5 2024-01-28 "Linux man-pages 6.06" +.SH NAME +dir_colors \- configuration file for dircolors(1) +.SH DESCRIPTION +The program +.BR ls (1) +uses the environment variable +.B LS_COLORS +to determine the colors in which the filenames are to be displayed. +This environment variable is usually set by a command like +.P +.RS +eval \`dircolors some_path/dir_colors\` +.RE +.P +found in a system default shell initialization file, like +.I /etc/profile +or +.IR /etc/csh.cshrc . +(See also +.BR dircolors (1).) +Usually, the file used here is +.I /etc/DIR_COLORS +and can be overridden by a +.I .dir_colors +file in one's home directory. +.P +This configuration file consists of several statements, one per line. +Anything right of a hash mark (#) is treated as a comment, if the +hash mark is at the beginning of a line or is preceded by at least one +whitespace. +Blank lines are ignored. +.P +The +.I global +section of the file consists of any statement before the first +.B TERM +statement. +Any statement in the global section of the file is +considered valid for all terminal types. +Following the global section +is one or more +.I terminal-specific +sections, preceded by one or more +.B TERM +statements which specify the terminal types (as given by the +.B TERM +environment variable) the following declarations apply to. +It is always possible to override a global declaration by a subsequent +terminal-specific one. +.P +The following statements are recognized; case is insignificant: +.TP +.B TERM \fIterminal-type\fR +Starts a terminal-specific section and specifies which terminal it +applies to. +Multiple +.B TERM +statements can be used to create a section which applies for several +terminal types. +.TP +.B COLOR yes|all|no|none|tty +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that colorization should always be enabled (\fIyes\fR or +\fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if +the output is a terminal (\fItty\fR). +The default is \fIno\fR. +.TP +.B EIGHTBIT yes|no +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that eight-bit ISO/IEC\~8859 characters should be enabled by +default. +For compatibility reasons, this can also be specified as 1 for +\fIyes\fR or 0 for \fIno\fR. +The default is \fIno\fR. +.TP +.B OPTIONS \fIoptions\fR +(Slackware only; ignored by GNU +.BR dircolors (1).) +Adds command-line options to the default +.B ls +command line. +The options can be any valid +.B ls +command-line options, and should include the leading minus sign. +Note that +.B dircolors +does not verify the validity of these options. +.TP +.B NORMAL \fIcolor-sequence\fR +Specifies the color used for normal (nonfilename) text. +.IP +Synonym: +.BR NORM . +.TP +.B FILE \fIcolor-sequence\fR +Specifies the color used for a regular file. +.TP +.B DIR \fIcolor-sequence\fR +Specifies the color used for directories. +.TP +.B LINK \fIcolor-sequence\fR +Specifies the color used for a symbolic link. +.IP +Synonyms: +.BR LNK , +.BR SYMLINK . +.TP +.B ORPHAN \fIcolor-sequence\fR +Specifies the color used for an orphaned symbolic link (one which +points to a nonexistent file). +If this is unspecified, +.B ls +will use the +.B LINK +color instead. +.TP +.B MISSING \fIcolor-sequence\fR +Specifies the color used for a missing file (a nonexistent file which +nevertheless has a symbolic link pointing to it). +If this is unspecified, +.B ls +will use the +.B FILE +color instead. +.TP +.B FIFO \fIcolor-sequence\fR +Specifies the color used for a FIFO (named pipe). +.IP +Synonym: +.BR PIPE . +.TP +.B SOCK \fIcolor-sequence\fR +Specifies the color used for a socket. +.TP +.B DOOR \fIcolor-sequence\fR +(Supported since fileutils 4.1) +Specifies the color used for a door (Solaris 2.5 and later). +.TP +.B BLK \fIcolor-sequence\fR +Specifies the color used for a block device special file. +.IP +Synonym: +.BR BLOCK . +.TP +.B CHR \fIcolor-sequence\fR +Specifies the color used for a character device special file. +.IP +Synonym: +.BR CHAR . +.TP +.B EXEC \fIcolor-sequence\fR +Specifies the color used for a file with the executable attribute set. +.TP +.B SUID \fIcolor-sequence\fR +Specifies the color used for a file with the set-user-ID attribute set. +.IP +Synonym: +.BR SETUID . +.TP +.B SGID \fIcolor-sequence\fR +Specifies the color used for a file with the set-group-ID attribute set. +.IP +Synonym: +.BR SETGID . +.TP +.B STICKY \fIcolor-sequence\fR +Specifies the color used for a directory with the sticky attribute set. +.TP +.B STICKY_OTHER_WRITABLE \fIcolor-sequence\fR +Specifies the color used for +an other-writable directory with the executable attribute set. +.IP +Synonym: +.BR OWT . +.TP +.B OTHER_WRITABLE \fIcolor-sequence\fR +Specifies the color used for +an other-writable directory without the executable attribute set. +.IP +Synonym: +.BR OWR . +.TP +.B LEFTCODE \fIcolor-sequence\fR +Specifies the +.I "left code" +for non-ISO/IEC\~6429 terminals (see below). +.IP +Synonym: +.BR LEFT . +.TP +.B RIGHTCODE \fIcolor-sequence\fR +Specifies the +.I "right code" +for non-ISO/IEC\~6429 terminals (see below). +.IP +Synonym: +.BR RIGHT . +.TP +.B ENDCODE \fIcolor-sequence\fR +Specifies the +.I "end code" +for non-ISO/IEC\~6429 terminals (see below). +.IP +Synonym: +.BR END . +.TP +.BI * "extension color-sequence" +Specifies the color used for any file that ends in \fIextension\fR. +.TP +.BI . "extension color-sequence" +Same as \fB*\fR.\fIextension\fR. +Specifies the color used for any file that +ends in .\fIextension\fR. +Note that the period is included in the +extension, which makes it impossible to specify an extension not +starting with a period, such as +.B \[ti] +for +.B emacs +backup files. +This form should be considered obsolete. +.SS ISO/IEC\~6429 (ANSI) color sequences +Most color-capable ASCII terminals today use ISO/IEC\~6429 (ANSI) color sequences, +and many common terminals without color capability, including +.B xterm +and the widely used and cloned DEC VT100, will recognize ISO/IEC\~6429 color +codes and harmlessly eliminate them from the output or emulate them. +.B ls +uses ISO/IEC\~6429 codes by default, assuming colorization is enabled. +.P +ISO/IEC\~6429 color sequences are composed of sequences of numbers +separated by semicolons. +The most common codes are: +.RS +.TS +l l. + 0 to restore default color + 1 for brighter colors + 4 for underlined text + 5 for flashing text +30 for black foreground +31 for red foreground +32 for green foreground +33 for yellow (or brown) foreground +34 for blue foreground +35 for purple foreground +36 for cyan foreground +37 for white (or gray) foreground +40 for black background +41 for red background +42 for green background +43 for yellow (or brown) background +44 for blue background +45 for purple background +46 for cyan background +47 for white (or gray) background +.TE +.RE +.P +Not all commands will work on all systems or display devices. +.P +.B ls +uses the following defaults: +.TS +lb l l. +NORMAL 0 Normal (nonfilename) text +FILE 0 Regular file +DIR 32 Directory +LINK 36 Symbolic link +ORPHAN undefined Orphaned symbolic link +MISSING undefined Missing file +FIFO 31 Named pipe (FIFO) +SOCK 33 Socket +BLK 44;37 Block device +CHR 44;37 Character device +EXEC 35 Executable file +.TE +.P +A few terminal programs do not recognize the default +properly. +If all text gets colorized after you do a directory +listing, change the +.B NORMAL +and +.B FILE +codes to the numerical codes for your normal foreground and background +colors. +.SS Other terminal types (advanced configuration) +If you have a color-capable (or otherwise highlighting) terminal (or +printer!) which uses a different set of codes, you can still generate +a suitable setup. +To do so, you will have to use the +.BR LEFTCODE , +.BR RIGHTCODE , +and +.B ENDCODE +definitions. +.P +When writing out a filename, +.B ls +generates the following output sequence: +.B LEFTCODE +.I typecode +.B RIGHTCODE +.I filename +.BR ENDCODE , +where the +.I typecode +is the color sequence that depends on the type or name of file. +If the +.B ENDCODE +is undefined, the sequence +.B "LEFTCODE NORMAL RIGHTCODE" +will be used instead. +The purpose of the left- and rightcodes is +merely to reduce the amount of typing necessary (and to hide ugly +escape codes away from the user). +If they are not appropriate for +your terminal, you can eliminate them by specifying the respective +keyword on a line by itself. +.P +.B NOTE: +If the +.B ENDCODE +is defined in the global section of the setup file, it +.I cannot +be undefined in a terminal-specific section of the file. +This means any +.B NORMAL +definition will have no effect. +A different +.B ENDCODE +can, however, be specified, which would have the same effect. +.SS Escape sequences +To specify control- or blank characters in the color sequences or +filename extensions, either C-style \e-escaped notation or +.BR stty \-style +\[ha]-notation can be used. +The C-style notation +includes the following characters: +.RS +.TS +lb l. +\ea Bell (ASCII 7) +\eb Backspace (ASCII 8) +\ee Escape (ASCII 27) +\ef Form feed (ASCII 12) +\en Newline (ASCII 10) +\er Carriage Return (ASCII 13) +\et Tab (ASCII 9) +\ev Vertical Tab (ASCII 11) +\e? Delete (ASCII 127) +\e\fInnn Any character (octal notation) +\ex\fInnn Any character (hexadecimal notation) +\e_ Space +\e\e Backslash (\e) +\e\[ha] Caret (\[ha]) +\e# Hash mark (#) +.TE +.RE +.P +Note that escapes are necessary to enter a space, backslash, +caret, or any control character anywhere in the string, as well as a +hash mark as the first character. +.SH FILES +.TP +.I /etc/DIR_COLORS +System-wide configuration file. +.TP +.I \[ti]/.dir_colors +Per-user configuration file. +.P +This page describes the +.B dir_colors +file format as used in the fileutils-4.1 package; +other versions may differ slightly. +.SH NOTES +The default +.B LEFTCODE +and +.B RIGHTCODE +definitions, which are used by ISO/IEC\~6429 terminals are: +.RS +.TS +lb l. +LEFTCODE \ee[ +RIGHTCODE m +.TE +.RE +.P +The default +.B ENDCODE +is undefined. +.SH SEE ALSO +.BR dircolors (1), +.BR ls (1), +.BR stty (1), +.BR xterm (1) diff --git a/upstream/fedora-40/man5/dnssec-trust-anchors.d.5 b/upstream/fedora-40/man5/dnssec-trust-anchors.d.5 new file mode 100644 index 00000000..4671d2f5 --- /dev/null +++ b/upstream/fedora-40/man5/dnssec-trust-anchors.d.5 @@ -0,0 +1,227 @@ +'\" t +.TH "DNSSEC\-TRUST\-ANCHORS\&.D" "5" "" "systemd 255" "dnssec-trust-anchors.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +dnssec-trust-anchors.d, systemd.positive, systemd.negative \- DNSSEC trust anchor configuration files +.SH "SYNOPSIS" +.PP +/etc/dnssec\-trust\-anchors\&.d/*\&.positive +.PP +/run/dnssec\-trust\-anchors\&.d/*\&.positive +.PP +/usr/lib/dnssec\-trust\-anchors\&.d/*\&.positive +.PP +/etc/dnssec\-trust\-anchors\&.d/*\&.negative +.PP +/run/dnssec\-trust\-anchors\&.d/*\&.negative +.PP +/usr/lib/dnssec\-trust\-anchors\&.d/*\&.negative +.SH "DESCRIPTION" +.PP +The DNSSEC trust anchor configuration files define positive and negative trust anchors +\fBsystemd-resolved.service\fR(8) +bases DNSSEC integrity proofs on\&. +.SH "POSITIVE TRUST ANCHORS" +.PP +Positive trust anchor configuration files contain +\fBDNSKEY\fR +and +\fBDS\fR +resource record definitions to use as base for DNSSEC integrity proofs\&. See +\m[blue]\fBRFC 4035, Section 4\&.4\fR\m[]\&\s-2\u[1]\d\s+2 +for more information about DNSSEC trust anchors\&. +.PP +Positive trust anchors are read from files with the suffix +\&.positive +located in +/etc/dnssec\-trust\-anchors\&.d/, +/run/dnssec\-trust\-anchors\&.d/ +and +/usr/lib/dnssec\-trust\-anchors\&.d/\&. These directories are searched in the specified order, and a trust anchor file of the same name in an earlier path overrides a trust anchor files in a later path\&. To disable a trust anchor file shipped in +/usr/lib/dnssec\-trust\-anchors\&.d/ +it is sufficient to provide an identically\-named file in +/etc/dnssec\-trust\-anchors\&.d/ +or +/run/dnssec\-trust\-anchors\&.d/ +that is either empty or a symlink to +/dev/null +("masked")\&. +.PP +Positive trust anchor files are simple text files resembling DNS zone files, as documented in +\m[blue]\fBRFC 1035, Section 5\fR\m[]\&\s-2\u[2]\d\s+2\&. One +\fBDS\fR +or +\fBDNSKEY\fR +resource record may be listed per line\&. Empty lines and lines starting with +"#" +or +";" +are ignored, which may be used for commenting\&. A +\fBDS\fR +resource record is specified like in the following example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\&. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5 +.fi +.if n \{\ +.RE +.\} +.PP +The first word specifies the domain, use +"\&." +for the root domain\&. The domain may be specified with or without trailing dot, which is considered equivalent\&. The second word must be +"IN" +the third word +"DS"\&. The following words specify the key tag, signature algorithm, digest algorithm, followed by the hex\-encoded key fingerprint\&. See +\m[blue]\fBRFC 4034, Section 5\fR\m[]\&\s-2\u[3]\d\s+2 +for details about the precise syntax and meaning of these fields\&. +.PP +Alternatively, +\fBDNSKEY\fR +resource records may be used to define trust anchors, like in the following example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\&. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= +.fi +.if n \{\ +.RE +.\} +.PP +The first word specifies the domain again, the second word must be +"IN", followed by +"DNSKEY"\&. The subsequent words encode the +\fBDNSKEY\fR +flags, protocol and algorithm fields, followed by the key data encoded in Base64\&. See +\m[blue]\fBRFC 4034, Section 2\fR\m[]\&\s-2\u[4]\d\s+2 +for details about the precise syntax and meaning of these fields\&. +.PP +If multiple +\fBDS\fR +or +\fBDNSKEY\fR +records are defined for the same domain (possibly even in different trust anchor files), all keys are used and are considered equivalent as base for DNSSEC proofs\&. +.PP +Note that +systemd\-resolved +will automatically use a built\-in trust anchor key for the Internet root domain if no positive trust anchors are defined for the root domain\&. In most cases it is hence unnecessary to define an explicit key with trust anchor files\&. The built\-in key is disabled as soon as at least one trust anchor key for the root domain is defined in trust anchor files\&. +.PP +It is generally recommended to encode trust anchors in +\fBDS\fR +resource records, rather than +\fBDNSKEY\fR +resource records\&. +.PP +If a trust anchor specified via a +\fBDS\fR +record is found revoked it is automatically removed from the trust anchor database for the runtime\&. See +\m[blue]\fBRFC 5011\fR\m[]\&\s-2\u[5]\d\s+2 +for details about revoked trust anchors\&. Note that +systemd\-resolved +will not update its trust anchor database from DNS servers automatically\&. Instead, it is recommended to update the resolver software or update the new trust anchor via adding in new trust anchor files\&. +.PP +The current DNSSEC trust anchor for the Internet\*(Aqs root domain is available at the +\m[blue]\fBIANA Trust Anchor and Keys\fR\m[]\&\s-2\u[6]\d\s+2 +page\&. +.SH "NEGATIVE TRUST ANCHORS" +.PP +Negative trust anchors define domains where DNSSEC validation shall be turned off\&. Negative trust anchor files are found at the same location as positive trust anchor files, and follow the same overriding rules\&. They are text files with the +\&.negative +suffix\&. Empty lines and lines whose first character is +";" +are ignored\&. Each line specifies one domain name which is the root of a DNS subtree where validation shall be disabled\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Reverse IPv4 mappings +10\&.in\-addr\&.arpa +16\&.172\&.in\-addr\&.arpa +168\&.192\&.in\-addr\&.arpa +\&.\&.\&. +# Some custom domains +prod +stag +.fi +.if n \{\ +.RE +.\} +.PP +Negative trust anchors are useful to support private DNS subtrees that are not referenced from the Internet DNS hierarchy, and not signed\&. +.PP +\m[blue]\fBRFC 7646\fR\m[]\&\s-2\u[7]\d\s+2 +for details on negative trust anchors\&. +.PP +If no negative trust anchor files are configured a built\-in set of well\-known private DNS zone domains is used as negative trust anchors\&. +.PP +It is also possibly to define per\-interface negative trust anchors using the +\fIDNSSECNegativeTrustAnchors=\fR +setting in +\fBsystemd.network\fR(5) +files\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-resolved.service\fR(8), +\fBresolved.conf\fR(5), +\fBsystemd.network\fR(5) +.SH "NOTES" +.IP " 1." 4 +RFC 4035, Section 4.4 +.RS 4 +\%https://tools.ietf.org/html/rfc4035#section-4.4 +.RE +.IP " 2." 4 +RFC 1035, Section 5 +.RS 4 +\%https://tools.ietf.org/html/rfc1035#section-5 +.RE +.IP " 3." 4 +RFC 4034, Section 5 +.RS 4 +\%https://tools.ietf.org/html/rfc4034#section-5 +.RE +.IP " 4." 4 +RFC 4034, Section 2 +.RS 4 +\%https://tools.ietf.org/html/rfc4034#section-2 +.RE +.IP " 5." 4 +RFC 5011 +.RS 4 +\%https://tools.ietf.org/html/rfc5011 +.RE +.IP " 6." 4 +IANA Trust Anchor and Keys +.RS 4 +\%https://data.iana.org/root-anchors/root-anchors.xml +.RE +.IP " 7." 4 +RFC 7646 +.RS 4 +\%https://tools.ietf.org/html/rfc7646 +.RE diff --git a/upstream/fedora-40/man5/e2fsck.conf.5 b/upstream/fedora-40/man5/e2fsck.conf.5 new file mode 100644 index 00000000..ad91762c --- /dev/null +++ b/upstream/fedora-40/man5/e2fsck.conf.5 @@ -0,0 +1,501 @@ +.\" -*- nroff -*- +.\" Copyright 2006 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH e2fsck.conf 5 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +e2fsck.conf \- Configuration file for e2fsck +.SH DESCRIPTION +.I e2fsck.conf +is the configuration file for +.BR e2fsck (8). +It controls the default behavior of +.BR e2fsck (8) +while it is checking ext2, ext3, or ext4 file systems. +.PP +The +.I e2fsck.conf +file uses an INI-style format. Stanzas, or top-level sections, are +delimited by square braces: [ ]. Within each section, each line +defines a relation, which assigns tags to values, or to a subsection, +which contains further relations or subsections. +.\" Tags can be assigned multiple values +An example of the INI-style format used by this configuration file +follows below: +.P + [section1] +.br + tag1 = value_a +.br + tag1 = value_b +.br + tag2 = value_c +.P + [section 2] +.br + tag3 = { +.br + subtag1 = subtag_value_a +.br + subtag1 = subtag_value_b +.br + subtag2 = subtag_value_c +.br + } +.br + tag1 = value_d +.br + tag2 = value_e +.br + } +.P +Comments are delimited by a semicolon (';') or a hash ('#') character +at the beginning of the comment, and are terminated by the end of +line character. +.P +Tags and values must be quoted using double quotes if they contain +spaces. Within a quoted string, the standard backslash interpretations +apply: "\en" (for the newline character), +"\et" (for the tab character), "\eb" (for the backspace character), +and "\e\e" (for the backslash character). +.P +The following stanzas are used in the +.I e2fsck.conf +file. They will be described in more detail in future sections of this +document. +.TP +.I [options] +This stanza contains general configuration parameters for +.BR e2fsck 's +behavior. +.TP +.I [defaults] +Contains relations which define the default parameters used by +.BR e2fsck (8). +In general, these defaults may be overridden by command-line options +provided by the user. +.TP +.I [problems] +This stanza allows the administrator to reconfigure how e2fsck handles +various file system inconsistencies. +.TP +.I [scratch_files] +This stanza controls when e2fsck will attempt to use +scratch files to reduce the need for memory. +.SH THE [options] STANZA +The following relations are defined in the +.I [options] +stanza. +.TP +.I allow_cancellation +If this relation is set to a boolean value of true, then if the user +interrupts e2fsck using ^C, and the file system is not explicitly flagged +as containing errors, e2fsck will exit with an exit status of 0 instead +of 32. This setting defaults to false. +.TP +.I accept_time_fudge +Unfortunately, due to Windows' unfortunate design decision +to configure the hardware clock to tick localtime, instead +of the more proper and less error-prone UTC time, many +users end up in the situation where the system clock is +incorrectly set at the time when e2fsck is run. +.IP +Historically this was usually due to some distributions +having buggy init scripts and/or installers that didn't +correctly detect this case and take appropriate +countermeasures. Unfortunately, this is occasionally +true even today, usually due to a +buggy or misconfigured virtualization manager or the +installer not having access to a network time server +during the installation process. So by default, we allow +the superblock times to be fudged by up to 24 hours. +This can be disabled by setting +.I accept_time_fudge +to the +boolean value of false. This setting defaults to true. +.TP +.I broken_system_clock +The +.BR e2fsck (8) +program has some heuristics that assume that the system clock is +correct. In addition, many system programs make similar assumptions. +For example, the UUID library depends on time not going backwards in +order for it to be able to make its guarantees about issuing universally +unique ID's. Systems with broken system clocks, are well, broken. +However, broken system clocks, particularly in embedded systems, do +exist. E2fsck will attempt to use heuristics to determine if the time +can not be trusted; and to skip time-based checks if this is true. If +this boolean is set to true, then e2fsck will always assume that the +system clock can not be trusted. +.TP +.I buggy_init_scripts +This boolean relation is an alias for +.I accept_time_fudge +for backwards compatibility; it used to +be that the behavior defined by +.I accept_time_fudge +above defaulted to false, and +.I buggy_init_scripts +would enable superblock time field to be wrong by up to 24 hours. When +we changed the default, we also renamed this boolean relation to +.IR accept_time_fudge. +.TP +.I clear_test_fs_flag +This boolean relation controls whether or not +.BR e2fsck (8) +will offer to clear +the test_fs flag if the ext4 file system is available on the system. It +defaults to true. +.TP +.I defer_check_on_battery +This boolean relation controls whether or not the interval between +file system checks (either based on time or number of mounts) should +be doubled if the system is running on battery. This setting defaults to +true. +.TP +.I indexed_dir_slack_percentage +When +.BR e2fsck (8) +repacks a indexed directory, reserve the specified percentage of +empty space in each leaf nodes so that a few new entries can +be added to the directory without splitting leaf nodes, so that +the average fill ratio of directories can be maintained at a +higher, more efficient level. This relation defaults to 20 +percent. +.TP +.I inode_count_fullmap +If this boolean relation is true, trade off using memory for speed when +checking a file system with a large number of hard-linked files. The +amount of memory required is proportional to the number of inodes in the +file system. For large file systems, this can be gigabytes of memory. +(For example a 40TB file system with 2.8 billion inodes will consume an +additional 5.7 GB memory if this optimization is enabled.) This setting +defaults to false. +.TP +.I log_dir +If the +.I log_filename +or +.I problem_log_filename +relations contains a relative pathname, then the log file will be placed +in the directory named by the +.I log_dir +relation. +.TP +.I log_dir_fallback +This relation contains an alternate directory that will be used if the +directory specified by +.I log_dir +is not available or is not writable. +.TP +.I log_dir_wait +If this boolean relation is true, them if the directories specified by +.I log_dir +or +.I log_dir_fallback +are not available or are not yet writable, e2fsck will save the output +in a memory buffer, and a child process will periodically test to see if +the log directory has become available after the boot sequence has +mounted the requested file system for reading/writing. This implements the +functionality provided by +.BR logsave (8) +for e2fsck log files. +.TP +.I log_filename +This relation specifies the file name where a copy of e2fsck's output +will be written. If certain problem reports are suppressed using the +.I max_count_problems +relation, (or on a per-problem basis using the +.I max_count +relation), the full set of problem reports will be written to the log +file. The filename may contain various percent-expressions (%D, %T, %N, +etc.) which will be expanded so that the file name for the log file can +include things like date, time, device name, and other run-time +parameters. See the +.B LOGGING +section for more details. +.TP +.I max_count_problems +This relation specifies the maximum number of problem reports of a +particular type will be printed to stdout before further problem reports +of that type are squelched. This can be useful if the console is slow +(i.e., connected to a serial port) and so a large amount of output could +end up delaying the boot process for a long time (potentially hours). +.TP +.I no_optimize_extents +If this boolean relation is true, do not offer to optimize the extent +tree by reducing the tree's width or depth. This setting defaults to false. +.TP +.I problem_log_filename +This relation specifies the file name where a log of problem codes +found by e2fsck be written. The filename may contain various +percent-expressions (%D, %T, %N, +etc.) which will be expanded so that the file name for the log file can +include things like date, time, device name, and other run-time +parameters. See the +.B LOGGING +section for more details. +.TP +.I readahead_mem_pct +Use this percentage of memory to try to read in metadata blocks ahead of the +main e2fsck thread. This should reduce run times, depending on the speed of +the underlying storage and the amount of free memory. There is no default, but +see +.B readahead_kb +for more details. +.TP +.I readahead_kb +Use this amount of memory to read in metadata blocks ahead of the main checking +thread. Setting this value to zero disables readahead entirely. By default, +this is set the size of two block groups' inode tables (typically 4MiB on a +regular ext4 file system); if this amount is more than 1/50th of total physical +memory, readahead is disabled. +.TP +.I report_features +If this boolean relation is true, e2fsck will print the file system +features as part of its verbose reporting (i.e., if the +.B -v +option is specified) +.TP +.I report_time +If this boolean relation is true, e2fsck will run as if the options +.B -tt +are always specified. This will cause e2fsck to print timing statistics +on a pass by pass basis for full file system checks. +.TP +.I report_verbose +If this boolean relation is true, e2fsck will run as if the option +.B -v +is always specified. This will cause e2fsck to print some additional +information at the end of each full file system check. +.SH THE [defaults] STANZA +The following relations are defined in the +.I [defaults] +stanza. +.TP +.I undo_dir +This relation specifies the directory where the undo file should be +stored. It can be overridden via the +.B E2FSPROGS_UNDO_DIR +environment variable. If the directory location is set to the value +.IR none , +.B e2fsck +will not create an undo file. +.SH THE [problems] STANZA +Each tag in the +.I [problems] +stanza names a problem code specified with a leading "0x" followed by +six hex digits. +The value of the tag is a subsection where the relations in that +subsection override the default treatment of that particular problem +code. +.P +Note that inappropriate settings in this stanza may cause +.B e2fsck +to behave incorrectly, or even crash. Most system administrators should +not be making changes to this section without referring to source code. +.P +Within each problem code's subsection, the following tags may be used: +.TP +.I description +This relation allows the message which is printed when this file system +inconsistency is detected to be overridden. +.TP +.I preen_ok +This boolean relation overrides the default behavior controlling +whether this file system problem should be automatically fixed when +.B e2fsck +is running in preen mode. +.TP +.I max_count +This integer relation overrides the +.I max_count_problems +parameter (set in the options section) for this particular problem. +.TP +.I no_ok +This boolean relation overrides the default behavior determining +whether or not the file system will be marked as inconsistent if the user +declines to fix the reported problem. +.TP +.I no_default +This boolean relation overrides whether the default answer for this +problem (or question) should be "no". +.TP +.I preen_nomessage +This boolean relation overrides the default behavior controlling +whether or not the description for this file system problem should +be suppressed when +.B e2fsck +is running in preen mode. +.TP +.I no_nomsg +This boolean relation overrides the default behavior controlling +whether or not the description for this file system problem should +be suppressed when a problem forced not to be fixed, either because +.B e2fsck +is run with the +.B -n +option or because the +.I force_no +flag has been set for the problem. +.TP +.I force_no +This boolean option, if set to true, forces a problem to never be fixed. +That is, it will be as if the user problem responds 'no' to the question +of 'should this problem be fixed?'. The +.I force_no +option even overrides the +.B -y +option given on the command-line (just for the specific problem, of course). +.TP +.I not_a_fix +This boolean option, it set to true, marks the problem as +one where if the user gives permission to make the requested change, +it does not mean that the file system had a problem which has since +been fixed. This is used for requests to optimize the file system's +data structure, such as pruning an extent tree. +.SH THE [scratch_files] STANZA +The following relations are defined in the +.I [scratch_files] +stanza. +.TP +.I directory +If the directory named by this relation exists and is +writeable, then e2fsck will attempt to use this +directory to store scratch files instead of using +in-memory data structures. +.TP +.I numdirs_threshold +If this relation is set, then in-memory data structures +will be used if the number of directories in the file system +are fewer than amount specified. +.TP +.I dirinfo +This relation controls whether or not the scratch file +directory is used instead of an in-memory data +structure for directory information. It defaults to +true. +.TP +.I icount +This relation controls whether or not the scratch file +directory is used instead of an in-memory data +structure when tracking inode counts. It defaults to +true. +.SH LOGGING +E2fsck has the facility to save the information from an e2fsck run in a +directory so that a system administrator can review its output at their +leisure. This allows information captured during the automatic e2fsck +preen run, as well as a manually started e2fsck run, to be saved for +posterity. This facility is controlled by the +.IR log_filename , +.IR log_dir , +.IR log_dir_fallback , +and +.I log_dir_wait +relations in the +.I [options] +stanza. +.PP +The filename in +.I log_filename +may contain the following percent-expressions that will be expanded as +follows. +.TP +.B %d +The current day of the month +.TP +.B %D +The current date; this is a equivalent of +.B %Y%m%d +.TP +.B %h +The hostname of the system. +.TP +.B %H +The current hour in 24-hour format (00..23) +.TP +.B %m +The current month as a two-digit number (01..12) +.TP +.B %M +The current minute (00..59) +.TP +.B %N +The name of the block device containing the file system, with any +directory pathname stripped off. +.TP +.B %p +The pid of the e2fsck process +.TP +.B %s +The current time expressed as the number of seconds since 1970-01-01 +00:00:00 UTC +.TP +.B %S +The current second (00..59) +.TP +.B %T +The current time; this is equivalent of +.B %H%M%S +.TP +.B %u +The name of the user running e2fsck. +.TP +.B %U +This percent expression does not expand to anything, but it signals that +any following date or time expressions should be expressed in UTC time +instead of the local timezone. +.TP +.B %y +The last two digits of the current year (00..99) +.TP +.B %Y +The current year (i.e., 2012). +.SH EXAMPLES +The following recipe will prevent e2fsck from aborting during the boot +process when a file system contains orphaned files. (Of course, this is +not always a good idea, since critical files that are needed for the +security of the system could potentially end up in lost+found, and +starting the system without first having a system administrator check +things out may be dangerous.) +.P +.br + [problems] +.br + 0x040002 = { +.br + preen_ok = true +.br + description = "@u @i %i. " +.br + } +.P +The following recipe will cause an e2fsck logfile to be written to the +directory /var/log/e2fsck, with a filename that contains the device +name, the hostname of the system, the date, and time: e.g., +"e2fsck-sda3.server.INFO.20120314-112142". If the directory containing +/var/log is located on the root file system +which is initially mounted read-only, then the output will be saved in +memory and written out once the root file system has been remounted +read/write. To avoid too much detail from being written to the serial +console (which could potentially slow down the boot sequence), only print +no more than 16 instances of each type of file system corruption. +.P +.br + [options] +.br + max_count_problems = 16 +.br + log_dir = /var/log/e2fsck +.br + log_filename = e2fsck-%N.%h.INFO.%D-%T +.br + log_dir_wait = true +.P +.SH FILES +.TP +.I /etc/e2fsck.conf +The configuration file for +.BR e2fsck (8). +.SH SEE ALSO +.BR e2fsck (8) diff --git a/upstream/fedora-40/man5/elf.5 b/upstream/fedora-40/man5/elf.5 new file mode 100644 index 00000000..730d58cd --- /dev/null +++ b/upstream/fedora-40/man5/elf.5 @@ -0,0 +1,2213 @@ +.\" $OpenBSD: elf.5,v 1.12 2003/10/27 20:23:58 jmc Exp $ +.\"Copyright (c) 1999 Jeroen Ruigrok van der Werven +.\"All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\"Redistribution and use in source and binary forms, with or without +.\"modification, are permitted provided that the following conditions +.\"are met: +.\"1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\"2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\"THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\"ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\"SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $FreeBSD: src/share/man/man5/elf.5,v 1.21 2001/10/01 16:09:23 ru Exp $ +.\" +.\" Slightly adapted - aeb, 2004-01-01 +.\" 2005-07-15, Mike Frysinger , various fixes +.\" 2007-10-11, Mike Frysinger , various fixes +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH ELF 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +elf \- format of Executable and Linking Format (ELF) files +.SH SYNOPSIS +.nf +.\" .B #include +.B #include +.fi +.SH DESCRIPTION +The header file +.I +defines the format of ELF executable binary files. +Amongst these files are +normal executable files, relocatable object files, core files, and shared +objects. +.P +An executable file using the ELF file format consists of an ELF header, +followed by a program header table or a section header table, or both. +The ELF header is always at offset zero of the file. +The program header +table and the section header table's offset in the file are defined in the +ELF header. +The two tables describe the rest of the particularities of +the file. +.P +.\" Applications which wish to process ELF binary files for their native +.\" architecture only should include +.\" .I +.\" in their source code. +.\" These applications should need to refer to +.\" all the types and structures by their generic names +.\" "Elf_xxx" +.\" and to the macros by +.\" ELF_xxx". +.\" Applications written this way can be compiled on any architecture, +.\" regardless of whether the host is 32-bit or 64-bit. +.\" .P +.\" Should an application need to process ELF files of an unknown +.\" architecture, then the application needs to explicitly use either +.\" "Elf32_xxx" +.\" or +.\" "Elf64_xxx" +.\" type and structure names. +.\" Likewise, the macros need to be identified by +.\" "ELF32_xxx" +.\" or +.\" "ELF64_xxx". +.\" .P +This header file describes the above mentioned headers as C structures +and also includes structures for dynamic sections, relocation sections and +symbol tables. +.\" +.SS Basic types +The following types are used for N-bit architectures (N=32,64, +.I ElfN +stands for +.I Elf32 +or +.IR Elf64 , +.I uintN_t +stands for +.I uint32_t +or +.IR uint64_t ): +.P +.in +4n +.EX +ElfN_Addr Unsigned program address, uintN_t +ElfN_Off Unsigned file offset, uintN_t +ElfN_Section Unsigned section index, uint16_t +ElfN_Versym Unsigned version symbol information, uint16_t +Elf_Byte unsigned char +ElfN_Half uint16_t +ElfN_Sword int32_t +ElfN_Word uint32_t +ElfN_Sxword int64_t +ElfN_Xword uint64_t +.\" Elf32_Size Unsigned object size +.EE +.in +.P +(Note: the *BSD terminology is a bit different. +There, +.I Elf64_Half +is +twice as large as +.IR Elf32_Half , +and +.I Elf64Quarter +is used for +.IR uint16_t . +In order to avoid confusion these types are replaced by explicit ones +in the below.) +.P +All data structures that the file format defines follow the +"natural" +size and alignment guidelines for the relevant class. +If necessary, +data structures contain explicit padding to ensure 4-byte alignment +for 4-byte objects, to force structure sizes to a multiple of 4, and so on. +.\" +.SS ELF header (Ehdr) +The ELF header is described by the type +.I Elf32_Ehdr +or +.IR Elf64_Ehdr : +.P +.in +4n +.EX +#define EI_NIDENT 16 +\& +typedef struct { + unsigned char e_ident[EI_NIDENT]; + uint16_t e_type; + uint16_t e_machine; + uint32_t e_version; + ElfN_Addr e_entry; + ElfN_Off e_phoff; + ElfN_Off e_shoff; + uint32_t e_flags; + uint16_t e_ehsize; + uint16_t e_phentsize; + uint16_t e_phnum; + uint16_t e_shentsize; + uint16_t e_shnum; + uint16_t e_shstrndx; +} ElfN_Ehdr; +.EE +.in +.P +The fields have the following meanings: +.\" +.\" +.TP +.I e_ident +This array of bytes specifies how to interpret the file, +independent of the processor or the file's remaining contents. +Within this array everything is named by macros, which start with +the prefix +.B EI_ +and may contain values which start with the prefix +.BR ELF . +The following macros are defined: +.RS +.TP +.B EI_MAG0 +The first byte of the magic number. +It must be filled with +.BR ELFMAG0 . +(0: 0x7f) +.TP +.B EI_MAG1 +The second byte of the magic number. +It must be filled with +.BR ELFMAG1 . +(1: \[aq]E\[aq]) +.TP +.B EI_MAG2 +The third byte of the magic number. +It must be filled with +.BR ELFMAG2 . +(2: \[aq]L\[aq]) +.TP +.B EI_MAG3 +The fourth byte of the magic number. +It must be filled with +.BR ELFMAG3 . +(3: \[aq]F\[aq]) +.TP +.B EI_CLASS +The fifth byte identifies the architecture for this binary: +.RS +.TP 14 +.PD 0 +.B ELFCLASSNONE +This class is invalid. +.TP +.B ELFCLASS32 +This defines the 32-bit architecture. +It supports machines with files +and virtual address spaces up to 4 Gigabytes. +.TP +.B ELFCLASS64 +This defines the 64-bit architecture. +.PD +.RE +.TP +.B EI_DATA +The sixth byte specifies the data encoding of the processor-specific +data in the file. +Currently, these encodings are supported: +.RS 9 +.TP 14 +.PD 0 +.B ELFDATANONE +Unknown data format. +.TP +.B ELFDATA2LSB +Two's complement, little-endian. +.TP +.B ELFDATA2MSB +Two's complement, big-endian. +.PD +.RE +.TP +.B EI_VERSION +The seventh byte is the version number of the ELF specification: +.IP +.PD 0 +.RS +.TP 14 +.B EV_NONE +Invalid version. +.TP +.B EV_CURRENT +Current version. +.PD +.RE +.\".El +.TP +.B EI_OSABI +The eighth byte identifies the operating system +and ABI to which the object is targeted. +Some fields in other ELF structures have flags +and values that have platform-specific meanings; +the interpretation of those fields is determined by the value of this byte. +For example: +.RS +.TP 21 +.PD 0 +.B ELFOSABI_NONE +Same as ELFOSABI_SYSV +.\" 0 +.TP +.B ELFOSABI_SYSV +UNIX System V ABI +.\" 0 +.\" synonym: ELFOSABI_NONE +.TP +.B ELFOSABI_HPUX +HP-UX ABI +.\" 1 +.TP +.B ELFOSABI_NETBSD +NetBSD ABI +.\" 2 +.TP +.B ELFOSABI_LINUX +Linux ABI +.\" 3 +.\" .TP +.\" .BR ELFOSABI_HURD +.\" Hurd ABI +.\" 4 +.\" .TP +.\" .BR ELFOSABI_86OPEN +.\" 86Open Common IA32 ABI +.\" 5 +.TP +.B ELFOSABI_SOLARIS +Solaris ABI +.\" 6 +.\" .TP +.\" .BR ELFOSABI_MONTEREY +.\" Monterey project ABI +.\" Now replaced by +.\" ELFOSABI_AIX +.\" 7 +.TP +.B ELFOSABI_IRIX +IRIX ABI +.\" 8 +.TP +.B ELFOSABI_FREEBSD +FreeBSD ABI +.\" 9 +.TP +.B ELFOSABI_TRU64 +TRU64 UNIX ABI +.\" 10 +.\" ELFOSABI_MODESTO +.\" 11 +.\" ELFOSABI_OPENBSD +.\" 12 +.TP +.B ELFOSABI_ARM +ARM architecture ABI +.\" 97 +.TP +.B ELFOSABI_STANDALONE +Stand-alone (embedded) ABI +.\" 255 +.PD +.RE +.TP +.B EI_ABIVERSION +The ninth byte identifies the version of the ABI +to which the object is targeted. +This field is used to distinguish among incompatible versions of an ABI. +The interpretation of this version number +is dependent on the ABI identified by the +.B EI_OSABI +field. +Applications conforming to this specification use the value 0. +.TP +.B EI_PAD +Start of padding. +These bytes are reserved and set to zero. +Programs +which read them should ignore them. +The value for +.B EI_PAD +will change in +the future if currently unused bytes are given meanings. +.\" As reported by Yuri Kozlov and confirmed by Mike Frysinger, EI_BRAND is +.\" not in GABI (http://www.sco.com/developers/gabi/latest/ch4.eheader.html) +.\" It looks to be a BSDism +.\" .TP +.\" .BR EI_BRAND +.\" Start of architecture identification. +.TP +.B EI_NIDENT +The size of the +.I e_ident +array. +.RE +.TP +.I e_type +This member of the structure identifies the object file type: +.RS +.TP 16 +.PD 0 +.B ET_NONE +An unknown type. +.TP +.B ET_REL +A relocatable file. +.TP +.B ET_EXEC +An executable file. +.TP +.B ET_DYN +A shared object. +.TP +.B ET_CORE +A core file. +.PD +.RE +.TP +.I e_machine +This member specifies the required architecture for an individual file. +For example: +.RS +.TP 16 +.PD 0 +.B EM_NONE +An unknown machine +.\" 0 +.TP +.B EM_M32 +AT&T WE 32100 +.\" 1 +.TP +.B EM_SPARC +Sun Microsystems SPARC +.\" 2 +.TP +.B EM_386 +Intel 80386 +.\" 3 +.TP +.B EM_68K +Motorola 68000 +.\" 4 +.TP +.B EM_88K +Motorola 88000 +.\" 5 +.\" .TP +.\" .BR EM_486 +.\" Intel 80486 +.\" 6 +.TP +.B EM_860 +Intel 80860 +.\" 7 +.TP +.B EM_MIPS +MIPS RS3000 (big-endian only) +.\" 8 +.\" EM_S370 +.\" 9 +.\" .TP +.\" .BR EM_MIPS_RS4_BE +.\" MIPS RS4000 (big-endian only). Deprecated +.\" 10 +.\" EM_MIPS_RS3_LE (MIPS R3000 little-endian) +.\" 10 +.TP +.B EM_PARISC +HP/PA +.\" 15 +.TP +.B EM_SPARC32PLUS +SPARC with enhanced instruction set +.\" 18 +.TP +.B EM_PPC +PowerPC +.\" 20 +.TP +.B EM_PPC64 +PowerPC 64-bit +.\" 21 +.TP +.B EM_S390 +IBM S/390 +.\" 22 +.TP +.B EM_ARM +Advanced RISC Machines +.\" 40 +.TP +.B EM_SH +Renesas SuperH +.\" 42 +.TP +.B EM_SPARCV9 +SPARC v9 64-bit +.\" 43 +.TP +.B EM_IA_64 +Intel Itanium +.\" 50 +.TP +.B EM_X86_64 +AMD x86-64 +.\" 62 +.TP +.B EM_VAX +DEC Vax +.\" 75 +.\" EM_CRIS +.\" 76 +.\" .TP +.\" .BR EM_ALPHA +.\" Compaq [DEC] Alpha +.\" .TP +.\" .BR EM_ALPHA_EXP +.\" Compaq [DEC] Alpha with enhanced instruction set +.PD +.RE +.TP +.I e_version +This member identifies the file version: +.RS +.TP 16 +.PD 0 +.B EV_NONE +Invalid version +.TP +.B EV_CURRENT +Current version +.PD +.RE +.TP +.I e_entry +This member gives the virtual address to which the system first transfers +control, thus starting the process. +If the file has no associated entry +point, this member holds zero. +.TP +.I e_phoff +This member holds the program header table's file offset in bytes. +If +the file has no program header table, this member holds zero. +.TP +.I e_shoff +This member holds the section header table's file offset in bytes. +If the +file has no section header table, this member holds zero. +.TP +.I e_flags +This member holds processor-specific flags associated with the file. +Flag names take the form EF_`machine_flag'. +Currently, no flags have been defined. +.TP +.I e_ehsize +This member holds the ELF header's size in bytes. +.TP +.I e_phentsize +This member holds the size in bytes of one entry in the file's +program header table; all entries are the same size. +.TP +.I e_phnum +This member holds the number of entries in the program header +table. +Thus the product of +.I e_phentsize +and +.I e_phnum +gives the table's size +in bytes. +If a file has no program header, +.I e_phnum +holds the value zero. +.IP +If the number of entries in the program header table is +larger than or equal to +.\" This is a Linux extension, added in Linux 2.6.34. +.B PN_XNUM +(0xffff), this member holds +.B PN_XNUM +(0xffff) and the real number of entries in the program header table is held +in the +.I sh_info +member of the initial entry in section header table. +Otherwise, the +.I sh_info +member of the initial entry contains the value zero. +.RS +.TP +.B PN_XNUM +This is defined as 0xffff, the largest number +.I e_phnum +can have, specifying where the actual number of program headers is assigned. +.PD +.RE +.TP +.I e_shentsize +This member holds a sections header's size in bytes. +A section header is one +entry in the section header table; all entries are the same size. +.TP +.I e_shnum +This member holds the number of entries in the section header table. +Thus +the product of +.I e_shentsize +and +.I e_shnum +gives the section header table's size in bytes. +If a file has no section +header table, +.I e_shnum +holds the value of zero. +.IP +If the number of entries in the section header table is +larger than or equal to +.B SHN_LORESERVE +(0xff00), +.I e_shnum +holds the value zero and the real number of entries in the section header +table is held in the +.I sh_size +member of the initial entry in section header table. +Otherwise, the +.I sh_size +member of the initial entry in the section header table holds +the value zero. +.TP +.I e_shstrndx +This member holds the section header table index of the entry associated +with the section name string table. +If the file has no section name string +table, this member holds the value +.BR SHN_UNDEF . +.IP +If the index of section name string table section is +larger than or equal to +.B SHN_LORESERVE +(0xff00), this member holds +.B SHN_XINDEX +(0xffff) and the real index of the section name string table section +is held in the +.I sh_link +member of the initial entry in section header table. +Otherwise, the +.I sh_link +member of the initial entry in section header table contains the value zero. +.\" +.SS Program header (Phdr) +An executable or shared object file's program header table is an array of +structures, each describing a segment or other information the system needs +to prepare the program for execution. +An object file +.I segment +contains one or more +.IR sections . +Program headers are meaningful only for executable and shared object files. +A file specifies its own program header size with the ELF header's +.I e_phentsize +and +.I e_phnum +members. +The ELF program header is described by the type +.I Elf32_Phdr +or +.I Elf64_Phdr +depending on the architecture: +.P +.in +4n +.EX +typedef struct { + uint32_t p_type; + Elf32_Off p_offset; + Elf32_Addr p_vaddr; + Elf32_Addr p_paddr; + uint32_t p_filesz; + uint32_t p_memsz; + uint32_t p_flags; + uint32_t p_align; +} Elf32_Phdr; +.EE +.in +.P +.in +4n +.EX +typedef struct { + uint32_t p_type; + uint32_t p_flags; + Elf64_Off p_offset; + Elf64_Addr p_vaddr; + Elf64_Addr p_paddr; + uint64_t p_filesz; + uint64_t p_memsz; + uint64_t p_align; +} Elf64_Phdr; +.EE +.in +.P +The main difference between the 32-bit and the 64-bit program header lies +in the location of the +.I p_flags +member in the total struct. +.TP +.I p_type +This member of the structure indicates what kind of segment this array +element describes or how to interpret the array element's information. +.RS 10 +.TP +.B PT_NULL +The array element is unused and the other members' values are undefined. +This lets the program header have ignored entries. +.TP +.B PT_LOAD +The array element specifies a loadable segment, described by +.I p_filesz +and +.IR p_memsz . +The bytes from the file are mapped to the beginning of the memory +segment. +If the segment's memory size +.I p_memsz +is larger than the file size +.IR p_filesz , +the +"extra" +bytes are defined to hold the value 0 and to follow the segment's +initialized area. +The file size may not be larger than the memory size. +Loadable segment entries in the program header table appear in ascending +order, sorted on the +.I p_vaddr +member. +.TP +.B PT_DYNAMIC +The array element specifies dynamic linking information. +.TP +.B PT_INTERP +The array element specifies the location and size of a null-terminated +pathname to invoke as an interpreter. +This segment type is meaningful +only for executable files (though it may occur for shared objects). +However it may not occur more than once in a file. +If it is present, it must precede any loadable segment entry. +.TP +.B PT_NOTE +The array element specifies the location of notes (ElfN_Nhdr). +.TP +.B PT_SHLIB +This segment type is reserved but has unspecified semantics. +Programs that +contain an array element of this type do not conform to the ABI. +.TP +.B PT_PHDR +The array element, if present, +specifies the location and size of the program header table itself, +both in the file and in the memory image of the program. +This segment type may not occur more than once in a file. +Moreover, it may +occur only if the program header table is part of the memory image of the +program. +If it is present, it must precede any loadable segment entry. +.TP +.B PT_LOPROC +.TQ +.B PT_HIPROC +Values in the inclusive range +.RB [ PT_LOPROC , +.BR PT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B PT_GNU_STACK +GNU extension which is used by the Linux kernel to control the state of the +stack via the flags set in the +.I p_flags +member. +.RE +.TP +.I p_offset +This member holds the offset from the beginning of the file at which +the first byte of the segment resides. +.TP +.I p_vaddr +This member holds the virtual address at which the first byte of the +segment resides in memory. +.TP +.I p_paddr +On systems for which physical addressing is relevant, this member is +reserved for the segment's physical address. +Under +BSD +this member is +not used and must be zero. +.TP +.I p_filesz +This member holds the number of bytes in the file image of the segment. +It may be zero. +.TP +.I p_memsz +This member holds the number of bytes in the memory image of the segment. +It may be zero. +.TP +.I p_flags +This member holds a bit mask of flags relevant to the segment: +.RS +.TP +.PD 0 +.B PF_X +An executable segment. +.TP +.B PF_W +A writable segment. +.TP +.B PF_R +A readable segment. +.PD +.RE +.IP +A text segment commonly has the flags +.B PF_X +and +.B PF_R . +A data segment commonly has +.B PF_W +and +.BR PF_R . +.TP +.I p_align +This member holds the value to which the segments are aligned in memory +and in the file. +Loadable process segments must have congruent values for +.I p_vaddr +and +.IR p_offset , +modulo the page size. +Values of zero and one mean no alignment is required. +Otherwise, +.I p_align +should be a positive, integral power of two, and +.I p_vaddr +should equal +.IR p_offset , +modulo +.IR p_align . +.\" +.SS Section header (Shdr) +A file's section header table lets one locate all the file's sections. +The +section header table is an array of +.I Elf32_Shdr +or +.I Elf64_Shdr +structures. +The +ELF header's +.I e_shoff +member gives the byte offset from the beginning of the file to the section +header table. +.I e_shnum +holds the number of entries the section header table contains. +.I e_shentsize +holds the size in bytes of each entry. +.P +A section header table index is a subscript into this array. +Some section +header table indices are reserved: +the initial entry and the indices between +.B SHN_LORESERVE +and +.BR SHN_HIRESERVE . +The initial entry is used in ELF extensions for +.IR e_phnum , +.IR e_shnum , +and +.IR e_shstrndx ; +in other cases, each field in the initial entry is set to zero. +An object file does not have sections for +these special indices: +.TP +.B SHN_UNDEF +This value marks an undefined, missing, irrelevant, +or otherwise meaningless section reference. +.TP +.B SHN_LORESERVE +This value specifies the lower bound of the range of reserved indices. +.TP +.B SHN_LOPROC +.TQ +.B SHN_HIPROC +Values greater in the inclusive range +.RB [ SHN_LOPROC , +.BR SHN_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B SHN_ABS +This value specifies the absolute value for the corresponding reference. +For +example, a symbol defined relative to section number +.B SHN_ABS +has an absolute value and is not affected by relocation. +.TP +.B SHN_COMMON +Symbols defined relative to this section are common symbols, +such as FORTRAN COMMON or unallocated C external variables. +.TP +.B SHN_HIRESERVE +This value specifies the upper bound of the range of reserved indices. +The +system reserves indices between +.B SHN_LORESERVE +and +.BR SHN_HIRESERVE , +inclusive. +The section header table does not contain entries for the +reserved indices. +.P +The section header has the following structure: +.P +.in +4n +.EX +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint32_t sh_flags; + Elf32_Addr sh_addr; + Elf32_Off sh_offset; + uint32_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint32_t sh_addralign; + uint32_t sh_entsize; +} Elf32_Shdr; +.EE +.in +.P +.in +4n +.EX +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint64_t sh_flags; + Elf64_Addr sh_addr; + Elf64_Off sh_offset; + uint64_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint64_t sh_addralign; + uint64_t sh_entsize; +} Elf64_Shdr; +.EE +.in +.P +No real differences exist between the 32-bit and 64-bit section headers. +.TP +.I sh_name +This member specifies the name of the section. +Its value is an index +into the section header string table section, giving the location of +a null-terminated string. +.TP +.I sh_type +This member categorizes the section's contents and semantics. +.RS +.TP +.B SHT_NULL +This value marks the section header as inactive. +It does not +have an associated section. +Other members of the section header +have undefined values. +.TP +.B SHT_PROGBITS +This section holds information defined by the program, whose +format and meaning are determined solely by the program. +.TP +.B SHT_SYMTAB +This section holds a symbol table. +Typically, +.B SHT_SYMTAB +provides symbols for link editing, though it may also be used +for dynamic linking. +As a complete symbol table, it may contain +many symbols unnecessary for dynamic linking. +An object file can +also contain a +.B SHT_DYNSYM +section. +.TP +.B SHT_STRTAB +This section holds a string table. +An object file may have multiple +string table sections. +.TP +.B SHT_RELA +This section holds relocation entries with explicit addends, such +as type +.I Elf32_Rela +for the 32-bit class of object files. +An object may have multiple +relocation sections. +.TP +.B SHT_HASH +This section holds a symbol hash table. +An object participating in +dynamic linking must contain a symbol hash table. +An object file may +have only one hash table. +.TP +.B SHT_DYNAMIC +This section holds information for dynamic linking. +An object file may +have only one dynamic section. +.TP +.B SHT_NOTE +This section holds notes (ElfN_Nhdr). +.TP +.B SHT_NOBITS +A section of this type occupies no space in the file but otherwise +resembles +.BR SHT_PROGBITS . +Although this section contains no bytes, the +.I sh_offset +member contains the conceptual file offset. +.TP +.B SHT_REL +This section holds relocation offsets without explicit addends, such +as type +.I Elf32_Rel +for the 32-bit class of object files. +An object file may have multiple +relocation sections. +.TP +.B SHT_SHLIB +This section is reserved but has unspecified semantics. +.TP +.B SHT_DYNSYM +This section holds a minimal set of dynamic linking symbols. +An +object file can also contain a +.B SHT_SYMTAB +section. +.TP +.B SHT_LOPROC +.TQ +.B SHT_HIPROC +Values in the inclusive range +.RB [ SHT_LOPROC , +.BR SHT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B SHT_LOUSER +This value specifies the lower bound of the range of indices reserved for +application programs. +.TP +.B SHT_HIUSER +This value specifies the upper bound of the range of indices reserved for +application programs. +Section types between +.B SHT_LOUSER +and +.B SHT_HIUSER +may be used by the application, without conflicting with current or future +system-defined section types. +.RE +.TP +.I sh_flags +Sections support one-bit flags that describe miscellaneous attributes. +If a flag bit is set in +.IR sh_flags , +the attribute is +"on" +for the section. +Otherwise, the attribute is +"off" +or does not apply. +Undefined attributes are set to zero. +.RS +.TP +.B SHF_WRITE +This section contains data that should be writable during process +execution. +.TP +.B SHF_ALLOC +This section occupies memory during process execution. +Some control +sections do not reside in the memory image of an object file. +This +attribute is off for those sections. +.TP +.B SHF_EXECINSTR +This section contains executable machine instructions. +.TP +.B SHF_MASKPROC +All bits included in this mask are reserved for processor-specific +semantics. +.RE +.TP +.I sh_addr +If this section appears in the memory image of a process, this member +holds the address at which the section's first byte should reside. +Otherwise, the member contains zero. +.TP +.I sh_offset +This member's value holds the byte offset from the beginning of the file +to the first byte in the section. +One section type, +.BR SHT_NOBITS , +occupies no space in the file, and its +.I sh_offset +member locates the conceptual placement in the file. +.TP +.I sh_size +This member holds the section's size in bytes. +Unless the section type +is +.BR SHT_NOBITS , +the section occupies +.I sh_size +bytes in the file. +A section of type +.B SHT_NOBITS +may have a nonzero size, but it occupies no space in the file. +.TP +.I sh_link +This member holds a section header table index link, whose interpretation +depends on the section type. +.TP +.I sh_info +This member holds extra information, whose interpretation depends on the +section type. +.TP +.I sh_addralign +Some sections have address alignment constraints. +If a section holds a +doubleword, the system must ensure doubleword alignment for the entire +section. +That is, the value of +.I sh_addr +must be congruent to zero, modulo the value of +.IR sh_addralign . +Only zero and positive integral powers of two are allowed. +The value 0 or 1 means that the section has no alignment constraints. +.TP +.I sh_entsize +Some sections hold a table of fixed-sized entries, such as a symbol table. +For such a section, this member gives the size in bytes for each entry. +This member contains zero if the section does not hold a table of +fixed-size entries. +.P +Various sections hold program and control information: +.TP +.I .bss +This section holds uninitialized data that contributes to the program's +memory image. +By definition, the system initializes the data with zeros +when the program begins to run. +This section is of type +.BR SHT_NOBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .comment +This section holds version control information. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.I .ctors +This section holds initialized pointers to the C++ constructor functions. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .data +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .data1 +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .debug +This section holds information for symbolic debugging. +The contents +are unspecified. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.I .dtors +This section holds initialized pointers to the C++ destructor functions. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .dynamic +This section holds dynamic linking information. +The section's attributes +will include the +.B SHF_ALLOC +bit. +Whether the +.B SHF_WRITE +bit is set is processor-specific. +This section is of type +.BR SHT_DYNAMIC . +See the attributes above. +.TP +.I .dynstr +This section holds strings needed for dynamic linking, most commonly +the strings that represent the names associated with symbol table entries. +This section is of type +.BR SHT_STRTAB . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .dynsym +This section holds the dynamic linking symbol table. +This section is of type +.BR SHT_DYNSYM . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .fini +This section holds executable instructions that contribute to the process +termination code. +When a program exits normally the system arranges to +execute the code in this section. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.B SHF_ALLOC +and +.BR SHF_EXECINSTR . +.TP +.I .gnu.version +This section holds the version symbol table, an array of +.I ElfN_Half +elements. +This section is of type +.BR SHT_GNU_versym . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .gnu.version_d +This section holds the version symbol definitions, a table of +.I ElfN_Verdef +structures. +This section is of type +.BR SHT_GNU_verdef . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .gnu.version_r +This section holds the version symbol needed elements, a table of +.I ElfN_Verneed +structures. +This section is of +type +.BR SHT_GNU_versym . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .got +This section holds the global offset table. +This section is of type +.BR SHT_PROGBITS . +The attributes are processor-specific. +.TP +.I .hash +This section holds a symbol hash table. +This section is of type +.BR SHT_HASH . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .init +This section holds executable instructions that contribute to the process +initialization code. +When a program starts to run the system arranges to execute +the code in this section before calling the main program entry point. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.B SHF_ALLOC +and +.BR SHF_EXECINSTR . +.TP +.I .interp +This section holds the pathname of a program interpreter. +If the file has +a loadable segment that includes the section, the section's attributes will +include the +.B SHF_ALLOC +bit. +Otherwise, that bit will be off. +This section is of type +.BR SHT_PROGBITS . +.TP +.I .line +This section holds line number information for symbolic debugging, +which describes the correspondence between the program source and +the machine code. +The contents are unspecified. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.I .note +This section holds various notes. +This section is of type +.BR SHT_NOTE . +No attribute types are used. +.TP +.I .note.ABI\-tag +This section is used to declare the expected run-time ABI of the ELF image. +It may include the operating system name and its run-time versions. +This section is of type +.BR SHT_NOTE . +The only attribute used is +.BR SHF_ALLOC . +.TP +.I .note.gnu.build\-id +This section is used to hold an ID that uniquely identifies +the contents of the ELF image. +Different files with the same build ID should contain the same executable +content. +See the +.B \-\-build\-id +option to the GNU linker (\fBld\fR (1)) for more details. +This section is of type +.BR SHT_NOTE . +The only attribute used is +.BR SHF_ALLOC . +.TP +.I .note.GNU\-stack +This section is used in Linux object files for declaring stack attributes. +This section is of type +.BR SHT_PROGBITS . +The only attribute used is +.BR SHF_EXECINSTR . +This indicates to the GNU linker that the object file requires an +executable stack. +.TP +.I .note.openbsd.ident +OpenBSD native executables usually contain this section +to identify themselves so the kernel can bypass any compatibility +ELF binary emulation tests when loading the file. +.TP +.I .plt +This section holds the procedure linkage table. +This section is of type +.BR SHT_PROGBITS . +The attributes are processor-specific. +.TP +.I .relNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +By convention, +"NAME" +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.B .text +normally would have the name +.BR .rel.text . +This section is of type +.BR SHT_REL . +.TP +.I .relaNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +By convention, +"NAME" +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.B .text +normally would have the name +.BR .rela.text . +This section is of type +.BR SHT_RELA . +.TP +.I .rodata +This section holds read-only data that typically contributes to a +nonwritable segment in the process image. +This section is of type +.BR SHT_PROGBITS . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .rodata1 +This section holds read-only data that typically contributes to a +nonwritable segment in the process image. +This section is of type +.BR SHT_PROGBITS . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .shstrtab +This section holds section names. +This section is of type +.BR SHT_STRTAB . +No attribute types are used. +.TP +.I .strtab +This section holds strings, most commonly the strings that represent the +names associated with symbol table entries. +If the file has a loadable +segment that includes the symbol string table, the section's attributes +will include the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +This section is of type +.BR SHT_STRTAB . +.TP +.I .symtab +This section holds a symbol table. +If the file has a loadable segment +that includes the symbol table, the section's attributes will include +the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +This section is of type +.BR SHT_SYMTAB . +.TP +.I .text +This section holds the +"text", +or executable instructions, of a program. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.B SHF_ALLOC +and +.BR SHF_EXECINSTR . +.\" +.SS String and symbol tables +String table sections hold null-terminated character sequences, commonly +called strings. +The object file uses these strings to represent symbol +and section names. +One references a string as an index into the string +table section. +The first byte, which is index zero, is defined to hold +a null byte (\[aq]\e0\[aq]). +Similarly, a string table's last byte is defined to +hold a null byte, ensuring null termination for all strings. +.P +An object file's symbol table holds information needed to locate and +relocate a program's symbolic definitions and references. +A symbol table +index is a subscript into this array. +.P +.in +4n +.EX +typedef struct { + uint32_t st_name; + Elf32_Addr st_value; + uint32_t st_size; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; +} Elf32_Sym; +.EE +.in +.P +.in +4n +.EX +typedef struct { + uint32_t st_name; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; + Elf64_Addr st_value; + uint64_t st_size; +} Elf64_Sym; +.EE +.in +.P +The 32-bit and 64-bit versions have the same members, just in a different +order. +.TP +.I st_name +This member holds an index into the object file's symbol string table, +which holds character representations of the symbol names. +If the value +is nonzero, it represents a string table index that gives the symbol +name. +Otherwise, the symbol has no name. +.TP +.I st_value +This member gives the value of the associated symbol. +.TP +.I st_size +Many symbols have associated sizes. +This member holds zero if the symbol +has no size or an unknown size. +.TP +.I st_info +This member specifies the symbol's type and binding attributes: +.RS +.TP +.B STT_NOTYPE +The symbol's type is not defined. +.TP +.B STT_OBJECT +The symbol is associated with a data object. +.TP +.B STT_FUNC +The symbol is associated with a function or other executable code. +.TP +.B STT_SECTION +The symbol is associated with a section. +Symbol table entries of +this type exist primarily for relocation and normally have +.B STB_LOCAL +bindings. +.TP +.B STT_FILE +By convention, the symbol's name gives the name of the source file +associated with the object file. +A file symbol has +.B STB_LOCAL +bindings, its section index is +.BR SHN_ABS , +and it precedes the other +.B STB_LOCAL +symbols of the file, if it is present. +.TP +.B STT_LOPROC +.TQ +.B STT_HIPROC +Values in the inclusive range +.RB [ STT_LOPROC , +.BR STT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B STB_LOCAL +Local symbols are not visible outside the object file containing their +definition. +Local symbols of the same name may exist in multiple files +without interfering with each other. +.TP +.B STB_GLOBAL +Global symbols are visible to all object files being combined. +One file's +definition of a global symbol will satisfy another file's undefined +reference to the same symbol. +.TP +.B STB_WEAK +Weak symbols resemble global symbols, but their definitions have lower +precedence. +.TP +.B STB_LOPROC +.TQ +.B STB_HIPROC +Values in the inclusive range +.RB [ STB_LOPROC , +.BR STB_HIPROC ] +are reserved for processor-specific semantics. +.RE +.IP +There are macros for packing and unpacking the binding and type fields: +.RS +.TP +.BI ELF32_ST_BIND( info ) +.TQ +.BI ELF64_ST_BIND( info ) +Extract a binding from an +.I st_info +value. +.TP +.BI ELF32_ST_TYPE( info ) +.TQ +.BI ELF64_ST_TYPE( info ) +Extract a type from an +.I st_info +value. +.TP +.BI ELF32_ST_INFO( bind ", " type ) +.TQ +.BI ELF64_ST_INFO( bind ", " type ) +Convert a binding and a type into an +.I st_info +value. +.RE +.TP +.I st_other +This member defines the symbol visibility. +.RS +.TP +.PD 0 +.B STV_DEFAULT +Default symbol visibility rules. +Global and weak symbols are available to other modules; +references in the local module can be interposed +by definitions in other modules. +.TP +.B STV_INTERNAL +Processor-specific hidden class. +.TP +.B STV_HIDDEN +Symbol is unavailable to other modules; +references in the local module always resolve to the local symbol +(i.e., the symbol can't be interposed by definitions in other modules). +.TP +.B STV_PROTECTED +Symbol is available to other modules, +but references in the local module always resolve to the local symbol. +.PD +.P +There are macros for extracting the visibility type: +.P +.BR ELF32_ST_VISIBILITY (other) +or +.BR ELF64_ST_VISIBILITY (other) +.RE +.TP +.I st_shndx +Every symbol table entry is +"defined" +in relation to some section. +This member holds the relevant section +header table index. +.\" +.SS Relocation entries (Rel & Rela) +Relocation is the process of connecting symbolic references with +symbolic definitions. +Relocatable files must have information that +describes how to modify their section contents, thus allowing executable +and shared object files to hold the right information for a process's +program image. +Relocation entries are these data. +.P +Relocation structures that do not need an addend: +.P +.in +4n +.EX +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; +} Elf32_Rel; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; +} Elf64_Rel; +.EE +.in +.P +Relocation structures that need an addend: +.P +.in +4n +.EX +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; + int32_t r_addend; +} Elf32_Rela; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; + int64_t r_addend; +} Elf64_Rela; +.EE +.in +.TP +.I r_offset +This member gives the location at which to apply the relocation action. +For a relocatable file, the value is the byte offset from the beginning +of the section to the storage unit affected by the relocation. +For an +executable file or shared object, the value is the virtual address of +the storage unit affected by the relocation. +.TP +.I r_info +This member gives both the symbol table index with respect to which the +relocation must be made and the type of relocation to apply. +Relocation +types are processor-specific. +When the text refers to a relocation +entry's relocation type or symbol table index, it means the result of +applying +.B ELF[32|64]_R_TYPE +or +.BR ELF[32|64]_R_SYM , +respectively, to the entry's +.I r_info +member. +.TP +.I r_addend +This member specifies a constant addend used to compute the value to be +stored into the relocatable field. +.\" +.SS Dynamic tags (Dyn) +The +.I .dynamic +section contains a series of structures that hold relevant +dynamic linking information. +The +.I d_tag +member controls the interpretation +of +.IR d_un . +.P +.in +4n +.EX +typedef struct { + Elf32_Sword d_tag; + union { + Elf32_Word d_val; + Elf32_Addr d_ptr; + } d_un; +} Elf32_Dyn; +extern Elf32_Dyn _DYNAMIC[]; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Sxword d_tag; + union { + Elf64_Xword d_val; + Elf64_Addr d_ptr; + } d_un; +} Elf64_Dyn; +extern Elf64_Dyn _DYNAMIC[]; +.EE +.in +.TP +.I d_tag +This member may have any of the following values: +.RS +.TP 12 +.B DT_NULL +Marks end of dynamic section +.TP +.B DT_NEEDED +String table offset to name of a needed library +.TP +.B DT_PLTRELSZ +Size in bytes of PLT relocation entries +.TP +.B DT_PLTGOT +Address of PLT and/or GOT +.TP +.B DT_HASH +Address of symbol hash table +.TP +.B DT_STRTAB +Address of string table +.TP +.B DT_SYMTAB +Address of symbol table +.TP +.B DT_RELA +Address of Rela relocation table +.TP +.B DT_RELASZ +Size in bytes of the Rela relocation table +.TP +.B DT_RELAENT +Size in bytes of a Rela relocation table entry +.TP +.B DT_STRSZ +Size in bytes of string table +.TP +.B DT_SYMENT +Size in bytes of a symbol table entry +.TP +.B DT_INIT +Address of the initialization function +.TP +.B DT_FINI +Address of the termination function +.TP +.B DT_SONAME +String table offset to name of shared object +.TP +.B DT_RPATH +String table offset to library search path (deprecated) +.TP +.B DT_SYMBOLIC +Alert linker to search this shared object before the executable for symbols +.TP +.B DT_REL +Address of Rel relocation table +.TP +.B DT_RELSZ +Size in bytes of Rel relocation table +.TP +.B DT_RELENT +Size in bytes of a Rel table entry +.TP +.B DT_PLTREL +Type of relocation entry to which the PLT refers (Rela or Rel) +.TP +.B DT_DEBUG +Undefined use for debugging +.TP +.B DT_TEXTREL +Absence of this entry indicates that no relocation entries should +apply to a nonwritable segment +.TP +.B DT_JMPREL +Address of relocation entries associated solely with the PLT +.TP +.B DT_BIND_NOW +Instruct dynamic linker to process all relocations before +transferring control to the executable +.TP +.B DT_RUNPATH +String table offset to library search path +.TP +.B DT_LOPROC +.TQ +.B DT_HIPROC +Values in the inclusive range +.RB [ DT_LOPROC , +.BR DT_HIPROC ] +are reserved for processor-specific semantics +.RE +.TP +.I d_val +This member represents integer values with various interpretations. +.TP +.I d_ptr +This member represents program virtual addresses. +When interpreting +these addresses, the actual address should be computed based on the +original file value and memory base address. +Files do not contain +relocation entries to fixup these addresses. +.TP +.I _DYNAMIC +Array containing all the dynamic structures in the +.I .dynamic +section. +This is automatically populated by the linker. +.\" GABI ELF Reference for Note Sections: +.\" http://www.sco.com/developers/gabi/latest/ch5.pheader.html#note_section +.\" +.\" Note that it implies the sizes and alignments of notes depend on the ELF +.\" size (e.g. 32-bit ELFs have three 4-byte words and use 4-byte alignment +.\" while 64-bit ELFs use 8-byte words & alignment), but that is not the case +.\" in the real world. Notes always have three 4-byte words as can be seen +.\" in the source links below (remember that Elf64_Word is a 32-bit quantity). +.\" glibc: https://sourceware.org/git/?p=glibc.git;a=blob;f=elf/elf.h;h=9e59b3275917549af0cebe1f2de9ded3b7b10bf2#l1173 +.\" binutils: https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=binutils/readelf.c;h=274ddd17266aef6e4ad1f67af8a13a21500ff2af#l15943 +.\" Linux: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/elf.h?h=v4.8#n422 +.\" Solaris: https://docs.oracle.com/cd/E23824_01/html/819-0690/chapter6-18048.html +.\" FreeBSD: https://svnweb.freebsd.org/base/head/sys/sys/elf_common.h?revision=303677&view=markup#l33 +.\" NetBSD: https://www.netbsd.org/docs/kernel/elf-notes.html +.\" OpenBSD: https://github.com/openbsd/src/blob/master/sys/sys/exec_elf.h#L533 +.\" +.SS Notes (Nhdr) +ELF notes allow for appending arbitrary information for the system to use. +They are largely used by core files +.RI ( e_type +of +.BR ET_CORE ), +but many projects define their own set of extensions. +For example, +the GNU tool chain uses ELF notes to pass information from +the linker to the C library. +.P +Note sections contain a series of notes (see the +.I struct +definitions below). +Each note is followed by the name field (whose length is defined in +\fIn_namesz\fR) and then by the descriptor field (whose length is defined in +\fIn_descsz\fR) and whose starting address has a 4 byte alignment. +Neither field is defined in the note struct due to their arbitrary lengths. +.P +An example for parsing out two consecutive notes should clarify their layout +in memory: +.P +.in +4n +.EX +void *memory, *name, *desc; +Elf64_Nhdr *note, *next_note; +\& +/* The buffer is pointing to the start of the section/segment. */ +note = memory; +\& +/* If the name is defined, it follows the note. */ +name = note\->n_namesz == 0 ? NULL : memory + sizeof(*note); +\& +/* If the descriptor is defined, it follows the name + (with alignment). */ +\& +desc = note\->n_descsz == 0 ? NULL : + memory + sizeof(*note) + ALIGN_UP(note\->n_namesz, 4); +\& +/* The next note follows both (with alignment). */ +next_note = memory + sizeof(*note) + + ALIGN_UP(note\->n_namesz, 4) + + ALIGN_UP(note\->n_descsz, 4); +.EE +.in +.P +Keep in mind that the interpretation of +.I n_type +depends on the namespace defined by the +.I n_namesz +field. +If the +.I n_namesz +field is not set (e.g., is 0), then there are two sets of notes: +one for core files and one for all other ELF types. +If the namespace is unknown, then tools will usually fallback to these sets +of notes as well. +.P +.in +4n +.EX +typedef struct { + Elf32_Word n_namesz; + Elf32_Word n_descsz; + Elf32_Word n_type; +} Elf32_Nhdr; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Word n_namesz; + Elf64_Word n_descsz; + Elf64_Word n_type; +} Elf64_Nhdr; +.EE +.in +.TP +.I n_namesz +The length of the name field in bytes. +The contents will immediately follow this note in memory. +The name is null terminated. +For example, if the name is "GNU", then +.I n_namesz +will be set to 4. +.TP +.I n_descsz +The length of the descriptor field in bytes. +The contents will immediately follow the name field in memory. +.TP +.I n_type +Depending on the value of the name field, this member may have any of the +following values: +.RS +.TP 5 +.B Core files (e_type = ET_CORE) +Notes used by all core files. +These are highly operating system or architecture specific and often require +close coordination with kernels, C libraries, and debuggers. +These are used when the namespace is the default (i.e., +.I n_namesz +will be set to 0), or a fallback when the namespace is unknown. +.RS +.TP 21 +.PD 0 +.B NT_PRSTATUS +prstatus struct +.TP +.B NT_FPREGSET +fpregset struct +.TP +.B NT_PRPSINFO +prpsinfo struct +.TP +.B NT_PRXREG +prxregset struct +.TP +.B NT_TASKSTRUCT +task structure +.TP +.B NT_PLATFORM +String from sysinfo(SI_PLATFORM) +.TP +.B NT_AUXV +auxv array +.TP +.B NT_GWINDOWS +gwindows struct +.TP +.B NT_ASRS +asrset struct +.TP +.B NT_PSTATUS +pstatus struct +.TP +.B NT_PSINFO +psinfo struct +.TP +.B NT_PRCRED +prcred struct +.TP +.B NT_UTSNAME +utsname struct +.TP +.B NT_LWPSTATUS +lwpstatus struct +.TP +.B NT_LWPSINFO +lwpinfo struct +.TP +.B NT_PRFPXREG +fprxregset struct +.TP +.B NT_SIGINFO +siginfo_t (size might increase over time) +.TP +.B NT_FILE +Contains information about mapped files +.TP +.B NT_PRXFPREG +user_fxsr_struct +.TP +.B NT_PPC_VMX +PowerPC Altivec/VMX registers +.TP +.B NT_PPC_SPE +PowerPC SPE/EVR registers +.TP +.B NT_PPC_VSX +PowerPC VSX registers +.TP +.B NT_386_TLS +i386 TLS slots (struct user_desc) +.TP +.B NT_386_IOPERM +x86 io permission bitmap (1=deny) +.TP +.B NT_X86_XSTATE +x86 extended state using xsave +.TP +.B NT_S390_HIGH_GPRS +s390 upper register halves +.TP +.B NT_S390_TIMER +s390 timer register +.TP +.B NT_S390_TODCMP +s390 time-of-day (TOD) clock comparator register +.TP +.B NT_S390_TODPREG +s390 time-of-day (TOD) programmable register +.TP +.B NT_S390_CTRS +s390 control registers +.TP +.B NT_S390_PREFIX +s390 prefix register +.TP +.B NT_S390_LAST_BREAK +s390 breaking event address +.TP +.B NT_S390_SYSTEM_CALL +s390 system call restart data +.TP +.B NT_S390_TDB +s390 transaction diagnostic block +.TP +.B NT_ARM_VFP +ARM VFP/NEON registers +.TP +.B NT_ARM_TLS +ARM TLS register +.TP +.B NT_ARM_HW_BREAK +ARM hardware breakpoint registers +.TP +.B NT_ARM_HW_WATCH +ARM hardware watchpoint registers +.TP +.B NT_ARM_SYSTEM_CALL +ARM system call number +.PD +.RE +.TP +.B n_name = GNU +Extensions used by the GNU tool chain. +.RS +.TP +.B NT_GNU_ABI_TAG +Operating system (OS) ABI information. +The desc field will be 4 words: +.IP +.PD 0 +.RS +.IP [0] 5 +OS descriptor +(\fBELF_NOTE_OS_LINUX\fR, \fBELF_NOTE_OS_GNU\fR, and so on)` +.IP [1] +major version of the ABI +.IP [2] +minor version of the ABI +.IP [3] +subminor version of the ABI +.RE +.PD +.TP +.B NT_GNU_HWCAP +Synthetic hwcap information. +The desc field begins with two words: +.IP +.PD 0 +.RS +.IP [0] 5 +number of entries +.IP [1] +bit mask of enabled entries +.RE +.PD +.IP +Then follow variable-length entries, one byte followed by a null-terminated +hwcap name string. +The byte gives the bit number to test if enabled, (1U << bit) & bit mask. +.TP +.B NT_GNU_BUILD_ID +Unique build ID as generated by the GNU +.BR ld (1) +.B \-\-build\-id +option. +The desc consists of any nonzero number of bytes. +.TP +.B NT_GNU_GOLD_VERSION +The desc contains the GNU Gold linker version used. +.RE +.TP +.B Default/unknown namespace (e_type != ET_CORE) +These are used when the namespace is the default (i.e., +.I n_namesz +will be set to 0), or a fallback when the namespace is unknown. +.RS +.TP 12 +.PD 0 +.B NT_VERSION +A version string of some sort. +.TP +.B NT_ARCH +Architecture information. +.PD +.RE +.RE +.SH NOTES +.\" OpenBSD +.\" ELF support first appeared in +.\" OpenBSD 1.2, +.\" although not all supported platforms use it as the native +.\" binary file format. +ELF first appeared in +System V. +The ELF format is an adopted standard. +.P +The extensions for +.IR e_phnum , +.IR e_shnum , +and +.I e_shstrndx +respectively are +Linux extensions. +Sun, BSD, and AMD64 also support them; for further information, +look under SEE ALSO. +.\" .SH AUTHORS +.\" The original version of this manual page was written by +.\" .An Jeroen Ruigrok van der Werven +.\" .Aq asmodai@FreeBSD.org +.\" with inspiration from BSDi's +.\" .Bsx +.\" .Nm elf +.\" man page. +.SH SEE ALSO +.BR as (1), +.BR elfedit (1), +.BR gdb (1), +.BR ld (1), +.BR nm (1), +.BR objcopy (1), +.BR objdump (1), +.BR patchelf (1), +.BR readelf (1), +.BR size (1), +.BR strings (1), +.BR strip (1), +.BR execve (2), +.BR dl_iterate_phdr (3), +.BR core (5), +.BR ld.so (8) +.P +Hewlett-Packard, +.IR "Elf-64 Object File Format" . +.P +Santa Cruz Operation, +.IR "System V Application Binary Interface" . +.P +UNIX System Laboratories, +"Object Files", +.IR "Executable and Linking Format (ELF)" . +.P +Sun Microsystems, +.IR "Linker and Libraries Guide" . +.P +AMD64 ABI Draft, +.IR "System V Application Binary Interface AMD64 Architecture Processor Supplement" . diff --git a/upstream/fedora-40/man5/environment.d.5 b/upstream/fedora-40/man5/environment.d.5 new file mode 100644 index 00000000..063bfb25 --- /dev/null +++ b/upstream/fedora-40/man5/environment.d.5 @@ -0,0 +1,151 @@ +'\" t +.TH "ENVIRONMENT\&.D" "5" "" "systemd 255" "environment.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +environment.d \- Definition of user service environment +.SH "SYNOPSIS" +.PP +~/\&.config/environment\&.d/*\&.conf +.PP +/etc/environment\&.d/*\&.conf +.PP +/run/environment\&.d/*\&.conf +.PP +/usr/lib/environment\&.d/*\&.conf +.PP +/etc/environment +.SH "DESCRIPTION" +.PP +Configuration files in the +environment\&.d/ +directories contain lists of environment variable assignments passed to services started by the systemd user instance\&. +\fBsystemd-environment-d-generator\fR(8) +parses them and updates the environment exported by the systemd user instance\&. See below for an discussion of which processes inherit those variables\&. +.PP +It is recommended to use numerical prefixes for file names to simplify ordering\&. +.PP +For backwards compatibility, a symlink to +/etc/environment +is installed, so this file is also parsed\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +Configuration files are read from directories in +/etc/, +/run/, +/usr/local/lib/, and +/usr/lib/, in order of precedence, as listed in the SYNOPSIS section above\&. Files must have the +"\&.conf" +extension\&. Files in +/etc/ +override files with the same name in +/run/, +/usr/local/lib/, and +/usr/lib/\&. Files in +/run/ +override files with the same name under +/usr/\&. +.PP +All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence\&. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later)\&. +.PP +Packages should install their configuration files in +/usr/lib/ +(distribution packages) or +/usr/local/lib/ +(local installs)\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. It is recommended to prefix all filenames with a two\-digit number and a dash, to simplify the ordering of the files\&. +.PP +If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. If the vendor configuration file is included in the initrd image, the image has to be regenerated\&. +.SH "CONFIGURATION FORMAT" +.PP +The configuration files contain a list of +"\fIKEY\fR=\fIVALUE\fR" +environment variable assignments, separated by newlines\&. The right hand side of these assignments may reference previously defined environment variables, using the +"${OTHER_KEY}" +and +"$OTHER_KEY" +format\&. It is also possible to use +"${\fIFOO\fR:\-\fIDEFAULT_VALUE\fR}" +to expand in the same way as +"${\fIFOO\fR}" +unless the expansion would be empty, in which case it expands to +\fIDEFAULT_VALUE\fR, and use +"${\fIFOO\fR:+\fIALTERNATE_VALUE\fR}" +to expand to +\fIALTERNATE_VALUE\fR +as long as +"${\fIFOO\fR}" +would have expanded to a non\-empty value\&. No other elements of shell syntax are supported\&. +.PP +Each +\fIKEY\fR +must be a valid variable name\&. Empty lines and lines beginning with the comment character +"#" +are ignored\&. +.SS "Example" +.PP +\fBExample\ \&1.\ \&Setup environment to allow access to a program installed in /opt/foo\fR +.PP +/etc/environment\&.d/60\-foo\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf + FOO_DEBUG=force\-software\-gl,log\-verbose + PATH=/opt/foo/bin:$PATH + LD_LIBRARY_PATH=/opt/foo/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} + XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS:\-/usr/local/share/:/usr/share/} + +.fi +.if n \{\ +.RE +.\} +.SH "APPLICABILITY" +.PP +Environment variables exported by the user service manager (\fBsystemd \-\-user\fR +instance started in the +user@\fIuid\fR\&.service +system service) are passed to any services started by that service manager\&. In particular, this may include services which run user shells\&. For example in the GNOME environment, the graphical terminal emulator runs as the +gnome\-terminal\-server\&.service +user unit, which in turn runs the user shell, so that shell will inherit environment variables exported by the user manager\&. For other instances of the shell, not launched by the user service manager, the environment they inherit is defined by the program that starts them\&. Hint: in general, +\fBsystemd.service\fR(5) +units contain programs launched by systemd, and +\fBsystemd.scope\fR(5) +units contain programs launched by something else\&. +.PP +Note that these files do not affect the environment block of the service manager itself, but exclusively the environment blocks passed to the services it manages\&. Environment variables set that way thus cannot be used to influence behaviour of the service manager\&. In order to make changes to the service manager\*(Aqs environment block the environment must be modified before the user\*(Aqs service manager is invoked, for example from the system service manager or via a PAM module\&. +.PP +Specifically, for ssh logins, the +\fBsshd\fR(8) +service builds an environment that is a combination of variables forwarded from the remote system and defined by +\fBsshd\fR, see the discussion in +\fBssh\fR(1)\&. A graphical display session will have an analogous mechanism to define the environment\&. Note that some managers query the systemd user instance for the exported environment and inject this configuration into programs they start, using +\fBsystemctl show\-environment\fR +or the underlying D\-Bus call\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-environment-d-generator\fR(8), +\fBsystemd.environment-generator\fR(7) diff --git a/upstream/fedora-40/man5/erofs.5 b/upstream/fedora-40/man5/erofs.5 new file mode 100644 index 00000000..12de0ec7 --- /dev/null +++ b/upstream/fedora-40/man5/erofs.5 @@ -0,0 +1,97 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH erofs 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +erofs \- the Enhanced Read-Only File System +.SH DESCRIPTION +.B erofs +is a create-once read-only filesystem, +with support for compression and a multi-device backing store. +.P +There are two inode formats: +.IP \[bu] 3 +32-byte compact with 16-bit UID/GID, +32-bit file size, +and no file times +.PD 0 +.IP \[bu] +64-byte extended with 32-bit UID/GID, +64-bit file size, +and a modification time +.RI ( st_mtim ). +.PD +.\" See fs/erofs/super.c:shmem_parse_options for options it supports. +.SS Mount options +.TP +.B user_xattr +.TQ +.B nouser_xattr +Controls whether +.I user +extended attributes are exposed. +Defaults to yes. +.TP +.B acl +.TQ +.B noacl +Controls whether POSIX +.BR acl (5)s +are exposed. +Defaults to yes. +.TP +.BR cache_strategy = disabled | readahead | readaround +Cache allocation for compressed files: +never, if reading from start of file, regardless of position. +Defaults to +.BR readaround . +.TP +.B dax +.TQ +.BR dax = always | never +Direct Access control. +If +.B always +and the source device supports DAX, uncompressed non-inlined files +will be read directly, without going through the page cache. +.B dax +is a synonym for +.BR always . +Defaults to unset, which is equivalent to +.BR never . +.TP +.BR device = \fIblobdev\fP +Add extra device holding some of the data. +Must be given as many times and in the same order as +.B \-\-blobdev +was to +.BR mkfs.erofs (1). +.\" Nominally there's a device_table feature and it somehow scans(?) for them, +.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work +.TP +.BR domain_id = \fIdid\fP +.TQ +.BR fsid = \fIid\fP +Control CacheFiles on-demand read support. +To be documented. +.SH VERSIONS +.B erofs +images are versioned through the use of feature flags; +these are listed in the +.B \-E +section of +.BR mkfs.erofs (1), +.SH CONFIGURATION +Linux must be configured with the +.B CONFIG_EROFS_FS +option to mount EROFS filesystems. +There are sub-configuration items that restrict the availability +of some of the parameters above. +.SH SEE ALSO +.BR mkfs.erofs (1), +.BR fsck.erofs (1), +.BR dump.erofs (1) +.P +.I Documentation/filesystems/erofs.txt +in the Linux source. diff --git a/upstream/fedora-40/man5/ethers.5 b/upstream/fedora-40/man5/ethers.5 new file mode 100644 index 00000000..af934a08 --- /dev/null +++ b/upstream/fedora-40/man5/ethers.5 @@ -0,0 +1,28 @@ +.TH ETHERS 5 "2008\-10\-03" "net\-tools" "Linux System Administrator's Manual" +.SH NAME \"{{{roff}}}\"{{{ +ethers \- Ethernet address to IP number database +.\"}}} +.SH DESCRIPTION \"{{{ +\fB/etc/ethers\fP contains 48 bit Ethernet addresses and their corresponding +IP numbers, one line for each IP number: +.sp +.RS +\fIEthernet\-address\fP \fIIP\-number\fP +.RE +.sp +The two items are separated by any number of SPACE and/or TAB characters. +A \fB#\fP at the beginning of a line starts a comment +which extends to the end of the line. The \fIEthernet\-address\fP is +written as +.IR x : x : x : x : x : x , +where \fIx\fP is a hexadecimal number between \fB0\fP and \fBff\fP +which represents one byte of the address, which is in network byte +order (big-endian). The \fIIP\-number\fP may be a hostname which +can be resolved by DNS or a dot separated number. +.\"}}} +.SH EXAMPLES \"{{{ +08:00:20:00:61:CA pal +.\"}}} +.SH FILES \"{{{ +/etc/ethers +.\"}}} diff --git a/upstream/fedora-40/man5/exports.5 b/upstream/fedora-40/man5/exports.5 new file mode 100644 index 00000000..58537a22 --- /dev/null +++ b/upstream/fedora-40/man5/exports.5 @@ -0,0 +1,678 @@ +.\"@(#)exports.5" +.\" +.TH exports 5 "31 December 2009" +.SH NAME +exports \- NFS server export table +.SH DESCRIPTION +The file +.I /etc/exports +contains a table of local physical file systems on an NFS server +that are accessible to NFS clients. +The contents of the file are maintained by the server's system +administrator. +.PP +Each file system in this table has a list of options and an +access control list. +The table is used by +.BR exportfs (8) +to give information to +.BR mountd (8). +.PP +The file format is similar to the SunOS +.I exports +file. Each line contains an export point and a whitespace-separated list +of clients allowed to mount the file system at that point. Each listed +client may be immediately followed by a parenthesized, comma-separated +list of export options for that client. No whitespace is permitted +between a client and its option list. +.PP +Also, each line may have one or more specifications for default options +after the path name, in the form of a dash ("\-") followed by an option +list. The option list is used for all subsequent exports on that line +only. +.PP +Blank lines are ignored. A pound sign ("#") introduces a comment to the +end of the line. Entries may be continued across newlines using a +backslash. If an export name contains spaces it should be quoted using +double quotes. You can also specify spaces or other unusual character in +the export name using a backslash followed by the character code as three +octal digits. +.PP +To apply changes to this file, run +.BR "exportfs \-ra" +or restart the NFS server. +.PP +.SS Machine Name Formats +NFS clients may be specified in a number of ways: +.IP "single host +You may specify a host either by an +abbreviated name recognized be the resolver, the fully qualified domain +name, an IPv4 address, or an IPv6 address. IPv6 addresses must not be +inside square brackets in /etc/exports lest they be confused with +character-class wildcard matches. +.IP "IP networks +You can also export directories to all hosts on an IP (sub-) network +simultaneously. This is done by specifying an IP address and netmask pair +as +.IR address/netmask +where the netmask can be specified in dotted-decimal format, or as a +contiguous mask length. +For example, either `/255.255.252.0' or `/22' appended +to the network base IPv4 address results in identical subnetworks with 10 bits +of host. IPv6 addresses must use a contiguous mask length and must not be inside square brackets to avoid confusion with character-class wildcards. Wildcard characters generally do not work on IP addresses, though they +may work by accident when reverse DNS lookups fail. +.IP "wildcards +Machine names may contain the wildcard characters \fI*\fR and \fI?\fR, or may contain character class lists within [square brackets]. +This can be used to make the \fIexports\fR file more compact; for instance, +\fI*.cs.foo.edu\fR matches all hosts in the domain +\fIcs.foo.edu\fR. As these characters also match the dots in a domain +name, the given pattern will also match all hosts within any subdomain +of \fIcs.foo.edu\fR. +.IP "netgroups +NIS netgroups may be given as +.IR @group . +Only the host part of each +netgroup members is consider in checking for membership. Empty host +parts or those containing a single dash (\-) are ignored. +.IP "anonymous +This is specified by a single +.I * +character (not to be confused with the +.I wildcard +entry above) and will match all clients. +.\".TP +.\".B =public +.\"This is a special ``hostname'' that identifies the given directory name +.\"as the public root directory (see the section on WebNFS in +.\".BR nfsd (8) +.\"for a discussion of WebNFS and the public root handle). When using this +.\"convention, +.\".B =public +.\"must be the only entry on this line, and must have no export options +.\"associated with it. Note that this does +.\".I not +.\"actually export the named directory; you still have to set the exports +.\"options in a separate entry. +.\".PP +.\"The public root path can also be specified by invoking +.\".I nfsd +.\"with the +.\".B \-\-public\-root +.\"option. Multiple specifications of a public root will be ignored. +.PP +If a client matches more than one of the specifications above, then +the first match from the above list order takes precedence - regardless of +the order they appear on the export line. However, if a client matches +more than one of the same type of specification (e.g. two netgroups), +then the first match from the order they appear on the export line takes +precedence. +.SS RPCSEC_GSS security +You may use the special strings "gss/krb5", "gss/krb5i", or "gss/krb5p" +to restrict access to clients using rpcsec_gss security. However, this +syntax is deprecated; on linux kernels since 2.6.23, you should instead +use the "sec=" export option: +.TP +.IR sec= +The sec= option, followed by a colon-delimited list of security flavors, +restricts the export to clients using those flavors. Available security +flavors include sys (the default--no cryptographic security), krb5 +(authentication only), krb5i (integrity protection), and krb5p (privacy +protection). For the purposes of security flavor negotiation, order +counts: preferred flavors should be listed first. The order of the sec= +option with respect to the other options does not matter, unless you +want some options to be enforced differently depending on flavor. +In that case you may include multiple sec= options, and following options +will be enforced only for access using flavors listed in the immediately +preceding sec= option. The only options that are permitted to vary in +this way are ro, rw, no_root_squash, root_squash, and all_squash. +.SS Transport layer security +The Linux NFS server allows the use of RPC-with-TLS (RFC 9289) to +protect RPC traffic between itself and its clients. +Alternately, administrators can secure NFS traffic using a VPN, +or an ssh tunnel or similar mechanism, in a way that is transparent +to the server. +.PP +To enable the use of RPC-with-TLS, the server's administrator must +install and configure +.BR tlshd +to handle transport layer security handshake requests from the local +kernel. +Clients can then choose to use RPC-with-TLS or they may continue +operating without it. +.PP +Administrators may require the use of RPC-with-TLS to protect access +to individual exports. +This is particularly useful when using non-cryptographic security +flavors such as +.IR sec=sys . +The +.I xprtsec= +option, followed by an unordered colon-delimited list of security policies, +can restrict access to the export to only clients that have negotiated +transport-layer security. +Currently supported transport layer security policies include: +.TP +.IR none +The server permits clients to access the export +without the use of transport layer security. +.TP +.IR tls +The server permits clients that have negotiated an RPC-with-TLS session +without peer authentication (confidentiality only) to access the export. +Clients are not required to offer an x.509 certificate +when establishing a transport layer security session. +.TP +.IR mtls +The server permits clients that have negotiated an RPC-with-TLS session +with peer authentication to access the export. +The server requires clients to offer an x.509 certificate +when establishing a transport layer security session. +.PP +If RPC-with-TLS is configured and enabled and the +.I xprtsec= +option is not specified, the default setting for an export is +.IR xprtsec=none:tls:mtls . +With this setting, the server permits clients to use any transport +layer security mechanism or none at all to access the export. +.SS General Options +.BR exportfs +understands the following export options: +.TP +.IR secure +This option requires that requests not using gss originate on an +Internet port less than IPPORT_RESERVED (1024). This option is on by default. +To turn it off, specify +.IR insecure . +(NOTE: older kernels (before upstream kernel version 4.17) enforced this +requirement on gss requests as well.) +.TP +.IR rw +Allow both read and write requests on this NFS volume. The +default is to disallow any request which changes the filesystem. +This can also be made explicit by using +the +.IR ro " option. +.TP +.IR async +This option allows the NFS server to violate the NFS protocol and +reply to requests before any changes made by that request have been +committed to stable storage (e.g. disc drive). + +Using this option usually improves performance, but at the cost that +an unclean server restart (i.e. a crash) can cause data to be lost or +corrupted. + +.TP +.IR sync +Reply to requests only after the changes have been committed to stable +storage (see +.IR async +above). + +In releases of nfs-utils up to and including 1.0.0, the +.I async +option was the +default. In all releases after 1.0.0, +.I sync +is the default, and +.I async +must be explicitly requested if needed. +.TP +.IR no_wdelay +This option has no effect if +.I async +is also set. The NFS server will normally delay committing a write request +to disc slightly if it suspects that another related write request may be in +progress or may arrive soon. This allows multiple write requests to +be committed to disc with the one operation which can improve +performance. If an NFS server received mainly small unrelated +requests, this behaviour could actually reduce performance, so +.IR no_wdelay +is available to turn it off. +The default can be explicitly requested with the +.IR wdelay " option. +.TP +.IR nohide +This option is based on the option of the same name provided in IRIX +NFS. Normally, if a server exports two filesystems one of which is +mounted on the other, then the client will have to mount both +filesystems explicitly to get access to them. If it just mounts the +parent, it will see an empty directory at the place where the other +filesystem is mounted. That filesystem is "hidden". + +Setting the +.I nohide +option on a filesystem causes it not to be hidden, and an +appropriately authorised client will be able to move from the parent to +that filesystem without noticing the change. + +However, some NFS clients do not cope well with this situation as, for +instance, it is then possible for two files in the one apparent +filesystem to have the same inode number. + +The +.I nohide +option is currently only effective on +.I "single host +exports. It does not work reliably with netgroup, subnet, or wildcard +exports. + +This option can be very useful in some situations, but it should be +used with due care, and only after confirming that the client system +copes with the situation effectively. + +The option can be explicitly disabled for NFSv2 and NFSv3 with +.IR hide . + +This option is not relevant when NFSv4 is use. NFSv4 never hides +subordinate filesystems. Any filesystem that is exported will be +visible where expected when using NFSv4. +.TP +.I crossmnt +This option is similar to +.I nohide +but it makes it possible for clients to access all filesystems mounted +on a filesystem marked with +.IR crossmnt . +Thus when a child filesystem "B" is mounted on a parent "A", setting +crossmnt on "A" has a similar effect to setting "nohide" on B. + +With +.I nohide +the child filesystem needs to be explicitly exported. With +.I crossmnt +it need not. If a child of a +.I crossmnt +file is not explicitly exported, then it will be implicitly exported +with the same export options as the parent, except for +.IR fsid= . +This makes it impossible to +.B not +export a child of a +.I crossmnt +filesystem. If some but not all subordinate filesystems of a parent +are to be exported, then they must be explicitly exported and the +parent should not have +.I crossmnt +set. + +The +.I nocrossmnt +option can explicitly disable +.I crossmnt +if it was previously set. This is rarely useful. +.TP +.IR no_subtree_check +This option disables subtree checking, which has mild security +implications, but can improve reliability in some circumstances. + +If a subdirectory of a filesystem is exported, but the whole +filesystem isn't then whenever a NFS request arrives, the server must +check not only that the accessed file is in the appropriate filesystem +(which is easy) but also that it is in the exported tree (which is +harder). This check is called the +.IR subtree_check . + +In order to perform this check, the server must include some +information about the location of the file in the "filehandle" that is +given to the client. This can cause problems with accessing files that +are renamed while a client has them open (though in many simple cases +it will still work). + +subtree checking is also used to make sure that files inside +directories to which only root has access can only be accessed if the +filesystem is exported with +.I no_root_squash +(see below), even if the file itself allows more general access. + +As a general guide, a home directory filesystem, which is normally +exported at the root and may see lots of file renames, should be +exported with subtree checking disabled. A filesystem which is mostly +readonly, and at least doesn't see many file renames (e.g. /usr or +/var) and for which subdirectories may be exported, should probably be +exported with subtree checks enabled. + +The default of having subtree checks enabled, can be explicitly +requested with +.IR subtree_check . + +From release 1.1.0 of nfs-utils onwards, the default will be +.I no_subtree_check +as subtree_checking tends to cause more problems than it is worth. +If you genuinely require subtree checking, you should explicitly put +that option in the +.B exports +file. If you put neither option, +.B exportfs +will warn you that the change is pending. + +.TP +.IR insecure_locks +.TP +.IR no_auth_nlm +This option (the two names are synonymous) tells the NFS server not to require authentication of +locking requests (i.e. requests which use the NLM protocol). Normally +the NFS server will require a lock request to hold a credential for a +user who has read access to the file. With this flag no access checks +will be performed. + +Early NFS client implementations did not send credentials with lock +requests, and many current NFS clients still exist which are based on +the old implementations. Use this flag if you find that you can only +lock files which are world readable. + +The default behaviour of requiring authentication for NLM requests can +be explicitly requested with either of the synonymous +.IR auth_nlm , +or +.IR secure_locks . +.\".TP +.\".I noaccess +.\"This makes everything below the directory inaccessible for the named +.\"client. This is useful when you want to export a directory hierarchy to +.\"a client, but exclude certain subdirectories. The client's view of a +.\"directory flagged with noaccess is very limited; it is allowed to read +.\"its attributes, and lookup `.' and `..'. These are also the only entries +.\"returned by a readdir. +.\".TP +.\".IR link_relative +.\"Convert absolute symbolic links (where the link contents start with a +.\"slash) into relative links by prepending the necessary number of ../'s +.\"to get from the directory containing the link to the root on the +.\"server. This has subtle, perhaps questionable, semantics when the file +.\"hierarchy is not mounted at its root. +.\".TP +.\".IR link_absolute +.\"Leave all symbolic link as they are. This is the default operation. + +.TP +.IR mountpoint= path +.TP +.I mp +This option makes it possible to only export a directory if it has +successfully been mounted. +If no path is given (e.g. +.IR mountpoint " or " mp ) +then the export point must also be a mount point. If it isn't then +the export point is not exported. This allows you to be sure that the +directory underneath a mountpoint will never be exported by accident +if, for example, the filesystem failed to mount due to a disc error. + +If a path is given (e.g. +.IR mountpoint= "/path or " mp= /path) +then the nominated path must be a mountpoint for the exportpoint to be +exported. + +.TP +.IR fsid= num|root|uuid +NFS needs to be able to identify each filesystem that it exports. +Normally it will use a UUID for the filesystem (if the filesystem has +such a thing) or the device number of the device holding the +filesystem (if the filesystem is stored on the device). + +As not all filesystems are stored on devices, and not all filesystems +have UUIDs, it is sometimes necessary to explicitly tell NFS how to +identify a filesystem. This is done with the +.I fsid= +option. + +For NFSv4, there is a distinguished filesystem which is the root of +all exported filesystem. This is specified with +.I fsid=root +or +.I fsid=0 +both of which mean exactly the same thing. + +Other filesystems can be identified with a small integer, or a UUID +which should contain 32 hex digits and arbitrary punctuation. + +Linux kernels version 2.6.20 and earlier do not understand the UUID +setting so a small integer must be used if an fsid option needs to be +set for such kernels. Setting both a small number and a UUID is +supported so the same configuration can be made to work on old and new +kernels alike. + +.TP +.IR nordirplus +This option will disable READDIRPLUS request handling. When set, +READDIRPLUS requests from NFS clients return NFS3ERR_NOTSUPP, and +clients fall back on READDIR. This option affects only NFSv3 clients. +.TP +.IR refer= path@host[+host][:path@host[+host]] +A client referencing the export point will be directed to choose from +the given list an alternative location for the filesystem. +(Note that the server must have a mountpoint here, though a different +filesystem is not required; so, for example, +.IR "mount --bind" " /path /path" +is sufficient.) +.TP +.IR replicas= path@host[+host][:path@host[+host]] +If the client asks for alternative locations for the export point, it +will be given this list of alternatives. (Note that actual replication +of the filesystem must be handled elsewhere.) + +.TP +.IR pnfs +This option enables the use of the pNFS extension if the protocol level +is NFSv4.1 or higher, and the filesystem supports pNFS exports. With +pNFS clients can bypass the server and perform I/O directly to storage +devices. The default can be explicitly requested with the +.I no_pnfs +option. + +.TP +.IR security_label +With this option set, clients using NFSv4.2 or higher will be able to +set and retrieve security labels (such as those used by SELinux). This +will only work if all clients use a consistent security policy. Note +that early kernels did not support this export option, and instead +enabled security labels by default. + +.TP +.IR reexport= auto-fsidnum|predefined-fsidnum +This option helps when a NFS share is re-exported. Since the NFS server +needs a unique identifier for each exported filesystem and a NFS share +cannot provide such, usually a manual fsid is needed. +As soon +.IR crossmnt +is used manually assigning fsid won't work anymore. This is where this +option becomes handy. It will automatically assign a numerical fsid +to exported NFS shares. The fsid and path relations are stored in a SQLite +database. If +.IR auto-fsidnum +is selected, the fsid is also autmatically allocated. +.IR predefined-fsidnum +assumes pre-allocated fsid numbers and will just look them up. +This option depends also on the kernel, you will need at least kernel version +5.19. +Since +.IR reexport= +can automatically allocate and assign numerical fsids, it is no longer possible +to have numerical fsids in other exports as soon this option is used in at least +one export entry. + +The association between fsid numbers and paths is stored in a SQLite database. +Don't edit or remove the database unless you know exactly what you're doing. +.IR predefined-fsidnum +is useful when you have used +.IR auto-fsidnum +before and don't want further entries stored. + + +.SS User ID Mapping +.PP +.B nfsd +bases its access control to files on the server machine on the uid and +gid provided in each NFS RPC request. The normal behavior a user would +expect is that she can access her files on the server just as she would +on a normal file system. This requires that the same uids and gids are +used on the client and the server machine. This is not always true, nor +is it always desirable. +.PP +Very often, it is not desirable that the root user on a client machine +is also treated as root when accessing files on the NFS server. To this +end, uid 0 is normally mapped to a different id: the so-called +anonymous or +.I nobody +uid. This mode of operation (called `root squashing') is the default, +and can be turned off with +.IR no_root_squash . +.PP +By default, +.\".B nfsd +.\"tries to obtain the anonymous uid and gid by looking up user +.\".I nobody +.\"in the password file at startup time. If it isn't found, a uid and gid +.B exportfs +chooses a uid and gid +of 65534 for squashed access. These values can also be overridden by +the +.IR anonuid " and " anongid +options. +.\".PP +.\"In addition to this, +.\".B nfsd +.\"lets you specify arbitrary uids and gids that should be mapped to user +.\"nobody as well. +Finally, you can map all user requests to the +anonymous uid by specifying the +.IR all_squash " option. +.PP +Here's the complete list of mapping options: +.TP +.IR root_squash +Map requests from uid/gid 0 to the anonymous uid/gid. Note that this does +not apply to any other uids or gids that might be equally sensitive, such as +user +.IR bin +or group +.IR staff . +.TP +.IR no_root_squash +Turn off root squashing. This option is mainly useful for diskless clients. +.TP +.IR all_squash +Map all uids and gids to the anonymous user. Useful for NFS-exported +public FTP directories, news spool directories, etc. The opposite option +is +.IR no_all_squash , +which is the default setting. +.TP +.IR anonuid " and " anongid +These options explicitly set the uid and gid of the anonymous account. +This option is primarily useful for PC/NFS clients, where you might want +all requests appear to be from one user. As an example, consider the +export entry for +.B /home/joe +in the example section below, which maps all requests to uid 150 (which +is supposedly that of user joe). + +.SS Subdirectory Exports + +Normally you should only export only the root of a filesystem. The NFS +server will also allow you to export a subdirectory of a filesystem, +however, this has drawbacks: + +First, it may be possible for a malicious user to access files on the +filesystem outside of the exported subdirectory, by guessing filehandles +for those other files. The only way to prevent this is by using the +.IR no_subtree_check +option, which can cause other problems. + +Second, export options may not be enforced in the way that you would +expect. For example, the +.IR security_label +option will not work on subdirectory exports, and if nested subdirectory +exports change the +.IR security_label +or +.IR sec= +options, NFSv4 clients will normally see only the options on the parent +export. Also, where security options differ, a malicious client may use +filehandle-guessing attacks to access the files from one subdirectory +using the options from another. + + +.SS Extra Export Tables +After reading +.I /etc/exports +.B exportfs +reads files in the +.I /etc/exports.d +directory as extra export tables. Only files ending in +.I .exports +are considered. Files beginning with a dot are ignored. +The format for extra export tables is the same as +.I /etc/exports +. +.IP +.SH EXAMPLE +.PP +.nf +.ta +3i +# sample /etc/exports file +/ master(rw) trusty(rw,no_root_squash) +/projects proj*.local.domain(rw) +/usr *.local.domain(ro) @trusted(rw) +/home/joe pc001(rw,all_squash,anonuid=150,anongid=100) +/pub *(ro,insecure,all_squash) +/srv/www \-sync,rw server @trusted @external(ro) +/foo 2001:db8:9:e54::/64(rw) 192.0.2.0/24(rw) +/build buildhost[0-9].local.domain(rw) +.\"/pub/private (noaccess) +.fi +.PP +The first line exports the entire filesystem to machines master and trusty. +In addition to write access, all uid squashing is turned off for host +trusty. The second and third entry show examples for wildcard hostnames +and netgroups (this is the entry `@trusted'). The fourth line shows the +entry for the PC/NFS client discussed above. Line 5 exports the +public FTP directory to every host in the world, executing all requests +under the nobody account. The +.I insecure +option in this entry also allows clients with NFS implementations that +don't use a reserved port for NFS. +The sixth line exports a directory read-write to the machine 'server' +as well as the `@trusted' netgroup, and read-only to netgroup `@external', +all three mounts with the `sync' option enabled. The seventh line exports +a directory to both an IPv6 and an IPv4 subnet. The eighth line demonstrates +a character class wildcard match. +.\" The last line denies all NFS clients +.\"access to the private directory. +.\".SH CAVEATS +.\"Unlike other NFS server implementations, this +.\".B nfsd +.\"allows you to export both a directory and a subdirectory thereof to +.\"the same host, for instance +.\".IR /usr " and " /usr/X11R6 . +.\"In this case, the mount options of the most specific entry apply. For +.\"instance, when a user on the client host accesses a file in +.\".IR /usr/X11R6 , +.\"the mount options given in the +.\".I /usr/X11R6 +.\"entry apply. This is also true when the latter is a wildcard or netgroup +.\"entry. +.SH FILES +/etc/exports +/etc/exports.d +.SH SEE ALSO +.BR exportfs (8), +.BR netgroup (5), +.BR mountd (8), +.BR nfsd (8), +.BR showmount (8), +.BR tlshd (8). +.\".SH DIAGNOSTICS +.\"An error parsing the file is reported using syslogd(8) as level NOTICE from +.\"a DAEMON whenever +.\".BR nfsd (8) +.\"or +.\".BR mountd (8) +.\"is started up. Any unknown +.\"host is reported at that time, but often not all hosts are not yet known +.\"to +.\".BR named (8) +.\"at boot time, thus as hosts are found they are reported +.\"with the same +.\".BR syslogd (8) +.\"parameters. diff --git a/upstream/fedora-40/man5/ext2.5 b/upstream/fedora-40/man5/ext2.5 new file mode 100644 index 00000000..5be4c1d1 --- /dev/null +++ b/upstream/fedora-40/man5/ext2.5 @@ -0,0 +1,815 @@ +.\" -*- nroff -*- +.\" Copyright 1993, 1994, 1995 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH EXT4 5 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +ext2 \- the second extended file system +.br +ext3 \- the third extended file system +.br +ext4 \- the fourth extended file system +.SH DESCRIPTION +The second, third, and fourth extended file systems, or ext2, ext3, and +ext4 as they are commonly known, are Linux file systems that have +historically been the default file system for many Linux distributions. +They are general purpose file systems that have been designed for +extensibility and backwards compatibility. In particular, file systems +previously intended for use with the ext2 and ext3 file systems can be +mounted using the ext4 file system driver, and indeed in many modern +Linux distributions, the ext4 file system driver has been configured +to handle mount requests for ext2 and ext3 file systems. +.SH FILE SYSTEM FEATURES +A file system formatted for ext2, ext3, or ext4 can have some +collection of the following file system feature flags enabled. Some of +these features are not supported by all implementations of the ext2, +ext3, and ext4 file system drivers, depending on Linux kernel version in +use. On other operating systems, such as the GNU/HURD or FreeBSD, only +a very restrictive set of file system features may be supported in their +implementations of ext2. +.TP +.B 64bit +.br +Enables the file system to be larger than 2^32 blocks. This feature is set +automatically, as needed, but it can be useful to specify this feature +explicitly if the file system might need to be resized larger than 2^32 +blocks, even if it was smaller than that threshold when it was +originally created. Note that some older kernels and older versions +of e2fsprogs will not support file systems with this ext4 feature enabled. +.TP +.B bigalloc +.br +This ext4 feature enables clustered block allocation, so that the unit of +allocation is a power of two number of blocks. That is, each bit in the +what had traditionally been known as the block allocation bitmap now +indicates whether a cluster is in use or not, where a cluster is by +default composed of 16 blocks. This feature can decrease the time +spent on doing block allocation and brings smaller fragmentation, especially +for large files. The size can be specified using the +.B mke2fs \-C +option. +.IP +.B Warning: +The bigalloc feature is still under development, and may not be fully +supported with your kernel or may have various bugs. Please see the web +page http://ext4.wiki.kernel.org/index.php/Bigalloc for details. +May clash with delayed allocation (see +.B nodelalloc +mount option). +.IP +This feature requires that the +.B extent +feature be enabled. +.TP +.B casefold +.br +This ext4 feature provides file system level character encoding support +for directories with the casefold (+F) flag enabled. This feature is +name-preserving on the disk, but it allows applications to lookup for a +file in the file system using an encoding equivalent version of the file +name. +.TP +.B dir_index +.br +Use hashed b-trees to speed up name lookups in large directories. This +feature is supported by ext3 and ext4 file systems, and is ignored by +ext2 file systems. +.TP +.B dir_nlink +.br +Normally, ext4 allows an inode to have no more than 65,000 hard links. +This applies to regular files as well as directories, which means that +there can be no more than 64,998 subdirectories in a directory (because +each of the '.' and '..' entries, as well as the directory entry for the +directory in its parent directory counts as a hard link). This feature +lifts this limit by causing ext4 to use a link count of 1 to indicate +that the number of hard links to a directory is not known when the link +count might exceed the maximum count limit. +.TP +.B ea_inode +.br +Normally, a file's extended attributes and associated metadata must fit within +the inode or the inode's associated extended attribute block. This feature +allows the value of each extended attribute to be placed in the data blocks of a +separate inode if necessary, increasing the limit on the size and number of +extended attributes per file. +.TP +.B encrypt +.br +Enables support for file-system level encryption of data blocks and file +names. The inode metadata (timestamps, file size, user/group ownership, +etc.) is +.I not +encrypted. +.IP +This feature is most useful on file systems with multiple users, or +where not all files should be encrypted. In many use cases, especially +on single-user systems, encryption at the block device layer using +dm-crypt may provide much better security. +.TP +.B ext_attr +.br +This feature enables the use of extended attributes. This feature is +supported by ext2, ext3, and ext4. +.TP +.B extent +.br +This ext4 feature allows the mapping of logical block numbers for a +particular inode to physical blocks on the storage device to be stored +using an extent tree, which is a more efficient data structure than the +traditional indirect block scheme used by the ext2 and ext3 file +systems. The use of the extent tree decreases metadata block overhead, +improves file system performance, and decreases the needed to run +.BR e2fsck (8) +on the file system. +(Note: both +.B extent +and +.B extents +are accepted as valid names for this feature for +historical/backwards compatibility reasons.) +.TP +.B extra_isize +.br +This ext4 feature reserves a specific amount of space in each inode for +extended metadata such as nanosecond timestamps and file creation time, +even if the current kernel does not currently need to reserve this much +space. Without this feature, the kernel will reserve the amount of +space for features it currently needs, and the rest may be +consumed by extended attributes. + +For this feature to be useful the inode size must be 256 bytes in size +or larger. +.TP +.B filetype +.br +This feature enables the storage of file type information in directory +entries. This feature is supported by ext2, ext3, and ext4. +.TP +.B flex_bg +.br +This ext4 feature allows the per-block group metadata (allocation +bitmaps +and inode tables) +to be placed anywhere on the storage media. In addition, +.B mke2fs +will place the per-block group metadata together starting at the first +block group of each "flex_bg group". The size of the flex_bg group +can be specified using the +.B \-G +option. +.TP +.B has_journal +.br +Create a journal to ensure file system consistency even across unclean +shutdowns. Setting the file system feature is equivalent to using the +.B \-j +option with +.BR mke2fs " or " tune2fs. +This feature is supported by ext3 and ext4, and ignored by the +ext2 file system driver. +.TP +.B huge_file +.br +This ext4 feature allows files to be larger than 2 terabytes in size. +.TP +.B inline_data +Allow data to be stored in the inode and extended attribute area. +.TP +.B journal_dev +.br +This feature is enabled on the superblock found on an external journal +device. The block size for the external journal must be the same as the +file system which uses it. +.IP +The external journal device can be used by a file system by specifying +the +.B \-J +.BR device= +option to +.BR mke2fs (8) +or +.BR tune2fs(8) . +.TP +.B large_dir +.br +This feature increases the limit on the number of files per directory by +raising the maximum size of directories and, for hashed b-tree directories (see +.BR dir_index ), +the maximum height of the hashed b-tree used to store the directory entries. +.TP +.B large_file +.br +This feature flag is set automatically by modern kernels when a file +larger than 2 gigabytes is created. Very old kernels could not +handle large files, so this feature flag was used to prohibit those +kernels from mounting file systems that they could not understand. +.TP +.B metadata_csum +.br +This ext4 feature enables metadata checksumming. This feature stores +checksums for all of the file system metadata (superblock, group +descriptor blocks, inode and block bitmaps, directories, and +extent tree blocks). The checksum algorithm used for the metadata +blocks is different than the one used for group descriptors with the +.B uninit_bg +feature. These two features are incompatible and +.B metadata_csum +will be used preferentially instead of +.BR uninit_bg . +.TP +.B metadata_csum_seed +.br +This feature allows the file system to store the metadata checksum seed in the +superblock, which allows the administrator to change the UUID of a file system +using the +.B metadata_csum +feature while it is mounted. +.TP +.B meta_bg +.br +This ext4 feature allows file systems to be resized on-line without explicitly +needing to reserve space for growth in the size of the block group +descriptors. This scheme is also used to resize file systems which are +larger than 2^32 blocks. It is not recommended that this feature be set +when a file system is created, since this alternate method of storing +the block group descriptors will slow down the time needed to mount the +file system, and newer kernels can automatically set this feature as +necessary when doing an online resize and no more reserved space is +available in the resize inode. +.TP +.B mmp +.br +This ext4 feature provides multiple mount protection (MMP). MMP helps to +protect the file system from being multiply mounted and is useful in +shared storage environments. +.TP +.B project +.br +This ext4 feature provides project quota support. With this feature, +the project ID of inode will be managed when the file system is mounted. +.TP +.B quota +.br +Create quota inodes (inode #3 for userquota and inode +#4 for group quota) and set them in the superblock. +With this feature, the quotas will be enabled +automatically when the file system is mounted. +.IP +Causes the quota files (i.e., user.quota and +group.quota which existed +in the older quota design) to be hidden inodes. +.TP +.B resize_inode +.br +This file system feature indicates that space has been reserved so that +the block group descriptor table can be extended while resizing a mounted +file system. The online resize operation +is carried out by the kernel, triggered by +.BR resize2fs (8). +By default +.B mke2fs +will attempt to reserve enough space so that the +file system may grow to 1024 times its initial size. This can be changed +using the +.B resize +extended option. +.IP +This feature requires that the +.B sparse_super +or +.B sparse_super2 +feature be enabled. +.TP +.B sparse_super +.br +This file system feature is set on all modern ext2, ext3, and ext4 file +systems. It indicates that backup copies of the superblock and block +group descriptors are present only in a few block groups, not all of +them. +.TP +.B sparse_super2 +.br +This feature indicates that there will only be at most two backup +superblocks and block group descriptors. The block groups used to store +the backup superblock(s) and blockgroup descriptor(s) are stored in the +superblock, but typically, one will be located at the beginning of block +group #1, and one in the last block group in the file system. This +feature is essentially a more extreme version of sparse_super and is +designed to allow a much larger percentage of the disk to have +contiguous blocks available for data files. +.TP +.B stable_inodes +.br +Marks the file system's inode numbers and UUID as stable. +.BR resize2fs (8) +will not allow shrinking a file system with this feature, nor +will +.BR tune2fs (8) +allow changing its UUID. This feature allows the use of specialized encryption +settings that make use of the inode numbers and UUID. Note that the +.B encrypt +feature still needs to be enabled separately. +.B stable_inodes +is a "compat" feature, so old kernels will allow it. +.TP +.B uninit_bg +.br +This ext4 file system feature indicates that the block group descriptors +will be protected using checksums, making it safe for +.BR mke2fs (8) +to create a file system without initializing all of the block groups. +The kernel will keep a high watermark of unused inodes, and initialize +inode tables and blocks lazily. This feature speeds up the time to check +the file system using +.BR e2fsck (8), +and it also speeds up the time required for +.BR mke2fs (8) +to create the file system. +.TP +.B verity +.br +Enables support for verity protected files. Verity files are readonly, +and their data is transparently verified against a Merkle tree hidden +past the end of the file. Using the Merkle tree's root hash, a verity +file can be efficiently authenticated, independent of the file's size. +.IP +This feature is most useful for authenticating important read-only files +on read-write file systems. If the file system itself is read-only, +then using dm-verity to authenticate the entire block device may provide +much better security. +.SH MOUNT OPTIONS +This section describes mount options which are specific to ext2, ext3, +and ext4. Other generic mount options may be used as well; see +.BR mount (8) +for details. +.SH "Mount options for ext2" +The `ext2' file system is the standard Linux file system. +Since Linux 2.5.46, for most mount options the default +is determined by the file system superblock. Set them with +.BR tune2fs (8). +.TP +.BR acl | noacl +Support POSIX Access Control Lists (or not). See the +.BR acl (5) +manual page. +.TP +.BR bsddf | minixdf +Set the behavior for the +.I statfs +system call. The +.B minixdf +behavior is to return in the +.I f_blocks +field the total number of blocks of the file system, while the +.B bsddf +behavior (which is the default) is to subtract the overhead blocks +used by the ext2 file system and not available for file storage. Thus +.sp 1 +% mount /k \-o minixdf; df /k; umount /k +.TS +tab(#); +l2 l2 r2 l2 l2 l +l c r c c l. +File System#1024-blocks#Used#Available#Capacity#Mounted on +/dev/sda6#2630655#86954#2412169#3%#/k +.TE +.sp 1 +% mount /k \-o bsddf; df /k; umount /k +.TS +tab(#); +l2 l2 r2 l2 l2 l +l c r c c l. +File System#1024-blocks#Used#Available#Capacity#Mounted on +/dev/sda6#2543714#13#2412169#0%#/k +.TE +.sp 1 +(Note that this example shows that one can add command line options +to the options given in +.IR /etc/fstab .) +.TP +.BR check=none " or " nocheck +No checking is done at mount time. This is the default. This is fast. +It is wise to invoke +.BR e2fsck (8) +every now and then, e.g.\& at boot time. The non-default behavior is unsupported +(check=normal and check=strict options have been removed). Note that these mount options +don't have to be supported if ext4 kernel driver is used for ext2 and ext3 file systems. +.TP +.B debug +Print debugging info upon each (re)mount. +.TP +.BR errors= { continue | remount-ro | panic } +Define the behavior when an error is encountered. +(Either ignore errors and just mark the file system erroneous and continue, +or remount the file system read-only, or panic and halt the system.) +The default is set in the file system superblock, and can be +changed using +.BR tune2fs (8). +.TP +.BR grpid | bsdgroups " and " nogrpid | sysvgroups +These options define what group id a newly created file gets. +When +.B grpid +is set, it takes the group id of the directory in which it is created; +otherwise (the default) it takes the fsgid of the current process, unless +the directory has the setgid bit set, in which case it takes the gid +from the parent directory, and also gets the setgid bit set +if it is a directory itself. +.TP +.BR grpquota | noquota | quota | usrquota +The usrquota (same as quota) mount option enables user quota support on the +file system. grpquota enables group quotas support. You need the quota utilities +to actually enable and manage the quota system. +.TP +.B nouid32 +Disables 32-bit UIDs and GIDs. This is for interoperability with older +kernels which only store and expect 16-bit values. +.TP +.BR oldalloc " or " orlov +Use old allocator or Orlov allocator for new inodes. Orlov is default. +.TP +\fBresgid=\fP\,\fIn\fP and \fBresuid=\fP\,\fIn\fP +The ext2 file system reserves a certain percentage of the available +space (by default 5%, see +.BR mke2fs (8) +and +.BR tune2fs (8)). +These options determine who can use the reserved blocks. +(Roughly: whoever has the specified uid, or belongs to the specified group.) +.TP +.BI sb= n +Instead of using the normal superblock, use an alternative superblock +specified by +.IR n . +This option is normally used when the primary superblock has been +corrupted. The location of backup superblocks is dependent on the +file system's blocksize, the number of blocks per group, and features +such as +.BR sparse_super . +.IP +Additional backup superblocks can be determined by using the +.B mke2fs +program using the +.B \-n +option to print out where the superblocks exist, supposing +.B mke2fs +is supplied with arguments that are consistent with the file system's layout +(e.g. blocksize, blocks per group, +.BR sparse_super , +etc.). +.IP +The block number here uses 1\ k units. Thus, if you want to use logical +block 32768 on a file system with 4\ k blocks, use "sb=131072". +.TP +.BR user_xattr | nouser_xattr +Support "user." extended attributes (or not). + + +.SH "Mount options for ext3" +The ext3 file system is a version of the ext2 file system which has been +enhanced with journaling. It supports the same options as ext2 as +well as the following additions: +.TP +.BR journal_dev=devnum / journal_path=path +When the external journal device's major/minor numbers +have changed, these options allow the user to specify +the new journal location. The journal device is +identified either through its new major/minor numbers encoded +in devnum, or via a path to the device. +.TP +.BR norecovery / noload +Don't load the journal on mounting. Note that +if the file system was not unmounted cleanly, +skipping the journal replay will lead to the +file system containing inconsistencies that can +lead to any number of problems. +.TP +.BR data= { journal | ordered | writeback } +Specifies the journaling mode for file data. Metadata is always journaled. +To use modes other than +.B ordered +on the root file system, pass the mode to the kernel as boot parameter, e.g.\& +.IR rootflags=data=journal . +.RS +.TP +.B journal +All data is committed into the journal prior to being written into the +main file system. +.TP +.B ordered +This is the default mode. All data is forced directly out to the main file +system prior to its metadata being committed to the journal. +.TP +.B writeback +Data ordering is not preserved \(en data may be written into the main +file system after its metadata has been committed to the journal. +This is rumoured to be the highest-throughput option. It guarantees +internal file system integrity, however it can allow old data to appear +in files after a crash and journal recovery. +.RE +.TP +.B data_err=ignore +Just print an error message if an error occurs in a file data buffer in +ordered mode. +.TP +.B data_err=abort +Abort the journal if an error occurs in a file data buffer in ordered mode. +.TP +.BR barrier=0 " / " barrier=1 " +This disables / enables the use of write barriers in the jbd code. barrier=0 +disables, barrier=1 enables (default). This also requires an IO stack which can +support barriers, and if jbd gets an error on a barrier write, it will disable +barriers again with a warning. Write barriers enforce proper on-disk ordering +of journal commits, making volatile disk write caches safe to use, at some +performance penalty. If your disks are battery-backed in one way or another, +disabling barriers may safely improve performance. +.TP +.BI commit= nrsec +Start a journal commit every +.I nrsec +seconds. The default value is 5 seconds. Zero means default. +.TP +.B user_xattr +Enable Extended User Attributes. See the +.BR attr (5) +manual page. +.TP +.BR jqfmt= { vfsold | vfsv0 | vfsv1 } +Apart from the old quota system (as in ext2, jqfmt=vfsold aka version 1 quota) +ext3 also supports journaled quotas (version 2 quota). jqfmt=vfsv0 or +jqfmt=vfsv1 enables journaled quotas. Journaled quotas have the advantage that +even after a crash no quota check is required. When the +.B quota +file system feature is enabled, journaled quotas are used automatically, and +this mount option is ignored. +.TP +.BR usrjquota=aquota.user | grpjquota=aquota.group +For journaled quotas (jqfmt=vfsv0 or jqfmt=vfsv1), the mount options +usrjquota=aquota.user and grpjquota=aquota.group are required to tell the +quota system which quota database files to use. When the +.B quota +file system feature is enabled, journaled quotas are used automatically, and +this mount option is ignored. + +.SH "Mount options for ext4" +The ext4 file system is an advanced level of the ext3 file system which +incorporates scalability and reliability enhancements for supporting large +file system. + +The options +.B journal_dev, journal_path, norecovery, noload, data, commit, orlov, +.B oldalloc, [no]user_xattr, [no]acl, bsddf, minixdf, debug, errors, +.B data_err, grpid, bsdgroups, nogrpid, sysvgroups, resgid, resuid, sb, +.B quota, noquota, nouid32, grpquota, usrquota, usrjquota, grpjquota, +.B and jqfmt are backwardly compatible with ext3 or ext2. +.TP +.B journal_checksum | nojournal_checksum +The journal_checksum option enables checksumming of the journal transactions. +This will allow the recovery code in e2fsck and the kernel to detect corruption +in the kernel. It is a compatible change and will be ignored by older kernels. +.TP +.B journal_async_commit +Commit block can be written to disk without waiting for descriptor blocks. If +enabled older kernels cannot mount the device. +This will enable 'journal_checksum' internally. +.TP +.BR barrier=0 " / " barrier=1 " / " barrier " / " nobarrier +These mount options have the same effect as in ext3. The mount options +"barrier" and "nobarrier" are added for consistency with other ext4 mount +options. + +The ext4 file system enables write barriers by default. +.TP +.BI inode_readahead_blks= n +This tuning parameter controls the maximum number of inode table blocks that +ext4's inode table readahead algorithm will pre-read into the buffer cache. +The value must be a power of 2. The default value is 32 blocks. +.TP +.BI stripe= n +Number of file system blocks that mballoc will try to use for allocation size +and alignment. For RAID5/6 systems this should be the number of data disks * +RAID chunk size in file system blocks. +.TP +.B delalloc +Deferring block allocation until write-out time. +.TP +.B nodelalloc +Disable delayed allocation. Blocks are allocated when data is copied from user +to page cache. +.TP +.BI max_batch_time= usec +Maximum amount of time ext4 should wait for additional file system operations to +be batch together with a synchronous write operation. Since a synchronous +write operation is going to force a commit and then a wait for the I/O +complete, it doesn't cost much, and can be a huge throughput win, we wait for a +small amount of time to see if any other transactions can piggyback on the +synchronous write. The algorithm used is designed to automatically tune for +the speed of the disk, by measuring the amount of time (on average) that it +takes to finish committing a transaction. Call this time the "commit time". +If the time that the transaction has been running is less than the commit time, +ext4 will try sleeping for the commit time to see if other operations will join +the transaction. The commit time is capped by the max_batch_time, which +defaults to 15000\ \[mc]s (15\ ms). This optimization can be turned off entirely by +setting max_batch_time to 0. +.TP +.BI min_batch_time= usec +This parameter sets the commit time (as described above) to be at least +min_batch_time. It defaults to zero microseconds. Increasing this parameter +may improve the throughput of multi-threaded, synchronous workloads on very +fast disks, at the cost of increasing latency. +.TP +.BI journal_ioprio= prio +The I/O priority (from 0 to 7, where 0 is the highest priority) which should be +used for I/O operations submitted by kjournald2 during a commit operation. +This defaults to 3, which is a slightly higher priority than the default I/O +priority. +.TP +.B abort +Simulate the effects of calling ext4_abort() for +debugging purposes. This is normally used while +remounting a file system which is already mounted. +.TP +.BR auto_da_alloc | noauto_da_alloc +Many broken applications don't use fsync() when +replacing existing files via patterns such as + +fd = open("foo.new")/write(fd,...)/close(fd)/ rename("foo.new", "foo") + +or worse yet + +fd = open("foo", O_TRUNC)/write(fd,...)/close(fd). + +If auto_da_alloc is enabled, ext4 will detect the replace-via-rename and +replace-via-truncate patterns and force that any delayed allocation blocks are +allocated such that at the next journal commit, in the default data=ordered +mode, the data blocks of the new file are forced to disk before the rename() +operation is committed. This provides roughly the same level of guarantees as +ext3, and avoids the "zero-length" problem that can happen when a system +crashes before the delayed allocation blocks are forced to disk. +.TP +.B noinit_itable +Do not initialize any uninitialized inode table blocks in the background. This +feature may be used by installation CD's so that the install process can +complete as quickly as possible; the inode table initialization process would +then be deferred until the next time the file system is mounted. +.TP +.B init_itable=n +The lazy itable init code will wait n times the number of milliseconds it took +to zero out the previous block group's inode table. This minimizes the impact on +system performance while the file system's inode table is being initialized. +.TP +.BR discard / nodiscard +Controls whether ext4 should issue discard/TRIM commands to the underlying +block device when blocks are freed. This is useful for SSD devices and +sparse/thinly-provisioned LUNs, but it is off by default until sufficient +testing has been done. +.TP +.BR block_validity / noblock_validity +This option enables/disables the in-kernel facility for tracking +file system metadata blocks within internal data structures. This allows multi-\c +block allocator and other routines to quickly locate extents which might +overlap with file system metadata blocks. This option is intended for debugging +purposes and since it negatively affects the performance, it is off by default. +.TP +.BR dioread_lock / dioread_nolock +Controls whether or not ext4 should use the DIO read locking. If the +dioread_nolock option is specified ext4 will allocate uninitialized extent +before buffer write and convert the extent to initialized after IO completes. +This approach allows ext4 code to avoid using inode mutex, which improves +scalability on high speed storages. However this does not work with data +journaling and dioread_nolock option will be ignored with kernel warning. +Note that dioread_nolock code path is only used for extent-based files. +Because of the restrictions this options comprises it is off by default +(e.g.\& dioread_lock). +.TP +.B max_dir_size_kb=n +This limits the size of the directories so that any attempt to expand them +beyond the specified limit in kilobytes will cause an ENOSPC error. This is +useful in memory-constrained environments, where a very large directory can +cause severe performance problems or even provoke the Out Of Memory killer. (For +example, if there is only 512\ MB memory available, a 176\ MB directory may +seriously cramp the system's style.) +.TP +.B i_version +Enable 64-bit inode version support. This option is off by default. +.TP +.B nombcache +This option disables use of mbcache for extended attribute deduplication. On +systems where extended attributes are rarely or never shared between files, +use of mbcache for deduplication adds unnecessary computational overhead. +.TP +.B prjquota +The prjquota mount option enables project quota support on the file system. +You need the quota utilities to actually enable and manage the quota system. +This mount option requires the +.B project +file system feature. + +.SH FILE ATTRIBUTES +The ext2, ext3, and ext4 file systems support setting the following file +attributes on Linux systems using the +.BR chattr (1) +utility: +.sp +.BR a " - append only" +.sp +.BR A " - no atime updates" +.sp +.BR d " - no dump" +.sp +.BR D " - synchronous directory updates" +.sp +.BR i " - immutable" +.sp +.BR S " - synchronous updates" +.sp +.BR u " - undeletable" +.sp +In addition, the ext3 and ext4 file systems support the following flag: +.sp +.BR j " - data journaling" +.sp +Finally, the ext4 file system also supports the following flag: +.sp +.BR e " - extents format" +.sp +For descriptions of these attribute flags, please refer to the +.BR chattr (1) +man page. +.SH KERNEL SUPPORT +This section lists the file system driver (e.g., ext2, ext3, ext4) and +upstream kernel version where a particular file system feature was +supported. Note that in some cases the feature was present in earlier +kernel versions, but there were known, serious bugs. In other cases the +feature may still be considered in an experimental state. Finally, note +that some distributions may have backported features into older kernels; +in particular the kernel versions in certain "enterprise distributions" +can be extremely misleading. +.IP "\fBfiletype\fR" 2in +ext2, 2.2.0 +.IP "\fBsparse_super\fR" 2in +ext2, 2.2.0 +.IP "\fBlarge_file\fR" 2in +ext2, 2.2.0 +.IP "\fBhas_journal\fR" 2in +ext3, 2.4.15 +.IP "\fBext_attr\fR" 2in +ext2/ext3, 2.6.0 +.IP "\fBdir_index\fR" 2in +ext3, 2.6.0 +.IP "\fBresize_inode\fR" 2in +ext3, 2.6.10 (online resizing) +.IP "\fB64bit\fR" 2in +ext4, 2.6.28 +.IP "\fBdir_nlink\fR" 2in +ext4, 2.6.28 +.IP "\fBextent\fR" 2in +ext4, 2.6.28 +.IP "\fBextra_isize\fR" 2in +ext4, 2.6.28 +.IP "\fBflex_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBhuge_file\fR" 2in +ext4, 2.6.28 +.IP "\fBmeta_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBuninit_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBmmp\fR" 2in +ext4, 3.0 +.IP "\fBbigalloc\fR" 2in +ext4, 3.2 +.IP "\fBquota\fR" 2in +ext4, 3.6 +.IP "\fBinline_data\fR" 2in +ext4, 3.8 +.IP "\fBsparse_super2\fR" 2in +ext4, 3.16 +.IP "\fBmetadata_csum\fR" 2in +ext4, 3.18 +.IP "\fBencrypt\fR" 2in +ext4, 4.1 +.IP "\fBmetadata_csum_seed\fR" 2i +ext4, 4.4 +.IP "\fBproject\fR" 2i +ext4, 4.5 +.IP "\fBea_inode\fR" 2i +ext4, 4.13 +.IP "\fBlarge_dir\fR" 2i +ext4, 4.13 +.IP "\fBcasefold\fR" 2i +ext4, 5.2 +.IP "\fBverity\fR" 2i +ext4, 5.4 +.IP "\fBstable_inodes\fR" 2i +ext4, 5.5 +.SH SEE ALSO +.BR mke2fs (8), +.BR mke2fs.conf (5), +.BR e2fsck (8), +.BR dumpe2fs (8), +.BR tune2fs (8), +.BR debugfs (8), +.BR mount (8), +.BR chattr (1) diff --git a/upstream/fedora-40/man5/ext3.5 b/upstream/fedora-40/man5/ext3.5 new file mode 100644 index 00000000..5be4c1d1 --- /dev/null +++ b/upstream/fedora-40/man5/ext3.5 @@ -0,0 +1,815 @@ +.\" -*- nroff -*- +.\" Copyright 1993, 1994, 1995 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH EXT4 5 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +ext2 \- the second extended file system +.br +ext3 \- the third extended file system +.br +ext4 \- the fourth extended file system +.SH DESCRIPTION +The second, third, and fourth extended file systems, or ext2, ext3, and +ext4 as they are commonly known, are Linux file systems that have +historically been the default file system for many Linux distributions. +They are general purpose file systems that have been designed for +extensibility and backwards compatibility. In particular, file systems +previously intended for use with the ext2 and ext3 file systems can be +mounted using the ext4 file system driver, and indeed in many modern +Linux distributions, the ext4 file system driver has been configured +to handle mount requests for ext2 and ext3 file systems. +.SH FILE SYSTEM FEATURES +A file system formatted for ext2, ext3, or ext4 can have some +collection of the following file system feature flags enabled. Some of +these features are not supported by all implementations of the ext2, +ext3, and ext4 file system drivers, depending on Linux kernel version in +use. On other operating systems, such as the GNU/HURD or FreeBSD, only +a very restrictive set of file system features may be supported in their +implementations of ext2. +.TP +.B 64bit +.br +Enables the file system to be larger than 2^32 blocks. This feature is set +automatically, as needed, but it can be useful to specify this feature +explicitly if the file system might need to be resized larger than 2^32 +blocks, even if it was smaller than that threshold when it was +originally created. Note that some older kernels and older versions +of e2fsprogs will not support file systems with this ext4 feature enabled. +.TP +.B bigalloc +.br +This ext4 feature enables clustered block allocation, so that the unit of +allocation is a power of two number of blocks. That is, each bit in the +what had traditionally been known as the block allocation bitmap now +indicates whether a cluster is in use or not, where a cluster is by +default composed of 16 blocks. This feature can decrease the time +spent on doing block allocation and brings smaller fragmentation, especially +for large files. The size can be specified using the +.B mke2fs \-C +option. +.IP +.B Warning: +The bigalloc feature is still under development, and may not be fully +supported with your kernel or may have various bugs. Please see the web +page http://ext4.wiki.kernel.org/index.php/Bigalloc for details. +May clash with delayed allocation (see +.B nodelalloc +mount option). +.IP +This feature requires that the +.B extent +feature be enabled. +.TP +.B casefold +.br +This ext4 feature provides file system level character encoding support +for directories with the casefold (+F) flag enabled. This feature is +name-preserving on the disk, but it allows applications to lookup for a +file in the file system using an encoding equivalent version of the file +name. +.TP +.B dir_index +.br +Use hashed b-trees to speed up name lookups in large directories. This +feature is supported by ext3 and ext4 file systems, and is ignored by +ext2 file systems. +.TP +.B dir_nlink +.br +Normally, ext4 allows an inode to have no more than 65,000 hard links. +This applies to regular files as well as directories, which means that +there can be no more than 64,998 subdirectories in a directory (because +each of the '.' and '..' entries, as well as the directory entry for the +directory in its parent directory counts as a hard link). This feature +lifts this limit by causing ext4 to use a link count of 1 to indicate +that the number of hard links to a directory is not known when the link +count might exceed the maximum count limit. +.TP +.B ea_inode +.br +Normally, a file's extended attributes and associated metadata must fit within +the inode or the inode's associated extended attribute block. This feature +allows the value of each extended attribute to be placed in the data blocks of a +separate inode if necessary, increasing the limit on the size and number of +extended attributes per file. +.TP +.B encrypt +.br +Enables support for file-system level encryption of data blocks and file +names. The inode metadata (timestamps, file size, user/group ownership, +etc.) is +.I not +encrypted. +.IP +This feature is most useful on file systems with multiple users, or +where not all files should be encrypted. In many use cases, especially +on single-user systems, encryption at the block device layer using +dm-crypt may provide much better security. +.TP +.B ext_attr +.br +This feature enables the use of extended attributes. This feature is +supported by ext2, ext3, and ext4. +.TP +.B extent +.br +This ext4 feature allows the mapping of logical block numbers for a +particular inode to physical blocks on the storage device to be stored +using an extent tree, which is a more efficient data structure than the +traditional indirect block scheme used by the ext2 and ext3 file +systems. The use of the extent tree decreases metadata block overhead, +improves file system performance, and decreases the needed to run +.BR e2fsck (8) +on the file system. +(Note: both +.B extent +and +.B extents +are accepted as valid names for this feature for +historical/backwards compatibility reasons.) +.TP +.B extra_isize +.br +This ext4 feature reserves a specific amount of space in each inode for +extended metadata such as nanosecond timestamps and file creation time, +even if the current kernel does not currently need to reserve this much +space. Without this feature, the kernel will reserve the amount of +space for features it currently needs, and the rest may be +consumed by extended attributes. + +For this feature to be useful the inode size must be 256 bytes in size +or larger. +.TP +.B filetype +.br +This feature enables the storage of file type information in directory +entries. This feature is supported by ext2, ext3, and ext4. +.TP +.B flex_bg +.br +This ext4 feature allows the per-block group metadata (allocation +bitmaps +and inode tables) +to be placed anywhere on the storage media. In addition, +.B mke2fs +will place the per-block group metadata together starting at the first +block group of each "flex_bg group". The size of the flex_bg group +can be specified using the +.B \-G +option. +.TP +.B has_journal +.br +Create a journal to ensure file system consistency even across unclean +shutdowns. Setting the file system feature is equivalent to using the +.B \-j +option with +.BR mke2fs " or " tune2fs. +This feature is supported by ext3 and ext4, and ignored by the +ext2 file system driver. +.TP +.B huge_file +.br +This ext4 feature allows files to be larger than 2 terabytes in size. +.TP +.B inline_data +Allow data to be stored in the inode and extended attribute area. +.TP +.B journal_dev +.br +This feature is enabled on the superblock found on an external journal +device. The block size for the external journal must be the same as the +file system which uses it. +.IP +The external journal device can be used by a file system by specifying +the +.B \-J +.BR device= +option to +.BR mke2fs (8) +or +.BR tune2fs(8) . +.TP +.B large_dir +.br +This feature increases the limit on the number of files per directory by +raising the maximum size of directories and, for hashed b-tree directories (see +.BR dir_index ), +the maximum height of the hashed b-tree used to store the directory entries. +.TP +.B large_file +.br +This feature flag is set automatically by modern kernels when a file +larger than 2 gigabytes is created. Very old kernels could not +handle large files, so this feature flag was used to prohibit those +kernels from mounting file systems that they could not understand. +.TP +.B metadata_csum +.br +This ext4 feature enables metadata checksumming. This feature stores +checksums for all of the file system metadata (superblock, group +descriptor blocks, inode and block bitmaps, directories, and +extent tree blocks). The checksum algorithm used for the metadata +blocks is different than the one used for group descriptors with the +.B uninit_bg +feature. These two features are incompatible and +.B metadata_csum +will be used preferentially instead of +.BR uninit_bg . +.TP +.B metadata_csum_seed +.br +This feature allows the file system to store the metadata checksum seed in the +superblock, which allows the administrator to change the UUID of a file system +using the +.B metadata_csum +feature while it is mounted. +.TP +.B meta_bg +.br +This ext4 feature allows file systems to be resized on-line without explicitly +needing to reserve space for growth in the size of the block group +descriptors. This scheme is also used to resize file systems which are +larger than 2^32 blocks. It is not recommended that this feature be set +when a file system is created, since this alternate method of storing +the block group descriptors will slow down the time needed to mount the +file system, and newer kernels can automatically set this feature as +necessary when doing an online resize and no more reserved space is +available in the resize inode. +.TP +.B mmp +.br +This ext4 feature provides multiple mount protection (MMP). MMP helps to +protect the file system from being multiply mounted and is useful in +shared storage environments. +.TP +.B project +.br +This ext4 feature provides project quota support. With this feature, +the project ID of inode will be managed when the file system is mounted. +.TP +.B quota +.br +Create quota inodes (inode #3 for userquota and inode +#4 for group quota) and set them in the superblock. +With this feature, the quotas will be enabled +automatically when the file system is mounted. +.IP +Causes the quota files (i.e., user.quota and +group.quota which existed +in the older quota design) to be hidden inodes. +.TP +.B resize_inode +.br +This file system feature indicates that space has been reserved so that +the block group descriptor table can be extended while resizing a mounted +file system. The online resize operation +is carried out by the kernel, triggered by +.BR resize2fs (8). +By default +.B mke2fs +will attempt to reserve enough space so that the +file system may grow to 1024 times its initial size. This can be changed +using the +.B resize +extended option. +.IP +This feature requires that the +.B sparse_super +or +.B sparse_super2 +feature be enabled. +.TP +.B sparse_super +.br +This file system feature is set on all modern ext2, ext3, and ext4 file +systems. It indicates that backup copies of the superblock and block +group descriptors are present only in a few block groups, not all of +them. +.TP +.B sparse_super2 +.br +This feature indicates that there will only be at most two backup +superblocks and block group descriptors. The block groups used to store +the backup superblock(s) and blockgroup descriptor(s) are stored in the +superblock, but typically, one will be located at the beginning of block +group #1, and one in the last block group in the file system. This +feature is essentially a more extreme version of sparse_super and is +designed to allow a much larger percentage of the disk to have +contiguous blocks available for data files. +.TP +.B stable_inodes +.br +Marks the file system's inode numbers and UUID as stable. +.BR resize2fs (8) +will not allow shrinking a file system with this feature, nor +will +.BR tune2fs (8) +allow changing its UUID. This feature allows the use of specialized encryption +settings that make use of the inode numbers and UUID. Note that the +.B encrypt +feature still needs to be enabled separately. +.B stable_inodes +is a "compat" feature, so old kernels will allow it. +.TP +.B uninit_bg +.br +This ext4 file system feature indicates that the block group descriptors +will be protected using checksums, making it safe for +.BR mke2fs (8) +to create a file system without initializing all of the block groups. +The kernel will keep a high watermark of unused inodes, and initialize +inode tables and blocks lazily. This feature speeds up the time to check +the file system using +.BR e2fsck (8), +and it also speeds up the time required for +.BR mke2fs (8) +to create the file system. +.TP +.B verity +.br +Enables support for verity protected files. Verity files are readonly, +and their data is transparently verified against a Merkle tree hidden +past the end of the file. Using the Merkle tree's root hash, a verity +file can be efficiently authenticated, independent of the file's size. +.IP +This feature is most useful for authenticating important read-only files +on read-write file systems. If the file system itself is read-only, +then using dm-verity to authenticate the entire block device may provide +much better security. +.SH MOUNT OPTIONS +This section describes mount options which are specific to ext2, ext3, +and ext4. Other generic mount options may be used as well; see +.BR mount (8) +for details. +.SH "Mount options for ext2" +The `ext2' file system is the standard Linux file system. +Since Linux 2.5.46, for most mount options the default +is determined by the file system superblock. Set them with +.BR tune2fs (8). +.TP +.BR acl | noacl +Support POSIX Access Control Lists (or not). See the +.BR acl (5) +manual page. +.TP +.BR bsddf | minixdf +Set the behavior for the +.I statfs +system call. The +.B minixdf +behavior is to return in the +.I f_blocks +field the total number of blocks of the file system, while the +.B bsddf +behavior (which is the default) is to subtract the overhead blocks +used by the ext2 file system and not available for file storage. Thus +.sp 1 +% mount /k \-o minixdf; df /k; umount /k +.TS +tab(#); +l2 l2 r2 l2 l2 l +l c r c c l. +File System#1024-blocks#Used#Available#Capacity#Mounted on +/dev/sda6#2630655#86954#2412169#3%#/k +.TE +.sp 1 +% mount /k \-o bsddf; df /k; umount /k +.TS +tab(#); +l2 l2 r2 l2 l2 l +l c r c c l. +File System#1024-blocks#Used#Available#Capacity#Mounted on +/dev/sda6#2543714#13#2412169#0%#/k +.TE +.sp 1 +(Note that this example shows that one can add command line options +to the options given in +.IR /etc/fstab .) +.TP +.BR check=none " or " nocheck +No checking is done at mount time. This is the default. This is fast. +It is wise to invoke +.BR e2fsck (8) +every now and then, e.g.\& at boot time. The non-default behavior is unsupported +(check=normal and check=strict options have been removed). Note that these mount options +don't have to be supported if ext4 kernel driver is used for ext2 and ext3 file systems. +.TP +.B debug +Print debugging info upon each (re)mount. +.TP +.BR errors= { continue | remount-ro | panic } +Define the behavior when an error is encountered. +(Either ignore errors and just mark the file system erroneous and continue, +or remount the file system read-only, or panic and halt the system.) +The default is set in the file system superblock, and can be +changed using +.BR tune2fs (8). +.TP +.BR grpid | bsdgroups " and " nogrpid | sysvgroups +These options define what group id a newly created file gets. +When +.B grpid +is set, it takes the group id of the directory in which it is created; +otherwise (the default) it takes the fsgid of the current process, unless +the directory has the setgid bit set, in which case it takes the gid +from the parent directory, and also gets the setgid bit set +if it is a directory itself. +.TP +.BR grpquota | noquota | quota | usrquota +The usrquota (same as quota) mount option enables user quota support on the +file system. grpquota enables group quotas support. You need the quota utilities +to actually enable and manage the quota system. +.TP +.B nouid32 +Disables 32-bit UIDs and GIDs. This is for interoperability with older +kernels which only store and expect 16-bit values. +.TP +.BR oldalloc " or " orlov +Use old allocator or Orlov allocator for new inodes. Orlov is default. +.TP +\fBresgid=\fP\,\fIn\fP and \fBresuid=\fP\,\fIn\fP +The ext2 file system reserves a certain percentage of the available +space (by default 5%, see +.BR mke2fs (8) +and +.BR tune2fs (8)). +These options determine who can use the reserved blocks. +(Roughly: whoever has the specified uid, or belongs to the specified group.) +.TP +.BI sb= n +Instead of using the normal superblock, use an alternative superblock +specified by +.IR n . +This option is normally used when the primary superblock has been +corrupted. The location of backup superblocks is dependent on the +file system's blocksize, the number of blocks per group, and features +such as +.BR sparse_super . +.IP +Additional backup superblocks can be determined by using the +.B mke2fs +program using the +.B \-n +option to print out where the superblocks exist, supposing +.B mke2fs +is supplied with arguments that are consistent with the file system's layout +(e.g. blocksize, blocks per group, +.BR sparse_super , +etc.). +.IP +The block number here uses 1\ k units. Thus, if you want to use logical +block 32768 on a file system with 4\ k blocks, use "sb=131072". +.TP +.BR user_xattr | nouser_xattr +Support "user." extended attributes (or not). + + +.SH "Mount options for ext3" +The ext3 file system is a version of the ext2 file system which has been +enhanced with journaling. It supports the same options as ext2 as +well as the following additions: +.TP +.BR journal_dev=devnum / journal_path=path +When the external journal device's major/minor numbers +have changed, these options allow the user to specify +the new journal location. The journal device is +identified either through its new major/minor numbers encoded +in devnum, or via a path to the device. +.TP +.BR norecovery / noload +Don't load the journal on mounting. Note that +if the file system was not unmounted cleanly, +skipping the journal replay will lead to the +file system containing inconsistencies that can +lead to any number of problems. +.TP +.BR data= { journal | ordered | writeback } +Specifies the journaling mode for file data. Metadata is always journaled. +To use modes other than +.B ordered +on the root file system, pass the mode to the kernel as boot parameter, e.g.\& +.IR rootflags=data=journal . +.RS +.TP +.B journal +All data is committed into the journal prior to being written into the +main file system. +.TP +.B ordered +This is the default mode. All data is forced directly out to the main file +system prior to its metadata being committed to the journal. +.TP +.B writeback +Data ordering is not preserved \(en data may be written into the main +file system after its metadata has been committed to the journal. +This is rumoured to be the highest-throughput option. It guarantees +internal file system integrity, however it can allow old data to appear +in files after a crash and journal recovery. +.RE +.TP +.B data_err=ignore +Just print an error message if an error occurs in a file data buffer in +ordered mode. +.TP +.B data_err=abort +Abort the journal if an error occurs in a file data buffer in ordered mode. +.TP +.BR barrier=0 " / " barrier=1 " +This disables / enables the use of write barriers in the jbd code. barrier=0 +disables, barrier=1 enables (default). This also requires an IO stack which can +support barriers, and if jbd gets an error on a barrier write, it will disable +barriers again with a warning. Write barriers enforce proper on-disk ordering +of journal commits, making volatile disk write caches safe to use, at some +performance penalty. If your disks are battery-backed in one way or another, +disabling barriers may safely improve performance. +.TP +.BI commit= nrsec +Start a journal commit every +.I nrsec +seconds. The default value is 5 seconds. Zero means default. +.TP +.B user_xattr +Enable Extended User Attributes. See the +.BR attr (5) +manual page. +.TP +.BR jqfmt= { vfsold | vfsv0 | vfsv1 } +Apart from the old quota system (as in ext2, jqfmt=vfsold aka version 1 quota) +ext3 also supports journaled quotas (version 2 quota). jqfmt=vfsv0 or +jqfmt=vfsv1 enables journaled quotas. Journaled quotas have the advantage that +even after a crash no quota check is required. When the +.B quota +file system feature is enabled, journaled quotas are used automatically, and +this mount option is ignored. +.TP +.BR usrjquota=aquota.user | grpjquota=aquota.group +For journaled quotas (jqfmt=vfsv0 or jqfmt=vfsv1), the mount options +usrjquota=aquota.user and grpjquota=aquota.group are required to tell the +quota system which quota database files to use. When the +.B quota +file system feature is enabled, journaled quotas are used automatically, and +this mount option is ignored. + +.SH "Mount options for ext4" +The ext4 file system is an advanced level of the ext3 file system which +incorporates scalability and reliability enhancements for supporting large +file system. + +The options +.B journal_dev, journal_path, norecovery, noload, data, commit, orlov, +.B oldalloc, [no]user_xattr, [no]acl, bsddf, minixdf, debug, errors, +.B data_err, grpid, bsdgroups, nogrpid, sysvgroups, resgid, resuid, sb, +.B quota, noquota, nouid32, grpquota, usrquota, usrjquota, grpjquota, +.B and jqfmt are backwardly compatible with ext3 or ext2. +.TP +.B journal_checksum | nojournal_checksum +The journal_checksum option enables checksumming of the journal transactions. +This will allow the recovery code in e2fsck and the kernel to detect corruption +in the kernel. It is a compatible change and will be ignored by older kernels. +.TP +.B journal_async_commit +Commit block can be written to disk without waiting for descriptor blocks. If +enabled older kernels cannot mount the device. +This will enable 'journal_checksum' internally. +.TP +.BR barrier=0 " / " barrier=1 " / " barrier " / " nobarrier +These mount options have the same effect as in ext3. The mount options +"barrier" and "nobarrier" are added for consistency with other ext4 mount +options. + +The ext4 file system enables write barriers by default. +.TP +.BI inode_readahead_blks= n +This tuning parameter controls the maximum number of inode table blocks that +ext4's inode table readahead algorithm will pre-read into the buffer cache. +The value must be a power of 2. The default value is 32 blocks. +.TP +.BI stripe= n +Number of file system blocks that mballoc will try to use for allocation size +and alignment. For RAID5/6 systems this should be the number of data disks * +RAID chunk size in file system blocks. +.TP +.B delalloc +Deferring block allocation until write-out time. +.TP +.B nodelalloc +Disable delayed allocation. Blocks are allocated when data is copied from user +to page cache. +.TP +.BI max_batch_time= usec +Maximum amount of time ext4 should wait for additional file system operations to +be batch together with a synchronous write operation. Since a synchronous +write operation is going to force a commit and then a wait for the I/O +complete, it doesn't cost much, and can be a huge throughput win, we wait for a +small amount of time to see if any other transactions can piggyback on the +synchronous write. The algorithm used is designed to automatically tune for +the speed of the disk, by measuring the amount of time (on average) that it +takes to finish committing a transaction. Call this time the "commit time". +If the time that the transaction has been running is less than the commit time, +ext4 will try sleeping for the commit time to see if other operations will join +the transaction. The commit time is capped by the max_batch_time, which +defaults to 15000\ \[mc]s (15\ ms). This optimization can be turned off entirely by +setting max_batch_time to 0. +.TP +.BI min_batch_time= usec +This parameter sets the commit time (as described above) to be at least +min_batch_time. It defaults to zero microseconds. Increasing this parameter +may improve the throughput of multi-threaded, synchronous workloads on very +fast disks, at the cost of increasing latency. +.TP +.BI journal_ioprio= prio +The I/O priority (from 0 to 7, where 0 is the highest priority) which should be +used for I/O operations submitted by kjournald2 during a commit operation. +This defaults to 3, which is a slightly higher priority than the default I/O +priority. +.TP +.B abort +Simulate the effects of calling ext4_abort() for +debugging purposes. This is normally used while +remounting a file system which is already mounted. +.TP +.BR auto_da_alloc | noauto_da_alloc +Many broken applications don't use fsync() when +replacing existing files via patterns such as + +fd = open("foo.new")/write(fd,...)/close(fd)/ rename("foo.new", "foo") + +or worse yet + +fd = open("foo", O_TRUNC)/write(fd,...)/close(fd). + +If auto_da_alloc is enabled, ext4 will detect the replace-via-rename and +replace-via-truncate patterns and force that any delayed allocation blocks are +allocated such that at the next journal commit, in the default data=ordered +mode, the data blocks of the new file are forced to disk before the rename() +operation is committed. This provides roughly the same level of guarantees as +ext3, and avoids the "zero-length" problem that can happen when a system +crashes before the delayed allocation blocks are forced to disk. +.TP +.B noinit_itable +Do not initialize any uninitialized inode table blocks in the background. This +feature may be used by installation CD's so that the install process can +complete as quickly as possible; the inode table initialization process would +then be deferred until the next time the file system is mounted. +.TP +.B init_itable=n +The lazy itable init code will wait n times the number of milliseconds it took +to zero out the previous block group's inode table. This minimizes the impact on +system performance while the file system's inode table is being initialized. +.TP +.BR discard / nodiscard +Controls whether ext4 should issue discard/TRIM commands to the underlying +block device when blocks are freed. This is useful for SSD devices and +sparse/thinly-provisioned LUNs, but it is off by default until sufficient +testing has been done. +.TP +.BR block_validity / noblock_validity +This option enables/disables the in-kernel facility for tracking +file system metadata blocks within internal data structures. This allows multi-\c +block allocator and other routines to quickly locate extents which might +overlap with file system metadata blocks. This option is intended for debugging +purposes and since it negatively affects the performance, it is off by default. +.TP +.BR dioread_lock / dioread_nolock +Controls whether or not ext4 should use the DIO read locking. If the +dioread_nolock option is specified ext4 will allocate uninitialized extent +before buffer write and convert the extent to initialized after IO completes. +This approach allows ext4 code to avoid using inode mutex, which improves +scalability on high speed storages. However this does not work with data +journaling and dioread_nolock option will be ignored with kernel warning. +Note that dioread_nolock code path is only used for extent-based files. +Because of the restrictions this options comprises it is off by default +(e.g.\& dioread_lock). +.TP +.B max_dir_size_kb=n +This limits the size of the directories so that any attempt to expand them +beyond the specified limit in kilobytes will cause an ENOSPC error. This is +useful in memory-constrained environments, where a very large directory can +cause severe performance problems or even provoke the Out Of Memory killer. (For +example, if there is only 512\ MB memory available, a 176\ MB directory may +seriously cramp the system's style.) +.TP +.B i_version +Enable 64-bit inode version support. This option is off by default. +.TP +.B nombcache +This option disables use of mbcache for extended attribute deduplication. On +systems where extended attributes are rarely or never shared between files, +use of mbcache for deduplication adds unnecessary computational overhead. +.TP +.B prjquota +The prjquota mount option enables project quota support on the file system. +You need the quota utilities to actually enable and manage the quota system. +This mount option requires the +.B project +file system feature. + +.SH FILE ATTRIBUTES +The ext2, ext3, and ext4 file systems support setting the following file +attributes on Linux systems using the +.BR chattr (1) +utility: +.sp +.BR a " - append only" +.sp +.BR A " - no atime updates" +.sp +.BR d " - no dump" +.sp +.BR D " - synchronous directory updates" +.sp +.BR i " - immutable" +.sp +.BR S " - synchronous updates" +.sp +.BR u " - undeletable" +.sp +In addition, the ext3 and ext4 file systems support the following flag: +.sp +.BR j " - data journaling" +.sp +Finally, the ext4 file system also supports the following flag: +.sp +.BR e " - extents format" +.sp +For descriptions of these attribute flags, please refer to the +.BR chattr (1) +man page. +.SH KERNEL SUPPORT +This section lists the file system driver (e.g., ext2, ext3, ext4) and +upstream kernel version where a particular file system feature was +supported. Note that in some cases the feature was present in earlier +kernel versions, but there were known, serious bugs. In other cases the +feature may still be considered in an experimental state. Finally, note +that some distributions may have backported features into older kernels; +in particular the kernel versions in certain "enterprise distributions" +can be extremely misleading. +.IP "\fBfiletype\fR" 2in +ext2, 2.2.0 +.IP "\fBsparse_super\fR" 2in +ext2, 2.2.0 +.IP "\fBlarge_file\fR" 2in +ext2, 2.2.0 +.IP "\fBhas_journal\fR" 2in +ext3, 2.4.15 +.IP "\fBext_attr\fR" 2in +ext2/ext3, 2.6.0 +.IP "\fBdir_index\fR" 2in +ext3, 2.6.0 +.IP "\fBresize_inode\fR" 2in +ext3, 2.6.10 (online resizing) +.IP "\fB64bit\fR" 2in +ext4, 2.6.28 +.IP "\fBdir_nlink\fR" 2in +ext4, 2.6.28 +.IP "\fBextent\fR" 2in +ext4, 2.6.28 +.IP "\fBextra_isize\fR" 2in +ext4, 2.6.28 +.IP "\fBflex_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBhuge_file\fR" 2in +ext4, 2.6.28 +.IP "\fBmeta_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBuninit_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBmmp\fR" 2in +ext4, 3.0 +.IP "\fBbigalloc\fR" 2in +ext4, 3.2 +.IP "\fBquota\fR" 2in +ext4, 3.6 +.IP "\fBinline_data\fR" 2in +ext4, 3.8 +.IP "\fBsparse_super2\fR" 2in +ext4, 3.16 +.IP "\fBmetadata_csum\fR" 2in +ext4, 3.18 +.IP "\fBencrypt\fR" 2in +ext4, 4.1 +.IP "\fBmetadata_csum_seed\fR" 2i +ext4, 4.4 +.IP "\fBproject\fR" 2i +ext4, 4.5 +.IP "\fBea_inode\fR" 2i +ext4, 4.13 +.IP "\fBlarge_dir\fR" 2i +ext4, 4.13 +.IP "\fBcasefold\fR" 2i +ext4, 5.2 +.IP "\fBverity\fR" 2i +ext4, 5.4 +.IP "\fBstable_inodes\fR" 2i +ext4, 5.5 +.SH SEE ALSO +.BR mke2fs (8), +.BR mke2fs.conf (5), +.BR e2fsck (8), +.BR dumpe2fs (8), +.BR tune2fs (8), +.BR debugfs (8), +.BR mount (8), +.BR chattr (1) diff --git a/upstream/fedora-40/man5/ext4.5 b/upstream/fedora-40/man5/ext4.5 new file mode 100644 index 00000000..5be4c1d1 --- /dev/null +++ b/upstream/fedora-40/man5/ext4.5 @@ -0,0 +1,815 @@ +.\" -*- nroff -*- +.\" Copyright 1993, 1994, 1995 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH EXT4 5 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +ext2 \- the second extended file system +.br +ext3 \- the third extended file system +.br +ext4 \- the fourth extended file system +.SH DESCRIPTION +The second, third, and fourth extended file systems, or ext2, ext3, and +ext4 as they are commonly known, are Linux file systems that have +historically been the default file system for many Linux distributions. +They are general purpose file systems that have been designed for +extensibility and backwards compatibility. In particular, file systems +previously intended for use with the ext2 and ext3 file systems can be +mounted using the ext4 file system driver, and indeed in many modern +Linux distributions, the ext4 file system driver has been configured +to handle mount requests for ext2 and ext3 file systems. +.SH FILE SYSTEM FEATURES +A file system formatted for ext2, ext3, or ext4 can have some +collection of the following file system feature flags enabled. Some of +these features are not supported by all implementations of the ext2, +ext3, and ext4 file system drivers, depending on Linux kernel version in +use. On other operating systems, such as the GNU/HURD or FreeBSD, only +a very restrictive set of file system features may be supported in their +implementations of ext2. +.TP +.B 64bit +.br +Enables the file system to be larger than 2^32 blocks. This feature is set +automatically, as needed, but it can be useful to specify this feature +explicitly if the file system might need to be resized larger than 2^32 +blocks, even if it was smaller than that threshold when it was +originally created. Note that some older kernels and older versions +of e2fsprogs will not support file systems with this ext4 feature enabled. +.TP +.B bigalloc +.br +This ext4 feature enables clustered block allocation, so that the unit of +allocation is a power of two number of blocks. That is, each bit in the +what had traditionally been known as the block allocation bitmap now +indicates whether a cluster is in use or not, where a cluster is by +default composed of 16 blocks. This feature can decrease the time +spent on doing block allocation and brings smaller fragmentation, especially +for large files. The size can be specified using the +.B mke2fs \-C +option. +.IP +.B Warning: +The bigalloc feature is still under development, and may not be fully +supported with your kernel or may have various bugs. Please see the web +page http://ext4.wiki.kernel.org/index.php/Bigalloc for details. +May clash with delayed allocation (see +.B nodelalloc +mount option). +.IP +This feature requires that the +.B extent +feature be enabled. +.TP +.B casefold +.br +This ext4 feature provides file system level character encoding support +for directories with the casefold (+F) flag enabled. This feature is +name-preserving on the disk, but it allows applications to lookup for a +file in the file system using an encoding equivalent version of the file +name. +.TP +.B dir_index +.br +Use hashed b-trees to speed up name lookups in large directories. This +feature is supported by ext3 and ext4 file systems, and is ignored by +ext2 file systems. +.TP +.B dir_nlink +.br +Normally, ext4 allows an inode to have no more than 65,000 hard links. +This applies to regular files as well as directories, which means that +there can be no more than 64,998 subdirectories in a directory (because +each of the '.' and '..' entries, as well as the directory entry for the +directory in its parent directory counts as a hard link). This feature +lifts this limit by causing ext4 to use a link count of 1 to indicate +that the number of hard links to a directory is not known when the link +count might exceed the maximum count limit. +.TP +.B ea_inode +.br +Normally, a file's extended attributes and associated metadata must fit within +the inode or the inode's associated extended attribute block. This feature +allows the value of each extended attribute to be placed in the data blocks of a +separate inode if necessary, increasing the limit on the size and number of +extended attributes per file. +.TP +.B encrypt +.br +Enables support for file-system level encryption of data blocks and file +names. The inode metadata (timestamps, file size, user/group ownership, +etc.) is +.I not +encrypted. +.IP +This feature is most useful on file systems with multiple users, or +where not all files should be encrypted. In many use cases, especially +on single-user systems, encryption at the block device layer using +dm-crypt may provide much better security. +.TP +.B ext_attr +.br +This feature enables the use of extended attributes. This feature is +supported by ext2, ext3, and ext4. +.TP +.B extent +.br +This ext4 feature allows the mapping of logical block numbers for a +particular inode to physical blocks on the storage device to be stored +using an extent tree, which is a more efficient data structure than the +traditional indirect block scheme used by the ext2 and ext3 file +systems. The use of the extent tree decreases metadata block overhead, +improves file system performance, and decreases the needed to run +.BR e2fsck (8) +on the file system. +(Note: both +.B extent +and +.B extents +are accepted as valid names for this feature for +historical/backwards compatibility reasons.) +.TP +.B extra_isize +.br +This ext4 feature reserves a specific amount of space in each inode for +extended metadata such as nanosecond timestamps and file creation time, +even if the current kernel does not currently need to reserve this much +space. Without this feature, the kernel will reserve the amount of +space for features it currently needs, and the rest may be +consumed by extended attributes. + +For this feature to be useful the inode size must be 256 bytes in size +or larger. +.TP +.B filetype +.br +This feature enables the storage of file type information in directory +entries. This feature is supported by ext2, ext3, and ext4. +.TP +.B flex_bg +.br +This ext4 feature allows the per-block group metadata (allocation +bitmaps +and inode tables) +to be placed anywhere on the storage media. In addition, +.B mke2fs +will place the per-block group metadata together starting at the first +block group of each "flex_bg group". The size of the flex_bg group +can be specified using the +.B \-G +option. +.TP +.B has_journal +.br +Create a journal to ensure file system consistency even across unclean +shutdowns. Setting the file system feature is equivalent to using the +.B \-j +option with +.BR mke2fs " or " tune2fs. +This feature is supported by ext3 and ext4, and ignored by the +ext2 file system driver. +.TP +.B huge_file +.br +This ext4 feature allows files to be larger than 2 terabytes in size. +.TP +.B inline_data +Allow data to be stored in the inode and extended attribute area. +.TP +.B journal_dev +.br +This feature is enabled on the superblock found on an external journal +device. The block size for the external journal must be the same as the +file system which uses it. +.IP +The external journal device can be used by a file system by specifying +the +.B \-J +.BR device= +option to +.BR mke2fs (8) +or +.BR tune2fs(8) . +.TP +.B large_dir +.br +This feature increases the limit on the number of files per directory by +raising the maximum size of directories and, for hashed b-tree directories (see +.BR dir_index ), +the maximum height of the hashed b-tree used to store the directory entries. +.TP +.B large_file +.br +This feature flag is set automatically by modern kernels when a file +larger than 2 gigabytes is created. Very old kernels could not +handle large files, so this feature flag was used to prohibit those +kernels from mounting file systems that they could not understand. +.TP +.B metadata_csum +.br +This ext4 feature enables metadata checksumming. This feature stores +checksums for all of the file system metadata (superblock, group +descriptor blocks, inode and block bitmaps, directories, and +extent tree blocks). The checksum algorithm used for the metadata +blocks is different than the one used for group descriptors with the +.B uninit_bg +feature. These two features are incompatible and +.B metadata_csum +will be used preferentially instead of +.BR uninit_bg . +.TP +.B metadata_csum_seed +.br +This feature allows the file system to store the metadata checksum seed in the +superblock, which allows the administrator to change the UUID of a file system +using the +.B metadata_csum +feature while it is mounted. +.TP +.B meta_bg +.br +This ext4 feature allows file systems to be resized on-line without explicitly +needing to reserve space for growth in the size of the block group +descriptors. This scheme is also used to resize file systems which are +larger than 2^32 blocks. It is not recommended that this feature be set +when a file system is created, since this alternate method of storing +the block group descriptors will slow down the time needed to mount the +file system, and newer kernels can automatically set this feature as +necessary when doing an online resize and no more reserved space is +available in the resize inode. +.TP +.B mmp +.br +This ext4 feature provides multiple mount protection (MMP). MMP helps to +protect the file system from being multiply mounted and is useful in +shared storage environments. +.TP +.B project +.br +This ext4 feature provides project quota support. With this feature, +the project ID of inode will be managed when the file system is mounted. +.TP +.B quota +.br +Create quota inodes (inode #3 for userquota and inode +#4 for group quota) and set them in the superblock. +With this feature, the quotas will be enabled +automatically when the file system is mounted. +.IP +Causes the quota files (i.e., user.quota and +group.quota which existed +in the older quota design) to be hidden inodes. +.TP +.B resize_inode +.br +This file system feature indicates that space has been reserved so that +the block group descriptor table can be extended while resizing a mounted +file system. The online resize operation +is carried out by the kernel, triggered by +.BR resize2fs (8). +By default +.B mke2fs +will attempt to reserve enough space so that the +file system may grow to 1024 times its initial size. This can be changed +using the +.B resize +extended option. +.IP +This feature requires that the +.B sparse_super +or +.B sparse_super2 +feature be enabled. +.TP +.B sparse_super +.br +This file system feature is set on all modern ext2, ext3, and ext4 file +systems. It indicates that backup copies of the superblock and block +group descriptors are present only in a few block groups, not all of +them. +.TP +.B sparse_super2 +.br +This feature indicates that there will only be at most two backup +superblocks and block group descriptors. The block groups used to store +the backup superblock(s) and blockgroup descriptor(s) are stored in the +superblock, but typically, one will be located at the beginning of block +group #1, and one in the last block group in the file system. This +feature is essentially a more extreme version of sparse_super and is +designed to allow a much larger percentage of the disk to have +contiguous blocks available for data files. +.TP +.B stable_inodes +.br +Marks the file system's inode numbers and UUID as stable. +.BR resize2fs (8) +will not allow shrinking a file system with this feature, nor +will +.BR tune2fs (8) +allow changing its UUID. This feature allows the use of specialized encryption +settings that make use of the inode numbers and UUID. Note that the +.B encrypt +feature still needs to be enabled separately. +.B stable_inodes +is a "compat" feature, so old kernels will allow it. +.TP +.B uninit_bg +.br +This ext4 file system feature indicates that the block group descriptors +will be protected using checksums, making it safe for +.BR mke2fs (8) +to create a file system without initializing all of the block groups. +The kernel will keep a high watermark of unused inodes, and initialize +inode tables and blocks lazily. This feature speeds up the time to check +the file system using +.BR e2fsck (8), +and it also speeds up the time required for +.BR mke2fs (8) +to create the file system. +.TP +.B verity +.br +Enables support for verity protected files. Verity files are readonly, +and their data is transparently verified against a Merkle tree hidden +past the end of the file. Using the Merkle tree's root hash, a verity +file can be efficiently authenticated, independent of the file's size. +.IP +This feature is most useful for authenticating important read-only files +on read-write file systems. If the file system itself is read-only, +then using dm-verity to authenticate the entire block device may provide +much better security. +.SH MOUNT OPTIONS +This section describes mount options which are specific to ext2, ext3, +and ext4. Other generic mount options may be used as well; see +.BR mount (8) +for details. +.SH "Mount options for ext2" +The `ext2' file system is the standard Linux file system. +Since Linux 2.5.46, for most mount options the default +is determined by the file system superblock. Set them with +.BR tune2fs (8). +.TP +.BR acl | noacl +Support POSIX Access Control Lists (or not). See the +.BR acl (5) +manual page. +.TP +.BR bsddf | minixdf +Set the behavior for the +.I statfs +system call. The +.B minixdf +behavior is to return in the +.I f_blocks +field the total number of blocks of the file system, while the +.B bsddf +behavior (which is the default) is to subtract the overhead blocks +used by the ext2 file system and not available for file storage. Thus +.sp 1 +% mount /k \-o minixdf; df /k; umount /k +.TS +tab(#); +l2 l2 r2 l2 l2 l +l c r c c l. +File System#1024-blocks#Used#Available#Capacity#Mounted on +/dev/sda6#2630655#86954#2412169#3%#/k +.TE +.sp 1 +% mount /k \-o bsddf; df /k; umount /k +.TS +tab(#); +l2 l2 r2 l2 l2 l +l c r c c l. +File System#1024-blocks#Used#Available#Capacity#Mounted on +/dev/sda6#2543714#13#2412169#0%#/k +.TE +.sp 1 +(Note that this example shows that one can add command line options +to the options given in +.IR /etc/fstab .) +.TP +.BR check=none " or " nocheck +No checking is done at mount time. This is the default. This is fast. +It is wise to invoke +.BR e2fsck (8) +every now and then, e.g.\& at boot time. The non-default behavior is unsupported +(check=normal and check=strict options have been removed). Note that these mount options +don't have to be supported if ext4 kernel driver is used for ext2 and ext3 file systems. +.TP +.B debug +Print debugging info upon each (re)mount. +.TP +.BR errors= { continue | remount-ro | panic } +Define the behavior when an error is encountered. +(Either ignore errors and just mark the file system erroneous and continue, +or remount the file system read-only, or panic and halt the system.) +The default is set in the file system superblock, and can be +changed using +.BR tune2fs (8). +.TP +.BR grpid | bsdgroups " and " nogrpid | sysvgroups +These options define what group id a newly created file gets. +When +.B grpid +is set, it takes the group id of the directory in which it is created; +otherwise (the default) it takes the fsgid of the current process, unless +the directory has the setgid bit set, in which case it takes the gid +from the parent directory, and also gets the setgid bit set +if it is a directory itself. +.TP +.BR grpquota | noquota | quota | usrquota +The usrquota (same as quota) mount option enables user quota support on the +file system. grpquota enables group quotas support. You need the quota utilities +to actually enable and manage the quota system. +.TP +.B nouid32 +Disables 32-bit UIDs and GIDs. This is for interoperability with older +kernels which only store and expect 16-bit values. +.TP +.BR oldalloc " or " orlov +Use old allocator or Orlov allocator for new inodes. Orlov is default. +.TP +\fBresgid=\fP\,\fIn\fP and \fBresuid=\fP\,\fIn\fP +The ext2 file system reserves a certain percentage of the available +space (by default 5%, see +.BR mke2fs (8) +and +.BR tune2fs (8)). +These options determine who can use the reserved blocks. +(Roughly: whoever has the specified uid, or belongs to the specified group.) +.TP +.BI sb= n +Instead of using the normal superblock, use an alternative superblock +specified by +.IR n . +This option is normally used when the primary superblock has been +corrupted. The location of backup superblocks is dependent on the +file system's blocksize, the number of blocks per group, and features +such as +.BR sparse_super . +.IP +Additional backup superblocks can be determined by using the +.B mke2fs +program using the +.B \-n +option to print out where the superblocks exist, supposing +.B mke2fs +is supplied with arguments that are consistent with the file system's layout +(e.g. blocksize, blocks per group, +.BR sparse_super , +etc.). +.IP +The block number here uses 1\ k units. Thus, if you want to use logical +block 32768 on a file system with 4\ k blocks, use "sb=131072". +.TP +.BR user_xattr | nouser_xattr +Support "user." extended attributes (or not). + + +.SH "Mount options for ext3" +The ext3 file system is a version of the ext2 file system which has been +enhanced with journaling. It supports the same options as ext2 as +well as the following additions: +.TP +.BR journal_dev=devnum / journal_path=path +When the external journal device's major/minor numbers +have changed, these options allow the user to specify +the new journal location. The journal device is +identified either through its new major/minor numbers encoded +in devnum, or via a path to the device. +.TP +.BR norecovery / noload +Don't load the journal on mounting. Note that +if the file system was not unmounted cleanly, +skipping the journal replay will lead to the +file system containing inconsistencies that can +lead to any number of problems. +.TP +.BR data= { journal | ordered | writeback } +Specifies the journaling mode for file data. Metadata is always journaled. +To use modes other than +.B ordered +on the root file system, pass the mode to the kernel as boot parameter, e.g.\& +.IR rootflags=data=journal . +.RS +.TP +.B journal +All data is committed into the journal prior to being written into the +main file system. +.TP +.B ordered +This is the default mode. All data is forced directly out to the main file +system prior to its metadata being committed to the journal. +.TP +.B writeback +Data ordering is not preserved \(en data may be written into the main +file system after its metadata has been committed to the journal. +This is rumoured to be the highest-throughput option. It guarantees +internal file system integrity, however it can allow old data to appear +in files after a crash and journal recovery. +.RE +.TP +.B data_err=ignore +Just print an error message if an error occurs in a file data buffer in +ordered mode. +.TP +.B data_err=abort +Abort the journal if an error occurs in a file data buffer in ordered mode. +.TP +.BR barrier=0 " / " barrier=1 " +This disables / enables the use of write barriers in the jbd code. barrier=0 +disables, barrier=1 enables (default). This also requires an IO stack which can +support barriers, and if jbd gets an error on a barrier write, it will disable +barriers again with a warning. Write barriers enforce proper on-disk ordering +of journal commits, making volatile disk write caches safe to use, at some +performance penalty. If your disks are battery-backed in one way or another, +disabling barriers may safely improve performance. +.TP +.BI commit= nrsec +Start a journal commit every +.I nrsec +seconds. The default value is 5 seconds. Zero means default. +.TP +.B user_xattr +Enable Extended User Attributes. See the +.BR attr (5) +manual page. +.TP +.BR jqfmt= { vfsold | vfsv0 | vfsv1 } +Apart from the old quota system (as in ext2, jqfmt=vfsold aka version 1 quota) +ext3 also supports journaled quotas (version 2 quota). jqfmt=vfsv0 or +jqfmt=vfsv1 enables journaled quotas. Journaled quotas have the advantage that +even after a crash no quota check is required. When the +.B quota +file system feature is enabled, journaled quotas are used automatically, and +this mount option is ignored. +.TP +.BR usrjquota=aquota.user | grpjquota=aquota.group +For journaled quotas (jqfmt=vfsv0 or jqfmt=vfsv1), the mount options +usrjquota=aquota.user and grpjquota=aquota.group are required to tell the +quota system which quota database files to use. When the +.B quota +file system feature is enabled, journaled quotas are used automatically, and +this mount option is ignored. + +.SH "Mount options for ext4" +The ext4 file system is an advanced level of the ext3 file system which +incorporates scalability and reliability enhancements for supporting large +file system. + +The options +.B journal_dev, journal_path, norecovery, noload, data, commit, orlov, +.B oldalloc, [no]user_xattr, [no]acl, bsddf, minixdf, debug, errors, +.B data_err, grpid, bsdgroups, nogrpid, sysvgroups, resgid, resuid, sb, +.B quota, noquota, nouid32, grpquota, usrquota, usrjquota, grpjquota, +.B and jqfmt are backwardly compatible with ext3 or ext2. +.TP +.B journal_checksum | nojournal_checksum +The journal_checksum option enables checksumming of the journal transactions. +This will allow the recovery code in e2fsck and the kernel to detect corruption +in the kernel. It is a compatible change and will be ignored by older kernels. +.TP +.B journal_async_commit +Commit block can be written to disk without waiting for descriptor blocks. If +enabled older kernels cannot mount the device. +This will enable 'journal_checksum' internally. +.TP +.BR barrier=0 " / " barrier=1 " / " barrier " / " nobarrier +These mount options have the same effect as in ext3. The mount options +"barrier" and "nobarrier" are added for consistency with other ext4 mount +options. + +The ext4 file system enables write barriers by default. +.TP +.BI inode_readahead_blks= n +This tuning parameter controls the maximum number of inode table blocks that +ext4's inode table readahead algorithm will pre-read into the buffer cache. +The value must be a power of 2. The default value is 32 blocks. +.TP +.BI stripe= n +Number of file system blocks that mballoc will try to use for allocation size +and alignment. For RAID5/6 systems this should be the number of data disks * +RAID chunk size in file system blocks. +.TP +.B delalloc +Deferring block allocation until write-out time. +.TP +.B nodelalloc +Disable delayed allocation. Blocks are allocated when data is copied from user +to page cache. +.TP +.BI max_batch_time= usec +Maximum amount of time ext4 should wait for additional file system operations to +be batch together with a synchronous write operation. Since a synchronous +write operation is going to force a commit and then a wait for the I/O +complete, it doesn't cost much, and can be a huge throughput win, we wait for a +small amount of time to see if any other transactions can piggyback on the +synchronous write. The algorithm used is designed to automatically tune for +the speed of the disk, by measuring the amount of time (on average) that it +takes to finish committing a transaction. Call this time the "commit time". +If the time that the transaction has been running is less than the commit time, +ext4 will try sleeping for the commit time to see if other operations will join +the transaction. The commit time is capped by the max_batch_time, which +defaults to 15000\ \[mc]s (15\ ms). This optimization can be turned off entirely by +setting max_batch_time to 0. +.TP +.BI min_batch_time= usec +This parameter sets the commit time (as described above) to be at least +min_batch_time. It defaults to zero microseconds. Increasing this parameter +may improve the throughput of multi-threaded, synchronous workloads on very +fast disks, at the cost of increasing latency. +.TP +.BI journal_ioprio= prio +The I/O priority (from 0 to 7, where 0 is the highest priority) which should be +used for I/O operations submitted by kjournald2 during a commit operation. +This defaults to 3, which is a slightly higher priority than the default I/O +priority. +.TP +.B abort +Simulate the effects of calling ext4_abort() for +debugging purposes. This is normally used while +remounting a file system which is already mounted. +.TP +.BR auto_da_alloc | noauto_da_alloc +Many broken applications don't use fsync() when +replacing existing files via patterns such as + +fd = open("foo.new")/write(fd,...)/close(fd)/ rename("foo.new", "foo") + +or worse yet + +fd = open("foo", O_TRUNC)/write(fd,...)/close(fd). + +If auto_da_alloc is enabled, ext4 will detect the replace-via-rename and +replace-via-truncate patterns and force that any delayed allocation blocks are +allocated such that at the next journal commit, in the default data=ordered +mode, the data blocks of the new file are forced to disk before the rename() +operation is committed. This provides roughly the same level of guarantees as +ext3, and avoids the "zero-length" problem that can happen when a system +crashes before the delayed allocation blocks are forced to disk. +.TP +.B noinit_itable +Do not initialize any uninitialized inode table blocks in the background. This +feature may be used by installation CD's so that the install process can +complete as quickly as possible; the inode table initialization process would +then be deferred until the next time the file system is mounted. +.TP +.B init_itable=n +The lazy itable init code will wait n times the number of milliseconds it took +to zero out the previous block group's inode table. This minimizes the impact on +system performance while the file system's inode table is being initialized. +.TP +.BR discard / nodiscard +Controls whether ext4 should issue discard/TRIM commands to the underlying +block device when blocks are freed. This is useful for SSD devices and +sparse/thinly-provisioned LUNs, but it is off by default until sufficient +testing has been done. +.TP +.BR block_validity / noblock_validity +This option enables/disables the in-kernel facility for tracking +file system metadata blocks within internal data structures. This allows multi-\c +block allocator and other routines to quickly locate extents which might +overlap with file system metadata blocks. This option is intended for debugging +purposes and since it negatively affects the performance, it is off by default. +.TP +.BR dioread_lock / dioread_nolock +Controls whether or not ext4 should use the DIO read locking. If the +dioread_nolock option is specified ext4 will allocate uninitialized extent +before buffer write and convert the extent to initialized after IO completes. +This approach allows ext4 code to avoid using inode mutex, which improves +scalability on high speed storages. However this does not work with data +journaling and dioread_nolock option will be ignored with kernel warning. +Note that dioread_nolock code path is only used for extent-based files. +Because of the restrictions this options comprises it is off by default +(e.g.\& dioread_lock). +.TP +.B max_dir_size_kb=n +This limits the size of the directories so that any attempt to expand them +beyond the specified limit in kilobytes will cause an ENOSPC error. This is +useful in memory-constrained environments, where a very large directory can +cause severe performance problems or even provoke the Out Of Memory killer. (For +example, if there is only 512\ MB memory available, a 176\ MB directory may +seriously cramp the system's style.) +.TP +.B i_version +Enable 64-bit inode version support. This option is off by default. +.TP +.B nombcache +This option disables use of mbcache for extended attribute deduplication. On +systems where extended attributes are rarely or never shared between files, +use of mbcache for deduplication adds unnecessary computational overhead. +.TP +.B prjquota +The prjquota mount option enables project quota support on the file system. +You need the quota utilities to actually enable and manage the quota system. +This mount option requires the +.B project +file system feature. + +.SH FILE ATTRIBUTES +The ext2, ext3, and ext4 file systems support setting the following file +attributes on Linux systems using the +.BR chattr (1) +utility: +.sp +.BR a " - append only" +.sp +.BR A " - no atime updates" +.sp +.BR d " - no dump" +.sp +.BR D " - synchronous directory updates" +.sp +.BR i " - immutable" +.sp +.BR S " - synchronous updates" +.sp +.BR u " - undeletable" +.sp +In addition, the ext3 and ext4 file systems support the following flag: +.sp +.BR j " - data journaling" +.sp +Finally, the ext4 file system also supports the following flag: +.sp +.BR e " - extents format" +.sp +For descriptions of these attribute flags, please refer to the +.BR chattr (1) +man page. +.SH KERNEL SUPPORT +This section lists the file system driver (e.g., ext2, ext3, ext4) and +upstream kernel version where a particular file system feature was +supported. Note that in some cases the feature was present in earlier +kernel versions, but there were known, serious bugs. In other cases the +feature may still be considered in an experimental state. Finally, note +that some distributions may have backported features into older kernels; +in particular the kernel versions in certain "enterprise distributions" +can be extremely misleading. +.IP "\fBfiletype\fR" 2in +ext2, 2.2.0 +.IP "\fBsparse_super\fR" 2in +ext2, 2.2.0 +.IP "\fBlarge_file\fR" 2in +ext2, 2.2.0 +.IP "\fBhas_journal\fR" 2in +ext3, 2.4.15 +.IP "\fBext_attr\fR" 2in +ext2/ext3, 2.6.0 +.IP "\fBdir_index\fR" 2in +ext3, 2.6.0 +.IP "\fBresize_inode\fR" 2in +ext3, 2.6.10 (online resizing) +.IP "\fB64bit\fR" 2in +ext4, 2.6.28 +.IP "\fBdir_nlink\fR" 2in +ext4, 2.6.28 +.IP "\fBextent\fR" 2in +ext4, 2.6.28 +.IP "\fBextra_isize\fR" 2in +ext4, 2.6.28 +.IP "\fBflex_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBhuge_file\fR" 2in +ext4, 2.6.28 +.IP "\fBmeta_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBuninit_bg\fR" 2in +ext4, 2.6.28 +.IP "\fBmmp\fR" 2in +ext4, 3.0 +.IP "\fBbigalloc\fR" 2in +ext4, 3.2 +.IP "\fBquota\fR" 2in +ext4, 3.6 +.IP "\fBinline_data\fR" 2in +ext4, 3.8 +.IP "\fBsparse_super2\fR" 2in +ext4, 3.16 +.IP "\fBmetadata_csum\fR" 2in +ext4, 3.18 +.IP "\fBencrypt\fR" 2in +ext4, 4.1 +.IP "\fBmetadata_csum_seed\fR" 2i +ext4, 4.4 +.IP "\fBproject\fR" 2i +ext4, 4.5 +.IP "\fBea_inode\fR" 2i +ext4, 4.13 +.IP "\fBlarge_dir\fR" 2i +ext4, 4.13 +.IP "\fBcasefold\fR" 2i +ext4, 5.2 +.IP "\fBverity\fR" 2i +ext4, 5.4 +.IP "\fBstable_inodes\fR" 2i +ext4, 5.5 +.SH SEE ALSO +.BR mke2fs (8), +.BR mke2fs.conf (5), +.BR e2fsck (8), +.BR dumpe2fs (8), +.BR tune2fs (8), +.BR debugfs (8), +.BR mount (8), +.BR chattr (1) diff --git a/upstream/fedora-40/man5/filesystems.5 b/upstream/fedora-40/man5/filesystems.5 new file mode 100644 index 00000000..5196cec5 --- /dev/null +++ b/upstream/fedora-40/man5/filesystems.5 @@ -0,0 +1,227 @@ +.\" Copyright 1996 Daniel Quinlan (Daniel.Quinlan@linux.org) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2007-12-14 mtk Added Reiserfs, XFS, JFS. +.\" +.TH filesystems 5 2024-01-28 "Linux man-pages 6.06" +.nh +.SH NAME +filesystems \- Linux filesystem types: ext, ext2, ext3, ext4, hpfs, iso9660, +JFS, minix, msdos, ncpfs nfs, ntfs, proc, Reiserfs, smb, sysv, umsdos, vfat, +XFS, xiafs +.SH DESCRIPTION +When, as is customary, the +.B proc +filesystem is mounted on +.IR /proc , +you can find in the file +.I /proc/filesystems +which filesystems your kernel currently supports; +see +.BR proc (5) +for more details. +There is also a legacy +.BR sysfs (2) +system call (whose availability is controlled by the +.\" commit: 6af9f7bf3c399e0ab1eee048e13572c6d4e15fe9 +.B CONFIG_SYSFS_SYSCALL +kernel build configuration option since Linux 3.15) +that enables enumeration of the currently available filesystem types +regardless of +.I /proc +availability and/or sanity. +.P +If you need a currently unsupported filesystem, insert the corresponding +kernel module or recompile the kernel. +.P +In order to use a filesystem, you have to +.I mount +it; see +.BR mount (2) +and +.BR mount (8). +.P +The following list provides a +short description of the available or historically available +filesystems in the Linux kernel. +See the kernel documentation for a comprehensive +description of all options and limitations. +.TP +.B erofs +is the Enhanced Read-Only File System, stable since Linux 5.4. +.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging +See +.BR erofs (5). +.TP +.B ext +is an elaborate extension of the +.B minix +filesystem. +It has been completely superseded by the second version +of the extended filesystem +.RB ( ext2 ) +and has been removed from the kernel (in Linux 2.1.21). +.TP +.B ext2 +is a disk filesystem that was used by Linux for fixed disks +as well as removable media. +The second extended filesystem was designed as an extension of the +extended filesystem +.RB ( ext ). +See +.BR ext2 (5). +.TP +.B ext3 +is a journaling version of the +.B ext2 +filesystem. +It is easy to +switch back and forth between +.B ext2 +and +.BR ext3 . +See +.BR ext3 (5). +.TP +.B ext4 +is a set of upgrades to +.B ext3 +including substantial performance and +reliability enhancements, +plus large increases in volume, file, and directory size limits. +See +.BR ext4 (5). +.TP +.B hpfs +is the High Performance Filesystem, used in OS/2. +This filesystem is +read-only under Linux due to the lack of available documentation. +.TP +.B iso9660 +is a CD-ROM filesystem type conforming to the ISO/IEC\~9660 standard. +.RS +.TP +.B "High Sierra" +Linux supports High Sierra, the precursor to the ISO/IEC\~9660 standard for +CD-ROM filesystems. +It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.TP +.B "Rock Ridge" +Linux also supports the System Use Sharing Protocol records specified +by the Rock Ridge Interchange Protocol. +They are used to further describe the files in the +.B iso9660 +filesystem to a UNIX host, and provide information such as long +filenames, UID/GID, POSIX permissions, and devices. +It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.RE +.TP +.B JFS +is a journaling filesystem, developed by IBM, +that was integrated into Linux 2.4.24. +.TP +.B minix +is the filesystem used in the Minix operating system, the first to run +under Linux. +It has a number of shortcomings, including a 64\ MB partition size +limit, short filenames, and a single timestamp. +It remains useful for floppies and RAM disks. +.TP +.B msdos +is the filesystem used by DOS, Windows, and some OS/2 computers. +.B msdos +filenames can be no longer than 8 characters, followed by an +optional period and 3 character extension. +.TP +.B ncpfs +is a network filesystem that supports the NCP protocol, +used by Novell NetWare. +It was removed from the kernel in Linux 4.17. +.IP +To use +.BR ncpfs , +you need special programs, which can be found at +.UR ftp://ftp.gwdg.de\:/pub\:/linux\:/misc\:/ncpfs +.UE . +.TP +.B nfs +is the network filesystem used to access disks located on remote computers. +.TP +.B ntfs +is the filesystem native to Microsoft Windows NT, +supporting features like ACLs, journaling, encryption, and so on. +.TP +.B proc +is a pseudo filesystem which is used as an interface to kernel data +structures rather than reading and interpreting +.IR /dev/kmem . +In particular, its files do not take disk space. +See +.BR proc (5). +.TP +.B Reiserfs +is a journaling filesystem, designed by Hans Reiser, +that was integrated into Linux 2.4.1. +.TP +.B smb +is a network filesystem that supports the SMB protocol, used by +Windows. +See +.UR https://www.samba.org\:/samba\:/smbfs/ +.UE . +.TP +.B sysv +is an implementation of the System V/Coherent filesystem for Linux. +It implements all of Xenix FS, System V/386 FS, and Coherent FS. +.TP +.B umsdos +is an extended DOS filesystem used by Linux. +It adds capability for +long filenames, UID/GID, POSIX permissions, and special files +(devices, named pipes, etc.) under the DOS filesystem, without +sacrificing compatibility with DOS. +.TP +.B tmpfs +is a filesystem whose contents reside in virtual memory. +Since the files on such filesystems typically reside in RAM, +file access is extremely fast. +See +.BR tmpfs (5). +.TP +.B vfat +is an extended FAT filesystem used by Microsoft Windows95 and Windows NT. +.B vfat +adds the capability to use long filenames under the MSDOS filesystem. +.TP +.B XFS +is a journaling filesystem, developed by SGI, +that was integrated into Linux 2.4.20. +.TP +.B xiafs +was designed and implemented to be a stable, safe filesystem by +extending the Minix filesystem code. +It provides the basic most +requested features without undue complexity. +The +.B xiafs +filesystem is no longer actively developed or maintained. +It was removed from the kernel in Linux 2.1.21. +.SH SEE ALSO +.BR fuse (4), +.BR btrfs (5), +.BR ext2 (5), +.BR ext3 (5), +.BR ext4 (5), +.BR nfs (5), +.BR proc (5), +.BR sysfs (5), +.BR tmpfs (5), +.BR xfs (5), +.BR fsck (8), +.BR mkfs (8), +.BR mount (8) diff --git a/upstream/fedora-40/man5/ftpusers.5 b/upstream/fedora-40/man5/ftpusers.5 new file mode 100644 index 00000000..9595622e --- /dev/null +++ b/upstream/fedora-40/man5/ftpusers.5 @@ -0,0 +1,42 @@ +.\" Copyright (c) 2000 Christoph J. Thompson +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ftpusers 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +ftpusers \- list of users that may not log in via the FTP daemon +.SH DESCRIPTION +The text file +.B ftpusers +contains a list of users that may not log in using the +File Transfer Protocol (FTP) server daemon. +This file is used not merely for +system administration purposes but also for improving security within a TCP/IP +networked environment. +.P +The +.B ftpusers +file will typically contain a list of the users that +either have no business using ftp or have too many privileges to be allowed +to log in through the FTP server daemon. +Such users usually include root, daemon, bin, uucp, and news. +.P +If your FTP server daemon doesn't use +.BR ftpusers , +then it is suggested that you read its documentation to find out how to +block access for certain users. +Washington University FTP server Daemon +(wuftpd) and Professional FTP Daemon (proftpd) are known to make use of +.BR ftpusers . +.SS Format +The format of +.B ftpusers +is very simple. +There is one account name (or username) per line. +Lines starting with a # are ignored. +.SH FILES +.I /etc/ftpusers +.SH SEE ALSO +.BR passwd (5), +.BR proftpd (8), +.BR wuftpd (8) diff --git a/upstream/fedora-40/man5/gai.conf.5 b/upstream/fedora-40/man5/gai.conf.5 new file mode 100644 index 00000000..7fed47e4 --- /dev/null +++ b/upstream/fedora-40/man5/gai.conf.5 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved. +.\" Author: Ulrich Drepper +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.TH gai.conf 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +gai.conf \- getaddrinfo(3) configuration file +.SH DESCRIPTION +A call to +.BR getaddrinfo (3) +might return multiple answers. +According to RFC\ 3484 these answers must be sorted so that +the answer with the highest success rate is first in the list. +The RFC provides an algorithm for the sorting. +The static rules are not always adequate, though. +For this reason, +the RFC also requires that system administrators should have the possibility +to dynamically change the sorting. +For the glibc implementation, this can be achieved with the +.I /etc/gai.conf +file. +.P +Each line in the configuration file consists of a keyword and its parameters. +White spaces in any place are ignored. +Lines starting with \[aq]#\[aq] are comments and are ignored. +.P +The keywords currently recognized are: +.TP +\fBlabel\fR \fInetmask\fR \fIprecedence\fR +The value is added to the label table used in the RFC\ 3484 sorting. +If any \fBlabel\fR definition is present in the configuration file, +the default table is not used. +All the label definitions +of the default table which are to be maintained have to be duplicated. +Following the keyword, +the line has to contain a network mask and a precedence value. +.TP +\fBprecedence\fR \fInetmask\fR \fIprecedence\fR +This keyword is similar to \fBlabel\fR, but instead the value is added +to the precedence table as specified in RFC\ 3484. +Once again, the +presence of a single \fBprecedence\fR line in the configuration file +causes the default table to not be used. +.TP +\fBreload\fR <\fByes\fR|\fBno\fR> +This keyword controls whether a process checks whether the configuration +file has been changed since the last time it was read. +If the value is +"\fByes\fR", the file is reread. +This might cause problems in multithreaded +applications and is generally a bad idea. +The default is "\fBno\fR". +.TP +\fBscopev4\fR \fImask\fR \fIvalue\fR +Add another rule to the RFC\ 3484 scope table for IPv4 address. +By default, the scope IDs described in section 3.2 in RFC\ 3438 are used. +Changing these defaults should hardly ever be necessary. +.SH FILES +\fI/etc/gai.conf\fR +.SH VERSIONS +The +.I gai.conf +.\" Added in 2006 +file is supported since glibc 2.5. +.SH EXAMPLES +The default table according to RFC\ 3484 would be specified with the +following configuration file: +.P +.in +4n +.EX +label ::1/128 0 +label ::/0 1 +label 2002::/16 2 +label ::/96 3 +label ::ffff:0:0/96 4 +precedence ::1/128 50 +precedence ::/0 40 +precedence 2002::/16 30 +precedence ::/96 20 +precedence ::ffff:0:0/96 10 +.EE +.in +.\" .SH AUTHOR +.\" Ulrich Drepper +.\" +.SH SEE ALSO +.BR getaddrinfo (3), +RFC\ 3484 diff --git a/upstream/fedora-40/man5/genisoimagerc.5 b/upstream/fedora-40/man5/genisoimagerc.5 new file mode 100644 index 00000000..71082b48 --- /dev/null +++ b/upstream/fedora-40/man5/genisoimagerc.5 @@ -0,0 +1,144 @@ +.\" genisoimagerc.5 -*- nroff -*- +.\" Derived from genisoimage.1 +.\" Copyright 1993-1998 by Yggdrasil Computing +.\" Copyright 1996-1997 by Robert Leslie +.\" Copyright 1997-2001 by James Pearson +.\" Copyright 1999-2006 by Joerg Schilling +.\" Copyright 2002-2003 by Jungshik Shin +.\" Copyright 2003 by Jaakko Heinonen +.\" Copyright 2006 by the Cdrkit maintainers +.\" +.TH GENISOIMAGERC 5 "13 Dec 2006" +.\" ---------------------------------------- +.SH NAME +genisoimagerc \- startup configuration file for genisoimage +.SH DESCRIPTION +.BR genisoimage (1) +searches for a configuration file in several places; it uses the first +one it is able to open. First, if the +.B GENISOIMAGERC +environment variable is set, its value is used as the filename; +likewise for the +.B MKISOFSRC +environment variable. Next, +.B genisoimage +looks for files named +.IR .genisoimagerc " or " .mkisofsrc , +first in the current working directory, then in the user's home +directory. Next, it looks for +.IR /etc/genisoimagerc . +Finally, it looks for a +.I .genisoimagerc +in the same directory as +.B genisoimage +itself is stored. +.PP +The +.I .genisoimagerc +file contains lines of the form +.IP +.BI TAG= value +.PP +where +.B TAG +is one of the settings defined below. The case of the tag is not +significant. All settings have command-line equivalents; if the +command-line parameter is specified, it takes priority over the +configuration file. +.PP +Blank lines and lines beginning with `#' are ignored. +.\" ---------------------------------------- +.SH "CONFIGURATION SETTINGS" +.IP ABST +The abstract information, typically the name of a file on the disc +containing an abstract. There is space for 37 characters. +Equivalent to the +.B \-abstract +command-line option. +.IP APPI +The application identifier should describe the application that will be +on the disc. There is space for 128 characters. Equivalent to the +.B \-A +command-line option. +.IP BIBL +The bibliographic information, often the name of a file on the disc +containing a bibliography. There is space for 37 characters. +Equivalent to the +.B \-biblio +command-line option. +.IP COPY +The copyright information, typically the name of a file on the disc +containing the copyright notice. There is space for 37 characters. +Equivalent to the +.B \-copyright +command-line option. +.IP HFS_TYPE +The default +.B TYPE +for Macintosh files. Must be exactly 4 characters. Equivalent to the +.B \-hfs\-type +command-line option. The default value is +.IR TEXT . +.IP HFS_CREATOR +The default +.B CREATOR +for Macintosh files. Must be exactly 4 characters. Equivalent to the +.B \-hfs\-creator +command-line option. The default value is +.IR Unix . +.IP PREP +This should describe the preparer of the CD-ROM, usually with a mailing +address and phone number. There is space for 128 characters. +Equivalent to the +.B \-p +command-line option. +.IP PUBL +This should describe the publisher of the CD-ROM, usually with a +mailing address and phone number. There is space for 128 characters. +Equivalent to the +.B \-publisher +command-line option. +.IP SYSI +The System Identifier. There is space for 32 characters. +Equivalent to the +.B \-sysid +command-line option. +.IP VOLI +The Volume Identifier. There is space for 32 characters. +Equivalent to the +.B \-V +command-line option. +.IP VOLS +The Volume Set Name. There is space for 128 characters. +Equivalent to the +.B \-volset +command-line option. +.PP +.B genisoimage +can also be configured at compile time with defaults for many of these +fields. See the file +.IR defaults.h . +.\" ---------------------------------------- +.SH EXAMPLES +The following file +.IP +.nf +COPY=src/COPYING +SYSI=Multics 75 +.fi +.PP +is equivalent to the +.B genisoimage +command-line parameters +.IP +.I "\-copyright src/COPYING \-sysid \(dqMultics 75\(dq" +.\" ---------------------------------------- +.SH "SEE ALSO" +.BR genisoimage (1). +.\" ---------------------------------------- +.SH AUTHORS +See the +.BR genisoimage (1) +manual page for credits for the +.B genisoimage +program and documentation. diff --git a/upstream/fedora-40/man5/groff_font.5 b/upstream/fedora-40/man5/groff_font.5 new file mode 100644 index 00000000..7012073e --- /dev/null +++ b/upstream/fedora-40/man5/groff_font.5 @@ -0,0 +1,1114 @@ +.TH groff_font 5 "24 January 2024" "groff 1.23.0" +.SH Name +groff_font \- GNU +.I roff +device and font description files +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2021 Free Software Foundation, Inc. +.\" +.\" This file is part of groff (GNU roff), which is a free software +.\" project. +.\" +.\" You can redistribute it and/or modify it under the terms of the GNU +.\" General Public License as published by the Free Software Foundation, +.\" either version 2 of the License, or (at your option) any later +.\" version. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" . +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_font_5_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.\" BEGIN Keep parallel with groff.texi node "Device and Font Files". +The +.I groff +font and output device description formats are slight +extensions of those used by AT&T device-independent +.IR troff . \" AT&T +. +In distinction to the AT&T implementation, +.I groff +lacks a binary format; +all files are text files. +. +(Plan\~9 +.I troff \" Plan 9 +has also abandoned the binary format.) +. +The device and font description files for a device +.I name +are stored in a +.IR dev name +directory. +. +The device description file is called +.IR DESC , +and, +for each font supported by the device, +a font description file is +.RI called\~ f, +where +.IR f \~is +usually an abbreviation of a font's name and/or style. +. +For example, +the +.B ps +(PostScript) +device has +.I groff +font description files for Times roman +.RB ( TR ) +and Zapf Chancery Medium italic +.RB ( ZCMI ), +among many others, +while the +.B utf8 +device +(for terminal emulators) +has only font descriptions for the roman, +italic, +bold, +and bold-italic styles +.RB ( R , +.BR I , +.BR B , +and +.BR BI , +respectively). +. +. +.P +Device and font description files are read by the formatter, +.IR \%troff , +and by output drivers. +. +The programs typically delegate these files' processing to an internal +library, +.IR libgroff , +ensuring their consistent interpretation. +. +. +.\" ==================================================================== +.SH "\f[I]DESC\f[] file format" +.\" ==================================================================== +. +The +.I DESC +file contains a series of directives; +each begins a line. +. +Their order is not important, +with two exceptions: +(1) the +.B res +directive must precede any +.B \%papersize +directive; +and +(2) the +.B charset +directive must come last +(if at all). +. +If a directive name is repeated, +later entries in the file override previous ones +(except that the paper dimensions are computed based on the +.B res +directive last seen when +.B \%papersize +is encountered). +. +Spaces and/or tabs separate words and are ignored at line boundaries. +. +Comments start with the +.RB \[lq] # \[rq] +character and extend to the end of a line. +. +Empty lines are ignored. +. +. +.TP +.BI family\~ fam +The default font family is +.IR fam . +. +. +.TP +.BI fonts\~ "n F1"\~\c +.RI .\|.\|.\&\~ Fn +Fonts +.IR F1 ", \|.\|.\|.\|, " Fn +are mounted at font positions +.IR m "\|+\|1, \|.\|.\|., " m \|+\| n +where +.I m +is the number of +.B styles +(see below). +. +This directive may extend over more than one line. +. +A font name +.RB of\~ 0 +causes no font to be mounted at the corresponding position. +. +. +.TP +.BI hor\~ n +The horizontal motion quantum is +.IR n \~basic +units. +. +Horizontal quantities are rounded to multiples +.RI of\~ n. +. +. +.TP +.BI image_generator\~ program +Use +.I program +to generate PNG images from PostScript input. +. +Under GNU/Linux, +this is usually +.MR gs 1 , +but under other systems +(notably Cygwin) +it might be set to another name. +. +The +.MR grohtml 1 +driver uses this directive. +. +. +.TP +.BI paperlength\~ n +The vertical dimension of the output medium is +.IR n \~basic +units +(deprecated: +use +.B \%papersize +instead). +. +. +.TP +.BI papersize\~ format-or-dimension-pair-or-file-name\c +\~.\|.\|. +The dimensions of the output medium are as according to the +argument, +which is either +a standard paper format, +a pair of dimensions, +or the name of a plain text file containing either of the foregoing. +. +Recognized paper formats are the ISO and DIN formats +.BR A0 \[en] A7 , +.BR B0 \[en] B7 , +.BR C0 \[en] C7 , +and +.BR D0 \[en] D7 ; +.\" XXX: tmac/papersize.tmac does not support [ABCD]7. +the U.S.\& formats +.BR letter , +.BR legal , +.BR tabloid , +.BR ledger , +.BR statement , +and +.BR executive ; +and the envelope formats +.BR com10 , +.BR monarch , +and +.BR DL . +. +Matching is performed without regard for lettercase. +. +. +.IP +Alternatively, +the argument can be a custom paper format +.IB length , width +(with no spaces before or after the comma). +. +Both +.I length +and +.I width +must have a unit appended; +valid units are +.RB \[lq] i \[rq] +for inches, +.RB \[lq] c \[rq] +for centimeters, +.RB \[lq] p \[rq] +for points, +and +.RB \[lq] P \[rq] +for picas. +. +Example: +.RB \[lq] 12c,235p \[rq]. +. +An argument that starts with a digit is always treated as a custom paper +format. +. +. +.IP +Finally, +the argument can be a file name +(e.g., +.IR /etc/papersize ); +if the file can be opened, +the first line is read and a match attempted against each other form. +. +No comment syntax is supported. +. +. +.IP +More than one argument can be specified; +each is scanned in turn and the first valid paper specification used. +. +. +.TP +.BI paperwidth\~ n +The horizontal dimension of the output medium is +.IR n \~basic +units +(deprecated: +use +.B \%papersize +instead). +. +. +.TP +.B pass_filenames +Direct +.I \%troff +to emit the name of the source file being processed. +. +This is achieved with the intermediate output command +.RB \[lq] "x F" \[rq], +which +.I \%grohtml +interprets. +. +. +.TP +.BI postpro\~ program +Use +.I program +as the postprocessor. +. +. +.TP +.BI prepro\~ program +Use +.I program +as a preprocessor. +. +The +.B html +and +.B xhtml +output devices use this directive. +. +. +.TP +.BI print\~ program +Use +.I program +as the print spooler. +. +If omitted, +.IR groff 's +.B \-l +and +.B \-L +options are ignored. +. +. +.TP +.BI res\~ n +The device resolution is +.I n +basic units per inch. +. +. +.TP +.BI sizes\~ s1\~\c +.RI .\|.\|.\&\~ sn\~\c +.B 0 +The device has fonts at +.IR s1 , +\&.\|.\|., +.I sn +scaled points +(see below). +. +The list of sizes must be terminated by +.RB a\~ 0 . +. +Each +.I si +can also be a range of sizes +.IR m \[en] n . +. +The list can extend over more than one line. +. +. +.TP +.BI sizescale\~ n +A typographical point +is subdivided into +.IR n \~scaled +points. +. +The default +.RB is\~ 1 . +. +. +.TP +.BI styles\~ S1\~\c +.RI .\|.\|.\&\~ Sm +The +.RI first\~ m +font mounting positions are associated with styles +.IR S1 , +\&.\|.\|., +.IR Sm . +. +. +.TP +.B tcommand +The postprocessor can handle the +.B t +.RB and\~ u +intermediate output commands. +. +. +.TP +.B unicode +The output device supports the complete Unicode repertoire. +. +This directive is useful only for devices which produce character +entities instead of glyphs. +. +. +.IP +If +.B unicode +is present, +no +.B charset +section is required in the font description files since the Unicode +handling built into +.I groff +is used. +. +However, +if there are entries in a font description file's +.B charset +section, +they either override the default mappings for those particular +characters or add new mappings +(normally for composite characters). +. +. +.IP +The +.BR utf8 , +.BR html , +and +.B xhtml +output devices use this directive. +. +. +.TP +.BI unitwidth\~ n +Quantities in the font description files are in basic units for fonts +whose type size is +.IR n \~scaled +points. +. +. +.TP +.B unscaled_charwidths +Make the font handling module always return unscaled glyph widths. +. +The +.I \%grohtml +driver uses this directive. +. +. +.TP +.B use_charnames_in_special +.I \%troff +should encode named glyphs inside device control commands. +. +The +.I \%grohtml +driver uses this directive. +. +. +.TP +.BI vert\~ n +The vertical motion quantum is +.IR n \~basic +units. +. +Vertical quantities are rounded to multiples +.RI of\~ n. +. +. +.TP +.B charset +This directive and the rest of the file are ignored. +. +It is recognized for compatibility with other +.I troff \" generic +implementations. +. +In GNU +.IR troff , \" GNU +character set repertoire is described on a per-font basis. +. +. +.P +.I \%troff +recognizes but ignores the directives +.BR spare1 , +.BR spare2 , +and +.BR biggestfont . +. +. +.P +The +.BR res , +.BR unitwidth , +.BR fonts , +and +.B sizes +lines are mandatory. +. +Directives not listed above are ignored by +.I \%troff +but may be used by postprocessors to obtain further information about +the device. +. +. +.\" ==================================================================== +.SH "Font description file format" +.\" ==================================================================== +. +On typesetting output devices, +each font is typically available at multiple sizes. +. +While paper measurements in the device description file are in absolute +units, +measurements applicable to fonts must be proportional to the type size. +. +.I groff +achieves this using the precedent set by AT&T device-independent +.IR troff : \" AT&T +one font size is chosen as a norm, +and all others are scaled linearly relative to that basis. +. +The \[lq]unit width\[rq] is the number of basic units per point when the +font is rendered at this nominal size. +. +. +.P +For instance, +.IR groff 's +.B lbp +device uses a +.B unitwidth +of\~800. +. +Its Times roman font +.RB (\[lq] TR \[rq]) +has a +.B spacewidth +of\~833; +this is also the width of its comma, +period, +centered period, +and mathematical asterisk, +while its \[lq]M\[rq] is 2,963 basic units. +. +Thus, +an \[lq]M\[rq] on the +.B lbp +device is 2,963 basic units wide at a notional type size of 800\~points. +. +(800-point type is not practical for most purposes, +but using it enables the quantities in the font description files to be +expressed as integers.) +. +. +.P +A font description file has two sections. +. +The first is a sequence of directives, +and is parsed similarly to the +.I DESC +file described above. +. +Except for the directive names that begin the second section, +their ordering is immaterial. +. +Later directives of the same name override earlier ones, +spaces and tabs are handled in the same way, +and the same comment syntax is supported. +. +Empty lines are ignored throughout. +. +. +.TP +.BI name\~ F +The name of the font +.RI is\~ F . +. +.RB \[lq] DESC \[rq] +is an invalid font name. +. +Simple integers are valid, +but their use is discouraged. +. +.RI ( groff +requests and escape sequences interpret non-negative font names as +mounting positions instead. +. +Further, +a font named +.RB \[lq] 0 \[rq] +cannot be automatically mounted by the +.B fonts +directive of a +.I DESC +file.) +. +. +.TP +.BI spacewidth\~ n +The width of an unadjusted inter-word space is +.IR n \~basic +units. +. +. +.P +The directives above must appear in the first section; +those below are optional. +. +. +.TP +.BI slant\~ n +The font's glyphs have a slant of +.IR n \~degrees; +a positive +.I n +slants in the direction of text flow. +. +. +.TP +.BI ligatures\~ lig1\~\c +.RI .\|.\|.\&\~ lign\~\c +.RB [ 0 ] +Glyphs +.IR lig1 , +\&.\|.\|., +.I lign +are ligatures; +possible ligatures are +.BR ff , +.BR fi , +.BR fl , +.BR ffi , +and +.BR ffl . +. +For compatibility with other +.I troff +implementations, +the list of ligatures may be terminated with +.RB a\~ 0 . +. +The list of ligatures must not extend over more than one line. +. +. +.TP +.B special +The font is +.IR special : +when a glyph is requested that is not present in the current font, +it is sought in any mounted fonts that bear this property. +. +. +.P +Other directives in this section are ignored by +.IR \%troff , +but may be used by postprocessors to obtain further information about +the font. +. +. +.P +The second section contains one or two subsections. +. +These can appear in either order; +the first one encountered commences the second section. +. +Each starts with a directive on a line by itself. +. +A +.B charset +subsection is mandatory unless the associated +.I DESC +file contains the +.B unicode +directive. +. +Another subsection, +.BR \%kernpairs , +is optional. +. +. +.P +The directive +.B charset +starts the character set subsection. +. +(For typesetter devices, +this directive is misnamed since it starts a list of glyphs, +not characters.) +. +It precedes a series of glyph descriptions, +one per line. +. +Each such glyph description comprises a set of fields separated by +spaces or tabs and organized as follows. +. +. +.IP +.I name metrics type code +.RI [ entity-name ] +.RB [ \-\- +.IR comment ] +. +. +.P +.I name +identifies the glyph: +if +.I name +is a printable +.RI character\~ c , +it corresponds to the +.I troff \" generic +ordinary +.RI character\~ c . +. +If +.I name +is a multi-character sequence not beginning with +.BR \[rs] , +it corresponds to the GNU +.I troff \" GNU +special character escape sequence +\[lq]\c +.BI \[rs][ name ]\c +\[rq]. +. +A name consisting of three minus signs, +.RB \[lq] \-\-\- \[rq], +indicates that the glyph is unnamed: +such glyphs can be accessed only by the +.B \[rs]N +escape sequence in +.IR troff . \" generic; \N is portable +. +A special character named +.RB \[lq] \-\-\- \[rq] +can still be defined using +.B .char +and similar requests. +. +The +.I name +.RB \[lq] \[rs]\- \[rq] +defines the minus sign glyph. +. +.\" TODO: Withdraw support for this. No one seems to use it. +Finally, +.I name +can be the horizontal motion escape sequences, +.B \[rs]| +and +.B \[rs]\[ha] +(\[lq]thin\[rq] and \[lq]hair\[rq] spaces, +respectively), +in which case only the width metric described below is applied; +a font can thus customize the widths of these spaces. +.\" XXX: For exhaustivity purposes...you can define "\whatever", which +.\" has to be accessed with \C'\\whatever' or \[\\whatever], but the +.\" parser matches predefined escape sequences before looking up special +.\" characters. Most such definitions are inaccessible from the +.\" language, because nearly every '\x', where 'x' is a Unicode basic +.\" Latin character, is a predefined groff escape sequence. +. +. +.br +.ne 4v \" Keep next paragraph together with (possibly 2-line) synopsis. +.P +The form of the +.I metrics +field is as follows +(on one line; +it may be broken here for readability). +. +. +.IP +.\" XXX: Turning off adjustment is ugly; thanks to meter-long specimens +.\" like this, we need an escape sequence that selectively disables +.\" adjustment at the end of a word. +.na +.I width\/\c +.RI [\fB,\fP[ \:height\/\c +.RI [\fB,\fP[ \:depth\/\c +.RI [\fB,\fP[ \:\%italic-correction\/\c +.RI [\fB,\fP[ \:\%left-italic-correction\/\c +.RI [\fB,\fP[ \:\%subscript-correction ]]]]]]]]]] +.ad \*[AD] +. +. +.P +There must not be any spaces, +tabs, +or newlines between these +.I subfields, +. +which are in basic units expressed as decimal integers. +. +Unspecified subfields default +.RB to\~ 0 . +. +Since there is no associated binary format, +these values are not required to fit into the C language data type +.B char +as they are in AT&T device-independent +.IR troff . \" AT&T +. +. +.P +The +.I width +subfield gives the width of the glyph. +. +The +.I height +subfield gives the height of the glyph +(upwards is positive); +if a glyph does not extend above the baseline, +it should be given a zero height, +rather than a negative height. +. +The +.I depth +subfield gives the depth of the glyph, +that is, +the distance below the baseline to which the glyph extends +(downwards is positive); +if a glyph does not extend below the baseline, +it should be given a zero depth, +rather than a negative depth. +. +Italic corrections are relevant to glyphs in italic or oblique styles. +. +The +.I italic-correction +is the amount of space that should be added after an oblique glyph to be +followed immediately by an upright glyph. +. +The +.I left-italic-correction +is the amount of space that should be added before an oblique glyph to +be preceded immediately by an upright glyph. +. +The +.I +subscript-correction +is the amount of space that should be added after an oblique glyph to be +followed by a subscript; +it should be less than the italic correction. +. +. +.P +For fonts used with typesetting devices, +the +.I type +field gives a featural description of the glyph: +it is a bit mask recording whether the glyph is an ascender, +descender, +both, +or neither. +. +When a +.B \[rs]w +escape sequence is interpolated, +these values are bitwise or-ed together +for each glyph +and stored in the +.B ct +register. +. +In font descriptions for terminal devices, +all glyphs might have a type of zero, +regardless of their appearance. +. +. +.TP +0 +means the glyph lies entirely between the baseline and +a horizontal line at the \[lq]x-height\[rq] of the font, +as with \[lq]a\[rq], +\[lq]c\[rq], +and +\[lq]x\[rq]; +. +. +.TP +1 +means the glyph descends below the baseline, +like \[lq]p\[rq]; +. +. +.TP +2 +means the glyph ascends above the font's x-height, +like \[lq]A\[rq] or +\[lq]b\[rq]); +and +. +. +.TP +3 +means the glyph is both an ascender and a descender\[em]this is true of +parentheses in some fonts. +. +. +.P +The +.I code +field gives a numeric identifier that the postprocessor uses to render +the glyph. +. +The glyph can be specified to +.I troff \" generic +using this code by means of the +.B \[rs]N +escape sequence. +. +The code can be any integer +(that is, +any integer parsable by the C standard library's +.MR strtol 3 +function). +. +. +.P +The +.I entity-name +field defines an identifier for the glyph that the postprocessor +uses to print the +.I \%troff +glyph +.IR name . +. +This field is optional; +it was introduced so that the +.I \%grohtml +output driver could encode its character set. +. +For example, +the glyph +.B \[rs][Po] +is represented by +.RB \[lq] £ \[rq] +in HTML 4.0. +. +For efficiency, +these data are now compiled directly into +.IR \%grohtml . +. +.I grops +uses the field to build sub-encoding arrays for PostScript fonts +containing more than 256 glyphs. +. +Anything on the line after the +.I entity-name +field or +.RB \[lq] \-\- \[rq] +is ignored. +. +. +.P +A line in the +.B charset +section can also have the form +. +.RS +.IB name\~ \[dq] +.RE +. +identifying +.I name +as another name for the glyph mentioned in the preceding line. +. +Such aliases can be chained. +. +. +.P +The directive +.B \%kernpairs +starts a list of kerning adjustments to be made to adjacent glyph pairs +from this font. +. +It contains a sequence of lines formatted as follows. +. +.RS +.I g1 g2 n +.RE +. +The foregoing means that when glyph +.I g1 +is typeset immediately before +.IR g2 , +the space between them should be increased +.RI by\~ n . +. +Most kerning pairs should have a negative value +.RI for\~ n . +.\" END Keep parallel with groff.texi node "Device and Font Files". +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%dev name / F +describes the font known +.RI as\~ F +on device +.IR name . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.P +\[lq]Troff User's Manual\[rq] +by Joseph F.\& Ossanna, +1976 +(revised by Brian W.\& Kernighan, +1992), +AT&T Bell Laboratories Computing Science Technical Report No.\& 54, +widely called simply \[lq]CSTR\~#54\[rq], +documents the language, +device and font description file formats, +and device-independent output format +referred to collectively in +.I groff +documentation as +.RI \[lq]AT&T\~ troff \[rq]. +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97, +provides additional insights into the +device and font description file formats +and device-independent output format. +. +. +.P +.MR groff 1 , +subsection \[lq]Utilities\[rq], +lists programs available for describing fonts in a variety of formats +such that +.I groff +output drivers can use them. +. +. +.P +.MR \%troff 1 +documents the default device and font description file search path. +. +. +.P +.MR groff_out 5 , +.MR addftinfo 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_font_5_man_C] +.do rr *groff_groff_font_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man5/groff_out.5 b/upstream/fedora-40/man5/groff_out.5 new file mode 100644 index 00000000..2e2fe3f4 --- /dev/null +++ b/upstream/fedora-40/man5/groff_out.5 @@ -0,0 +1,1963 @@ +.TH groff_out 5 "24 January 2024" "groff 1.23.0" +.SH Name +groff_out \- GNU +.I roff +intermediate output format +. +. +.\" XXX: This page needs review and editing. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff type-setting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, with no Front-Cover Texts, +.\" and with no Back-Cover Texts. +.\" +.\" A copy of the Free Documentation License is included as a file +.\" called FDL in the main directory of the groff source package. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_out_5_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.\" Setup +.\" ==================================================================== +. +.\" ================= Document configuration +. +.\" Number register to decide whether the commands '{' and '}' are used +.\" 0: disable (current default); 1: enable +.nr @USE_ENV_STACK 0 +. +.ig +Unfortunately, old versions of groff used an illogical position change +after some D\~commands (Dp, DP, Dt). If the register +@STUPID_DRAWING_POSITIONING is 1 (current default) then change position +after these commands, otherwise the position is not changed. +.. +.nr @STUPID_DRAWING_POSITIONING 1 +. +.\" ================= Semantical definitions +. +.nr @maxcolor 65536 +.ds @backslash \[rs]\" +.ds @linebreak \fR\[la]line-break\[ra]\fP\" +. +.\" Begin of macro definitions +. +.de offset +.RI ( \,\\$1\/ ,\ \,\\$2\/ )\\$3 +.. +.de indexed_offset +.offset \fI\\$1\/\fP\d\s-3\\$2\s+3\u\x'\n[.v]/4' \fI\\$3\/\fP\ +\d\s-3\\$4\s+3\u\x'\n[.v]/4' \\$5\x'\n[.v]/4' +.. +.\" format: .command "" +.de command +\fB\\$1\fP\ \fI\,\\$2\/\fP\\$3 +.. +.\" format: .D-command "" +.de D-command +\fBD\\$1\fP\ \fI\,\\$2\/\fP\|\*[@linebreak] +.. +. +.\" We set these as troff micromotions rather than eqn because \d and \u +.\" can be lifted to XML subscript/superscript tags. Don't change +.\" these to a parameterized string, man2html won't handle that. +.ds hv1 \fIh\d\s-3\&1\s+3\u\~v\d\s-3\&1\s+3\u\fP\x'\n[.v]/4' +.ds hv2 \fIh\d\s-3\&2\s+3\u\~v\d\s-3\&2\s+3\u\fP\x'\n[.v]/4' +.ds hvn \fIh\d\s-3\&n\s+3\u\~v\d\s-3\&n\s+3\u\fP\x'\n[.v]/4' +. +.de Da-command +\fBDa\fP\ \*[hv1] \*[hv2]\|\*[@linebreak] +.. +.\" graphics command .D with a variable number of arguments +.\" format: .D-multiarg +.de D-multiarg +\fBD\\$1\fP\ \*[hv1] \*[hv2] \&.\|.\|.\& \*[hvn]\|\*[@linebreak] +.. +.\" format: .x-command "" +.de x-command +\fBx\\$1\fP\ \fI\\$2\fP\|\*[@linebreak] +.. +.de xsub +.RI "(" "\\$1" " control command)" +.br +.. +.\" End of macro definitions +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The fundamental operation of the +.MR \%troff 1 +formatter is the translation of the +.MR groff 7 +input language into a series of instructions concerned primarily with +placing glyphs or geometric objects at specific positions on a +rectangular page. +. +In the following discussion, +the term +.I command +refers to this intermediate output language, +never to the +.MR groff 7 +language intended for use by document authors. +. +Intermediate output commands comprise several categories: +glyph output; +font, +color, +and text size selection; +motion of the printing position; +page advancement; +drawing of geometric primitives; +and device control commands, +a catch-all for other operations. +. +The last includes directives to start and stop output, +identify the intended output device, +and embed URL hyperlinks in supported output formats. +. +. +.P +Because the front-end command +.MR groff 1 +is a wrapper that normally runs the +.I \%troff +formatter to generate intermediate output +and an output driver (\[lq]postprocessor\[rq]) to consume it, +users normally do not encounter this language. +. +The +.I groff +program's +.B \-Z +option inhibits postprocessing such that this intermediate output is +sent to the standard output stream as when +.I \%troff +is run manually. +. +. +.P +.IR groff 's +intermediate output facilitates the development of output drivers and +other postprocessors by offering a common programming interface. +. +It is an extension of the page description language developed by Brian +Kernighan for AT&T device-independent +.I troff \" AT&T +circa 1980. +. +Where a distinction is necessary, +we will say +.RI \[lq] \%troff +output\[rq] to describe the output of GNU +.IR troff , \" GNU +and \[lq]intermediate output\[rq] to denote the language accepted by +the parser implemented in +.IR groff 's +internal C++ library used by most of its output drivers. +.\" XXX GBR leaves off here. +. +. +.\" ==================================================================== +.SH "Language concepts" +.\" ==================================================================== +. +During the run of +.IR \%troff , +the +.I roff +input is cracked down to the information on what has to be printed at +what position on the intended device. +. +So the language of the +.I intermediate output +format can be quite small. +. +Its only elements are commands with or without arguments. +. +In this document, the term \[lq]command\[rq] always refers to the +.I intermediate output +language, never to the +.I roff +language used for document formatting. +. +There are commands for positioning and text writing, for drawing, and +for device controlling. +. +. +.\" ==================================================================== +.SS Separation +.\" ==================================================================== +. +.I Classical troff output +had strange requirements on whitespace. +. +The +.I groff +output parser, however, is smart about whitespace by making it +maximally optional. +. +The whitespace characters, i.e., the +.IR tab , +.IR space , +and +.I newline +characters, always have a syntactical meaning. +. +They are never printable because spacing within the output is always +done by positioning commands. +. +. +.P +Any sequence of +.I space +or +.I tab +characters is treated as a single +.I syntactical +.IR space . +. +It separates commands and arguments, but is only required when there +would occur a clashing between the command code and the arguments +without the space. +. +Most often, this happens when variable length command names, +arguments, argument lists, or command clusters meet. +. +Commands and arguments with a known, fixed length need not be +separated by +.I syntactical +.IR space . +. +. +.P +A line break is a syntactical element, too. +. +Every command argument can be followed by whitespace, a comment, or a +newline character. +. +Thus a +.I syntactical line break +is defined to consist of optional +.I syntactical space +that is optionally followed by a comment, and a newline character. +. +. +.P +The normal commands, those for positioning and text, consist of a +single letter taking a fixed number of arguments. +. +For historical reasons, the parser allows stacking of such commands on +the same line, but fortunately, in +.I groff intermediate +.IR output , +every command with at least one argument is followed by a line break, +thus providing excellent readability. +. +.P +The other commands \[em] those for drawing and device controlling \[em] +have a more complicated structure; some recognize long command names, +and some take a variable number of arguments. +. +So all +.B D +and +.B x +commands were designed to request a +.I syntactical line break +after their last argument. +. +Only one command, +.RB \[oq] x\ X \[cq] +has an argument that can stretch over several lines, all other +commands must have all of their arguments on the same line as the +command, i.e., the arguments may not be split by a line break. +. +.P +Lines containing only spaces and/or a comment are treated as empty and +ignored. +. +. +.\" ==================================================================== +.SS "Argument units" +.\" ==================================================================== +. +Some commands accept integer arguments that represent measurements, +but the scaling units of the formatter's language are never used. +. +Most commands assume a scaling unit +.RB of\~\[lq] u \[rq] +(basic units), +and others +.RB use\~\[lq] z \[rq] +(scaled points); +. +These are defined by the parameters specified in the device's +.I DESC +file; +see +.MR groff_font 5 +and, +for more on scaling units, +.MR groff 7 +and +.IR "Groff: The GNU Implementation of troff" , +the +.I groff +Texinfo manual. +. +Color-related commands use dimensionless integers. +. +. +.P +Note that single characters can have the eighth bit set, as can the +names of fonts and special characters (this is, glyphs). +. +The names of glyphs and fonts can be of arbitrary length. +. +A glyph that is to be printed will always be in the current font. +. +. +.P +A string argument is always terminated by the next whitespace +character (space, tab, or newline); an embedded +.B # +character is regarded as part of the argument, not as the beginning of +a comment command. +. +An integer argument is already terminated by the next non-digit +character, which then is regarded as the first character of the next +argument or command. +. +. +.\" ==================================================================== +.SS "Document parts" +.\" ==================================================================== +. +A correct +.I intermediate output +document consists of two parts, the +.I prologue +and the +.IR body . +. +.P +The task of the +.I prologue +is to set the general device parameters using three exactly specified +commands. +. +The +.I groff prologue +is guaranteed to consist of the following three lines (in that order): +.RS +.P +.B x\ T +.I device +.br +.B x\ res +.I n\ h\ v +.br +.B x init +.RE +.P +with the arguments set as outlined in subsection \[lq]Device Control +Commands\[rq] below. +. +However, the parser for the +.I intermediate output +format is able to swallow additional whitespace and comments as well. +. +. +.P +The +.I body +is the main section for processing the document data. +. +Syntactically, it is a sequence of any commands different from the +ones used in the +.IR prologue . +. +Processing is terminated as soon as the first +.B x\ stop +command is encountered; the last line of any +.I groff intermediate output +always contains such a command. +. +. +.P +Semantically, the +.I body +is page oriented. +. +A new page is started by a +.BR p \~command. +. +Positioning, writing, and drawing commands are always done within the +current page, so they cannot occur before the first +.BR p \~command. +. +Absolute positioning (by the +.B H +and +.BR V \~commands) +is done relative to the current page, all other positioning +is done relative to the current location within this page. +. +. +.\" ==================================================================== +.SH "Command reference" +.\" ==================================================================== +. +This section describes all +.I intermediate output +commands, the classical commands as well as the +.I groff +extensions. +. +. +.\" ==================================================================== +.SS "Comment command" +.\" ==================================================================== +. +.TP +.BI # anything\c +\[la]line-break\[ra] +A comment. +. +Ignore any characters from the +.BR # \~character +up to the next newline. +. +Each comment can be preceded by arbitrary +.I syntactical +.IR space ; +every command can be terminated by a comment. +. +. +.\" ==================================================================== +.SS "Simple commands" +.\" ==================================================================== +. +The commands in this subsection have a command code consisting of a +single character, taking a fixed number of arguments. +. +Most of them are commands for positioning and text writing. +. +These commands are smart about whitespace. +. +Optionally, +.I syntactical space +can be inserted before, after, and between the command letter and its +arguments. +. +All of these commands are stackable, i.e., they can be preceded by +other simple commands or followed by arbitrary other commands on the +same line. +. +A separating +.I syntactical space +is necessary only when two integer arguments would clash or if the +preceding argument ends with a string argument. +. +. +.if \n[@USE_ENV_STACK]=1 \{\ +.TP +.command { +Open a new environment by copying the current device configuration data +to the environment stack. +. +The current environment is setup by the device specification and +manipulated by the setting commands. +. +. +.TP +.command } +Close the current environment +(opened by a preceding +.BR { \~command) +and restore the previous environment from the environment +stack as the current device configuration data. +. +.\} \" endif @USE_ENV_STACK +. +. +.TP +.command C id \[la]white-space\[ra] +Typeset the glyph of the special character +.IR id . +. +Trailing syntactical space is necessary to allow special character names +of arbitrary length. +. +The drawing position is not advanced. +.\" XXX: Why does it matter that we read its size if we don't advance +.\" the drawing position? +.\" its size is read from the font description file. +. +. +.TP +.command c c +Typeset the glyph of the ordinary character +.RI character\~ c . +. +The drawing position is not advanced. +.\" XXX: Why does it matter that we read its size if we don't advance +.\" the drawing position? +.\" its size is read from the font description file. +. +. +.TP +.command f n +Select the font mounted at +.RI position\~ n . +. +.IR n\~ cannot +be negative. +. +. +.TP +.command H n +Horizontally move the drawing position to +.IR n\~ basic +units from the left edge of the page. +. +.IR n\~ cannot +be negative. +. +. +.TP +.command h n +Move the drawing position right +.I n +basic units. +. +AT&T +.I troff \" AT&T +allowed negative +.I n; +GNU +.I troff \" GNU +does not produce such values, +but +.IR groff 's +output driver library handles them. +. +. +.TP +.command m "scheme \f[R][\f[]component\f[R] .\|.\|.]" +Select the stroke color using the +.IR component s +in the color space +.IR scheme . +. +Each +.I component +is an integer between 0 and \n[@maxcolor]. +. +The quantity of components and their meanings vary with each +.IR scheme . +. +This command is a +.I groff +extension. +. +. +.RS +.TP +.command mc "cyan magenta yellow" +Use the CMY color scheme with components +cyan, +magenta, +and yellow. +. +. +.TP +.command md +Use the default color +(no components; +black in most cases). +. +. +.TP +.command mg gray +Use a grayscale color scheme with a component ranging +between 0 (black) and \n[@maxcolor] (white). +. +. +.TP +.command mk "cyan magenta yellow black" +Use the CMYK color scheme with components +cyan, +magenta, +yellow, +and black. +. +. +.TP +.command mr "red green blue" +Use the RGB color scheme with components +red, +green, +and blue. +.RE +. +. +.TP +.command N n +Typeset the glyph with +.RI index\~ n +in the current font. +. +.IR n\~ is +normally a non-negative integer. +. +The drawing position is not advanced. +. +The +.B html +and +.B xhtml +devices use this command with +.RI negative\~ n +to produce unbreakable space; +the absolute value of +.I n +is taken and interpreted in basic units. +. +. +.TP +.command n b\~a +Indicate a break. +. +No action is performed; +the command is present to make the output more easily parsed. +. +The integers +.I b +.RI and\~ a +describe the vertical space amounts before and after the break, +respectively. +. +GNU +.I troff \" GNU +issues this command but +.IR groff 's +output driver library ignores it. +. +See +.B v +and +.BR V . +. +. +.TP +.command p n +Begin a new page, +setting its number +.RI to\~ n . +. +Each page is independent, +even from those using the same number. +. +The vertical drawing position is set to\~0. +. +All positioning, +writing, +and drawing commands are interpreted in the context of a page, +so a +.BR p \~command +must precede them. +. +. +.TP +.command s n +Set type size to +.I n +scaled points +.RB (unit\~ z +in GNU +.IR troff ). \" GNU +. +AT&T +.I troff \" AT&T +used unscaled points +.RB ( p ) +instead; +see section \[lq]Compatibility\[rq] below. +. +. +.TP +.command t xyz\f[R]\|.\|.\|.\& \f[R]\[la]white-space\[ra] +.TQ +.command t "xyz\f[R]\|.\|.\|.\&\f[] dummy-arg" \[la]white-space\[ra] +Typeset word +.IR xyz ; +that is, +set a sequence of ordinary glyphs named +.IR x , +.IR y , +.IR z , +\&.\|.\|.\|, +terminated by a space or newline; +an optional second integer argument is ignored +(this allows the formatter to generate an even number of arguments). +.\" XXX: Why? +. +Each glyph is set at the current drawing position, +and the position is then advanced horizontally by the glyph's width. +. +A glyph's width is read from its metrics in the font description file, +scaled to the current type size, +and rounded to a multiple of the horizontal motion quantum. +. +Use the +.B C +command to emplace glyphs of special characters. +. +The +.BR t \~command +is a +.I groff +extension and is output only for devices whose +.I DESC +file contains the +.B tcommand +directive; +see +.MR groff_font 5 . +. +. +.TP +.command u "n xyz"\f[R]\|.\|.\|.\& \f[R]\[la]white-space\[ra] +.TQ +.command u "xyz\f[R]\|.\|.\|.\&\f[] dummy-arg" \[la]white-space\[ra] +Typeset word +.I xyz +with track kerning. +. +As +.BR t , +but after placing each glyph, +the drawing position is further advanced horizontally +.RI by\~ n +basic units. +. +The +.BR u \~command +is a +.I groff +extension and is output only for devices whose +.I DESC +file contains the +.B tcommand +directive; +see +.MR groff_font 5 . +. +. +.TP +.command V n +Vertically move the drawing position to +.IR n\~ basic +units from the top edge of the page. +. +.IR n\~ cannot +be negative. +. +. +.TP +.command v n +Move the drawing position down +.I n +basic units. +. +AT&T +.I troff \" AT&T +allowed negative +.I n; +GNU +.I troff \" GNU +does not produce such values, +but +.IR groff 's +output driver library handles them. +. +. +.TP +.command w +Indicate an inter-word space. +. +No action is performed; +the command is present to make the output more easily parsed. +. +Only adjustable, +breakable inter-word spaces are thus described; +those resulting from +.B \[rs]\[ti] +or horizontal motion escape sequences are not. +. +GNU +.I troff \" GNU +issues this command but +.IR groff 's +output driver library ignores it. +. +See +.B h +and +.BR H . +. +. +.\" ==================================================================== +.SS "Graphics commands" +.\" ==================================================================== +. +Each graphics or drawing command in the +.I intermediate output +starts with the letter\~\c +.B D +followed by one or two characters that specify a subcommand; this +is followed by a fixed or variable number of integer arguments that +are separated by a single space character. +. +A +.BR D \~command +may not be followed by another command on the same line (apart from a +comment), so each +.BR D \~command +is terminated by a +.I syntactical line +.IR break . +. +. +.P +.I \%troff +output follows the classical spacing rules (no space between command +and subcommand, all arguments are preceded by a single space +character), but the parser allows optional space between the command +letters and makes the space before the first argument optional. +. +As usual, each space can be any sequence of tab and space characters. +. +. +.P +Some graphics commands can take a variable number of arguments. +. +In this case, they are integers representing a size measured in basic +units\~\c +.BR u . +. +The +.I h +arguments +stand for horizontal distances where positive means right, negative +left. +. +The +.I v +arguments +stand for vertical distances where positive means down, negative up. +. +All these distances are offsets relative to the current location. +. +. +.P +Unless indicated otherwise, each graphics command directly corresponds +to a similar +.I groff +.B \*[@backslash]D +escape sequence; see +.MR groff 7 . +. +. +.P +Unknown +.BR D \~commands +are assumed to be device-specific. +. +Its arguments are parsed as strings; the whole information is then +sent to the postprocessor. +. +. +.P +In the following command reference, the syntax element +.I \[la]line-break\[ra] +means a +.I syntactical line break +as defined in subsection \[lq]Separation\[rq] above. +. +. +.TP +.D-multiarg \[ti] +Draw B-spline from current position to offset +.indexed_offset h 1 v 1 , +then to offset +.indexed_offset h 2 v 2 +if given, etc., up to +.indexed_offset h n v n . +This command takes a variable number of argument pairs; the current +position is moved to the terminal point of the drawn curve. +. +. +.TP +.Da-command +Draw arc from current position to +.indexed_offset h 1 v 1 \|+\|\c +.indexed_offset h 2 v 2 +with center at +.indexed_offset h 1 v 1 ; +then move the current position to the final point of the arc. +. +. +.TP +.D-command C d +.TQ +.D-command C "d dummy-arg" +Draw a solid circle using the current fill color with diameter\~\c +.I d +(integer in basic units\~\c +.BR u ) +with leftmost point at the current position; then move the current +position to the rightmost point of the circle. +. +An optional second integer argument is ignored (this allows the +formatter to generate an even number of arguments). +. +This command is a +.I groff +extension. +. +. +.TP +.D-command c d +Draw circle line with diameter\~\c +.I d +(integer in basic units\~\c +.BR u ) +with leftmost point at the current position; then move the current +position to the rightmost point of the circle. +. +. +.TP +.D-command E "h v" +Draw a solid ellipse in the current fill color with a horizontal +diameter of\~\c +.I h +and a vertical diameter of\~\c +.I v +(both integers in basic units\~\c +.BR u ) +with the leftmost point at the current position; then move to the +rightmost point of the ellipse. +. +This command is a +.I groff +extension. +. +. +.TP +.D-command e "h v" +Draw an outlined ellipse with a horizontal diameter of\~\c +.I h +and a vertical diameter of\~\c +.I v +(both integers in basic units\~\c +.BR u ) +with the leftmost point at current position; then move to the +rightmost point of the ellipse. +. +. +.TP +.D-command F "color-scheme \fR[\fPcomponent\fR .\|.\|.]\fP" +Set fill color for solid drawing objects using different color +schemes; the analogous command for setting the color of text, line +graphics, and the outline of graphic objects is +.BR m . +. +The color components are specified as integer arguments between 0 and +\n[@maxcolor]. +. +The number of color components and their meaning vary for the +different color schemes. +. +These commands are generated by the +.I groff +escape sequences +.BR \*[@backslash]D\[aq]F\ .\|.\|. ' +and +.B \*[@backslash]M +(with no other corresponding graphics commands). +. +This command is a +.I groff +extension. +. +. +.RS +. +.TP +.D-command Fc "cyan magenta yellow" +Set fill color for solid drawing objects using the CMY color scheme, +having the 3\~color components cyan, magenta, and yellow. +. +. +.TP +.D-command Fd +Set fill color for solid drawing objects to the default fill color value +(black in most cases). +. +No component arguments. +. +. +.TP +.D-command Fg "gray" +Set fill color for solid drawing objects to the shade of gray given by +the argument, an integer between 0 (black) and \n[@maxcolor] (white). +. +. +.TP +.D-command Fk "cyan magenta yellow black" +Set fill color for solid drawing objects using the CMYK color scheme, +having the 4\~color components cyan, magenta, yellow, and black. +. +.TP +.D-command Fr "red green blue" +Set fill color for solid drawing objects using the RGB color scheme, +having the 3\~color components red, green, and blue. +. +.RE +. +. +.TP +.D-command f n +The argument +.I n +must be an integer in the range \-32767 to 32767. +. +.RS +.TP +.RI 0\|\[<=]\| n \|\[<=]\|1000 +Set the color for filling solid drawing objects to a shade of gray, +where 0 corresponds to solid white, 1000 (the default) to solid black, +and values in between to intermediate shades of gray; this is +obsoleted by command +.BR DFg . +. +.TP +.IR n "\|<\|0 or " n \|>\|1000 +Set the filling color to the color that is currently being used for +the text and the outline, see command +.BR m . +For example, the command sequence +. +.RS +.IP +.EX +mg 0 0 \n[@maxcolor] +Df \-1 +.EE +.RE +. +.IP +sets all colors to blue. +. +.P +This command is a +.I groff +extension. +. +.RE +. +. +.TP +.D-command l "h v" +Draw line from current position to offset +.offset h v +(integers in basic units\~\c +.BR u ); +then set current position to the end of the drawn line. +. +. +.TP +.D-multiarg p +Draw a polygon line from current position to offset +.indexed_offset h 1 v 1 , +from there to offset +.indexed_offset h 2 v 2 , +etc., up to offset +.indexed_offset h n v n , +and from there back to the starting position. +. +.ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +For historical reasons, the position is changed by adding the sum of +all arguments with odd index to the current horizontal position and the +even ones to the vertical position. +. +Although this doesn't make sense it is kept for compatibility. +. +.\} +.el \{\ +As the polygon is closed, the end of drawing is the starting point, so +the position doesn't change. +.\} +. +This command is a +.I groff +extension. +. +. +.TP +.D-multiarg P +The same macro as the corresponding +.B Dp +command with the same arguments, but draws a solid polygon in the +current fill color rather than an outlined polygon. +. +.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +The position is changed in the same way as with +.BR Dp . +.\} +. +This command is a +.I groff +extension. +. +. +.TP +.D-command t n +Set the current line thickness +.RI to\~ n +(an integer in basic +.RB units\~ u ) +if +.IR n \|>\|0; +if +.IR n \|=\|0 +select the smallest available line thickness; +otherwise, +the line thickness is made proportional to the type size, +which is the default. +. +.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +For historical reasons, +the horizontal position is changed by adding the argument to the current +horizontal position, +while the vertical position is not changed. +. +Although this doesn't make sense, +it is kept for compatibility. +.\} +. +This command is a +.I groff +extension. +. +. +.\" ==================================================================== +.SS "Device control commands" +.\" ==================================================================== +. +Each device control command starts with the letter +.B x +followed by a space character (optional or arbitrary space/\:tab in +.IR groff ) +and a subcommand letter or word; each argument (if any) must be +preceded by a +.I syntactical +.IR space . +. +All +.B x +commands are terminated by a +.IR "syntactical line break" ; +no device control command can be followed by another command on the same +line (except a comment). +. +.P +The subcommand is basically a single letter, but to increase +readability, it can be written as a word, i.e., an arbitrary sequence +of characters terminated by the next tab, space, or newline character. +. +All characters of the subcommand word but the first are simply ignored. +. +For example, +.I \%troff +outputs the initialization command +.B x\ i +as +.B x\ init +and the resolution command +.B x\ r +as +.BR "x\ res" . +. +But writings like +.B x\ i_like_groff +and +.B x\ roff_is_groff +are accepted as well to mean the same commands. +. +.P +In the following, the syntax element +.I \[la]line-break\[ra] +means a +.I syntactical line break +as defined in subsection \[lq]Separation\[rq] above. +. +.TP +.x-command F name +.xsub Filename +Use +.I name +as the intended name for the current file in error reports. +. +This is useful for remembering the original file name when +.I groff +uses an internal piping mechanism. +. +The input file is not changed by this command. +. +This command is a +.I groff +extension. +. +. +.TP +.x-command f "n\ s" +.xsub font +Mount font position\~\c +.I n +(a non-negative integer) with font named\~\c +.I s +(a text word); +see +.MR groff_font 5 . +. +. +.TP +.x-command H n +.xsub Height +Set character height to\~\c +.I n +(a positive integer in scaled points\~\c +.BR z ). +. +.I Classical troff +used the unit points (\c +.BR p ) +instead; +see section \[lq]Compatibility\[rq] below. +. +. +.TP +.x-command i +.xsub init +Initialize device. +. +This is the third command of the +.IR prologue . +. +. +.TP +.x-command p +.xsub pause +Parsed but ignored. +. +The classical documentation reads +.I pause device, can be +.IR restarted . +. +. +.TP +.x-command r "n\ h\ v" +.xsub resolution +Resolution is\~\c +.IR n , +while +.I h +is the minimal horizontal motion, and +.I v +the minimal vertical motion possible with this device; all arguments +are positive integers in basic units\~\c +.B u +per inch. +. +This is the second command of the +.IR prologue . +. +. +.TP +.x-command S n +.xsub Slant +Set slant to\~\c +.I n +degrees (an integer in basic units\~\c +.BR u ). +. +. +.TP +.x-command s +.xsub stop +Terminates the processing of the current file; issued as the last +command of any +.I intermediate \%troff +.IR output . +. +. +.TP +.x-command t +.xsub trailer +Generate trailer information, if any. +. +In +.BR groff , +this is currently ignored. +. +. +.TP +.x-command T xxx +.xsub Typesetter +. +Set the name of the output driver to +.IR xxx , +a sequence of non-whitespace characters terminated by whitespace. +. +The possible names correspond to those of +.IR groff 's +.B \-T +option. +. +This is the first command of the prologue. +. +. +.TP +.x-command u n +.xsub underline +Configure underlining of spaces. +. +If +.I n +is\~1, start underlining of spaces; +if +.I n +is\~0, stop underlining of spaces. +. +This is needed for the +.B cu +request in +.B \%nroff +mode and is ignored otherwise. +. +This command is a +.I groff +extension. +. +. +.TP +.x-command X anything +.xsub X-escape +Send string +.I anything +uninterpreted to the device. +. +If the line following this command starts with a +.B + +character this line is interpreted as a continuation line in the +following sense. +. +The +.B + +is ignored, but a newline character is sent instead to the device, the +rest of the line is sent uninterpreted. +. +The same applies to all following lines until the first character of a +line is not a +.B + +character. +. +This command is generated by the +.I groff +escape sequence +.BR \*[@backslash]X . +. +The line-continuing feature is a +.I groff +extension. +. +. +.\" ==================================================================== +.SS "Obsolete command" +.\" ==================================================================== +. +In +.I classical troff +output, emitting a single glyph was mostly done by a very +strange command that combined a horizontal move and the printing of a +glyph. +. +It didn't have a command code, but is represented by a 3-character +argument consisting of exactly 2\~digits and a character. +. +.TP +.I ddc +Move right +.I dd +(exactly two decimal digits) basic units\~\c +.BR u , +then print glyph with single-letter name\~\c +.IR c . +. +. +.RS +.P +In +.IR groff , +arbitrary +.I syntactical space +around and within this command is allowed to be added. +. +Only when a preceding command on the same line ends with an argument +of variable length a separating space is obligatory. +. +In +.I classical +.IR troff , +large clusters of these and other commands were used, mostly without +spaces; this made such output almost unreadable. +. +.RE +. +. +.P +For modern high-resolution devices, this command does not make sense +because the width of the glyphs can become much larger than two +decimal digits. +. +In +.IR groff , +it is used only for output to the +.BR X75 , +.BR X75\-12 , +.BR X100 , +and +.B X100\-12 +devices. +. +For others, +the commands +.B t +.RB and\~ u +provide greater functionality and superior troubleshooting capacity. +. +. +.\" ==================================================================== +.SH Postprocessing +.\" ==================================================================== +. +The +.I roff +postprocessors are programs that have the task to translate the +.I intermediate output +into actions that are sent to a device. +. +A device can be some piece of hardware such as a printer, or a software +file format suitable for graphical or text processing. +. +The +.I groff +system provides powerful means that make the programming of such +postprocessors an easy task. +.P +There is a library function that parses the +.I intermediate output +and sends the information obtained to the device via methods of a +class with a common interface for each device. +. +So a +.I groff +postprocessor must only redefine the methods of this class. +. +For details, +see the reference in section \[lq]Files\[rq] below. +. +. +.\" ==================================================================== +.SH Example +.\" ==================================================================== +. +This section presents the +.I intermediate output +generated from the same input for three different devices. +. +The input is the sentence +.I hell world +fed into +.I groff +on the command line. +. +. +.IP \[bu] 2m +High-resolution device +.I ps +. +. +.RS +.P +.EX +.RB "shell>\~" "echo \[dq]hell world\[dq] | groff \-Z \-T ps" +.EE +. +. +.P +.EX +x T ps +x res 72000 1 1 +x init +p1 +x font 5 TR +f5 +s10000 +V12000 +H72000 +thell +wh2500 +tw +H96620 +torld +n12000 0 +x trailer +V792000 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR grops 1 +to get its representation as a PostScript file, or +.MR gropdf 1 +to output directly to PDF. +. +. +.IP \[bu] 2m +Low-resolution device +.I latin1 +. +. +.RS +.P +This is similar to the high-resolution device except that the +positioning is done at a minor scale. +. +Some comments (lines starting with +.IR # ) +were added for clarification; they were not generated by the +formatter. +. +. +.P +.EX +\fBshell>\fP "hell world" | groff \-Z \-T latin1 +.EE +. +. +.P +.EX +.I # prologue +x T latin1 +x res 240 24 40 +x init +.I # begin a new page +p1 +.I # font setup +x font 1 R +f1 +s10 +.I # initial positioning on the page +V40 +H0 +.I # write text \[aq]hell\[aq] +thell +.I # inform about a space, and do it by a horizontal jump +wh24 +.I # write text \[aq]world\[aq] +tworld +.I # announce line break, but do nothing because ... +n40 0 +.I # ... the end of the document has been reached +x trailer +V2640 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR grotty 1 +to get a formatted text document. +. +. +.IP \[bu] 2m +Classical style output +. +. +.RS +.P +As a computer monitor has a very low resolution compared to modern +printers the +.I intermediate output +for the X\~devices can use the jump-and-write command with its 2-digit +displacements. +. +. +.P +.EX +\fBshell>\fP "hell world" | groff \-Z \-T X100 +.EE +. +. +.P +.EX +x T X100 +x res 100 1 1 +x init +p1 +x font 5 TR +f5 +s10 +V16 +H100 +.I # write text with old-style jump-and-write command +ch07e07l03lw06w11o07r05l03dh7 +n16 0 +x trailer +V1100 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR xditview 1x +or +.MR gxditview 1 +for displaying in\~X. +. +. +.P +Due to the obsolete jump-and-write command, the text clusters in the +classical output are almost unreadable. +. +. +.\" ==================================================================== +.SH Compatibility +.\" ==================================================================== +. +The +.I intermediate output +language of the +.I classical troff +was first documented in +[CSTR\~#97]. +. +The +.I groff intermediate output +format is compatible with this specification except for the following +features. +. +. +.IP \[bu] 2m +The classical quasi device independence is not yet implemented. +. +. +.IP \[bu] 2m +The old hardware was very different from what we use today. +. +So the +.I groff +devices are also fundamentally different from the ones in +.I classical +.IR troff . +. +For example, the classical PostScript device was called +.I post +and had a resolution of 720 units per inch, +while +.IR groff 's +.I ps +device has a resolution of 72000 units per inch. +. +Maybe, by implementing some rescaling mechanism similar to the +classical quasi device independence, these could be integrated into +modern +.IR groff . +. +. +.IP \[bu] 2m +The B-spline command +.B D\[ti] +is correctly handled by the +.I intermediate output +parser, but the drawing routines aren't implemented in some of the +postprocessor programs. +. +. +.IP \[bu] 2m +The argument of the commands +.B s +and +.B x H +has the implicit unit scaled point\~\c +.B z +in +.IR groff , +while +.I classical troff +had point (\c +.BR p ). +. +This isn't an incompatibility, but a compatible extension, for both +units coincide for all devices without a +.I sizescale +parameter, including all classical and the +.I groff +text devices. +. +The few +.I groff +devices with a sizescale parameter either did not exist, had a +different name, or seem to have had a different resolution. +. +So conflicts with classical devices are very unlikely. +. +. +.ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +.IP \[bu] 2m +The position changing after the commands +.BR Dp , +.BR DP , +and +.B Dt +is illogical, but as old versions of groff used this feature it is +kept for compatibility reasons. +.\} \" @STUPID_DRAWING_POSITIONING +.el \{\ +.IP \[bu] 2m +Temporarily, there existed some confusion on the positioning after the +.B D +commands that are +.I groff +extensions. +. +This has been clarified by establishing the classical rule for all +groff drawing commands: +. +. +.RS +.P +.ft I +The position after a graphic object has been drawn is at its end; +for circles and ellipses, the "end" is at the right side. +.ft +.RE +. +. +.P +From this, the positionings specified for the drawing commands above +follow quite naturally. +.\} \" @STUPID_DRAWING_POSITIONING +. +.P +The differences between +.I groff +and +.I classical troff +are documented in +.MR groff_diff 7 . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +James Clark wrote an early version of this document, +which described only the differences between AT&T +device-independent +.IR troff 's +output format and that of GNU +.IR roff . +. +The present version was completely rewritten in 2001 by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.P +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.P +\[lq]Troff User's Manual\[rq] +by Joseph F.\& Ossanna, +1976 +(revised by Brian W.\& Kernighan, +1992), +AT&T Bell Laboratories Computing Science Technical Report No.\& 54, +widely called simply \[lq]CSTR\~#54\[rq], +documents the language, +device and font description file formats, +and device-independent output format +referred to collectively in +.I groff +documentation as +.RI \[lq]AT&T\~ troff \[rq]. +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97, +provides additional insights into the +device and font description file formats +and device-independent output format. +. +. +.TP +.MR groff 1 +documents the +.B \-Z +option and contains pointers to further +.I groff +documentation. +. +. +.TP +.MR groff 7 +describes the +.I groff +language, +including its escape sequences and system of units. +. +. +.TP +.MR groff_font 5 +details the device scaling parameters of device +.I DESC +files. +. +. +.TP +.MR \%troff 1 +generates the device-independent intermediate output documented here. +. +. +.TP +.MR roff 7 +presents historical aspects and the general structure of +.I roff +systems. +. +. +.TP +.MR groff_diff 7 +enumerates differences between the intermediate output produced by AT&T +.I troff \" AT&T +and that of +.IR groff . +. +. +.TP +.MR gxditview 1 +is a viewer for intermediate output. +. +. +.TP +.UR https://\:github.com/\:Alhadis/\:Roff\:.js/ +.I Roff.js +.UE +is a viewer for intermediate output written in JavaScript. +. +. +.P +.MR grodvi 1 , +.MR grohtml 1 , +.MR grolbp 1 , +.MR grolj4 1 , +.MR gropdf 1 , +.MR grops 1 , +and +.MR grotty 1 +are +.I groff +postprocessors. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_out_5_man_C] +.do rr *groff_groff_out_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man5/groff_tmac.5 b/upstream/fedora-40/man5/groff_tmac.5 new file mode 100644 index 00000000..bde81235 --- /dev/null +++ b/upstream/fedora-40/man5/groff_tmac.5 @@ -0,0 +1,1474 @@ +.TH groff_tmac 5 "24 January 2024" "groff 1.23.0" +.SH Name +groff_tmac \- macro files in the GNU +.I roff +typesetting system +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2000-2022 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff typesetting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, with no Front-Cover Texts, +.\" and with no Back-Cover Texts. +.\" +.\" A copy of the Free Documentation License is included as a file +.\" called FDL in the main directory of the groff source package. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_tmac_5_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" TODO: Consider parallelizing with our Texinfo node "Macro Packages". +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +Definitions of macros, +strings, +and registers for use in a +.MR roff 7 +document can be collected into +.IR "macro files" , +.I roff +input files designed to produce no output themselves but instead ease +the preparation of other +.I roff +documents. +. +There is no syntactical difference between a macro file and any other +.I roff +document; +only its purpose distinguishes it. +. +When a macro file is installed at a standard location, +named according to a certain convention, +and suitable for use by a general audience, +it is termed a +.IR "macro package" . +. +Macro packages can be loaded by supplying the +.B \-m +option to +.MR \%troff 1 +or a +.I groff +front end. +. +. +.P +Each macro package stores its macro, +string, +and register definitions in one or more +.I tmac +files. +. +This name originated in early Unix culture as an abbreviation of +.RI \[lq] troff \" generic +macros\[rq]. +. +. +.P +A macro file must have a name in the form +.RI name .tmac +(or +.IR tmac. name) +and be placed in a +.RI \[lq] tmac +directory\[rq] to be loadable with the +.BI \-m name +option. +. +Section \[lq]Environment\[rq] of +.MR \%troff 1 +lists these directories. +. +Alternatively, +a +.I groff +document requiring a macro file can load it with the +.B mso +(\[lq]macro source\[rq]) request. +. +. +.P +Like any other +.I roff +document, +a macro file can use the +.RB \[lq] so \[rq] +request (\[lq]source\[rq]) to load further files relative to its own +location. +. +. +.P +Macro files are named for their most noteworthy application, +but a macro file need not define any macros. +. +It can restrict itself to defining registers and strings or invoking +other +.I groff +requests. +. +It can even be empty. +. +. +.\" ==================================================================== +.SH "Macro packages" +.\" ==================================================================== +. +Macro packages come in two varieties; +those which assume responsibility for page layout and other critical +functions +(\[lq]major\[rq] or \[lq]full-service\[rq]) +and those which do not +(\[lq]supplemental\[rq] or \[lq]auxiliary\[rq]). +. +GNU +.I roff +provides most major macro packages found in AT&T and BSD Unix systems, +an additional full-service package, +and many supplemental packages. +. +Multiple full-service macro packages cannot be used by the same +document. +. +Auxiliary packages can generally be freely combined, +though attention to their use of the +.I groff +language name spaces for identifiers +(particularly registers, +macros, +strings, +and diversions) +should be paid. +. +Name space management was a significant challenge in AT&T +.IR troff ; +.IR groff 's +support for arbitrarily long identifiers affords few excuses for name +collisions, +apart from attempts at compatibility with the demands of historical +documents. +. +. +.\" ==================================================================== +.SS "Man pages" +.\" ==================================================================== +. +.TP +.I an +.TQ +.I man +.I an +is used to compose man pages in the format originating in Version\~7 +Unix (1979). +. +It has a small macro interface and is widely used; +see +.MR groff_man 7 . +. +. +.TP +.I doc +.TQ +.I mdoc +.I doc +is used to compose man pages in the format originating in 4.3BSD-Reno +(1990). +. +It provides many more features than +.IR an , +but is also larger, +more complex, +and not as widely adopted; +see +.MR groff_mdoc 7 . +. +. +.P +Because readers of man pages often do not know in advance which macros +are used to format a given document, +a wrapper is available. +. +. +.TP +.I \%andoc +.TQ +.I mandoc +This macro file, +specific to +.IR groff , +recognizes whether a document uses +.I man +or +.I mdoc +format and loads the corresponding macro package. +. +Multiple man pages, +in either format, +can be handled; +.I \%andoc +reloads each macro package as necessary. +. +. +.\" ==================================================================== +.SS "Full-service packages" +.\" ==================================================================== +. +The packages in this section provide a complete set of macros for +writing documents of any kind, up to whole books. +. +They are similar in functionality; it is a matter of taste which one +to use. +. +. +.TP +.I me +The classical +.I me +macro package; see +.MR groff_me 7 . +. +. +.TP +.I mm +The semi-classical +.I mm +macro package; see +.MR groff_mm 7 . +. +. +.TP +.I mom +The +.I mom +macro package, only available in groff. +. +As this was not based on other packages, it was freely designed as +quite a nice, modern macro package. +. +See +.MR groff_mom 7 . +. +. +.TP +.I ms +The classical +.I ms +macro package; see +.MR groff_ms 7 . +. +. +.\" ==================================================================== +.SS "Localization packages" +.\" ==================================================================== +. +For Western languages, +the localization file sets the hyphenation mode and loads hyphenation +patterns and exceptions. +. +Localization files can also adjust the date format and provide +translations of strings used by some of the full-service macro packages; +alter the input encoding +(see the next section); +and change the amount of additional inter-sentence space. +. +For Eastern languages, +the localization file defines character classes and sets flags on them. +. +By default, +.I troffrc +loads the localization file for English. +. +. +.TP +.I trans +loads localized strings used by various macro packages after their +localized forms have been prepared by a localization macro file. +. +. +.P +.I groff +provides the following localization files. +. +. +.TP +.I cs +Czech; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-2 by loading +.IR latin2.tmac . +. +. +.TP +.I de +.TQ +.I den +German; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-1 by loading +.IR latin1.tmac . +. +. +.IP +.I de.tmac +selects hyphenation patterns for traditional orthography, +and +.I den.tmac +does the same for the new orthography +(\[lq]Recht\%schreib\%reform\[rq]). +. +. +.TP +.I en +English. +. +. +.TP +.I fr +French; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-9 by loading +.IR latin9.tmac . +. +. +.TP +.I it +Italian; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +. +.TP +.I ja +Japanese. +. +. +.TP +.I sv +Swedish; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-1 by loading +.IR latin1.tmac . +. +Some of the localization of the +.I mm +package is handled separately; +see +.MR groff_mmse 7 . +. +. +.TP +.I zh +Chinese. +. +. +.\" ==================================================================== +.SS "Input encodings" +.\" ==================================================================== +. +.TP +.I latin1 +.TQ +.I latin2 +.TQ +.I latin5 +.TQ +.I latin9 +are various ISO\~8859 input encodings supported by +.IR groff . +. +On systems using ISO character encodings, +.I groff +loads +.I latin1.tmac +automatically at startup. +. +A document that uses Latin-2, +Latin-5, +or Latin-9 +can specify one of these alternative encodings. +. +. +.TP +.I cp1047 +provides support for EBCDIC-based systems. +. +On those platforms, +.I groff +loads +.I cp1047.tmac +automatically at startup. +. +. +.P +Because different input character codes constitute valid GNU +.I troff \" GNU +input on ISO and EBCDIC systems, +the +.I latin +macro files cannot be used on EBCDIC systems, +and +.I cp1047 +cannot be used on ISO systems. +. +. +.\" ==================================================================== +.SS "Auxiliary packages" +.\" ==================================================================== +. +The macro packages in this section are not intended for stand-alone +use, +but can add functionality to any other macro package or to plain +(\[lq]raw\[rq]) +.I groff +documents. +. +. +.\" TODO: +.\" a4 +.\" devtag +.\" doc-old +.\" europs +.\" psatk +.\" psfig +.TP +.I 62bit +provides macros for addition, +multiplication, +and division of 62-bit integers +(allowing safe multiplication of signed 31-bit integers, +for example). +. +. +.TP +.I hdtbl +allows the generation of tables using a syntax similar to the HTML table +model. +. +This Heidelberger table macro package is not a preprocessor, +which can be useful if the contents of table entries are determined by +macro calls or string interpolations. +. +Compare to +.MR \%tbl 1 . +. +It works only with the +.B ps +and +.B pdf +output devices. +. +See +.MR groff_hdtbl 7 . +. +. +.TP +.I papersize +enables the paper format to be set on the command line by giving a +.RB \[lq] \-d +.BI \%paper= format\c +\[rq] +option to +.IR \%troff . +. +Possible values for +.I format +are the ISO and DIN formats +.RB \[lq] A0 \[en] A6 \[rq], +.RB \[lq] B0 \[en] B6 \[rq], +.RB \[lq] C0 \[en] C6 \[rq], +and +.RB \[lq] D0 \[en] D6 \[rq]; +.\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7. +the U.S.\& formats +.RB \%\[lq] letter \[rq], +.RB \%\[lq] legal \[rq], +.RB \%\[lq] tabloid \[rq], +.RB \%\[lq] ledger \[rq], +.RB \%\[lq] statement \[rq], +and +.RB \%\[lq] executive \[rq]; +and the envelope formats +.RB \%\[lq] com10 \[rq], +.RB \%\[lq] monarch \[rq], +and +.RB \%\[lq] DL \[rq]. +. +All formats, +even those for envelopes, +are in portrait orientation: +the length measurement is vertical. +. +Appending \[lq]l\[rq] (ell) to any of these denotes landscape +orientation instead. +. +This macro file assumes one-inch horizontal margins, +and sets registers recognized by the +.I groff +.IR man , +.IR mdoc , +.IR mm , +.IR mom , +and +.I ms +packages to configure them accordingly. +. +If you want different margins, +you will need to use those packages' facilities, +or +.I \%troff +.B ll +and/or +.B po +requests to adjust them. +. +An output device typically requires command-line options +.B \-p +and +.B \-l +to override the paper dimensions and orientation, +respectively, +defined in its +.I DESC +file; +see subsection \[lq]Paper format\[rq] +of +.MR groff 1 . +. +This macro file is normally loaded at startup by the +.I troffrc +file when formatting for a typesetting device +(but not a terminal). +. +. +.TP +.I pdfpic +provides a single macro, +.BR PDFPIC , +to include a PDF graphic in a document using features of the +.B pdf +output driver. +. +For other output devices, +.B PDFPIC +calls +.BR PSPIC , +with which it shares an interface +(see below). +. +This macro file is normally loaded at startup by the +.I troffrc +file. +. +. +.TP +.I pic +supplies definitions of the macros +.BR PS , +.BR PE , +and +.BR PF , +usable with the +.MR \%pic 1 +preprocessor. +. +They center each picture. +. +Use it if your document does not use a full-service macro package, +or that package does not supply working +.I pic +macro definitions. +. +Except for +.I man +and +.IR mdoc , +those provided with +.I groff +already do so +(exception: +.I mm +employs the name +.B PF +for a different purpose). +. +. +.TP +.I pspic +provides a macro, +.BR PSPIC , +that includes a PostScript graphic in a document. +. +The +.BR ps , +.BR dvi , +.BR html , +and +.B xhtml +output devices support such inclusions; +for all other drivers, +the image is replaced with a rectangular border of the same size. +. +.I pspic.tmac +is loaded at startup by the +.I troffrc +file. +. +. +.IP +Its syntax is as follows. +.RS +.IP +\&\fB.PSPIC\fP \ +[\fB\-L\fP\|\ +|\|\fB\-R\fP\|\ +|\|\fB\-C\fP\|\ +|\|\fB\-I\fP\~\fIn\fP] \ +\fI\|file\fP [\fIwidth\fP [\,\fIheight\/\fP]] +.RE +. +. +.IP +.I file +is the name of the PostScript file; +.I width +and +.I height +give the desired width and height of the image. +. +If neither a +.I width +nor a +.I height +argument is specified, +the image's natural width +(as given in the file's bounding box) +or the current line length is used as the width, +whatever is smaller. +. +The +.I width +and +.I height +arguments may have scaling units attached; +the default scaling unit +.RB is\~ i . +. +.B PSPIC +scales the graphic uniformly in the horizontal and vertical directions +so that it is no more than +.I width +wide +and +.I height +high. +. +Option +.B \-C +centers the graphic horizontally; +this is the default. +. +.B \-L +and +.B \-R +left- and right-align the graphic, +respectively. +. +.B \-I +indents the graphic +.RI by\~ n +(with a default scaling unit +.RB of\~ m ). +. +. +.IP +To use +.B PSPIC +within a diversion, +we recommend extending it with the following code, +assuring that the diversion's width completely covers the image's width. +. +. +.RS +.IP +.EX +\&.am PSPIC +\&.\~\~vpt 0 +\&\[rs]h\[aq](\[rs]\[rs]n[ps\-offset]u + \[rs]\[rs]n[ps\-deswid]u)\[aq] +\&.\~\~sp \-1 +\&.\~\~vpt 1 +\&.. +.EE +.RE +. +. +.IP +Failure to load +.BR PSPIC 's +image argument is not an error. +. +(The +.B psbb +request does issue an error diagnostic.) +. +To make such a failure fatal, +append to the +.B pspic*error\-hook +macro. +. +. +.RS +.IP +.EX +\&.am pspic*error\-hook +\&.\~\~ab +\&.. +.EE +.RE +. +. +.TP +.I ptx +provides a macro, +.BR xx , +to format permuted index entries as produced by the GNU +.MR ptx 1 +program. +. +If your formatting needs differ, +copy the macro into your document and adapt it to your needs. +. +. +.TP +.I rfc1345 +defines special character escape sequences named for the glyph mnemonics +specified in RFC\~1345 and the digraph table of the Vim text editor. +. +See +.MR groff_rfc1345 7 . +. +. +.TP +.I sboxes +offers an interface to the +.RB \[lq] "pdf: background" \[rq] +device control command supported by +.MR gropdf 1 . +. +Using this package, +.I groff ms +documents can draw colored rectangles beneath any output. +. +.RS +.TP +.BI \%.BOXSTART\~SHADED\~ color\~\c +.BI \%OUTLINED\~ color\~\c +.BI \%INDENT\~ size\~\c +.BI \%WEIGHT\~ size +begins a box, +where the argument after +.B \%SHADED +gives the fill color and that after +.B \%OUTLINED +the border color. +. +Omit the former to get a borderless filled box and the latter for a +border with no fill. +. +The specified +.B \%WEIGHT +is used if the box is +.BR \%OUTLINED . +. +. +.IP +.B \%INDENT +precedes a value which leaves a gap between the border and the contents +inside the box. +. +. +.IP +Each +.I color +must be a defined +.I groff +color name, +and each +.I size +a valid +.I groff +numeric expression. +. +The keyword/value pairs can be specified in any order. +.RE +. +. +.IP +Boxes can be stacked, +so you can start a box within another box; +usually the later boxes would be smaller than the containing box, +but this is not enforced. +. +When using +.BR \%BOXSTART , +the left position is the current indent minus the +.B \%INDENT +in the command, +and the right position is the left position +(calculated above) +plus the current line length and twice the indent. +. +. +.RS +.TP +.B \%.BOXSTOP +takes no parameters. +. +It closes the most recently started box at the current vertical position +after adding its +.B \%INDENT +spacing. +.RE +. +. +.IP +Your +.I groff +documents can conditionally exercise the +.I sboxes +macros. +. +The register +.B \%GSBOX +is defined if the package is loaded, +and interpolates a true value if the +.B pdf +output device is in use. +. +. +.IP +.I sboxes +furthermore hooks into the +.MR groff_ms 7 +package to receive notifications when footnotes are growing, +so that it can close boxes on a page before footnotes are printed. +. +When that condition obtains, +.I sboxes +will close open boxes two points +above the footnote separator and re-open them on the next page. +. +(This amount probably will not match the box's +.BR \%INDENT .) +. +. +.IP +See +.UR file:///usr/\:\%share/\:\%doc/\:\%groff/\:\%msboxes\:.pdf +\[lq]Using PDF boxes with +.I groff +and the +.I ms +macros\[rq] +.UE +for a demonstration. +. +. +.TP +.I trace +aids the debugging of +.I groff +documents by tracing macro calls. +. +See +.MR groff_trace 7 . +. +. +.TP +.I www +defines macros corresponding to HTML elements. +. +See +.MR groff_www 7 . +. +. +.\" ==================================================================== +.SH Naming +.\" ==================================================================== +. +AT&T +.I nroff \" AT&T +and +.I troff \" AT&T +were implemented before the conventions of the modern C +.MR getopt 3 +call evolved, +and used a naming scheme for macro packages that looks odd to modern +eyes. +. +Macro packages were typically loaded using the +.B \-m +option to the formatter; +when directly followed by its argument without an intervening space, +this looked like a long option preceded by a single minus\[em]a +sensation in the computer stone age. +. +Macro packages therefore came to be known by names that started with the +letter \[lq]m\[rq], +which was omitted from the name of the macro file as stored on disk. +. +For example, +the manuscript macro package was stored as +.I tmac.s +and loaded with the option +.BR \-ms . +. +. +.P +.I groff +commands permit space between an option and its argument. +. +The syntax +.RB \[lq] "groff \-m s" \[rq] +makes the macro file name more clear but may surprise users familiar +with the original convention, +unaware that the package's \[lq]real\[rq] name was \[lq]s\[rq] all +along. +. +For such packages of long pedigree, +.I groff +accommodates different users' expectations by supplying wrapper macro +files that load the desired file with +.B mso +requests. +. +Thus, +all of +.RB \[lq] "groff \-m s" \[rq], +.RB \[lq] "groff \-m ms" \[rq], +.RB \[lq] "groff \-ms" \[rq], +and +.RB \[lq] "groff \-mms" \[rq] +serve to load the manuscript macros. +. +. +.P +Wrappers are not provided for packages of more recent vintage, +like +.IR www.tmac . +. +. +.P +As noted in passing above, +AT&T +.I troff \" AT&T +named macro files in the form +.IR tmac. name. +. +It has since become conventional in operating systems to use a suffixed +file name extension to suggest a file type or format. +. +. +.\" ==================================================================== +.SH Inclusion +.\" ==================================================================== +. +The traditional method of employing a macro package is to specify the +.B \-m +.I package +option to the formatter, +which then reads +.IR package 's +macro file prior to any input files. +. +Historically, +.I package +was sought in a file named +.IR tmac. package +(that is, +with a +.RB \[lq] tmac.\& \[rq] +prefix). +. +GNU +.I troff \" GNU +searches for +.RI package .tmac +in the macro path; +if not found, +it looks for +.IR tmac. package +instead, +and vice versa. +. +. +.P +Alternatively, +one could include a macro file by using the request +.RB \[lq] .so +.IR file-name \[rq] +in the document; +.I file-name +is resolved relative to the location of the input document. +. +GNU +.I troff \" GNU +offers an improved feature in the similar request +.RB \[lq] mso +.IR package-file-name \[rq], +which searches the macro path for +.IR package-file-name . +. +Because its argument is a file name, +its +.RB \[lq] .tmac \[rq] +component must be included for the file to be found; +however, +as a convenience, +if opening it fails, +.B mso +strips any such suffix and tries again with a +.RB \[lq] tmac.\& \[rq] +prefix, +and vice versa. +. +. +.P +If a sourced file requires preprocessing, +for example if it includes +.I tbl \" generic +tables +or +.I eqn \" generic +equations, +the preprocessor +.MR \%soelim 1 +must be used. +. +This can be achieved with a pipeline or, +in +.IR groff , +by specifying +the +.B \-s +option to the formatter +(or front end). +. +.MR man 1 +librarian programs generally call +.I \%soelim +automatically. +. +(Macro packages themselves generally do not require preprocessing.) +. +. +.ig +.\" ==================================================================== +.SH Convention +.\" ==================================================================== +. +.\" This section does not fit into the framework of this document. +. +There is a convention that is supported by many modern roff +typesetters and +.MR man 1 +programs, the +.I preprocessor word +described in the following. +. +.P +If the first line in a document is a comment, the first word (after the +comment characters and a blank) constitutes the +.B preprocessor +.BR word . +That means that the letters of this word are interpreted as +abbreviations for those preprocessor commands that should be run +when formatting the document. +. +Mostly, only the letters corresponding to the options for the +preprocessors are recognized, +\[oq]e\[cq] +(for +.IR eqn ), +.\" \[oq]G\[cq], +.\" \[oq]g\[cq], +\[oq]p\[cq] +(for +.IR pic ), +\[oq]R\[cq] +(for +.IR refer ), +\[oq]s\[cq] +(for +.IR soelim ), +and +\[oq]t\[cq] +(for +.IR tbl ). +(see +.MR roff 7 ). +. +. +.P +Besides being a good reminder for the user, some formatters (like the +.MR man 1 +program) are even able to automatically start the preprocessors +specified in the preprocessor word, but do not bet on this. +. +. +.P +The +.I man +program handles some preprocessors automatically, such that in +man\~pages only the following characters should be used: +\[oq]e\[cq], \[oq]p\[cq], and \[oq]t\[cq]. +. +. +.. +.\" ==================================================================== +.SH "Writing macros" +.\" ==================================================================== +. +A +.MR roff 7 +document is a text file that is enriched by predefined formatting +constructs, such as requests, escape sequences, strings, numeric +registers, and macros from a macro package. +. +These elements are described in +.MR roff 7 . +. +. +.P +To give a document a personal style, it is most useful to extend the +existing elements by defining some macros for repeating tasks; the best +place for this is near the beginning of the document or in a separate +file. +. +. +.P +Macros without arguments are just like strings. +. +But the full power of macros occurs when arguments are passed with a +macro call. +. +Within the macro definition, the arguments are available as the escape +sequences +.BR \[rs]$1 , +\&.\|.\|., +.BR \[rs]$9 , +.BR \[rs]$[ .\|.\|. ] , +.BR \[rs]$* , +and +.BR \[rs]$@ , +the name under which the macro was called is in +.BR \[rs]$0 , +and the number of arguments is in register +.BR \[rs]n[.$] ; +see +.MR groff 7 . +. +. +.\" ==================================================================== +.SS "Draft mode" +.\" ==================================================================== +. +Writing groff macros is easy when the escaping mechanism is temporarily +disabled. +. +In groff, this is done by enclosing the macro definition(s) within a +pair of +.B .eo +and +.B .ec +requests. +. +Then the body in the macro definition is just like a normal part of +the document \[em] text enhanced by calls of requests, macros, +strings, registers, etc. +. +For example, the code above can be written in a simpler way by +. +. +.IP +.ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\" +.ds @2 arguments:\" +.EX +\&.eo +\&.ds midpart was called with the following +\&.de print_args +\&\*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2] +\&\[rs]$* +\&.. +\&.ec +.EE +.rm @1 +.rm @2 +. +. +.P +Unfortunately, draft mode cannot be used universally. +. +Although it is good enough for defining normal macros, draft mode +fails with advanced applications, such as indirectly defined +strings, registers, etc. +. +An optimal way is to define and test all macros in draft mode and then +do the backslash doubling as a final step; do not forget to remove the +.I .eo +request. +. +. +.\" ==================================================================== +.SS "Tips for macro definitions" +.\" ==================================================================== +. +.IP \(bu +Start every line with a dot, for example, by using the groff request +.B .nop +for text lines, or write your own macro that handles also text lines +with a leading dot. +. +.RS +.IP +.EX +\&.de Text +\&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs] +\&.\ \ \ \ return +\&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs]) +\&.. +.EE +.RE +. +.IP \(bu +Write a comment macro that works both for copy and draft modes; +since the escape character is off in draft mode, +trouble might occur when comment escape sequences are used. +. +For example, the following macro just ignores its arguments, so it +acts like a comment line: +. +.RS +.IP +.EX +\&.de\ c +\&.. +\&.c\ This\ is\ like\ a\ comment\ line. +.EE +.RE +. +.IP \(bu +In long macro definitions, make ample use of comment lines or +almost-empty lines (this is, lines which have a leading dot +and nothing else) for a better structuring. +. +.IP \(bu +To increase readability, use groff's indentation facility for +requests and macro calls (arbitrary whitespace after the leading dot). +. +. +.\" ==================================================================== +.SS Diversions +.\" ==================================================================== +. +Diversions can be used to implement quite advanced programming +constructs. +. +They are comparable to pointers to large data structures in the +C\~programming language, but their usage is quite different. +. +. +.P +In their simplest form, diversions are multi-line strings, but +diversions get their power when used dynamically within macros. +. +The (formatted) information stored in a diversion can be retrieved by +calling the diversion just like a macro. +. +. +.P +Most of the problems arising with diversions can be avoided if you +remember that diversions always store complete lines. +. +Using diversions when the line buffer has not been flushed produces +strange results; not knowing this, many people get desperate about +diversions. +. +To ensure that a diversion works, add line breaks at the right +places. +. +To be safe, enclose everything that has to do with diversions within +a pair of line breaks; for example, by explicitly using +.B .br +requests. +. +This rule should be applied to diversion definition, both inside and +outside, and to all calls of diversions. +. +This is a bit of overkill, but it works nicely. +. +. +.P +(If you really need diversions which should ignore the current partial +line, use environments to save the current partial line and/\:or use the +.B .box +request.) +. +. +.P +The most powerful feature using diversions is to start a diversion +within a macro definition and end it within another macro. +. +Then everything between each call of this macro pair is stored within +the diversion and can be manipulated from within the macros. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME , +.MT wl@\:gnu\:.org +Werner Lemberg +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.LP +The +.UR https://\:wiki\:.linuxfoundation\:.org/\:lsb/\:fhs +Filesystem Hierarchy Standard +.UE +is maintained by the Linux Foundation. +. +. +.TP +.MR groff 1 +is an overview of the +.I groff +system. +. +. +.TP +.MR groff_man 7 , +.TQ +.MR groff_mdoc 7 , +.TQ +.MR groff_me 7 , +.TQ +.MR groff_mm 7 , +.TQ +.MR groff_mom 7 , +.TQ +.MR groff_ms 7 , +.TQ +.MR groff_rfc1345 7 , +.TQ +.MR groff_trace 7 , +\~and +.TQ +.MR groff_www 7 +are +.I groff +macro packages. +. +. +.TP +.MR groff 7 +summarizes the language recognized by GNU +.IR troff . \" GNU +. +. +.TP +.MR troff 1 +documents the default macro file search path. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_tmac_5_man_C] +.do rr *groff_groff_tmac_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/upstream/fedora-40/man5/group.5 b/upstream/fedora-40/man5/group.5 new file mode 100644 index 00000000..41212819 --- /dev/null +++ b/upstream/fedora-40/man5/group.5 @@ -0,0 +1,55 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:06:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH group 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +group \- user group file +.SH DESCRIPTION +The +.I /etc/group +file is a text file that defines the groups on the system. +There is one entry per line, with the following format: +.P +.in +4n +.EX +group_name:password:GID:user_list +.EE +.in +.P +The fields are as follows: +.TP +.I group_name +the name of the group. +.TP +.I password +the (encrypted) group password. +If this field is empty, no password is needed. +.TP +.I GID +the numeric group ID. +.TP +.I user_list +a list of the usernames that are members of this group, separated by commas. +.SH FILES +.I /etc/group +.SH BUGS +As the 4.2BSD +.BR initgroups (3) +man page says: no one seems to keep +.I /etc/group +up-to-date. +.SH SEE ALSO +.BR chgrp (1), +.BR gpasswd (1), +.BR groups (1), +.BR login (1), +.BR newgrp (1), +.BR sg (1), +.BR getgrent (3), +.BR getgrnam (3), +.BR gshadow (5), +.BR passwd (5), +.BR vigr (8) diff --git a/upstream/fedora-40/man5/homed.conf.5 b/upstream/fedora-40/man5/homed.conf.5 new file mode 100644 index 00000000..af99d452 --- /dev/null +++ b/upstream/fedora-40/man5/homed.conf.5 @@ -0,0 +1,110 @@ +'\" t +.TH "HOMED\&.CONF" "5" "" "systemd 255" "homed.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +homed.conf, homed.conf.d \- Home area/user account manager configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/homed\&.conf +.PP +/etc/systemd/homed\&.conf\&.d/*\&.conf +.PP +/run/systemd/homed\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/homed\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These configuration files control default parameters for home areas/user accounts created and managed by +\fBsystemd-homed.service\fR(8)\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +The following options are available in the [Home] section: +.PP +\fIDefaultStorage=\fR +.RS 4 +The default storage to use for home areas\&. Takes one of +"luks", +"fscrypt", +"directory", +"subvolume", +"cifs"\&. For details about these options, see +\fBhomectl\fR(1)\&. If not configured or assigned the empty string, the default storage is automatically determined: if not running in a container environment and +/home/ +is not itself encrypted, defaults to +"luks"\&. Otherwise defaults to +"subvolume" +if +/home/ +is on a btrfs file system, and +"directory" +otherwise\&. Note that the storage selected on the +\fBhomectl\fR +command line always takes precedence\&. +.sp +Added in version 246\&. +.RE +.PP +\fIDefaultFileSystemType=\fR +.RS 4 +When using +"luks" +as storage (see above), selects the default file system to use inside the user\*(Aqs LUKS volume\&. Takes one of +"btrfs", +"ext4" +or +"xfs"\&. If not specified defaults to +"btrfs"\&. This setting has no effect if a different storage mechanism is used\&. The file system type selected on the +\fBhomectl\fR +command line always takes precedence\&. +.sp +Added in version 246\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-homed.service\fR(8) diff --git a/upstream/fedora-40/man5/host.conf.5 b/upstream/fedora-40/man5/host.conf.5 new file mode 100644 index 00000000..867c206f --- /dev/null +++ b/upstream/fedora-40/man5/host.conf.5 @@ -0,0 +1,204 @@ +.\" Copyright (c) 1997 Martin Schulze (joey@infodrom.north.de) +.\" Much of the text is copied from the manpage of resolv+(8). +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2003-08-23 Martin Schulze Updated according to glibc 2.3.2 +.TH host.conf 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +host.conf \- resolver configuration file +.SH DESCRIPTION +The file +.I /etc/host.conf +contains configuration information specific to the resolver library. +It should contain one configuration keyword per line, followed by +appropriate configuration information. +The following keywords are recognized: +.TP +.I trim +This keyword may be listed more than once. +Each time it should be +followed by a list of domains, separated by colons (\[aq]:\[aq]), semicolons +(\[aq];\[aq]) or commas (\[aq],\[aq]), with the leading dot. +When set, the +resolver library will automatically trim the given domain name from the +end of any hostname resolved via DNS. +This is intended for use with +local hosts and domains. +(Related note: +.I trim +will not affect hostnames gathered via NIS or the +.BR hosts (5) +file. +Care should be taken to +ensure that the first hostname for each entry in the hosts file is +fully qualified or unqualified, as appropriate for the local +installation.) +.TP +.I multi +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library will return all valid addresses for a host that +appears in the +.I /etc/hosts +file, +instead of only the first. +This is +.I off +by default, as it may cause a substantial performance loss at sites +with large hosts files. +.TP +.I reorder +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library +will attempt to reorder host addresses so that local addresses +(i.e., on the same subnet) are listed first when a +.BR gethostbyname (3) +is performed. +Reordering is done for all lookup methods. +The default value is +.IR off . +.SH ENVIRONMENT +The following environment variables can be used to allow users to +override the behavior which is configured in +.IR /etc/host.conf : +.TP +.B RESOLV_HOST_CONF +If set, this variable points to a file that should be read instead of +.IR /etc/host.conf . +.TP +.B RESOLV_MULTI +Overrides the +.I multi +command. +.TP +.B RESOLV_REORDER +Overrides the +.I reorder +command. +.TP +.B RESOLV_ADD_TRIM_DOMAINS +A list of domains, +separated by +colons (\[aq]:\[aq]), semicolons (\[aq];\[aq]), or commas (\[aq],\[aq]), +with the leading dot, +which will be added to the list of domains that should be trimmed. +.TP +.B RESOLV_OVERRIDE_TRIM_DOMAINS +A list of domains, +separated by +colons (\[aq]:\[aq]), semicolons (\[aq];\[aq]), or commas (\[aq],\[aq]), +with the leading dot, +which will replace the list of domains that should be trimmed. +Overrides the +.I trim +command. +.SH FILES +.TP +.I /etc/host.conf +Resolver configuration file +.TP +.I /etc/resolv.conf +Resolver configuration file +.TP +.I /etc/hosts +Local hosts database +.SH NOTES +The following differences exist compared to the original implementation. +A new command +.I spoof +and a new environment variable +.B RESOLV_SPOOF_CHECK +can take arguments like +.IR off ", " nowarn ", and " warn . +Line comments can appear anywhere and not only at the beginning of a line. +.SS Historical +The +.BR nsswitch.conf (5) +file is the modern way of controlling the order of host lookups. +.P +In glibc 2.4 and earlier, the following keyword is recognized: +.TP +.I order +This keyword specifies how host lookups are to be performed. +It should be followed by one or more lookup methods, separated by commas. +Valid methods are +.IR bind ", " hosts ", and " nis . +.TP +.B RESOLV_SERV_ORDER +Overrides the +.I order +command. +.P +.\" commit 7d68cdaa4f748e87ee921f587ee2d483db624b3d +Since glibc 2.0.7, and up through glibc 2.24, +the following keywords and environment variable +have been recognized but never implemented: +.TP +.I nospoof +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library will attempt to prevent hostname spoofing to +enhance the security of +.BR rlogin " and " rsh . +It works as follows: after performing a host address lookup, +the resolver library will perform a hostname lookup for that address. +If the two hostnames +do not match, the query fails. +The default value is +.IR off . +.TP +.I spoofalert +Valid values are +.IR on " and " off . +If this option is set to +.I on +and the +.I nospoof +option is also set, +the resolver library will log a warning of the error via the +syslog facility. +The default value is +.IR off . +.TP +.I spoof +Valid values are +.IR off ", " nowarn ", and " warn . +If this option is set to +.IR off , +spoofed addresses are permitted and no warnings will be emitted +via the syslog facility. +If this option is set to +.IR warn , +the resolver library will attempt to prevent hostname spoofing to +enhance the security and log a warning of the error via the syslog +facility. +If this option is set to +.IR nowarn , +the resolver library will attempt to prevent hostname spoofing to +enhance the security but not emit warnings via the syslog facility. +Setting this option to anything else is equal to setting it to +.IR nowarn . +.TP +.B RESOLV_SPOOF_CHECK +Overrides the +.IR nospoof ", " spoofalert ", and " spoof +commands in the same way as the +.I spoof +command is parsed. +Valid values are +.IR off ", " nowarn ", and " warn . +.SH SEE ALSO +.BR gethostbyname (3), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR resolv.conf (5), +.BR hostname (7), +.BR named (8) diff --git a/upstream/fedora-40/man5/hostname.5 b/upstream/fedora-40/man5/hostname.5 new file mode 100644 index 00000000..ff5139a9 --- /dev/null +++ b/upstream/fedora-40/man5/hostname.5 @@ -0,0 +1,130 @@ +'\" t +.TH "HOSTNAME" "5" "" "systemd 255" "hostname" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +hostname \- Local hostname configuration file +.SH "SYNOPSIS" +.PP +/etc/hostname +.SH "DESCRIPTION" +.PP +The +/etc/hostname +file configures the name of the local system\&. Unless overridden as described in the next section, +\fBsystemd\fR(1) +will set this hostname during boot using the +\fBsethostname\fR(2) +system call\&. +.PP +The file should contain a single newline\-terminated hostname string\&. Comments (lines starting with a +"#") are ignored\&. The hostname should be composed of up to 64 7\-bit ASCII lower\-case alphanumeric characters or hyphens forming a valid DNS domain name\&. It is recommended that this name contains only a single label, i\&.e\&. without any dots\&. Invalid characters will be filtered out in an attempt to make the name valid, but obviously it is recommended to use a valid name and not rely on this filtering\&. +.PP +You may use +\fBhostnamectl\fR(1) +to change the value of this file during runtime from the command line\&. Use +\fBsystemd-firstboot\fR(1) +to initialize it on mounted (but not booted) system images\&. +.SH "HOSTNAME SEMANTICS" +.PP +\fBsystemd\fR(1) +and the associated tools will obtain the hostname in the following ways: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the kernel command line parameter +\fIsystemd\&.hostname=\fR +specifies a valid hostname, +\fBsystemd\fR(1) +will use it to set the hostname during early boot, see +\fBkernel-command-line\fR(7), +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, the "static" hostname specified by +/etc/hostname +as described above will be used\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, a transient hostname may be set during runtime, for example based on information in a DHCP lease, see +\fBsystemd-hostnamed.service\fR(8)\&. Both +\m[blue]\fBNetworkManager\fR\m[]\&\s-2\u[1]\d\s+2 +and +\fBsystemd-networkd.service\fR(8) +allow this\&. Note that +\fBsystemd-hostnamed.service\fR(8) +gives higher priority to the static hostname, so the transient hostname will only be used if the static hostname is not configured\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, a fallback hostname configured at compilation time will be used ("localhost")\&. +.RE +.PP +Effectively, the static hostname has higher priority than a transient hostname, which has higher priority than the fallback hostname\&. Transient hostnames are equivalent, so setting a new transient hostname causes the previous transient hostname to be forgotten\&. The hostname specified on the kernel command line is like a transient hostname, with the exception that it has higher priority when the machine boots\&. Also note that those are the semantics implemented by systemd tools, but other programs may also set the hostname\&. +.SH "HISTORY" +.PP +The simple configuration file format of +/etc/hostname +originates from Debian GNU/Linux\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsethostname\fR(2), +\fBhostname\fR(1), +\fBhostname\fR(7), +\fBmachine-id\fR(5), +\fBmachine-info\fR(5), +\fBhostnamectl\fR(1), +\fBsystemd-hostnamed.service\fR(8), +\fBsystemd-firstboot\fR(1) +.SH "NOTES" +.IP " 1." 4 +NetworkManager +.RS 4 +\%https://developer.gnome.org/NetworkManager/stable/ +.RE diff --git a/upstream/fedora-40/man5/hosts.5 b/upstream/fedora-40/man5/hosts.5 new file mode 100644 index 00000000..e111ccb8 --- /dev/null +++ b/upstream/fedora-40/man5/hosts.5 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2000 Manoj Srivastava +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Minor polishing, aeb +.\" Modified, 2002-06-16, Mike Coleman +.\" +.TH hosts 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +hosts \- static table lookup for hostnames +.SH SYNOPSIS +.nf +.B /etc/hosts +.fi +.SH DESCRIPTION +This manual page describes the format of the +.I /etc/hosts +file. +This file is a simple text file that associates IP addresses +with hostnames, one line per IP address. +For each host a single +line should be present with the following information: +.RS +.P +IP_address canonical_hostname [aliases...] +.RE +.P +The IP address can conform to either IPv4 or IPv6. +Fields of the entry are separated by any number of blanks and/or +tab characters. +Text from a "#" character until the end of the line is +a comment, and is ignored. +Host names may contain only alphanumeric +characters, minus signs ("\-"), and periods ("."). +They must begin with an +alphabetic character and end with an alphanumeric character. +Optional aliases provide for name changes, alternate spellings, +shorter hostnames, or generic hostnames (for example, +.IR localhost ). +If required, a host may have two separate entries in this file; +one for each version of the Internet Protocol (IPv4 and IPv6). +.P +The Berkeley Internet Name Domain (BIND) Server implements the +Internet name server for UNIX systems. +It augments or replaces the +.I /etc/hosts +file or hostname lookup, and frees a host from relying on +.I /etc/hosts +being up to date and complete. +.P +In modern systems, even though the host table has been superseded by +DNS, it is still widely used for: +.TP +.B bootstrapping +Most systems have a small host table containing the name and address +information for important hosts on the local network. +This is useful +when DNS is not running, for example during system bootup. +.TP +.B NIS +Sites that use NIS use the host table as input to the NIS host +database. +Even though NIS can be used with DNS, most NIS sites still +use the host table with an entry for all local hosts as a backup. +.TP +.B isolated nodes +Very small sites that are isolated from the network use the host table +instead of DNS. +If the local information rarely changes, and the +network is not connected to the Internet, DNS offers little +advantage. +.SH FILES +.I /etc/hosts +.SH NOTES +Modifications to this file normally take effect immediately, +except in cases where the file is cached by applications. +.SS Historical notes +RFC\ 952 gave the original format for the host table, though it has +since changed. +.P +Before the advent of DNS, the host table was the only way of resolving +hostnames on the fledgling Internet. +Indeed, this file could be +created from the official host data base maintained at the Network +Information Control Center (NIC), though local changes were often +required to bring it up to date regarding unofficial aliases and/or +unknown hosts. +The NIC no longer maintains the hosts.txt files, +though looking around at the time of writing (circa 2000), there are +historical hosts.txt files on the WWW. +I just found three, from 92, +94, and 95. +.SH EXAMPLES +.EX +# The following lines are desirable for IPv4 capable hosts +127.0.0.1 localhost +\& +# 127.0.1.1 is often used for the FQDN of the machine +127.0.1.1 thishost.example.org thishost +192.168.1.10 foo.example.org foo +192.168.1.13 bar.example.org bar +146.82.138.7 master.debian.org master +209.237.226.90 www.opensource.org +\& +# The following lines are desirable for IPv6 capable hosts +::1 localhost ip6\-localhost ip6\-loopback +ff02::1 ip6\-allnodes +ff02::2 ip6\-allrouters +.EE +.SH SEE ALSO +.BR hostname (1), +.BR resolver (3), +.BR host.conf (5), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.P +Internet RFC\ 952 +.\" .SH AUTHOR +.\" This manual page was written by Manoj Srivastava , +.\" for the Debian GNU/Linux system. diff --git a/upstream/fedora-40/man5/hosts.equiv.5 b/upstream/fedora-40/man5/hosts.equiv.5 new file mode 100644 index 00000000..53d79104 --- /dev/null +++ b/upstream/fedora-40/man5/hosts.equiv.5 @@ -0,0 +1,212 @@ +.\" Copyright (c) 1995 Peter Tobias +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.TH hosts.equiv 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +hosts.equiv \- list of hosts and users that are granted "trusted" +.B r +command access to your system +.SH DESCRIPTION +The file +.I /etc/hosts.equiv +allows or denies hosts and users to use +the \fBr\fP-commands (e.g., +.BR rlogin , +.BR rsh , +or +.BR rcp ) +without +supplying a password. +.P +The file uses the following format: +.TP +\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP +.P +The +.I hostname +is the name of a host which is logically equivalent +to the local host. +Users logged into that host are allowed to access +like-named user accounts on the local host without supplying a password. +The +.I hostname +may be (optionally) preceded by a plus (+) sign. +If the plus sign is used alone, it allows any host to access your system. +You can explicitly deny access to a host by preceding the +.I hostname +by a minus (\-) sign. +Users from that host must always supply additional credentials, +including possibly a password. +For security reasons you should always +use the FQDN of the hostname and not the short hostname. +.P +The +.I username +entry grants a specific user access to all user +accounts (except root) without supplying a password. +That means the +user is NOT restricted to like-named accounts. +The +.I username +may +be (optionally) preceded by a plus (+) sign. +You can also explicitly +deny access to a specific user by preceding the +.I username +with +a minus (\-) sign. +This says that the user is not trusted no matter +what other entries for that host exist. +.P +Netgroups can be specified by preceding the netgroup by an @ sign. +.P +Be extremely careful when using the plus (+) sign. +A simple typographical +error could result in a standalone plus sign. +A standalone plus sign is +a wildcard character that means "any host"! +.SH FILES +.I /etc/hosts.equiv +.SH NOTES +Some systems will honor the contents of this file only when it has owner +root and no write permission for anybody else. +Some exceptionally +paranoid systems even require that there be no other hard links to the file. +.P +Modern systems use the Pluggable Authentication Modules library (PAM). +With PAM a standalone plus sign is considered a wildcard +character which means "any host" only when the word +.I promiscuous +is added to the auth component line in your PAM file for +the particular service +.RB "(e.g., " rlogin ). +.SH EXAMPLES +Below are some example +.I /etc/host.equiv +or +.I \[ti]/.rhosts +files. +.P +Allow any user to log in from any host: +.P +.in +4n +.EX ++ +.EE +.in +.P +Allow any user from +.I host +with a matching local account to log in: +.P +.in +4n +.EX +host +.EE +.in +.P +Note: the use of +.I +host +is never a valid syntax, +including attempting to specify that any user from the host is allowed. +.P +Allow any user from +.I host +to log in: +.P +.in +4n +.EX +host + +.EE +.in +.P +Note: this is distinct from the previous example +since it does not require a matching local account. +.P +Allow +.I user +from +.I host +to log in as any non-root user: +.P +.in +4n +.EX +host user +.EE +.in +.P +Allow all users with matching local accounts from +.I host +to log in except for +.IR baduser : +.P +.in +4n +.EX +host \-baduser +host +.EE +.in +.P +Deny all users from +.IR host : +.P +.in +4n +.EX +\-host +.EE +.in +.P +Note: the use of +.I "\-host\ \-user" +is never a valid syntax, +including attempting to specify that a particular user from the host +is not trusted. +.P +Allow all users with matching local accounts on all hosts in a +.IR netgroup : +.P +.in +4n +.EX ++@netgroup +.EE +.in +.P +Disallow all users on all hosts in a +.IR netgroup : +.P +.in +4n +.EX +\-@netgroup +.EE +.in +.P +Allow all users in a +.I netgroup +to log in from +.I host +as any non-root user: +.P +.in +4n +.EX +host +@netgroup +.EE +.in +.P +Allow all users with matching local accounts on all hosts in a +.I netgroup +except +.IR baduser : +.P +.in +4n +.EX ++@netgroup \-baduser ++@netgroup +.EE +.in +.P +Note: the deny statements must always precede the allow statements because +the file is processed sequentially until the first matching rule is found. +.SH SEE ALSO +.BR rhosts (5), +.BR rlogind (8), +.BR rshd (8) diff --git a/upstream/fedora-40/man5/icewm-env.5 b/upstream/fedora-40/man5/icewm-env.5 new file mode 100644 index 00000000..783678dc --- /dev/null +++ b/upstream/fedora-40/man5/icewm-env.5 @@ -0,0 +1,128 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-ENV 5" +.TH ICEWM-ENV 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-env \- icewm environment configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/env +\& $XDG_CONFIG_HOME/icewm/env +\& $HOME/.icewm/env +\& /etc/icewm/env +\& /usr/share/icewm/env +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +\&\fBicewm\-session\fR\|(1) loads additional environment variables from the file +\&\fIenv\fR before it does anything else. These variables are then propagated +to all other processes, including \fBicewm\fR\|(1), via their environment. +.SS FORMAT +.IX Subsection "FORMAT" +Each line is subjected to POSIX shell expansion by \fBwordexp\fR\|(3). +Comment lines starting by a hash-sign (\f(CW\*(C`#\*(C'\fR) are ignored. +\&\fBicewm\-session\fR\|(1) will load those expanded lines that contain a name, +followed by an equals sign, followed by the value (which may be empty). +.PP +The word \fBunset\fR begins a line with names to be removed from the +environment. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +.Vb 2 +\& # This is a comment. +\& # And another. +\& +\& XDG_CURRENT_DESKTOP="ICEWM" +\& XDG_MENU_PREFIX="unexicon\-" +\& +\& START_DATE=\`date\` +\& START_FROM=\`pwd\` +.Ve +.SS FILES +.IX Subsection "FILES" +\&\fBicewm\-session\fR\|(1) looks for the \fIenv\fR file in the following locations: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/env +\& $XDG_CONFIG_HOME/icewm/env +\& $HOME/.icewm/env +\& /etc/icewm/env +\& /usr/share/icewm/env +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-session\fR\|(1), +\&\fBicewm\-startup\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-focus_mode.5 b/upstream/fedora-40/man5/icewm-focus_mode.5 new file mode 100644 index 00000000..e4e9d6d2 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-focus_mode.5 @@ -0,0 +1,117 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-FOCUS_MODE 5" +.TH ICEWM-FOCUS_MODE 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-focus_mode \- icewm focus mode configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/focus_mode +\& $XDG_CONFIG_HOME/icewm/focus_mode +\& $HOME/.icewm/focus_mode +\& /etc/icewm/focus_mode +\& /usr/share/icewm/focus_mode +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +Defines the initial value for \f(CW\*(C`FocusMode\*(C'\fR. Its default value is +\&\f(CW\*(C`FocusMode=1\*(C'\fR (Click-to-focus). This can be changed via the menu. +\&\fBicewm\fR will save the Focus menu choice in this file. +.SS FORMAT +.IX Subsection "FORMAT" +The file contains a single line containing the preferences assignment +for \fBFocusMode\fR. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +The following is my \fIfocus_mode\fR file: +.PP +.Vb 1 +\& FocusMode=2 +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fIfocus_mode\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/focus_mode +\& $XDG_CONFIG_HOME/icewm/focus_mode +\& $HOME/.icewm/focus_mode +\& /usr/share/icewm/focus_mode +\& /usr/local/share/icewm/focus_mode +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-preferences\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-keys.5 b/upstream/fedora-40/man5/icewm-keys.5 new file mode 100644 index 00000000..2e942c95 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-keys.5 @@ -0,0 +1,220 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-KEYS 5" +.TH ICEWM-KEYS 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-keys \- icewm keys configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/keys +\& $XDG_CONFIG_HOME/icewm/keys +\& $HOME/.icewm/keys +\& /etc/icewm/keys +\& /usr/share/icewm/keys +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \f(CW\*(C`keys\*(C'\fR file defines global keybindings to launch applications. +A keybinding has three parts: the word \fBkey\fR, a double-quoted string +with an X11 key combination and a program with its arguments. +These are separated by one or more spaces. Empty lines are allowed. +Comment lines start with a hash. +.PP +For example, the following defines a hotkey to restart \fBicewm\fR: +.PP +.Vb 1 +\& key "Ctrl+Shift+r" icesh restart +.Ve +.PP +See the output of \f(CW\*(C`xmodmap \-pk\*(C'\fR for a list of the many keystroke names +you can use in icewm key definitions. Since IceWM version 3.4.0, +bindings can not only be defined by their keystroke name, but also by +their key label. In addition, the shifted key is now definable as well. +For example, the key with + and = can be bound in either of the +following four ways, which are identical: +.PP +.Vb 4 +\& key "Ctrl+Shift+equal" xterm +\& key "Ctrl+Shift+=" xterm +\& key "Ctrl+plus" xterm +\& key "Ctrl++" xterm +.Ve +.PP +To bind the mouse use \f(CW\*(C`Pointer_Button1\*(C'\fR for button 1, and so on. +The command \f(CW\*(C`icesh keys\*(C'\fR instructs icewm to reload this file. +.SS FORMAT +.IX Subsection "FORMAT" +The syntax of the \fIkeys\fR file is as follows: +.RS 4 +.IP "\fBkey\fR \fB""\fR\fIkey_combination\fR\fB""\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "key ""key_combination"" program options" +.RE +.RS 4 +.RE +.PP +Where, +.IP \fBkey\fR 4 +.IX Item "key" +The word \fBkey\fR begins the definition of a keybinding. +.IP \fIkey_combination\fR 4 +.IX Item "key_combination" +A combination of modifiers and a key, like \f(CW\*(C`Ctrl+Alt+Delete\*(C'\fR. +Valid modifiers are Alt, AltGr, Ctrl, Hyper, Meta, Shift, Super. +Each modifier must be followed by a single plus-sign. +The key is either a keystroke name or a key label. +Instead of a key, mouse pointer buttons can be specified by +\&\f(CW\*(C`Pointer_Button1\*(C'\fR and up, like \f(CW\*(C`Shift+Pointer_Button3\*(C'\fR. +.IP "\fIprogram\fR \fIoptions\fR" 4 +.IX Item "program options" +\&\fIprogram\fR is the name of the executable or its path. +It may start with a tilde or an environment variable, +which will be expanded. +The \fIoptions\fR are passed as arguments to the \fIprogram\fR. +.IP \fBswitchkey\fR 4 +.IX Item "switchkey" +Is an alternative to \fBkey\fR. In this case the \fIprogram\fR must print on +standard output the definition of a dynamic \fBicewm\-menu\fR\|(1). +This menu will presented as a popup menu. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +Following is the example \fIkeys\fR file that ships with \fBicewm\fR\|(1): +.PP +.Vb 10 +\& # This is an example for IceWM\*(Aqs hotkey definition file. +\& # +\& # A list of all valid keyboard symbols can be found in +\& # /usr/include/X11/keysymdef.h, XF86keysym.h, ... +\& # Omit the XK_ prefixs and replace XF86XK_ prefixes by XF86. +\& # Valid modifiers are Alt, AltGr, Ctrl, Shift, Meta, Super, Hyper. +\& # +\& key "Alt+Ctrl+t" xterm +\& key "Alt+Ctrl+b" xdg\-open about:blank +\& key "Alt+Ctrl+s" xdg\-open https://www.google.com +\& +\& key "Super+KP_Subtract" amixer sset PCM 5%\- +\& key "Super+KP_Add" amixer sset PCM 5%+ +\& +\& # "Multimedia key" bindings for XFree86. Gather the +\& # keycodes of your advanced function keys by watching the +\& # output of the xev command whilst pressing those keys +\& # and map those symbols using xmodmap. +\& +\& key "XF86AudioLowerVolume" amixer sset PCM 5%\- +\& key "XF86AudioRaiseVolume" amixer sset PCM 5%+ +\& key "XF86AudioMute" amixer sset PCM 0% +\& key "XF86HomePage" xdg\-open about:blank +\& key "XF86Search" xdg\-open https://www.google.com +\& key "XF86Eject" eject +\& +\& # display and select monitor setup configurations +\& switchkey "Super+p" icewm\-menu\-xrandr +.Ve +.PP +Following shows how to add mouse button bindings on the root window to +change the current workspace rolling the mouse wheel on the desktop: +.PP +.Vb 2 +\& key "Pointer_Button4" icesh goto prev +\& key "Pointer_Button5" icesh goto next +.Ve +.PP +These are key bindings for single window tile operations to replace the +\&\fIKeyWinArrange\fR key bindings from the \fIpreferences\fR file: +.PP +.Vb 9 +\& key "Ctrl+Alt+KP_Home" icesh \-f sizeto 49% 49% top left +\& key "Ctrl+Alt+KP_Up" icesh \-f sizeto 100% 49% top left +\& key "Ctrl+Alt+KP_Prior" icesh \-f sizeto 49% 49% top right +\& key "Ctrl+Alt+KP_Right" icesh \-f sizeto 49% 100% top right +\& key "Ctrl+Alt+KP_Next" icesh \-f sizeto 49% 49% bottom right +\& key "Ctrl+Alt+KP_Down" icesh \-f sizeto 100% 49% bottom left +\& key "Ctrl+Alt+KP_End" icesh \-f sizeto 49% 49% bottom left +\& key "Ctrl+Alt+KP_Left" icesh \-f sizeto 49% 100% top left +\& key "Ctrl+Alt+KP_Begin" icesh \-f sizeto 49% 49% center +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fIkeys\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/keys +\& $XDG_CONFIG_HOME/icewm/keys +\& $HOME/.icewm/keys +\& /etc/icewm/keys +\& /usr/share/icewm/keys +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-menu.5 b/upstream/fedora-40/man5/icewm-menu.5 new file mode 100644 index 00000000..e316d331 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-menu.5 @@ -0,0 +1,210 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-MENU 5" +.TH ICEWM-MENU 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-menu \- icewm menu configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/menu +\& $XDG_CONFIG_HOME/icewm/menu +\& $HOME/.icewm/menu +\& /etc/icewm/menu +\& /usr/share/icewm/menu +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \fImenu\fR file is responsible for configuring most of the \fBicewm\fR\|(1) +root menu and start menu. +.PP +A menu of applications; usually customized by the user. \fBicewm\fR +provides the \fBicewm\-menu\-fdo\fR\|(1) program to generate a default menu. +Similar programs are \fBxdg_menu\fR\|(1), \fBmmaker\fR\|(1) (MenuMaker), +\&\fBxde\-menu\fR\|(1), \fBxdgmenumaker\fR\|(1). +.SS FORMAT +.IX Subsection "FORMAT" +The file contains lines with the following syntax: +.IP "\fBprog\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "prog [""]title[""] icon program options" +Specifies a program to execute when the menu item is selected. +.IP "\fBrestart\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "restart [""]title[""] icon program options" +Specifies a program to replace the window manager when the menu item is +selected. This is for launching other window managers from within +\&\fBicewm\fR\|(1). +.IP "\fBrunonce\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fB""\fR[\fIres_name\fR][\fB.\fR\fIres_class\fR]\fB""\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "runonce [""]title[""] icon ""[res_name][.res_class]"" program options" +Specifies a program to execute when the menu item is selected; however, +if a window of the specified \fIres_name\fR and \fIres_class\fR is present, +the program will not be run again. +.IP "\fBmenu\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fB{\fR # contained items \fB}\fR" 4 +.IX Item "menu [""]title[""] icon { # contained items }" +Specifies a sub-menu. The lines that appear between the braces can be +any menu item described here. +.IP "\fBmenufile\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR [\fB""\fR]\fIfilename\fR[\fB""\fR]" 4 +.IX Item "menufile [""]title[""] icon [""]filename[""]" +Specifies a file from which to collect sub-menu items (lines) and place +them at this point in the menu. +.IP "\fBmenuprog\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "menuprog [""]title[""] icon program options" +Specifies a program that will print sub-menu items on standard output, +which will be collected and placed in the sub-menu at this point. +.IP "\fBmenuprogreload\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fItimeout\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "menuprogreload [""]title[""] icon timeout program options" +Similar to \fBmenuprog\fR, but after at least \fItimeout\fR seconds +the menu is regenerated. +.IP "\fBinclude\fR [\fB""\fR]\fIfilename\fR[\fB""\fR]" 4 +.IX Item "include [""]filename[""]" +Read additional entries from the file \fIfilename\fR +.IP "\fBincludeprog\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "includeprog program options" +Read additional entries from the output of \fIprogram\fR \fIoptions\fR. +.IP \fBseparator\fR 4 +.IX Item "separator" +A separator for menu items. +.PP +Where +.IP "\fBprog\fR, \fBrestart\fR, \fBrunonce\fR, \fBmenu\fR, \fBmenufile\fR, \fBmenuprog\fR, \fBmenuprogreload\fR, \fBinclude\fR, \fBincludeprog\fR, \fBseparator\fR" 4 +.IX Item "prog, restart, runonce, menu, menufile, menuprog, menuprogreload, include, includeprog, separator" +These are literal string keywords. +.IP "[\fB""\fR]\fItitle\fR[\fB""\fR]" 4 +.IX Item "[""]title[""]" +This is the \fItitle\fR string associated with the menu item that is +displayed in the menu. When the \fItitle\fR contains spaces, the title +must be surrounded by double quotes (\f(CW\*(C`\*(C'\fR). +.IP \fIicon\fR 4 +.IX Item "icon" +Is the name of the icon file (with or without extension) or the full +path to an icon file. +.IP "\fB""\fR[\fIres_name\fR][\fB.\fR\fIres_class\fR]\fB""\fR" 4 +.IX Item """[res_name][.res_class]""" +\&\fIres_name\fR is the resource name of a window launched by \fIprogram\fR and +\&\fIres_class\fR is the resource class of the window. Only one of +\&\fIres_name\fR or \fIres_class\fR need be specified. This is used to identify +whether the program is already running and is for use with the +\&\fBrunonce\fR keyword. +.IP "\fIprogram\fR \fIoptions\fR" 4 +.IX Item "program options" +\&\fIprogram\fR is the name of the executable or full path to the executable +file that will be run in response to selecting the menu item. +When used with the \fBmenuprog\fR keyword, the \fIprogram\fR must print on +standard output the contents of the menu and is used for dynamic menus. +.Sp +\&\fIoptions\fR are the options and arguments passed to the \fIprogram\fR +verbatim. +.IP \fIfilename\fR 4 +.IX Item "filename" +\&\fIfilename\fR is the name of the file relative to one of the \fBicewm\fR\|(1) +configuration directories, or the full path to a file. The file is used +with the \fBmenufile\fR keyword and specifies the file from which to read +further menu items. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +Following is the example \fImenu\fR file that ships with \fBicewm\fR\|(1): +.PP +.Vb 10 +\& # This is an example for IceWM\*(Aqs menu definition file. +\& # +\& # Place your variants in /etc/icewm or in $HOME/.icewm +\& # since modifications to this file will be discarded when you +\& # (re)install icewm. +\& # +\& prog xterm xterm xterm +\& prog rxvt xterm rxvt \-bg black \-cr green \-fg white \-C \-fn 9x15 \-sl 500 +\& prog fte fte fte +\& prog NEdit nedit nedit +\& prog Mozilla mozilla mozilla +\& prog XChat xchat xchat +\& prog Gimp gimp gimp +\& separator +\& menuprog "Desktop Apps" folder icewm\-menu\-fdo +\& menufile Programs folder programs +\& menufile Tool_bar folder toolbar +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fImenu\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/menu +\& $XDG_CONFIG_HOME/icewm/menu +\& $HOME/.icewm/menu +\& /etc/icewm/menu +\& /usr/share/icewm/menu +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-menu\-fdo\fR\|(1). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-preferences.5 b/upstream/fedora-40/man5/icewm-preferences.5 new file mode 100644 index 00000000..37190201 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-preferences.5 @@ -0,0 +1,1508 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-PREFERENCES 5" +.TH ICEWM-PREFERENCES 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-preferences \- icewm preferences configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/preferences +\& $XDG_CONFIG_HOME/icewm/preferences +\& $HOME/.icewm/preferences +\& /etc/icewm/preferences +\& /usr/share/icewm/preferences +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +Contains general settings like paths, colors and fonts, but also options +to control the \fBicewm\fR focus behaviour and the applets that are +started in the task bar. The \fBicewm\fR installation will provide a +default \fIpreferences\fR file, that can be copied to the \fBicewm\fR user +configuration directory and modified. +.SS FORMAT +.IX Subsection "FORMAT" +.SS "FOCUS AND BEHAVIOR" +.IX Subsection "FOCUS AND BEHAVIOR" +The following preferences affect focus and general behavior of +\&\fBicewm\fR\|(1): +.IP \fBAlpha\fR=0 4 +.IX Item "Alpha=0" +Use a 32\-bit visual for alpha blending +.IP \fBSynchronize\fR=0 4 +.IX Item "Synchronize=0" +Synchronize X11 for debugging (slow) +.IP \fBLogEvents\fR=0 4 +.IX Item "LogEvents=0" +Enable event logging for debugging +.IP "\fBOutputFile\fR=""""" 4 +.IX Item "OutputFile=""""" +Redirect all output to \fIFILE\fR. +A leading tilde or environment variable is expanded. +This file is truncated on startup if it exceeds 5 KB. +.IP "\fBSplash\fR=""""" 4 +.IX Item "Splash=""""" +Splash image on startup (IceWM.jpg) +.IP "\fBTrace\fR=""""" 4 +.IX Item "Trace=""""" +Enable tracing for the given list of modules. +Modules that are traceable include \fBconf, font, icon, prog, systray\fR. +.IP \fBClickToFocus\fR=1 4 +.IX Item "ClickToFocus=1" +Focus windows by clicking in them. +.IP \fBFocusOnAppRaise\fR=0 4 +.IX Item "FocusOnAppRaise=0" +Focus windows when applications request that they be raised. +.IP \fBRequestFocusOnAppRaise\fR=1 4 +.IX Item "RequestFocusOnAppRaise=1" +Request focus (flashing in taskbar) when application requests raise. +.IP \fBRaiseOnFocus\fR=1 4 +.IX Item "RaiseOnFocus=1" +Raise windows when focused. +.IP \fBFocusOnClickClient\fR=1 4 +.IX Item "FocusOnClickClient=1" +Focus window when client area clicked. +.IP \fBRaiseOnClickClient\fR=1 4 +.IX Item "RaiseOnClickClient=1" +Raise window when client area clicked. +.IP \fBRaiseOnClickTitleBar\fR=1 4 +.IX Item "RaiseOnClickTitleBar=1" +Raise window when title bar is clicked. +.IP \fBRaiseOnClickButton\fR=1 4 +.IX Item "RaiseOnClickButton=1" +Raise window when frame button is clicked. +.IP \fBRaiseOnClickFrame\fR=1 4 +.IX Item "RaiseOnClickFrame=1" +Raise window when frame border is clicked. +.IP \fBLowerOnClickWhenRaised\fR=0 4 +.IX Item "LowerOnClickWhenRaised=0" +Lower the active window when clicked again. +.IP \fBPassFirstClickToClient\fR=1 4 +.IX Item "PassFirstClickToClient=1" +Pass focusing click on client area to client. +.IP \fBFocusChangesWorkspace\fR=0 4 +.IX Item "FocusChangesWorkspace=0" +Change to the workspace of newly focused windows. +.IP \fBFocusCurrentWorkspace\fR=0 4 +.IX Item "FocusCurrentWorkspace=0" +Move newly focused windows to current workspace. +.IP \fBFocusOnMap\fR=1 4 +.IX Item "FocusOnMap=1" +Focus normal window when initially mapped. +.IP \fBFocusOnMapTransient\fR=0 4 +.IX Item "FocusOnMapTransient=0" +Focus dialog window when initially mapped. +.IP \fBFocusOnMapTransientActive\fR=1 4 +.IX Item "FocusOnMapTransientActive=1" +Focus dialog window when initially mapped only if parent frame focused. +.IP \fBMapInactiveOnTop\fR=1 4 +.IX Item "MapInactiveOnTop=1" +Put new windows on top even if not focusing them. +.IP \fBPointerColormap\fR=1 4 +.IX Item "PointerColormap=1" +Colormap focus follows pointer. +.IP \fBDontRotateMenuPointer\fR=1 4 +.IX Item "DontRotateMenuPointer=1" +Don't rotate the cursor for popup menus. +.IP \fBLimitSize\fR=1 4 +.IX Item "LimitSize=1" +Limit size of windows to screen. +.IP \fBLimitPosition\fR=1 4 +.IX Item "LimitPosition=1" +Limit position of windows to screen. +.IP \fBLimitByDockLayer\fR=0 4 +.IX Item "LimitByDockLayer=0" +Let the Dock layer limit the workspace (incompatible with GNOME Panel). +.IP \fBConsiderHBorder\fR=0 4 +.IX Item "ConsiderHBorder=0" +Consider border frames when maximizing horizontally. +.IP \fBConsiderVBorder\fR=0 4 +.IX Item "ConsiderVBorder=0" +Consider border frames when maximizing vertically. +.IP \fBConsiderSizeHintsMaximized\fR=1 4 +.IX Item "ConsiderSizeHintsMaximized=1" +Consider XSizeHints if frame is maximized. +Turning this off allows the titlebar to cover the width of the screen. +.IP \fBCenterMaximizedWindows\fR=0 4 +.IX Item "CenterMaximizedWindows=0" +Center maximized windows that can't fit the screen (like terminals). +.IP \fBHideBordersMaximized\fR=0 4 +.IX Item "HideBordersMaximized=0" +Hide window borders if window is maximized. +.IP \fBSizeMaximized\fR=0 4 +.IX Item "SizeMaximized=0" +Maximized windows can be resized. +.IP \fBShowMoveSizeStatus\fR=1 4 +.IX Item "ShowMoveSizeStatus=1" +Show position status window during move/resize. +.IP \fBShowWorkspaceStatus\fR=1 4 +.IX Item "ShowWorkspaceStatus=1" +Show name of current workspace while switching. +.IP \fBMinimizeToDesktop\fR=0 4 +.IX Item "MinimizeToDesktop=0" +Display mini-icons on desktop for minimized windows. +.IP \fBMiniIconsPlaceHorizontal\fR=0 4 +.IX Item "MiniIconsPlaceHorizontal=0" +Place the mini-icons horizontal instead of vertical. +.IP \fBMiniIconsRightToLeft\fR=0 4 +.IX Item "MiniIconsRightToLeft=0" +Place new mini-icons from right to left. +.IP \fBMiniIconsBottomToTop\fR=0 4 +.IX Item "MiniIconsBottomToTop=0" +Place new mini-icons from bottom to top. +.IP \fBStrongPointerFocus\fR=0 4 +.IX Item "StrongPointerFocus=0" +Always maintain focus under mouse window. Makes some keyboard support +non-functional or unreliable. +.IP \fBOpaqueMove\fR=1 4 +.IX Item "OpaqueMove=1" +Opaque window move. +.IP \fBOpaqueResize\fR=1 4 +.IX Item "OpaqueResize=1" +Opaque window resize. +.IP \fBManualPlacement\fR=0 4 +.IX Item "ManualPlacement=0" +Windows initially placed manually by user. +.IP \fBSmartPlacement\fR=1 4 +.IX Item "SmartPlacement=1" +Smart window placement (minimal overlap). +.IP \fBHideTitleBarWhenMaximized\fR=0 4 +.IX Item "HideTitleBarWhenMaximized=0" +Hide title bar when maximized. +.IP \fBCenterLarge\fR=0 4 +.IX Item "CenterLarge=0" +Center large windows. +.IP \fBCenterTransientsOnOwner\fR=1 4 +.IX Item "CenterTransientsOnOwner=1" +Center dialogs on owner window. +.IP \fBMenuMouseTracking\fR=0 4 +.IX Item "MenuMouseTracking=0" +Menus track mouse even with no mouse buttons held. +.IP \fBAutoRaise\fR=0 4 +.IX Item "AutoRaise=0" +Raise windows when the mouse pointer enters, after a delay of +\&\fIAutoRaiseDelay\fR milliseconds. Note that \f(CW\*(C`RaiseOnFocus=1\*(C'\fR +may interfere. +.IP \fBDelayPointerFocus\fR=1 4 +.IX Item "DelayPointerFocus=1" +Delay pointer focusing when mouse moves. +.IP \fBWin95Keys\fR=1 4 +.IX Item "Win95Keys=1" +Support the Windows/Super key modifier to activate special functions. +The left Super key toggles the Start menu, while the right Super key +toggles the Window list window. +.IP \fBModSuperIsCtrlAlt\fR=0 4 +.IX Item "ModSuperIsCtrlAlt=0" +Treat the Super/Win key modifier as a synonym for the Ctrl+Alt modifier +combination. The default key bindings have many occurrences of Ctrl+Alt. +If you enable this, then the Super modifier is an alternative way to +activate them. +.IP \fBUseMouseWheel\fR=0 4 +.IX Item "UseMouseWheel=0" +Support mouse wheel. When pressing Ctrl+Alt rotating the mouse wheel +on the root window will cycle the focus over the windows. +.IP \fBTaskBarTaskGrouping\fR=0 4 +.IX Item "TaskBarTaskGrouping=0" +Group applications with the same class name under a single task button. +0 disables it, 1 shows the number of windows, 2 shows bread crumbs, +3 shows a number + bread crumbs. +.IP \fBShowPopupsAbovePointer\fR=0 4 +.IX Item "ShowPopupsAbovePointer=0" +Show popup menus above mouse pointer. +.IP \fBReplayMenuCancelClick\fR=0 4 +.IX Item "ReplayMenuCancelClick=0" +Send the clicks outside menus to target window. +.IP \fBClientWindowMouseActions\fR=1 4 +.IX Item "ClientWindowMouseActions=1" +Allow mouse actions on client windows. This is buggy with some programs. +.IP \fBGrabRootWindow\fR=1 4 +.IX Item "GrabRootWindow=1" +Manage root window (EXPERIMENTAL \- normally enabled!). +.IP \fBSnapMove\fR=1 4 +.IX Item "SnapMove=1" +Snap to nearest screen edge/window when moving windows. +.IP "\fBSnapDistance\fR=8 [0\-64]" 4 +.IX Item "SnapDistance=8 [0-64]" +Distance in pixels before windows snap together. +.IP \fBArrangeWindowsOnScreenSizeChange\fR=1 4 +.IX Item "ArrangeWindowsOnScreenSizeChange=1" +Automatically arrange windows when screen size changes. +.IP \fBAllowFullscreen\fR=1 4 +.IX Item "AllowFullscreen=1" +Allow to switch a window to fullscreen. +.IP \fBFullscreenUseAllMonitors\fR=0 4 +.IX Item "FullscreenUseAllMonitors=0" +Span over all available screens if window goes into fullscreen. +.IP "\fBMsgBoxDefaultAction\fR=0 [0\-1]" 4 +.IX Item "MsgBoxDefaultAction=0 [0-1]" +Preselect to Cancel (0) or the OK (1) button in message boxes. +.IP "\fBNetWorkAreaBehaviour\fR=0 [0\-2]" 4 +.IX Item "NetWorkAreaBehaviour=0 [0-2]" +NET_WORKAREA behaviour: 0 (single/multi\-monitor with STRUT information, +like metacity), 1 (always full desktop), 2 (single monitor with STRUT, +multi-monitor without STRUT). +.SS "QUICK SWITCH" +.IX Subsection "QUICK SWITCH" +.IP \fBQuickSwitch\fR=1 4 +.IX Item "QuickSwitch=1" +Enable Alt+Tab window switching. +.IP \fBQuickSwitchToMinimized\fR=1 4 +.IX Item "QuickSwitchToMinimized=1" +Enable Alt+Tab to minimized windows. +.IP \fBQuickSwitchToHidden\fR=1 4 +.IX Item "QuickSwitchToHidden=1" +Enable Alt+Tab to hidden windows. +.IP \fBQuickSwitchToUrgent\fR=1 4 +.IX Item "QuickSwitchToUrgent=1" +Prioritize Alt+Tab to urgent windows. +.IP \fBQuickSwitchToAllWorkspaces\fR=0 4 +.IX Item "QuickSwitchToAllWorkspaces=0" +Include windows from all workspaces in Alt+Tab. +.IP \fBQuickSwitchGroupWorkspaces\fR=1 4 +.IX Item "QuickSwitchGroupWorkspaces=1" +Group windows by workspace together in Alt+Tab. +.IP \fBQuickSwitchPersistence\fR=0 4 +.IX Item "QuickSwitchPersistence=0" +Time in seconds to remember the state of Alt+Tab. +.IP \fBQuickSwitchRaiseCandidate\fR=0 4 +.IX Item "QuickSwitchRaiseCandidate=0" +Raise a selected window while Alt+Tabbing in the QuickSwitch. +.IP \fBQuickSwitchAllIcons\fR=1 4 +.IX Item "QuickSwitchAllIcons=1" +Show all reachable icons when quick switching. +.IP \fBQuickSwitchTextFirst\fR=0 4 +.IX Item "QuickSwitchTextFirst=0" +Show the window title above (all reachable) icons. +.IP \fBQuickSwitchSmallWindow\fR=0 4 +.IX Item "QuickSwitchSmallWindow=0" +Create a smaller QuickSwitch window of 1/3 screen width. +.IP \fBQuickSwitchMaxWidth\fR=0 4 +.IX Item "QuickSwitchMaxWidth=0" +Go trough all window titles and choose width of the longest one. +.IP \fBQuickSwitchVertical\fR=1 4 +.IX Item "QuickSwitchVertical=1" +Place the icons and titles vertical instead of horizontal. +.IP \fBQuickSwitchHugeIcon\fR=0 4 +.IX Item "QuickSwitchHugeIcon=0" +Show the huge (48x48) of the window icon for the active window. +.IP \fBQuickSwitchFillSelection\fR=0 4 +.IX Item "QuickSwitchFillSelection=0" +Fill the rectangle highlighting the current icon. +.SS "EDGE SWITCHING" +.IX Subsection "EDGE SWITCHING" +.IP \fBEdgeSwitch\fR=0 4 +.IX Item "EdgeSwitch=0" +Workspace switches by moving mouse to left/right screen edge. +.IP \fBHorizontalEdgeSwitch\fR=0 4 +.IX Item "HorizontalEdgeSwitch=0" +Workspace switches by moving mouse to left/right screen edge. +.IP \fBVerticalEdgeSwitch\fR=0 4 +.IX Item "VerticalEdgeSwitch=0" +Workspace switches by moving mouse to top/bottom screen edge. +.IP \fBContinuousEdgeSwitch\fR=1 4 +.IX Item "ContinuousEdgeSwitch=1" +Workspace switches continuously when moving mouse to screen edge. +.IP "\fBEdgeResistance\fR=32 [0\-10000]" 4 +.IX Item "EdgeResistance=32 [0-10000]" +Resistance in pixels when trying to move windows off the screen (10000 = +infinite). +.SS "TASK BAR" +.IX Subsection "TASK BAR" +The following preferences affect the \fBicewm\fR\|(1) task bar: +.IP \fBShowTaskBar\fR=1 4 +.IX Item "ShowTaskBar=1" +Show task bar. +.IP \fBTaskBarAtTop\fR=0 4 +.IX Item "TaskBarAtTop=0" +Task bar at top of the screen. +.IP \fBTaskBarKeepBelow\fR=0 4 +.IX Item "TaskBarKeepBelow=0" +Keep the task bar below regular windows. +.IP \fBTaskBarAutoHide\fR=0 4 +.IX Item "TaskBarAutoHide=0" +Auto hide task bar after delay. +.IP \fBTaskBarFullscreenAutoShow\fR=1 4 +.IX Item "TaskBarFullscreenAutoShow=1" +Auto show task bar when fullscreen window active. +.IP \fBTaskBarShowClock\fR=1 4 +.IX Item "TaskBarShowClock=1" +Show clock on task bar. +.IP \fBTaskBarShowAPMStatus\fR=0 4 +.IX Item "TaskBarShowAPMStatus=0" +Show battery status monitor on task bar. +.IP \fBTaskBarShowAPMAuto\fR=1 4 +.IX Item "TaskBarShowAPMAuto=1" +Enable TaskBarShowAPMStatus if a battery is present. +.IP \fBTaskBarShowAPMTime\fR=1 4 +.IX Item "TaskBarShowAPMTime=1" +Show battery status on task bar in time-format +.IP \fBTaskBarShowAPMGraph\fR=1 4 +.IX Item "TaskBarShowAPMGraph=1" +Show battery status in graph mode. +.IP \fBTaskBarShowMailboxStatus\fR=1 4 +.IX Item "TaskBarShowMailboxStatus=1" +Show mailbox status on task bar. +.IP \fBTaskBarMailboxStatusBeepOnNewMail\fR=0 4 +.IX Item "TaskBarMailboxStatusBeepOnNewMail=0" +Beep when new mail arrives. +.IP \fBTaskBarMailboxStatusCountMessages\fR=0 4 +.IX Item "TaskBarMailboxStatusCountMessages=0" +Count messages in mailbox. +.IP \fBTaskBarShowWorkspaces\fR=1 4 +.IX Item "TaskBarShowWorkspaces=1" +Show workspace switching buttons on task bar. +.IP \fBTaskBarShowWindows\fR=1 4 +.IX Item "TaskBarShowWindows=1" +Show windows on the taskbar. +.IP \fBTaskBarShowShowDesktopButton\fR=1 4 +.IX Item "TaskBarShowShowDesktopButton=1" +Show 'show desktop' button on taskbar. If set to 2, it will move the icon to the right side, after the clock. +.IP \fBShowEllipsis\fR=1 4 +.IX Item "ShowEllipsis=1" +Show Ellipsis in taskbar items. +.IP \fBTaskBarShowTray\fR=1 4 +.IX Item "TaskBarShowTray=1" +Show windows in the tray. +.IP \fBTaskBarEnableSystemTray\fR=1 4 +.IX Item "TaskBarEnableSystemTray=1" +Enable the system tray in the taskbar. +.IP \fBTrayShowAllWindows\fR=1 4 +.IX Item "TrayShowAllWindows=1" +Show windows from all workspaces on tray. +.IP \fBTaskBarShowTransientWindows\fR=1 4 +.IX Item "TaskBarShowTransientWindows=1" +Show transient (dialogs, ...) windows on task bar. +.IP \fBTaskBarShowAllWindows\fR=0 4 +.IX Item "TaskBarShowAllWindows=0" +Show windows from all workspaces on task bar. +.IP \fBTaskBarShowWindowIcons\fR=1 4 +.IX Item "TaskBarShowWindowIcons=1" +Show icons of windows on task buttons of the task bar. +.IP \fBTaskBarShowWindowTitles\fR=1 4 +.IX Item "TaskBarShowWindowTitles=1" +Show titles of windows on task buttons of the task bar. +.IP \fBTaskBarShowStartMenu\fR=1 4 +.IX Item "TaskBarShowStartMenu=1" +Show 'Start' menu on task bar. +.IP \fBTaskBarShowWindowListMenu\fR=1 4 +.IX Item "TaskBarShowWindowListMenu=1" +Show 'window list' menu on task bar. +.IP \fBTaskBarShowCPUStatus\fR=1 4 +.IX Item "TaskBarShowCPUStatus=1" +Show CPU status on task bar (Linux & Solaris). +.IP \fBCPUStatusShowRamUsage\fR=1 4 +.IX Item "CPUStatusShowRamUsage=1" +Show RAM usage in CPU status tool tip. +.IP \fBCPUStatusShowSwapUsage\fR=1 4 +.IX Item "CPUStatusShowSwapUsage=1" +Show swap usage in CPU status tool tip. +.IP \fBCPUStatusShowAcpiTemp\fR=1 4 +.IX Item "CPUStatusShowAcpiTemp=1" +Show ACPI temperature in CPU status tool tip. +.IP \fBCPUStatusShowAcpiTempInGraph\fR=0 4 +.IX Item "CPUStatusShowAcpiTempInGraph=0" +Show ACPI temperature in CPU status bar. +.IP \fBCPUStatusShowCpuFreq\fR=1 4 +.IX Item "CPUStatusShowCpuFreq=1" +Show CPU frequency in CPU status tool tip. +.IP \fBNetStatusShowOnlyRunning\fR=0 4 +.IX Item "NetStatusShowOnlyRunning=0" +Show network status only for connected devices, such as an active Ethernet link +or associated wireless interface. If false, any network interface that has been +brought up will be displayed. +.IP \fBTaskBarShowMEMStatus\fR=1 4 +.IX Item "TaskBarShowMEMStatus=1" +Show memory usage status on task bar (Linux only). +.IP \fBTaskBarShowNetStatus\fR=1 4 +.IX Item "TaskBarShowNetStatus=1" +Show network status on task bar (Linux only). +.IP \fBTaskBarShowCollapseButton\fR=0 4 +.IX Item "TaskBarShowCollapseButton=0" +Show a button to collapse the taskbar. +.IP \fBTaskBarDoubleHeight\fR=0 4 +.IX Item "TaskBarDoubleHeight=0" +Use double-height task bar. +.IP \fBTaskBarWorkspacesLeft\fR=1 4 +.IX Item "TaskBarWorkspacesLeft=1" +Place workspace pager on left, not right. +.IP \fBTaskBarWorkspacesTop\fR=0 4 +.IX Item "TaskBarWorkspacesTop=0" +Place workspace pager on top row when using dual-height taskbar. +.IP "\fBTaskBarWorkspacesLimit\fR=""""" 4 +.IX Item "TaskBarWorkspacesLimit=""""" +Limit the number of taskbar workspaces buttons that are shown on the +workspaces pane of the taskbar. If the numeric value has a \f(CW\*(C`p\*(C'\fR suffix +then the limitation is in pixels. A \f(CW\*(C`%\*(C'\fR suffix limits by percentage of +desktop width. By default a \f(CW\*(C`B\*(C'\fR suffix is assumed for number of buttons. +.IP \fBTaskBarUseMouseWheel\fR=1 4 +.IX Item "TaskBarUseMouseWheel=1" +Enable mouse wheel cycling over workspaces and task buttons in taskbar. +.IP \fBPagerShowPreview\fR=1 4 +.IX Item "PagerShowPreview=1" +Show a mini desktop preview on each workspace button. +.IP \fBPagerShowWindowIcons\fR=1 4 +.IX Item "PagerShowWindowIcons=1" +Draw window icons inside large enough preview windows on pager (if PagerShowPreview=1). +.IP \fBPagerShowMinimized\fR=1 4 +.IX Item "PagerShowMinimized=1" +Draw even minimized windows as unfilled rectangles (if PagerShowPreview=1). +.IP \fBPagerShowBorders\fR=1 4 +.IX Item "PagerShowBorders=1" +Draw border around workspace buttons (if PagerShowPreview=1). +.IP \fBPagerShowLabels\fR=1 4 +.IX Item "PagerShowLabels=1" +Show workspace name label on workspace button (if PagerShowPreview=1) +.IP \fBPagerShowNumbers\fR=1 4 +.IX Item "PagerShowNumbers=1" +Show number of workspace on workspace button (if PagerShowPreview=1). +.IP \fBTaskBarLaunchOnSingleClick\fR=1 4 +.IX Item "TaskBarLaunchOnSingleClick=1" +Execute taskbar applet commands (like MailCommand, ClockCommand, ...) on single click. +.IP \fBEnableAddressBar\fR=1 4 +.IX Item "EnableAddressBar=1" +Enable address bar functionality in taskbar. +.IP \fBShowAddressBar\fR=1 4 +.IX Item "ShowAddressBar=1" +Show address bar in task bar. +.IP \fBMultiByte\fR=1 4 +.IX Item "MultiByte=1" +Overrides automatic multiple byte detection. +.IP \fBConfirmLogout\fR=1 4 +.IX Item "ConfirmLogout=1" +Confirm logout. +.IP \fBShapesProtectClientWindow\fR=1 4 +.IX Item "ShapesProtectClientWindow=1" +Don't cut client windows by shapes set trough frame corner pixmap. +.IP \fBDoubleBuffer\fR=1 4 +.IX Item "DoubleBuffer=1" +Use double buffering when redrawing the display. +.IP \fBXRRDisable\fR=1 4 +.IX Item "XRRDisable=1" +Disable use of new XRANDR API for dual head (nvidia workaround). +.IP \fBPreferFreetypeFonts\fR=1 4 +.IX Item "PreferFreetypeFonts=1" +Favour Xft fonts over core X11 fonts where possible. +.IP "\fBMailBoxPath\fR=""""" 4 +.IX Item "MailBoxPath=""""" +A colon separated list of paths of your mailboxes. +If this is empty, \f(CW$MAILPATH\fR or \f(CW$MAIL\fR is used instead. +.Sp +Path to a mbox file. Remote mail boxes are accessed by specifying an URL +using the Common Internet Scheme Syntax (RFC 1738): +.Sp +.Vb 1 +\& \`scheme://[user[:password]@]server[:port][/path]\`. +.Ve +.Sp +Supported schemes are \f(CW\*(C`pop3\*(C'\fR, \f(CW\*(C`imap\*(C'\fR and \f(CW\*(C`file\*(C'\fR. When the scheme is +omitted \fIfile://\fR is prepended silently. IMAP subfolders can be +accessed by using the path component. Reserved characters like +\&\fIslash\fR (\f(CW\*(C`/\*(C'\fR), \fIat\fR (\f(CW\*(C`@\*(C'\fR) and \fIcolon\fR (\f(CW\*(C`:\*(C'\fR) can be specified using +escape sequences with a hexadecimal encoding like \f(CW%2f\fR for the slash +or \f(CW%40\fR for the at sign. For example: +.Sp +.Vb 3 +\& file:///var/spool/mail/captnmark +\& pop3://markus:%2f%40%3a@maol.ch/ +\& imap://mathias@localhost/INBOX.Maillisten.icewm\-user +.Ve +.IP "\fBNetworkStatusDevice\fR=""eth0 wlan0""" 4 +.IX Item "NetworkStatusDevice=""eth0 wlan0""" +Network devices for which to show status. +.IP "\fBTimeFormat\fR=""%X""" 4 +.IX Item "TimeFormat=""%X""" +The clock time format. See the strftime manpage for the meaning of all +the percent options. It is possible to define multiple clocks for +different time zones in a single \fITimeFormat\fR. A new clock is defined +by the beginning of the string, and by each time zone specification +that starts with \f(CW\*(C`TZ=...\*(C'\fR, followed by a space. For example, +\&\fBTimeFormat\fR=\f(CW\*(C`%X TZ=Asia/Aden %T TZ=Asia/Baku %T\*(C'\fR defines 3 clocks. +.IP "\fBTimeFormatAlt\fR=""""" 4 +.IX Item "TimeFormatAlt=""""" +Alternate Clock Time format shown every other second. +.IP "\fBDateFormat\fR=""%c""" 4 +.IX Item "DateFormat=""%c""" +Clock Date format for tooltip (strftime format string). +.IP "\fBDockApps\fR=""right high desktop""" 4 +.IX Item "DockApps=""right high desktop""" +Support DockApps (right, left, center, down, high, above, below, +desktop, or empty to disable). Control with Ctrl+Mouse. +.IP "\fBXRRPrimaryScreenName\fR=""""" 4 +.IX Item "XRRPrimaryScreenName=""""" +Screen/output name of the primary screen. +.IP "\fBAcpiIgnoreBatteries\fR=""""" 4 +.IX Item "AcpiIgnoreBatteries=""""" +List of battery names (directories) in /proc/acpi/battery to ignore. +Useful when more slots are built-in, but only one battery is used. +.IP "\fBTaskBarCPUSamples\fR=20 [2\-1000]" 4 +.IX Item "TaskBarCPUSamples=20 [2-1000]" +The width of the CPU Monitor applet in pixels. +.IP "\fBTaskBarMEMSamples\fR=20 [2\-1000]" 4 +.IX Item "TaskBarMEMSamples=20 [2-1000]" +The width of the Memory Monitor applet in pixels. +.IP "\fBTaskBarNetSamples\fR=20 [2\-1000]" 4 +.IX Item "TaskBarNetSamples=20 [2-1000]" +The width of the Net Monitor applet in pixels. +.IP "\fBTaskbarButtonWidthDivisor\fR=3 [1\-25]" 4 +.IX Item "TaskbarButtonWidthDivisor=3 [1-25]" +Default number of tasks in taskbar. +.IP "\fBTaskBarWidthPercentage\fR=100 [0\-100]" 4 +.IX Item "TaskBarWidthPercentage=100 [0-100]" +Task bar width as percentage of the screen width. +.IP "\fBTaskBarJustify\fR=""left""" 4 +.IX Item "TaskBarJustify=""left""" +Taskbar justify left, right or center. +.IP "\fBTaskBarApmGraphWidth\fR=10 [1\-1000]" 4 +.IX Item "TaskBarApmGraphWidth=10 [1-1000]" +Width of battery Monitor. +.IP "\fBXineramaPrimaryScreen\fR=0 [0\-63]" 4 +.IX Item "XineramaPrimaryScreen=0 [0-63]" +Primary screen for xinerama (taskbar, ...). +.IP "\fBKeyboardLayouts\fR=""""" 4 +.IX Item "KeyboardLayouts=""""" +A comma-separated list of keyboard layouts. +A layout may be enclosed in double quotes. +Each layout is a name with optional arguments, +that is to be parsed by the \f(CW\*(C`setxkbmap\*(C'\fR program. +To support changing keyboard layouts, the +\&\f(CW\*(C`setxkbmap\*(C'\fR program must be installed. +The first in the list is the default layout. +Programs may have their own keyboard layout +defined in the \fIwinoptions\fR file. +The first two letters of a layout are used +to locate an icon image file. +.SS MENUS +.IX Subsection "MENUS" +.IP \fBAutoReloadMenus\fR=1 4 +.IX Item "AutoReloadMenus=1" +Reload menu files automatically. +.IP \fBShowProgramsMenu\fR=0 4 +.IX Item "ShowProgramsMenu=0" +Show programs submenu. +.IP \fBShowSettingsMenu\fR=1 4 +.IX Item "ShowSettingsMenu=1" +Show settings submenu. +.IP \fBShowFocusModeMenu\fR=1 4 +.IX Item "ShowFocusModeMenu=1" +Show focus mode submenu. +.IP \fBShowThemesMenu\fR=1 4 +.IX Item "ShowThemesMenu=1" +Show themes submenu. +.IP \fBShowLogoutMenu\fR=1 4 +.IX Item "ShowLogoutMenu=1" +Show logout menu. +.IP \fBShowHelp\fR=1 4 +.IX Item "ShowHelp=1" +Show the help menu item. +.IP \fBShowLogoutSubMenu\fR=1 4 +.IX Item "ShowLogoutSubMenu=1" +Show logout submenu. +.IP \fBShowAbout\fR=1 4 +.IX Item "ShowAbout=1" +Show the about menu item. +.IP \fBShowRun\fR=1 4 +.IX Item "ShowRun=1" +Show the run menu item. +.IP \fBShowWindowList\fR=1 4 +.IX Item "ShowWindowList=1" +Show the window menu item. +.IP "\fBMenuMaximalWidth\fR=0 [0\-16384]" 4 +.IX Item "MenuMaximalWidth=0 [0-16384]" +Maximal width of popup menus, 2/3 of the screen's width if set to zero. +.IP "\fBNestedThemeMenuMinNumber\fR=25 [0\-1234]" 4 +.IX Item "NestedThemeMenuMinNumber=25 [0-1234]" +Minimal number of themes after which the Themes menu becomes nested (0=disabled). +.SS TIMINGS +.IX Subsection "TIMINGS" +.IP "\fBDelayFuzziness\fR=10 (0\-100)" 4 +.IX Item "DelayFuzziness=10 (0-100)" +Delay fuzziness, to allow merging of multiple timer timeouts into one +(notebook power saving). +.IP "\fBClickMotionDistance\fR=4 [0\-32]" 4 +.IX Item "ClickMotionDistance=4 [0-32]" +Pointer motion distance before click gets interpreted as drag. +.IP "\fBClickMotionDelay\fR=200 [0\-2000]" 4 +.IX Item "ClickMotionDelay=200 [0-2000]" +Delay before click gets interpreted as drag. +.IP "\fBMultiClickTime\fR=400 [0\-5000]" 4 +.IX Item "MultiClickTime=400 [0-5000]" +Multiple click time. +.IP "\fBMenuActivateDelay\fR=40 [0\-5000]" 4 +.IX Item "MenuActivateDelay=40 [0-5000]" +Delay before activating menu items. +.IP "\fBSubmenuMenuActivateDelay\fR=300 [0\-5000]" 4 +.IX Item "SubmenuMenuActivateDelay=300 [0-5000]" +Delay before activating menu submenus. +.IP \fBToolTipIcon\fR=1 4 +.IX Item "ToolTipIcon=1" +Show an application icon in toolbar and tray tooltips. +.IP "\fBToolTipDelay\fR=1000 [0\-5000]" 4 +.IX Item "ToolTipDelay=1000 [0-5000]" +Delay before tooltip window is displayed. +.IP "\fBToolTipTime\fR=0 [0\-60000]" 4 +.IX Item "ToolTipTime=0 [0-60000]" +Time before tooltip window is hidden (0 means never). +.IP "\fBAutoHideDelay\fR=300 [0\-5000]" 4 +.IX Item "AutoHideDelay=300 [0-5000]" +Delay before task bar is hidden. +.IP "\fBAutoShowDelay\fR=500 [0\-5000]" 4 +.IX Item "AutoShowDelay=500 [0-5000]" +Delay before task bar is shown. +.IP "\fBAutoRaiseDelay\fR=400 [0\-5000]" 4 +.IX Item "AutoRaiseDelay=400 [0-5000]" +Delay before windows are auto raised if \f(CW\*(C`AutoRaise=1\*(C'\fR. +.IP "\fBPointerFocusDelay\fR=200 [0\-1000]" 4 +.IX Item "PointerFocusDelay=200 [0-1000]" +Delay for pointer focus switching. +.IP "\fBEdgeSwitchDelay\fR=600 [0\-5000]" 4 +.IX Item "EdgeSwitchDelay=600 [0-5000]" +Screen edge workspace switching delay. +.IP "\fBScrollBarStartDelay\fR=500 [0\-5000]" 4 +.IX Item "ScrollBarStartDelay=500 [0-5000]" +Initial scroll bar autoscroll delay. +.IP "\fBScrollBarDelay\fR=30 [0\-5000]" 4 +.IX Item "ScrollBarDelay=30 [0-5000]" +Scroll bar autoscroll delay. +.IP "\fBAutoScrollStartDelay\fR=500 [0\-5000]" 4 +.IX Item "AutoScrollStartDelay=500 [0-5000]" +Auto scroll start delay. +.IP "\fBAutoScrollDelay\fR=60 [0\-5000]" 4 +.IX Item "AutoScrollDelay=60 [0-5000]" +Auto scroll delay. +.IP "\fBWorkspaceStatusTime\fR=2500 [0\-2500]" 4 +.IX Item "WorkspaceStatusTime=2500 [0-2500]" +Time before workspace status window is hidden. +.IP "\fBMailCheckDelay\fR=30 [0\-86400]" 4 +.IX Item "MailCheckDelay=30 [0-86400]" +Delay between new-mail checks. (seconds). +.IP "\fBTaskBarCPUDelay\fR=500 [10\-3600000]" 4 +.IX Item "TaskBarCPUDelay=500 [10-3600000]" +Delay between CPU Monitor samples in ms. +.IP "\fBTaskBarMEMDelay\fR=500 [10\-3600000]" 4 +.IX Item "TaskBarMEMDelay=500 [10-3600000]" +Delay between Memory Monitor samples in ms. +.IP "\fBTaskBarNetDelay\fR=500 [10\-3600000]" 4 +.IX Item "TaskBarNetDelay=500 [10-3600000]" +Delay between Net Monitor samples in ms. +.IP "\fBFocusRequestFlashTime\fR=0 [0\-86400]" 4 +.IX Item "FocusRequestFlashTime=0 [0-86400]" +Number of seconds the taskbar app will blink when requesting focus (0 = forever). +.IP "\fBFocusRequestFlashInterval\fR=250 [0\-30000]" 4 +.IX Item "FocusRequestFlashInterval=250 [0-30000]" +Taskbar blink interval (ms) when requesting focus (0 = blinking disabled). +.IP "\fBBatteryPollingPeriod\fR=10 [2\-3600]" 4 +.IX Item "BatteryPollingPeriod=10 [2-3600]" +Delay between power status updates (seconds). +.IP "\fBPingTimeout\fR=3 [0\-86400]" 4 +.IX Item "PingTimeout=3 [0-86400]" +Timeout in seconds for applications to respond to the _NET_WM_PING protocol. +.SS "BUTTONS AND KEYS" +.IX Subsection "BUTTONS AND KEYS" +.IP "\fBUseRootButtons\fR=255 [0\-255]" 4 +.IX Item "UseRootButtons=255 [0-255]" +Bitmask of root window button click to use in window manager. +.IP "\fBButtonRaiseMask\fR=1 [0\-255]" 4 +.IX Item "ButtonRaiseMask=1 [0-255]" +Bitmask of buttons that raise the window when pressed. +.IP "\fBDesktopWinMenuButton\fR=0 [0\-20]" 4 +.IX Item "DesktopWinMenuButton=0 [0-20]" +Desktop mouse-button click to show the window list menu. +.IP "\fBDesktopWinListButton\fR=2 # [0\-20]" 4 +.IX Item "DesktopWinListButton=2 # [0-20]" +Desktop mouse-button click to show the window list +.IP "\fBDesktopMenuButton\fR=3 [0\-20]" 4 +.IX Item "DesktopMenuButton=3 [0-20]" +Desktop mouse-button click to show the root menu. +.IP "\fBTitleBarMaximizeButton\fR=1 [0\-5]" 4 +.IX Item "TitleBarMaximizeButton=1 [0-5]" +Title bar mouse-button double click to maximize the window to full +screen with the frame border visible. +Press Shift to maximize only in the vertical direction. +Press Alt+Shift to maximize only in the horizontal direction. +.IP "\fBTitleBarRollupButton\fR=2 [0\-5]" 4 +.IX Item "TitleBarRollupButton=2 [0-5]" +Title bar mouse-button double click to rollup the window. +Press Shift to maximize in the horizontal direction. +.SS WORKSPACES +.IX Subsection "WORKSPACES" +.IP "\fBWorkspaceNames\fR="" 1 "", "" 2 "", "" 3 "", "" 4 """ 4 +.IX Item "WorkspaceNames="" 1 "", "" 2 "", "" 3 "", "" 4 """ +Create four workspaces with names \f(CW 1 \fR, \f(CW 2 \fR, \f(CW 3 \fR and \f(CW 4 \fR. +.SS PATHS +.IX Subsection "PATHS" +.IP "\fBIconPath\fR=""/usr/local/share/icons:/usr/local/share/pixmaps:/usr/share/icons:/usr/share/pixmaps""" 4 +.IX Item "IconPath=""/usr/local/share/icons:/usr/local/share/pixmaps:/usr/share/icons:/usr/share/pixmaps""" +Icon search path (colon separated). Also, the icons/ subdirectory in +IceWM resource folders are searched first. +.IP "\fBIconThemes\fR=""*:\-HighContrast""" 4 +.IX Item "IconThemes=""*:-HighContrast""" +List of icon themes (colon separated), acting as additional filter of +icon subdirectories in any of the \fBIconPath\fR folders. Expressions can be +wildcards, also special wildcards (starting with \fB\-\fR) can exclude matched +themes from selection. +.IP "\fBMailBoxPath\fR=""""" 4 +.IX Item "MailBoxPath=""""" +A colon separated list of paths of your mailboxes. +If this is empty, \f(CW$MAILPATH\fR or \f(CW$MAIL\fR is used instead. +.SS PROGRAMS +.IX Subsection "PROGRAMS" +.IP "\fBMailCommand\fR=""xterm \-name mutt \-e mutt""" 4 +.IX Item "MailCommand=""xterm -name mutt -e mutt""" +Command to run on mailbox. +.IP "\fBMailClassHint\fR=""mutt.XTerm""" 4 +.IX Item "MailClassHint=""mutt.XTerm""" +\&\fBWM_CLASS\fR to allow \fBrunonce\fR for \fBMailCommand\fR. +.IP "\fBNewMailCommand\fR=""""" 4 +.IX Item "NewMailCommand=""""" +Command to run when new mail arrives. +.IP "\fBLockCommand\fR=""""" 4 +.IX Item "LockCommand=""""" +Command to lock display/screensaver. +.IP "\fBClockCommand\fR=""xclock \-name icewm \-title Clock""" 4 +.IX Item "ClockCommand=""xclock -name icewm -title Clock""" +Command to run on clock. +.IP "\fBClockClassHint\fR=""icewm.XClock""" 4 +.IX Item "ClockClassHint=""icewm.XClock""" +\&\fBWM_CLASS\fR to allow \fBrunonce\fR for \fBClockCommand\fR. +.IP "\fBRunCommand\fR=""""" 4 +.IX Item "RunCommand=""""" +Command to select and run a program. +.IP "\fBOpenCommand\fR=""""" 4 +.IX Item "OpenCommand=""""" +Open command. +.IP "\fBTerminalCommand\fR=""xterm""" 4 +.IX Item "TerminalCommand=""xterm""" +Terminal emulator must accept \-e option. +.IP "\fBLogoutCommand\fR=""""" 4 +.IX Item "LogoutCommand=""""" +Command to start logout. +.IP "\fBLogoutCancelCommand\fR=""""" 4 +.IX Item "LogoutCancelCommand=""""" +Command to cancel logout. +.IP "\fBShutdownCommand\fR=""/bin/sh \-c ""{ test \-e /run/systemd/system && systemctl poweroff || loginctl poweroff; }""""" 4 +.IX Item "ShutdownCommand=""/bin/sh -c ""{ test -e /run/systemd/system && systemctl poweroff || loginctl poweroff; }""""" +Command to shutdown the system. +.IP "\fBRebootCommand\fR=""/bin/sh \-c ""{ test \-e /run/systemd/system && systemctl reboot || loginctl reboot; }""""" 4 +.IX Item "RebootCommand=""/bin/sh -c ""{ test -e /run/systemd/system && systemctl reboot || loginctl reboot; }""""" +Command to reboot the system. +.IP "\fBSuspendCommand\fR=""test \-e /run/systemd/system && systemctl suspend || loginctl suspend""" 4 +.IX Item "SuspendCommand=""test -e /run/systemd/system && systemctl suspend || loginctl suspend""" +Command to send the system to standby mode +.IP "\fBSuspendCommand\fR=""test \-e /run/systemd/system && systemctl hibernate || loginctl hibernate""" 4 +.IX Item "SuspendCommand=""test -e /run/systemd/system && systemctl hibernate || loginctl hibernate""" +Command to hibernate the system. +.IP "\fBCPUStatusCommand\fR=""xterm \-name top \-title Process\e Status \-e top""" 4 +.IX Item "CPUStatusCommand=""xterm -name top -title Process Status -e top""" +Command to run on CPU status. +.IP "\fBCPUStatusClassHint\fR=""top.XTerm""" 4 +.IX Item "CPUStatusClassHint=""top.XTerm""" +\&\fBWM_CLASS\fR to allow \fBrunonce\fR for \fBCPUStatusCommand\fR. +.IP "\fBCPUStatusCombine\fR=1 0/1" 4 +.IX Item "CPUStatusCombine=1 0/1" +Combine all CPUs to one. +.IP "\fBNetStatusCommand\fR=""xterm \-name netstat \-title 'Network Status' \-e netstat \-c""" 4 +.IX Item "NetStatusCommand=""xterm -name netstat -title 'Network Status' -e netstat -c""" +Command to run on Net status. +.IP "\fBNetStatusClassHint\fR=""netstat.XTerm""" 4 +.IX Item "NetStatusClassHint=""netstat.XTerm""" +\&\fBWM_CLASS\fR to allow \fBrunonce\fR for \fBNetStatusCommand\fR. +.IP "\fBAddressBarCommand\fR=""""" 4 +.IX Item "AddressBarCommand=""""" +Command to run for address bar entries. +.SS "WINDOW MENUS" +.IX Subsection "WINDOW MENUS" +.IP "\fBWinMenuItems\fR=""rmsnxfhualytiecw""" 4 +.IX Item "WinMenuItems=""rmsnxfhualytiecw""" +Items supported in menu window (rmsnxfhualytieckw) +.IP \fBRolloverButtonsSupported\fR=0 4 +.IX Item "RolloverButtonsSupported=0" +Does it support the 'O' title bar button images (for mouse rollover). +.IP "\fBShowMenuButtonIcon\fR=1 # 0/1" 4 +.IX Item "ShowMenuButtonIcon=1 # 0/1" +Show application icon over menu button +.SS "THEME SETTINGS" +.IX Subsection "THEME SETTINGS" +The following sections show settings that can be set in theme files. +They can also be set in the \fIpreferences\fR file, but themes will override +the values set there. To override the theme values, the settings should +be set in \fIprefoverrides\fR file: see \fBicewm\-prefoverrides\fR\|(5). Default +values are shown following the equal sign. +.PP +\fITHEME DESCRIPTION\fR +.IX Subsection "THEME DESCRIPTION" +.IP "\fBThemeAuthor\fR=""""" 4 +.IX Item "ThemeAuthor=""""" +Theme author, e\-mail address, credits. +.IP "\fBThemeDescription\fR=""""" 4 +.IX Item "ThemeDescription=""""" +Description of the theme, credits. +.IP "\fBLook\fR=""nice""" 4 +.IX Item "Look=""nice""" +Choose a theme look from one of: +"win95", "motif", "warp3", "warp4", +"nice", "metal2", "gtk2", and some others. +.IP "\fBGradients\fR=""""" 4 +.IX Item "Gradients=""""" +List of gradient pixmaps in the current theme. +.PP +\fITHEME BORDERS, ICONS, MARGINS AND BUTTONS\fR +.IX Subsection "THEME BORDERS, ICONS, MARGINS AND BUTTONS" +.IP "\fBBorderSizeX\fR=6 [0\-128]" 4 +.IX Item "BorderSizeX=6 [0-128]" +Horizontal window border. +.IP "\fBBorderSizeY\fR=6 [0\-128]" 4 +.IX Item "BorderSizeY=6 [0-128]" +Vertical window border. +.IP "\fBDlgBorderSizeX\fR=2 [0\-128]" 4 +.IX Item "DlgBorderSizeX=2 [0-128]" +Horizontal dialog window border. +.IP "\fBDlgBorderSizeY\fR=2 [0\-128]" 4 +.IX Item "DlgBorderSizeY=2 [0-128]" +Vertical dialog window border. +.IP "\fBCornerSizeX\fR=24 [0\-64]" 4 +.IX Item "CornerSizeX=24 [0-64]" +Resize corner width. +.IP "\fBCornerSizeY\fR=24 [0\-64]" 4 +.IX Item "CornerSizeY=24 [0-64]" +Resize corner height. +.IP "\fBTitleBarHeight\fR=20 [0\-128]" 4 +.IX Item "TitleBarHeight=20 [0-128]" +Title bar height. +.IP "\fBTitleBarJustify\fR=0 [0\-100]" 4 +.IX Item "TitleBarJustify=0 [0-100]" +Justification of the window title. +.IP "\fBTitleBarHorzOffset\fR=0 [\-128\-128]" 4 +.IX Item "TitleBarHorzOffset=0 [-128-128]" +Horizontal offset for the window title text. +.IP "\fBTitleBarVertOffset\fR=0 [\-128\-128]" 4 +.IX Item "TitleBarVertOffset=0 [-128-128]" +Vertical offset for the window title text. +.IP "\fBMenuButtonIconVertOffset\fR=0 [\-128\-128]" 4 +.IX Item "MenuButtonIconVertOffset=0 [-128-128]" +Vertical offset for the menu button icon. +.IP "\fBScrollBarX\fR=16 [0\-64]" 4 +.IX Item "ScrollBarX=16 [0-64]" +Scrollbar width. +.IP "\fBScrollBarY\fR=16 [0\-64]" 4 +.IX Item "ScrollBarY=16 [0-64]" +Scrollbar (button) height. +.IP "\fBMenuIconSize\fR=16 [8\-128]" 4 +.IX Item "MenuIconSize=16 [8-128]" +Menu icon size. +.IP "\fBSmallIconSize\fR=16 [8\-128]" 4 +.IX Item "SmallIconSize=16 [8-128]" +Dimension of the small icons. +.IP "\fBLargeIconSize\fR=32 [8\-128]" 4 +.IX Item "LargeIconSize=32 [8-128]" +Dimension of the large icons. +.IP "\fBHugeIconSize\fR=48 [8\-128]" 4 +.IX Item "HugeIconSize=48 [8-128]" +Dimension of the large icons. +.IP "\fBQuickSwitchHorzMargin\fR=3 [0\-64]" 4 +.IX Item "QuickSwitchHorzMargin=3 [0-64]" +Horizontal margin of the quickswitch window. +.IP "\fBQuickSwitchVertMargin\fR=3 [0\-64]" 4 +.IX Item "QuickSwitchVertMargin=3 [0-64]" +Vertical margin of the quickswitch window. +.IP "\fBQuickSwitchIconMargin\fR=4 [0\-64]" 4 +.IX Item "QuickSwitchIconMargin=4 [0-64]" +Vertical margin in the quickswitch window. +.IP "\fBQuickSwitchIconBorder\fR=2 [0\-64]" 4 +.IX Item "QuickSwitchIconBorder=2 [0-64]" +Distance between the active icon and it's border. +.IP "\fBQuickSwitchSeparatorSize\fR=6 [0\-64]" 4 +.IX Item "QuickSwitchSeparatorSize=6 [0-64]" +Height of the separator between (all reachable) icons and text, 0 to avoid it. +.IP "\fBTitleButtonsLeft\fR=""s""" 4 +.IX Item "TitleButtonsLeft=""s""" +Titlebar buttons from left to right (x=close, m=max, i=min, h=hide, r=rollup, s=sysmenu, d=depth). +.IP "\fBTitleButtonsRight\fR=""xmir""" 4 +.IX Item "TitleButtonsRight=""xmir""" +Titlebar buttons from right to left (x=close, m=max, i=min, h=hide, r=rollup, s=sysmenu, d=depth). +.IP "\fBTitleButtonsSupported\fR=""xmis""" 4 +.IX Item "TitleButtonsSupported=""xmis""" +Titlebar buttons supported by theme (x,m,i,r,h,s,d). +.IP "\fBTitleBarCentered\fR=0 # 0/1" 4 +.IX Item "TitleBarCentered=0 # 0/1" +Draw window title centered (obsoleted by TitleBarJustify). +.IP "\fBTitleBarJoinLeft\fR=0 # 0/1" 4 +.IX Item "TitleBarJoinLeft=0 # 0/1" +Join title*S and title*T. +.IP "\fBTitleBarJoinRight\fR=0 # 0/1" 4 +.IX Item "TitleBarJoinRight=0 # 0/1" +Join title*T and title*B. +.IP "\fBTaskBarClockLeds\fR=0 # 0/1" 4 +.IX Item "TaskBarClockLeds=0 # 0/1" +Task bar clock/battery monitor uses nice pixmap LCD display (but then it +doesn't display correctly in many languages anymore, e.g., for +Japanese and Korean it works only when a real font is used and not +the LCD pixmaps.) +.IP "\fBTaskBarGraphHeight\fR=20 [16\-1000]" 4 +.IX Item "TaskBarGraphHeight=20 [16-1000]" +Height of taskbar monitoring applets. +.IP "\fBTaskbuttonIconOffset\fR=0 # [0\-16]" 4 +.IX Item "TaskbuttonIconOffset=0 # [0-16]" +Width of taskbutton side icons. +.IP "\fBTrayIconMaxWidth\fR=32 # [16\-128]" 4 +.IX Item "TrayIconMaxWidth=32 # [16-128]" +Maximum scaled width of tray icons. +.IP "\fBTrayIconMaxHeight\fR=24 # [16\-128]" 4 +.IX Item "TrayIconMaxHeight=24 # [16-128]" +Maximum scaled height of tray icons. +.IP "\fBTrayDrawBevel\fR=0 # 0/1" 4 +.IX Item "TrayDrawBevel=0 # 0/1" +Surround the tray with plastic border. +.PP +\fITHEME FONTS\fR +.IX Subsection "THEME FONTS" +.IP "\fBTitleFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "TitleFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBTitleFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "TitleFontNameXft=""sans-serif:size=12""" +.PD +Name of the title bar font. +.IP "\fBMenuFontName\fR=""\-*\-sans\-bold\-r\-*\-*\-*\-100\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "MenuFontName=""-*-sans-bold-r-*-*-*-100-*-*-*-*-*-*""" +.PD 0 +.IP "\fBMenuFontNameXft\fR=""sans\-serif:size=10:bold""" 4 +.IX Item "MenuFontNameXft=""sans-serif:size=10:bold""" +.PD +Name of the menu font. +.IP "\fBStatusFontName\fR=""\-*\-monospace\-bold\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "StatusFontName=""-*-monospace-bold-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBStatusFontNameXft\fR=""monospace:size=12:bold""" 4 +.IX Item "StatusFontNameXft=""monospace:size=12:bold""" +.PD +Name of the status display font. +.IP "\fBQuickSwitchFontName\fR=""\-*\-monospace\-bold\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "QuickSwitchFontName=""-*-monospace-bold-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBQuickSwitchFontNameXft\fR=""monospace:size=12:bold""" 4 +.IX Item "QuickSwitchFontNameXft=""monospace:size=12:bold""" +.PD +Name of the font for Alt+Tab switcher window. +.IP "\fBNormalButtonFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "NormalButtonFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBNormalButtonFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "NormalButtonFontNameXft=""sans-serif:size=12""" +.PD +Name of the normal button font. +.IP "\fBActiveButtonFontName\fR=""\-*\-sans\-bold\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ActiveButtonFontName=""-*-sans-bold-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBActiveButtonFontNameXft\fR=""sans\-serif:size=12:bold""" 4 +.IX Item "ActiveButtonFontNameXft=""sans-serif:size=12:bold""" +.PD +Name of the active button font. +.IP "\fBNormalTaskBarFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "NormalTaskBarFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBNormalTaskBarFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "NormalTaskBarFontNameXft=""sans-serif:size=12""" +.PD +Name of the normal task bar item font. +.IP "\fBActiveTaskBarFontName\fR=""\-*\-sans\-bold\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ActiveTaskBarFontName=""-*-sans-bold-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBActiveTaskBarFontNameXft\fR=""sans\-serif:size=12:bold""" 4 +.IX Item "ActiveTaskBarFontNameXft=""sans-serif:size=12:bold""" +.PD +Name of the active task bar item font. +.IP "\fBToolButtonFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ToolButtonFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBToolButtonFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "ToolButtonFontNameXft=""sans-serif:size=12""" +.PD +Name of the tool button font (fallback: NormalButtonFontName). +.IP "\fBNormalWorkspaceFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "NormalWorkspaceFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBNormalWorkspaceFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "NormalWorkspaceFontNameXft=""sans-serif:size=12""" +.PD +Name of the normal workspace button font (fallback: NormalButtonFontName). +.IP "\fBActiveWorkspaceFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ActiveWorkspaceFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBActiveWorkspaceFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "ActiveWorkspaceFontNameXft=""sans-serif:size=12""" +.PD +Name of the active workspace button font (fallback: ActiveButtonFontName). +.IP "\fBMinimizedWindowFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "MinimizedWindowFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBMinimizedWindowFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "MinimizedWindowFontNameXft=""sans-serif:size=12""" +.PD +Name of the mini-window font. +.IP "\fBListBoxFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ListBoxFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBListBoxFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "ListBoxFontNameXft=""sans-serif:size=12""" +.PD +Name of the window list font. +.IP "\fBToolTipFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ToolTipFontName=""-*-sans-medium-r-*-*-*-120-*-*-*-*-*-*""" +.PD 0 +.IP "\fBToolTipFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "ToolTipFontNameXft=""sans-serif:size=12""" +.PD +Name of the tool tip font. +.IP "\fBClockFontName\fR=""\-*\-monospace\-medium\-r\-*\-*\-*\-140\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ClockFontName=""-*-monospace-medium-r-*-*-*-140-*-*-*-*-*-*""" +.PD 0 +.IP "\fBClockFontNameXft\fR=""monospace:size=12""" 4 +.IX Item "ClockFontNameXft=""monospace:size=12""" +.PD +Name of the task bar clock font. +.IP "\fBTempFontName\fR=""\-*\-monospace\-medium\-r\-*\-*\-*\-140\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "TempFontName=""-*-monospace-medium-r-*-*-*-140-*-*-*-*-*-*""" +.PD 0 +.IP "\fBTempFontNameXft\fR=""monospace:size=12""" 4 +.IX Item "TempFontNameXft=""monospace:size=12""" +.PD +Name of the task bar temperature font. +.IP "\fBApmFontName\fR=""\-*\-monospace\-medium\-r\-*\-*\-*\-140\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "ApmFontName=""-*-monospace-medium-r-*-*-*-140-*-*-*-*-*-*""" +.PD 0 +.IP "\fBApmFontNameXft\fR=""monospace:size=12""" 4 +.IX Item "ApmFontNameXft=""monospace:size=12""" +.PD +Name of the task bar battery font. +.IP "\fBInputFontName\fR=""\-*\-monospace\-medium\-r\-*\-*\-*\-140\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "InputFontName=""-*-monospace-medium-r-*-*-*-140-*-*-*-*-*-*""" +.PD 0 +.IP "\fBInputFontNameXft\fR=""monospace:size=12""" 4 +.IX Item "InputFontNameXft=""monospace:size=12""" +.PD +Name of the input field font. +.IP "\fBLabelFontName\fR=""\-*\-sans\-medium\-r\-*\-*\-*\-140\-*\-*\-*\-*\-*\-*""" 4 +.IX Item "LabelFontName=""-*-sans-medium-r-*-*-*-140-*-*-*-*-*-*""" +.PD 0 +.IP "\fBLabelFontNameXft\fR=""sans\-serif:size=12""" 4 +.IX Item "LabelFontNameXft=""sans-serif:size=12""" +.PD +Name of the label font. +.PP +\fITHEME COLORS\fR +.IX Subsection "THEME COLORS" +.IP "\fBColorDialog\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorDialog = ""rgb:C0/C0/C0""" +Background of dialog windows. +.IP "\fBColorNormalBorder\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorNormalBorder = ""rgb:C0/C0/C0""" +Border of inactive windows. +.IP "\fBColorActiveBorder\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorActiveBorder = ""rgb:C0/C0/C0""" +Border of active windows. +.IP "\fBColorNormalButton\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorNormalButton = ""rgb:C0/C0/C0""" +Background of regular buttons. +.IP "\fBColorNormalButtonText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNormalButtonText = ""rgb:00/00/00""" +Text color of regular buttons. +.IP "\fBColorActiveButton\fR = ""rgb:E0/E0/E0""" 4 +.IX Item "ColorActiveButton = ""rgb:E0/E0/E0""" +Background of pressed buttons. +.IP "\fBColorActiveButtonText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorActiveButtonText = ""rgb:00/00/00""" +Text color of pressed buttons. +.IP "\fBColorNormalTitleButton\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorNormalTitleButton = ""rgb:C0/C0/C0""" +Background of titlebar buttons. +.IP "\fBColorNormalTitleButtonText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNormalTitleButtonText = ""rgb:00/00/00""" +Text color of titlebar buttons. +.IP "\fBColorToolButton\fR = """"" 4 +.IX Item "ColorToolButton = """"" +Background of toolbar buttons, ColorNormalButton is used if empty. +.IP "\fBColorToolButtonText\fR = """"" 4 +.IX Item "ColorToolButtonText = """"" +Text color of toolbar buttons, ColorNormalButtonText is used if empty. +.IP "\fBColorNormalWorkspaceButton\fR = """"" 4 +.IX Item "ColorNormalWorkspaceButton = """"" +Background of workspace buttons, ColorNormalButton is used if empty. +.IP "\fBColorNormalWorkspaceButtonText\fR = """"" 4 +.IX Item "ColorNormalWorkspaceButtonText = """"" +Text color of workspace buttons, ColorNormalButtonText is used if empty. +.IP "\fBColorActiveWorkspaceButton\fR = """"" 4 +.IX Item "ColorActiveWorkspaceButton = """"" +Background of the active workspace button, ColorActiveButton is used if empty. +.IP "\fBColorActiveWorkspaceButtonText\fR = """"" 4 +.IX Item "ColorActiveWorkspaceButtonText = """"" +Text color of the active workspace button, ColorActiveButtonText is used if empty. +.IP "\fBColorNormalTitleBar\fR = ""rgb:80/80/80""" 4 +.IX Item "ColorNormalTitleBar = ""rgb:80/80/80""" +Background of the titlebar of regular windows. +.IP "\fBColorNormalTitleBarText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNormalTitleBarText = ""rgb:00/00/00""" +Text color of the titlebar of regular windows. +.IP "\fBColorNormalTitleBarShadow\fR = """"" 4 +.IX Item "ColorNormalTitleBarShadow = """"" +Text shadow of the titlebar of regular windows. +.IP "\fBColorActiveTitleBar\fR = ""rgb:00/00/A0""" 4 +.IX Item "ColorActiveTitleBar = ""rgb:00/00/A0""" +Background of the titlebar of active windows. +.IP "\fBColorActiveTitleBarText\fR = ""rgb:FF/FF/FF""" 4 +.IX Item "ColorActiveTitleBarText = ""rgb:FF/FF/FF""" +Text color of the titlebar of active windows. +.IP "\fBColorActiveTitleBarShadow\fR = """"" 4 +.IX Item "ColorActiveTitleBarShadow = """"" +Text shadow of the titlebar of active windows. +.IP "\fBColorNormalMinimizedWindow\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorNormalMinimizedWindow = ""rgb:C0/C0/C0""" +Background for mini icons of regular windows. +.IP "\fBColorNormalMinimizedWindowText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNormalMinimizedWindowText = ""rgb:00/00/00""" +Text color for mini icons of regular windows. +.IP "\fBColorActiveMinimizedWindow\fR = ""rgb:E0/E0/E0""" 4 +.IX Item "ColorActiveMinimizedWindow = ""rgb:E0/E0/E0""" +Background for mini icons of active windows. +.IP "\fBColorActiveMinimizedWindowText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorActiveMinimizedWindowText = ""rgb:00/00/00""" +Text color for mini icons of active windows. +.IP "\fBColorNormalMenu\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorNormalMenu = ""rgb:C0/C0/C0""" +Background of pop-up menus. +.IP "\fBColorNormalMenuItemText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNormalMenuItemText = ""rgb:00/00/00""" +Text color of regular menu items. +.IP "\fBColorActiveMenuItem\fR = ""rgb:A0/A0/A0""" 4 +.IX Item "ColorActiveMenuItem = ""rgb:A0/A0/A0""" +Background of selected menu item, leave empty to force transparency. +.IP "\fBColorActiveMenuItemText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorActiveMenuItemText = ""rgb:00/00/00""" +Text color of selected menu items. +.IP "\fBColorDisabledMenuItemText\fR = ""rgb:80/80/80""" 4 +.IX Item "ColorDisabledMenuItemText = ""rgb:80/80/80""" +Text color of disabled menu items. +.IP "\fBColorDisabledMenuItemShadow\fR = """"" 4 +.IX Item "ColorDisabledMenuItemShadow = """"" +Shadow of regular menu items. +.IP "\fBColorMoveSizeStatus\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorMoveSizeStatus = ""rgb:C0/C0/C0""" +Background of move/resize status window. +.IP "\fBColorMoveSizeStatusText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorMoveSizeStatusText = ""rgb:00/00/00""" +Text color of move/resize status window. +.IP "\fBColorQuickSwitch\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorQuickSwitch = ""rgb:C0/C0/C0""" +Background of the quick switch window. +.IP "\fBColorQuickSwitchText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorQuickSwitchText = ""rgb:00/00/00""" +Text color in the quick switch window. +.IP "\fBColorQuickSwitchActive\fR = """"" 4 +.IX Item "ColorQuickSwitchActive = """"" +Rectangle around the active icon in the quick switch window. +.IP "\fBColorDefaultTaskBar\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorDefaultTaskBar = ""rgb:C0/C0/C0""" +Background of the taskbar. +.IP "\fBColorNormalTaskBarApp\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorNormalTaskBarApp = ""rgb:C0/C0/C0""" +Background for task buttons of regular windows. +.IP "\fBColorNormalTaskBarAppText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNormalTaskBarAppText = ""rgb:00/00/00""" +Text color for task buttons of regular windows. +.IP "\fBColorActiveTaskBarApp\fR = ""rgb:E0/E0/E0""" 4 +.IX Item "ColorActiveTaskBarApp = ""rgb:E0/E0/E0""" +Background for task buttons of the active window. +.IP "\fBColorActiveTaskBarAppText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorActiveTaskBarAppText = ""rgb:00/00/00""" +Text color for task buttons of the active window. +.IP "\fBColorMinimizedTaskBarApp\fR = ""rgb:A0/A0/A0""" 4 +.IX Item "ColorMinimizedTaskBarApp = ""rgb:A0/A0/A0""" +Background for task buttons of minimized windows. +.IP "\fBColorMinimizedTaskBarAppText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorMinimizedTaskBarAppText = ""rgb:00/00/00""" +Text color for task buttons of minimized windows. +.IP "\fBColorInvisibleTaskBarApp\fR = ""rgb:80/80/80""" 4 +.IX Item "ColorInvisibleTaskBarApp = ""rgb:80/80/80""" +Background for task buttons of windows on other workspaces. +.IP "\fBColorInvisibleTaskBarAppText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorInvisibleTaskBarAppText = ""rgb:00/00/00""" +Text color for task buttons of windows on other workspaces. +.IP "\fBColorScrollBar\fR = ""rgb:A0/A0/A0""" 4 +.IX Item "ColorScrollBar = ""rgb:A0/A0/A0""" +Scrollbar background (sliding area). +.IP "\fBColorScrollBarSlider\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorScrollBarSlider = ""rgb:C0/C0/C0""" +Background of the slider button in scrollbars. +.IP "\fBColorScrollBarButton\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorScrollBarButton = ""rgb:C0/C0/C0""" +Background of the arrow buttons in scrollbars. +.IP "\fBColorScrollBarArrow\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorScrollBarArrow = ""rgb:C0/C0/C0""" +Background of the arrow buttons in scrollbars (obsolete). +.IP "\fBColorScrollBarButtonArrow\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorScrollBarButtonArrow = ""rgb:00/00/00""" +Color of active arrows on scrollbar buttons. +.IP "\fBColorScrollBarInactiveArrow\fR = ""rgb:80/80/80""" 4 +.IX Item "ColorScrollBarInactiveArrow = ""rgb:80/80/80""" +Color of inactive arrows on scrollbar buttons. +.IP "\fBColorListBox\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorListBox = ""rgb:C0/C0/C0""" +Background of listboxes. +.IP "\fBColorListBoxText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorListBoxText = ""rgb:00/00/00""" +Text color in listboxes. +.IP "\fBColorListBoxSelection\fR = ""rgb:80/80/80""" 4 +.IX Item "ColorListBoxSelection = ""rgb:80/80/80""" +Background of selected listbox items. +.IP "\fBColorListBoxSelectionText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorListBoxSelectionText = ""rgb:00/00/00""" +Text color of selected listbox items. +.IP "\fBColorToolTip\fR = ""rgb:E0/E0/00""" 4 +.IX Item "ColorToolTip = ""rgb:E0/E0/00""" +Background of tooltips. +.IP "\fBColorToolTipText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorToolTipText = ""rgb:00/00/00""" +Text color of tooltips. +.IP "\fBColorLabel\fR = ""rgb:C0/C0/C0""" 4 +.IX Item "ColorLabel = ""rgb:C0/C0/C0""" +Background of labels, leave empty to force transparency. +.IP "\fBColorLabelText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorLabelText = ""rgb:00/00/00""" +Text color of labels. +.IP "\fBColorInput\fR = ""rgb:FF/FF/FF""" 4 +.IX Item "ColorInput = ""rgb:FF/FF/FF""" +Background of text entry fields (e.g., the addressbar). +.IP "\fBColorInputText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorInputText = ""rgb:00/00/00""" +Text color of text entry fields (e.g., the addressbar). +.IP "\fBColorInputSelection\fR = ""rgb:80/80/80""" 4 +.IX Item "ColorInputSelection = ""rgb:80/80/80""" +Background of selected text in an entry field. +.IP "\fBColorInputSelectionText\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorInputSelectionText = ""rgb:00/00/00""" +Selected text in an entry field. +.IP "\fBColorClock\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorClock = ""rgb:00/00/00""" +Background of non-LCD clock, leave empty to force transparency. +.IP "\fBColorClockText\fR = ""rgb:00/FF/00""" 4 +.IX Item "ColorClockText = ""rgb:00/FF/00""" +Text color of non-LCD clock. +.IP "\fBColorKeyboardLayoutText\fR = """"" 4 +.IX Item "ColorKeyboardLayoutText = """"" +Color of keyboard layout indicator. +.IP "\fBColorApm\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorApm = ""rgb:00/00/00""" +Background of battery monitor, leave empty to force transparency. +.IP "\fBColorApmText\fR = ""rgb:00/FF/00""" 4 +.IX Item "ColorApmText = ""rgb:00/FF/00""" +Text color of battery monitor. +.IP "\fBColorApmBattery\fR = ""rgb:FF/FF/00""" 4 +.IX Item "ColorApmBattery = ""rgb:FF/FF/00""" +Color of battery monitor when discharging. +.IP "\fBColorApmLine\fR = ""rgb:00/FF/00""" 4 +.IX Item "ColorApmLine = ""rgb:00/FF/00""" +Color of battery monitor when charging. +.IP "\fBColorApmGraphBg\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorApmGraphBg = ""rgb:00/00/00""" +Background color for graph mode. +.IP "\fBColorCPUStatusUser\fR = ""rgb:00/FF/00""" 4 +.IX Item "ColorCPUStatusUser = ""rgb:00/FF/00""" +User load on the CPU monitor. +.IP "\fBColorCPUStatusSystem\fR = ""rgb:FF/00/00""" 4 +.IX Item "ColorCPUStatusSystem = ""rgb:FF/00/00""" +System load on the CPU monitor. +.IP "\fBColorCPUStatusInterrupts\fR = ""rgb:FF/FF/00""" 4 +.IX Item "ColorCPUStatusInterrupts = ""rgb:FF/FF/00""" +Interrupts on the CPU monitor. +.IP "\fBColorCPUStatusIoWait\fR = ""rgb:60/00/60""" 4 +.IX Item "ColorCPUStatusIoWait = ""rgb:60/00/60""" +IO Wait on the CPU monitor. +.IP "\fBColorCPUStatusSoftIrq\fR = ""rgb:00/FF/FF""" 4 +.IX Item "ColorCPUStatusSoftIrq = ""rgb:00/FF/FF""" +Soft Interrupts on the CPU monitor. +.IP "\fBColorCPUStatusNice\fR = ""rgb:00/00/FF""" 4 +.IX Item "ColorCPUStatusNice = ""rgb:00/00/FF""" +Nice load on the CPU monitor. +.IP "\fBColorCPUStatusIdle\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorCPUStatusIdle = ""rgb:00/00/00""" +Idle (non) load on the CPU monitor, leave empty to force +transparency. +.IP "\fBColorCPUStatusSteal\fR = ""rgb:FF/8A/91""" 4 +.IX Item "ColorCPUStatusSteal = ""rgb:FF/8A/91""" +Involuntary Wait on the CPU monitor. +.IP "\fBColorCPUStatusTemp\fR = ""rgb:60/60/C0""" 4 +.IX Item "ColorCPUStatusTemp = ""rgb:60/60/C0""" +Temperature of the CPU. +.IP "\fBColorMEMStatusUser\fR = ""rgb:40/40/80""" 4 +.IX Item "ColorMEMStatusUser = ""rgb:40/40/80""" +User program usage in the memory monitor. +.IP "\fBColorMEMStatusBuffers\fR = ""rgb:60/60/C0""" 4 +.IX Item "ColorMEMStatusBuffers = ""rgb:60/60/C0""" +OS buffers usage in the memory monitor. +.IP "\fBColorMEMStatusCached\fR = ""rgb:80/80/FF""" 4 +.IX Item "ColorMEMStatusCached = ""rgb:80/80/FF""" +OS cached usage in the memory monitor. +.IP "\fBColorMEMStatusFree\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorMEMStatusFree = ""rgb:00/00/00""" +Free memory in the memory monitor. +.IP "\fBColorNetSend\fR = ""rgb:FF/FF/00""" 4 +.IX Item "ColorNetSend = ""rgb:FF/FF/00""" +Outgoing load on the network monitor. +.IP "\fBColorNetReceive\fR = ""rgb:FF/00/FF""" 4 +.IX Item "ColorNetReceive = ""rgb:FF/00/FF""" +Incoming load on the network monitor. +.IP "\fBColorNetIdle\fR = ""rgb:00/00/00""" 4 +.IX Item "ColorNetIdle = ""rgb:00/00/00""" +Idle (non) load on the network monitor, leave empty to force transparency. +.PP +\fIDESKTOP BACKGROUND\fR +.IX Subsection "DESKTOP BACKGROUND" +.PP +The following themeable preferences are read by \fBicewmbg\fR\|(1): +.IP "\fBDesktopBackgroundCenter\fR=0 0/1" 4 +.IX Item "DesktopBackgroundCenter=0 0/1" +Display desktop background centered and not tiled. +.IP "\fBDesktopBackgroundScaled\fR=0 0/1" 4 +.IX Item "DesktopBackgroundScaled=0 0/1" +Resize desktop background to full screen. +.IP "\fBDesktopBackgroundColor\fR=""""" 4 +.IX Item "DesktopBackgroundColor=""""" +A comma-separated list of zero or more desktop background colors. +.IP "\fBDesktopBackgroundImage\fR=""""" 4 +.IX Item "DesktopBackgroundImage=""""" +A comma-separated list of zero or more desktop background images. +Each image may be a path with a \fBglob\fR\|(7) pattern, or start with a +tilde or environment variable. +.IP "\fBShuffleBackgroundImages\fR=0 0/1" 4 +.IX Item "ShuffleBackgroundImages=0 0/1" +Choose a random selection from the list of background images. +.IP "\fBSupportSemitransparency\fR=1 0/1" 4 +.IX Item "SupportSemitransparency=1 0/1" +Support for semitransparent terminals like Eterm or gnome-terminal. +.IP "\fBDesktopTransparencyColor\fR=""""" 4 +.IX Item "DesktopTransparencyColor=""""" +Color(s) to announce for semitransparent windows. +.IP "\fBDesktopTransparencyImage\fR=""""" 4 +.IX Item "DesktopTransparencyImage=""""" +Image(s) to announce for semitransparent windows. +This is a list similar to \fBDesktopBackgroundImage\fR. +.IP "\fBDesktopBackgroundMultihead\fR=0 0/1" 4 +.IX Item "DesktopBackgroundMultihead=0 0/1" +Paint the background image over all multihead monitors combined. +.IP \fBCycleBackgroundsPeriod\fR=0 4 +.IX Item "CycleBackgroundsPeriod=0" +Seconds between cycling over all background images, default zero is off. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +.Vb 10 +\& Alpha=1 +\& Splash="IceWM.jpg" +\& LimitSize=0 +\& LimitPosition=0 +\& LimitByDockLayer=1 +\& QuickSwitchToAllWorkspaces=1 +\& QuickSwitchHugeIcon=1 +\& QuickSwitchFillSelection=1 +\& TaskBarMailboxStatusBeepOnNewMail=1 +\& TaskBarMailboxStatusCountMessages=1 +\& TaskBarShowMEMStatus=0 +\& TaskBarShowCollapseButton=1 +\& TaskBarWorkspacesLimit="8" +\& ShowProgramsMenu=1 +\& ShowAddressBar=0 +\& ToolTipDelay=200 +\& ToolTipTime=5000 +\& AutoHideDelay=900 +\& AutoShowDelay=100 +\& EdgeResistance=3 +\& KeySysWinMenu="" +\& KeySysWinListMenu="Shift+Ctrl+Esc" +.Ve +.PP +The above example shows how to tell \fBicewm\fR to not bind a specific key: +\&\fIKeySysWinMenu\fR in this case. +.SS FILES +.IX Subsection "FILES" +Locations for the \fIpreferences\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/preferences +\& $XDG_CONFIG_HOME/icewm/preferences +\& $HOME/.icewm/preferences +\& /etc/icewm/preferences +\& /usr/share/icewm/preferences +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-prefoverride\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-prefoverride.5 b/upstream/fedora-40/man5/icewm-prefoverride.5 new file mode 100644 index 00000000..52b7e8bd --- /dev/null +++ b/upstream/fedora-40/man5/icewm-prefoverride.5 @@ -0,0 +1,109 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-PREFOVERRIDE 5" +.TH ICEWM-PREFOVERRIDE 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-prefoverride \- override themable preferences file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/prefoverride +\& $XDG_CONFIG_HOME/icewm/prefoverride +\& $HOME/.icewm/prefoverride +\& /etc/icewm/prefoverride +\& /usr/share/icewm/prefoverride +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +Settings that override the settings from a theme. Some of the \fBicewm\fR +preferences that control the look may be set by the theme. +However, the settings in this \fIprefoverride\fR file override that. +It is safe to leave this file empty initially. +Note that this file is meant for themable preferences and a few icewm +startup settings cannot be set here, like \f(CW\*(C`Splash\*(C'\fR. +.SS FILES +.IX Subsection "FILES" +Locations for the \fIprefoverride\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/prefoverride +\& $XDG_CONFIG_HOME/icewm/prefoverride +\& $HOME/.icewm/prefoverride +\& /etc/icewm/prefoverride +\& /usr/share/icewm/prefoverride +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-preferences\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-programs.5 b/upstream/fedora-40/man5/icewm-programs.5 new file mode 100644 index 00000000..cf55983b --- /dev/null +++ b/upstream/fedora-40/man5/icewm-programs.5 @@ -0,0 +1,262 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-PROGRAMS 5" +.TH ICEWM-PROGRAMS 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-programs \- icewm programs configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/programs +\& $XDG_CONFIG_HOME/icewm/programs +\& $HOME/.icewm/programs +\& /etc/icewm/programs +\& /usr/share/icewm/programs +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \fIprograms\fR file is an automatically generated menu configuration +file of installed programs. This file should be automatically generated +by xdg_menu, wmconfig (Redhat), menu (Debian), or icewm-menu-fdo, +perhaps as part of the login or X startup sequence. +.SS FORMAT +.IX Subsection "FORMAT" +The format of the file contains one of the following line syntax: +.IP "\fBprog\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "prog [""]title[""] icon program options" +Specifies a program to execute when the menu item is selected. +.IP "\fBrestart\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "restart [""]title[""] icon program options" +Specifies a program to replace the window manager when the menu item is +selected. This is for launching other window managers from within +\&\fBicewm\fR\|(1). +.IP "\fBrunonce\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fB""\fR[\fIres_name\fR][\fB.\fR\fIres_class\fR]\fB""\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "runonce [""]title[""] icon ""[res_name][.res_class]"" program options" +Specifies a program to execute when the menu item is selected; however, +if a window of the specified \fIres_name\fR and \fIres_class\fR is present, +the program will not be run again. +.IP "\fBmenu\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fB{\fR # contained items \fB}\fR" 4 +.IX Item "menu [""]title[""] icon { # contained items }" +Specifies a sub-menu. The lines that appear between the braces can be +any menu item described here. +.IP "\fBmenufile\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR [\fB""\fR]\fIfilename\fR[\fB""\fR]" 4 +.IX Item "menufile [""]title[""] icon [""]filename[""]" +Specifies a file from which to collect sub-menu items (lines) and place +them at this point in the menu. +.IP "\fBmenuprog\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "menuprog [""]title[""] icon program options" +Specifies a program that will print sub-menu items on standard output +and will be collected and placed in the sub-menu at this point. +.IP "\fBmenuprogreload\fR [\fB""\fR]\fItitle\fR[\fB""\fR] \fIicon\fR \fItimeout\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "menuprogreload [""]title[""] icon timeout program options" +Similar to \fBmenuprog\fR, but after at least \fItimeout\fR seconds +the menu is regenerated. +.IP "\fBinclude\fR [\fB""\fR]\fIfilename\fR[\fB""\fR]" 4 +.IX Item "include [""]filename[""]" +Read additional entries from the file \fIfilename\fR +.IP "\fBincludeprog\fR \fIprogram\fR \fIoptions\fR" 4 +.IX Item "includeprog program options" +Read additional entries from the output of \fIprogram\fR \fIoptions\fR. +.IP \fBseparator\fR 4 +.IX Item "separator" +A separator for menu items. +.PP +Where +.IP "\fBprog\fR, \fBrestart\fR, \fBrunonce\fR, \fBmenu\fR, \fBmenufile\fR, \fBmenuprog\fR, \fBmenuprogreload\fR, \fBinclude\fR, \fBincludeprog\fR, \fBseparator\fR" 4 +.IX Item "prog, restart, runonce, menu, menufile, menuprog, menuprogreload, include, includeprog, separator" +These are literal string keywords. +.IP "[\fB""\fR]\fItitle\fR[\fB""\fR]" 4 +.IX Item "[""]title[""]" +This is the \fItitle\fR string associated with the menu item that is +displayed in the menu. When the \fItitle\fR contains spaces, the title +must be surrounded by double quotes (\f(CW\*(C`"\*(C'\fR), although the \fItitle\fR may +always be surrounded by double quotes if preferred. +.IP \fIicon\fR 4 +.IX Item "icon" +Is the name of the icon file (with or without extension) or the full +path to an icon file. +.IP "\fB""\fR[\fIres_name\fR][\fB.\fR\fIres_class\fR]\fB""\fR" 4 +.IX Item """[res_name][.res_class]""" +\&\fIres_name\fR is the resource name of a window launched by \fIprogram\fR and +\&\fIres_class\fR is the resource class of the window. Only one of +\&\fIres_name\fR or \fIres_class\fR need be specified. This is used to identify +whether the program is already running and is for use with the +\&\fBrunonce\fR keyword. +.IP "\fIprogram\fR \fIoptions\fR" 4 +.IX Item "program options" +\&\fIprogram\fR is the name of the executable or full path to the executable file that will +be run in response to selecting the menu item. When used with the +\&\fBmenuprog\fR keyword, the \fIprogram\fR must print on standard output the +contents of the menu and is used for dynamic menus. +.Sp +\&\fIoptions\fR is the options and arguments passed to the \fIprogram\fR +verbatim. +.IP \fIfilename\fR 4 +.IX Item "filename" +\&\fIfilename\fR is the name of the file relative to one of the \fBicewm\fR\|(1) +configuration directories, or the full path to a file. The file is used +with the \fBmenufile\fR keyword and specifies the file from which to read +further menu items. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +Following is the example \fIprograms\fR file that ships with \fBicewm\fR\|(1): +.PP +.Vb 10 +\& # This file is intended to be customized by the distributions. +\& # (they should place it in /etc/X11/icewm) +\& # +\& # mostly obsolete, fixme +\& menu Editors folder { +\& prog fte fte fte +\& prog vim vim gvim +\& prog xemacs xemacs xemacs +\& prog emacs emacs emacs +\& prog NEdit nedit nedit +\& prog xedit xedit xedit +\& prog Lyx emacs lyx +\& } +\& menu "WWW" folder { +\& prog Netscape netscape netscape +\& prog Mozilla mozilla mozilla +\& prog Galeon galeon galeon +\& prog Arena arena arena +\& prog Lynx lynx xterm \-e lynx +\& prog Links lynx xterm \-e links +\& } +\& menu "Document Viewers" folder { +\& prog "Acrobat Reader" pdf acroread +\& prog "DVI Previewer" xdvi xdvi +\& prog "Ghostview" ghostview gv +\& } +\& menu Graphics folder { +\& prog Gimp gimp gimp +\& prog XV xv xv +\& prog XPaint xpaint xpaint +\& prog XFig xfig xfig +\& } +\& menu Games folder { +\& prog "Koules for X" koules xkoules \-f +\& prog Xboing xboing xboing +\& prog Xboard xboard xboard +\& prog XGalaga xgalaga xgal +\& prog XDemineur xdemineur xdemineur +\& prog "Tux Racer" tuxracer tuxracer +\& } +\& menu System folder { +\& prog "Control Panel" redhat control\-panel +\& } +\& menu Utilities folder { +\& prog XPlayCD xplaycd xplaycd +\& prog XMixer xmixer xmixer +\& prog Clock xclock xclock +\& prog Magnify xmag xmag +\& prog Calculator xcalc xcalc +\& prog Colormap xcolormap xcmap +\& prog Clipboard xclipboard xclipboard +\& prog xkill bomb xkill +\& prog xload xload xload +\& prog xosview xosview xosview +\& separator +\& prog "Screen Saver" xlock xlock \-nolock +\& prog "Screen Lock" xlock xlock +\& } +\& menu "Window Managers" folder { +\& restart icewm \- icewm +\& restart metacity \- metacity +\& restart wmaker \- wmaker +\& restart fluxbox \- fluxbox +\& restart blackbox \- blackbox +\& restart enlightenment \- enlightenment +\& restart fvwm2 \- fvwm2 +\& restart fvwm \- fvwm +\& restart sawfish \- sawfish +\& restart sawfish2 \- sawfish2 +\& } +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fIprograms\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/programs +\& $XDG_CONFIG_HOME/icewm/programs +\& $HOME/.icewm/programs +\& /etc/icewm/programs +\& /usr/share/icewm/programs +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-menu\fR\|(5), +\&\fBicewm\-menu\-fdo\fR\|(1). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-shutdown.5 b/upstream/fedora-40/man5/icewm-shutdown.5 new file mode 100644 index 00000000..56cd4fa8 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-shutdown.5 @@ -0,0 +1,108 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-SHUTDOWN 5" +.TH ICEWM-SHUTDOWN 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-shutdown \- icewm shutdown configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/shutdown +\& $XDG_CONFIG_HOME/icewm/shutdown +\& $HOME/.icewm/shutdown +\& /etc/icewm/shutdown +\& /usr/share/icewm/shutdown +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +Contains commands to be executed on \fBicewm\fR shutdown. This is an +executable script with commands to be executed in the last stage of +\&\fBicewm\fR termination. Typically they may undo some of the effects of +the \fIstartup\fR script. It is run by \fBicewm\-session\fR\|(1) when \fBicewm\fR +terminates. +.SS FILES +.IX Subsection "FILES" +Locations for the \fIshutdown\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/shutdown +\& $XDG_CONFIG_HOME/icewm/shutdown +\& $HOME/.icewm/shutdown +\& /etc/icewm/shutdown +\& /usr/share/icewm/shutdown +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\-session\fR\|(1), +\&\fBicewm\-startup\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-startup.5 b/upstream/fedora-40/man5/icewm-startup.5 new file mode 100644 index 00000000..6962672c --- /dev/null +++ b/upstream/fedora-40/man5/icewm-startup.5 @@ -0,0 +1,121 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-STARTUP 5" +.TH ICEWM-STARTUP 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-startup \- icewm startup configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/startup +\& $XDG_CONFIG_HOME/icewm/startup +\& $HOME/.icewm/startup +\& /etc/icewm/startup +\& /usr/share/icewm/startup +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \fIstartup\fR file contains commands to be executed on \fBicewm\fR startup. +This is an executable script. Typically the commands tweak X11 settings +and launch some applications that always need to be active. +It is run by \fBicewm\-session\fR\|(1) when \fBicewm\fR starts. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +.Vb 6 +\& #!/bin/bash +\& xset r rate 250 32 +\& flameshot & +\& volumeicon & +\& redshift\-gtk & +\& picom \-b +.Ve +.PP +Remember to \f(CW\*(C`chmod +x ~/.icewm/startup\*(C'\fR. +The first line must be a hash-bang, followed by the path of your script +interpreter or shell. +.SS FILES +.IX Subsection "FILES" +Locations for the \fIstartup\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/startup +\& $XDG_CONFIG_HOME/icewm/startup +\& $HOME/.icewm/startup +\& /etc/icewm/startup +\& /usr/share/icewm/startup +.Ve +.PP +The locations are searched in the order listed; the first file found is +executed and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\-session\fR\|(1), +\&\fBicewm\-shutdown\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-theme.5 b/upstream/fedora-40/man5/icewm-theme.5 new file mode 100644 index 00000000..e09988c5 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-theme.5 @@ -0,0 +1,140 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-THEME 5" +.TH ICEWM-THEME 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-theme \- icewm theme configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/theme +\& $XDG_CONFIG_HOME/icewm/theme +\& $HOME/.icewm/theme +\& /etc/icewm/theme +\& /usr/share/icewm/theme +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \fItheme\fR file contains the name of the default theme. On startup +\&\fBicewm\fR reads this file to obtain the theme name, unless \fBicewm\fR was +started with the \fB\-\-theme\fR option. Whenever a different theme is +selected from the \fBicewm\fR Menu then the theme file is overwritten with +the name of the selected theme. +.SS FORMAT +.IX Subsection "FORMAT" +This theme file contains the keyword \f(CW\*(C`Theme\*(C'\fR, followed by an equals +sign, followed by a double-quoted string with the theme name. The theme +name is the name of the theme directory, followed by a slash, followed +by the theme file. +.PP +Usually the theme file is just \fIdefault.theme\fR, but a theme may have +alternatives. Alternatives are small tweaks of a theme. These are +specified in their own \fI.theme\fR file, which replaces \fIdefault.theme\fR. +.PP +If no theme file exists then \fBicewm\fR will use the default setting of +\&\f(CW\*(C`Theme="default/default.theme"\*(C'\fR. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +Following is my current \fItheme\fR file. You can see from the comments +that \fBicewm\fR\|(1) keeps a history of the previous ten theme settings. +.PP +.Vb 11 +\& Theme="Unexicon\-towers/default.theme" +\& #Theme="Unexicon\-pedestals/default.theme" +\& ##Theme="Unexicon\-penguins/default.theme" +\& ###Theme="Unexicon/default.theme" +\& ####Theme="Squared\-for\-debian/default.theme" +\& #####Theme="Squared\-grey/default.theme" +\& ######Theme="Squared\-green/default.theme" +\& #######Theme="Penguins/default.theme" +\& ########Theme="Squared\-blue/default.theme" +\& #########Theme="default/default.theme" +\& ##########Theme="yellowmotif/default.theme" +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fItheme\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/theme +\& $XDG_CONFIG_HOME/icewm/theme +\& $HOME/.icewm/theme +\& /etc/icewm/theme +\& /usr/share/icewm/theme +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-preferences\fR\|(5), +\&\fBicewm\-prefoverride\fR\|(5). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-toolbar.5 b/upstream/fedora-40/man5/icewm-toolbar.5 new file mode 100644 index 00000000..f2af59ab --- /dev/null +++ b/upstream/fedora-40/man5/icewm-toolbar.5 @@ -0,0 +1,167 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-TOOLBAR 5" +.TH ICEWM-TOOLBAR 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-toolbar \- icewm toolbar configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/toolbar +\& $XDG_CONFIG_HOME/icewm/toolbar +\& $HOME/.icewm/toolbar +\& /etc/icewm/toolbar +\& /usr/share/icewm/toolbar +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The \fItoolbar\fR file is responsible for configuring quick launch +application icons that are placed on the \fBicewm\fR\|(1) panel. It +contains names of quick to launch applications with icons for the task +bar. Each non-empty non-comment line starts with the keyword \fBprog\fR. +After one or more spaces follows a name, which is displayed in a tool +tip whenever the mouse cursor hovers over the toolbar icon. This name +may be a double quoted string. Then follows the bare name of the icon +to use without extensions. This icon will be shown in the toolbar. The +last component is a shell command line that will be executed whenever +the user presses the icon in the toolbar. For example, the following +line in toolbar will create a button with tool tip \f(CW\*(C`Mozilla Firefox\*(C'\fR +with the \fIfirefox\fR icon which launches \fBfirefox\fR\|(1) when clicked: +.PP +.Vb 1 +\& prog "Mozilla Firefox" firefox /usr/bin/firefox \-\-private\-window +.Ve +.SS FORMAT +.IX Subsection "FORMAT" +The format of the file contains one of the following line syntax: +.Sp +.RS 4 +\&\fBprog\fR \fB"\fR\fItitle\fR\fB"\fR \fIicon\fR \fIprogram\fR \fIoptions\fR +.RE +.PP +Where, +.IP \fBprog\fR 4 +.IX Item "prog" +The literal string \fBprog\fR. +.IP "\fB""\fR\fItitle\fR\fB""\fR" 4 +.IX Item """title""" +The title of the toolbar item, which will appear as a tool-tip for the +program button, enclosed in double quotes (\f(CW\*(C`"\*(C'\fR). +.IP \fIicon\fR 4 +.IX Item "icon" +The icon to display on the toolbar button. May be specified as a single +dash (\f(CW\*(C`\-\*(C'\fR) when no icon is provided. When no icon is provided, the +\&\fItitle\fR text will be displayed on the button in place of the icon. +.IP \fIprogram\fR 4 +.IX Item "program" +The executable program (full path or executable name) to run when the +button is pressed. +.IP \fIoptions\fR 4 +.IX Item "options" +Options and arguments that are passed to \fIprogram\fR. +.PP +Lines beginning with a hash (\f(CW\*(C`#\*(C'\fR) are comment lines. Comment lines and +blank lines are ignored. +.SS EXAMPLES +.IX Subsection "EXAMPLES" +Following is an example that places a number of toolbar buttons on the +\&\fBicewm\fR\|(1) panel: +.PP +.Vb 8 +\& prog "File Manager" file\-manager.png pcmanfm +\& prog "Web Browser" web\-browser.png /usr/lib/firefox/firefox +\& prog "Terminal" terminal.png roxterm +\& prog "Graphical Editor" text\-editor.png gvim \-f +\& prog "Calculator" accessories\-calculator.png calculator +\& prog "Run Command" gtk\-execute.png xde\-run +\& prog "Network" gtk\-network.png pcmanfm ~/Network +\& prog "Logout" system\-log\-out.png xde\-logout +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fItoolbar\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/toolbar +\& $XDG_CONFIG_HOME/icewm/toolbar +\& $HOME/.icewm/toolbar +\& /etc/icewm/toolbar +\& /usr/share/icewm/toolbar +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicewm\-programs\fR\|(5), +\&\fBicewm\-menu\fR\|(5), +\&\fBicewm\-menu\-fdo\fR\|(1). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/icewm-winoptions.5 b/upstream/fedora-40/man5/icewm-winoptions.5 new file mode 100644 index 00000000..b305b885 --- /dev/null +++ b/upstream/fedora-40/man5/icewm-winoptions.5 @@ -0,0 +1,344 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ICEWM-WINOPTIONS 5" +.TH ICEWM-WINOPTIONS 5 2024-01-24 "icewm\ 3.4.5" "Standards, Environments and Macros" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SS NAME +.IX Subsection "NAME" +.Vb 1 +\& icewm\-winoptions \- IceWM window options configuration file +.Ve +.SS SYNOPSIS +.IX Subsection "SYNOPSIS" +.Vb 5 +\& $ICEWM_PRIVCFG/winoptions +\& $XDG_CONFIG_HOME/icewm/winoptions +\& $HOME/.icewm/winoptions +\& /etc/icewm/winoptions +\& /usr/share/icewm/winoptions +.Ve +.SS DESCRIPTION +.IX Subsection "DESCRIPTION" +The IceWM \fIwinoptions\fR file contains settings to control +\&\fIapplication specific\fR window appearance and behavior. +For instance, they control the window border, placement and size, +the window layer, its workspace, its visibility on the task bar +and its focus behavior. +.PP +The winoptions are established when \fBicewm\fR\|(1) starts. However, +they can be overridden later using \fBicesh\fR\|(1) or \fBicewmhint\fR\|(1). +The command \f(CW\*(C`icesh winoptions\*(C'\fR instructs icewm to reload the +\&\fIwinoptions\fR file, while \fIicewmhint\fR tunes a specific application +instance when it starts. +.SS FORMAT +.IX Subsection "FORMAT" +Each line in the file must be in one of the following formats: +.RS 4 +.IP "\fINAME\fR\fB.\fR\fICLASS\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item "NAME.CLASS.OPTION: VALUE" +.PD 0 +.IP "\fICLASS\fR\fB.\fR\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item "CLASS.ROLE.OPTION: VALUE" +.IP "\fINAME\fR\fB.\fR\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item "NAME.ROLE.OPTION: VALUE" +.IP "\fICLASS\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item "CLASS.OPTION: VALUE" +.IP "\fINAME\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item "NAME.OPTION: VALUE" +.IP "\fIROLE\fR\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item "ROLE.OPTION: VALUE" +.IP "\fB.\fR\fIOPTION\fR\fB:\fR \fIVALUE\fR" 4 +.IX Item ".OPTION: VALUE" +.RE +.RS 4 +.RE +.PD +.PP +Here \fINAME\fR and \fICLASS\fR are from the \fBWM_CLASS\fR property of the +window. This can be found in the output of \f(CW\*(C`icesh \-a getClass\*(C'\fR. +.PP +While \fIROLE\fR refers to the \fBWM_WINDOW_ROLE\fR property of the window, +which is the application instance specific name. Only a minority of +windows have it. See the output of \f(CW\*(C`icesh \-a list prop WM_WINDOW_ROLE\*(C'\fR. +.PP +In rare cases, a name, class or role may contain a period. If it does, +the period should be escaped by a single backslash. +.PP +Lastly, the \fIOPTION: VALUE\fR pair refer to the options and values +described below. A line with just a dot, followed by an option/value +pair, applies to all windows. +.SS OPTIONS +.IX Subsection "OPTIONS" +There are four categories: \fIgeneral\fR, \fIfunction\fR, \fIdecor\fR and +\&\fIfeature\fR. +.SS "GENERAL OPTIONS" +.IX Subsection "GENERAL OPTIONS" +These control general characteristics of windows: +.IP "\fBicon\fR: \fINAME\fR (default: none)" 4 +.IX Item "icon: NAME (default: none)" +Specifies the icon name for the window. \fINAME\fR is the icon name, like +\&\fIutilities-terminal\fR. It can also be a file, like \fIxterm.png\fR, a full +path, or a prefix of a path without sizes or suffix. +.IP "\fBworkspace\fR: \fIWORKSPACE\fR (default: current)" 4 +.IX Item "workspace: WORKSPACE (default: current)" +Specifies the default workspace for the window. \fIWORKSPACE\fR is the +workspace number counting from zero (0). +.IP "\fBlayer\fR: {\fILAYER\fR|\fINUMBER\fR} (default: Normal)" 4 +.IX Item "layer: {LAYER|NUMBER} (default: Normal)" +Specifies the default layer for the window. Layer can be one of the +following names or a number from zero to fifteen: +.Sp +.Vb 9 +\& Desktop (0) Desktop window. +\& Below (2) Below the default layer. +\& Normal (4) Default layer for windows. +\& OnTop (6) Above the default layer. +\& Dock (8) Docked windows at edge of screen. +\& AboveDock (10) Windows above the dock. +\& Menu (12) The layer for menu\*(Aqs. +\& Fullscreen (14) When fullscreen and focused. +\& AboveAll (15) Always above anything. +.Ve +.IP "\fBgeometry\fR \fIgeometry\fR (default: WM_SIZE_HINTS property)" 4 +.IX Item "geometry geometry (default: WM_SIZE_HINTS property)" +The default geometry for the window. This geometry should be specified +in a format that can be parsed by \fBXParseGeometry\fR\|(3): +.Sp +.Vb 1 +\& [=][{xX}][{+\-}{+\-}] +.Ve +.Sp +The default geometry is taken from the WM_SIZE_HINTS property of the +window or else from the initial window geometry. This option overrides +the default. +.IP "\fBtray\fR: {\fBIgnore\fR|\fBMinimized\fR|\fBExclusive\fR|\fINUMBER\fR} (default: 0)" 4 +.IX Item "tray: {Ignore|Minimized|Exclusive|NUMBER} (default: 0)" +The default tray option for the window. This affects both the tray and +the task pane. Tray can be one of the following three strings or a number +from zero (0) to two (2): +.Sp +.Vb 3 +\& Ignore (0) No icon is added to the tray. +\& Minimized (1) Add to tray, no task when minimized. +\& Exclusive (2) Add to tray, no task button. +.Ve +.IP "\fBorder\fR: \fINUMBER\fR (default: 0)" 4 +.IX Item "order: NUMBER (default: 0)" +The sorting order for task buttons, tray icons, quick switch and window +list. The default value is zero. Increasing positive values go right, +while decreasing negative values go left. +.IP "\fBopacity\fR: \fINUMBER\fR (default: 0)" 4 +.IX Item "opacity: NUMBER (default: 0)" +Set the _NET_WM_WINDOW_OPACITY property if \fINUMBER\fR is a value between +1 and 100. \fINUMBER\fR is interpreted as percentage of maximum opaqueness. +.IP "\fBkeyboard\fR: \fIlayout\fR (default: none)" 4 +.IX Item "keyboard: layout (default: none)" +Specifies the keyboard layout to use for this window. +The \fIlayout\fR is the name of a keyboard layout. +It can be a space-separated list of arguments to the +\&\fBsetxkbmap\fR program. Please note that \fBsetxkbmap\fR +must be installed for this to work. Also define +a default keyboard layout in \fIpreferences\fR. +.IP "\fBframe\fR: \fIlabel\fR (default: none)" 4 +.IX Item "frame: label (default: none)" +All windows with the same frame label become tabs in a single frame. +.SS "FUNCTION OPTIONS" +.IX Subsection "FUNCTION OPTIONS" +Function options enable/disable (1/0) the ability to take an action on +the window. The normal default for all options is enabled (1) unless +overridden by the application: +.PP +.Vb 7 +\& fClose: {0|1} can be closed. (default: 1) +\& fHide: {0|1} can be hidden. (default: 1) +\& fMaximize: {0|1} can be maximized. (default: 1) +\& fMinimize: {0|1} can be minimized. (default: 1) +\& fMove: {0|1} can be moved. (default: 1) +\& fResize: {0|1} can be resized. (default: 1) +\& fRollup: {0|1} can be shaded. (default: 1) +.Ve +.SS "DECOR OPTIONS" +.IX Subsection "DECOR OPTIONS" +Decor options enable/disable (1/0) decorations on the window. The +normal default for all options is enabled (1) unless overridden by the +application or the theme: +.PP +.Vb 10 +\& dBorder: {0|1} has border. (default: 1) +\& dClose: {0|1} has close button. (default: 1) +\& dDepth: {0|1} has depth button. (default: 1) +\& dHide: {0|1} has hide button. (default: 1) +\& dMaximize: {0|1} has maximize button. (default: 1) +\& dMinimize: {0|1} has minimize button. (default: 1) +\& dResize: {0|1} has resize grips. (default: 1) +\& dRollup: {0|1} has shade button. (default: 1) +\& dSysMenu: {0|1} has window menu. (default: 1) +\& dTitleBar: {0|1} has title bar. (default: 1) +.Ve +.SS "FEATURE OPTIONS" +.IX Subsection "FEATURE OPTIONS" +Feature options enable/disable (1/0) additional features of the window. +The normal default for all options is disabled (0) unless overridden by +the application: +.PP +.Vb 10 +\& allWorkspaces: {1|0} on all workspaces. +\& appTakesFocus: {1|0} let application take focus. +\& doNotCover: {1|0} limits workspace if sticky. +\& doNotFocus: {1|0} do not focus. +\& doNotManage: {1|0} do not manage. +\& forcedClose: {1|0} no close confirmation dialog. +\& fullKeys: {1|0} don\*(Aqt install icewm key bindings. +\& ignoreNoFocusHint: {1|0} focus even when no\-input is set. +\& ignorePagerPreview: {1|0} do not show in pager preview. +\& ignorePositionHint: {1|0} always let icewm place the window. +\& ignoreQuickSwitch: {1|0} not on quick switch. +\& ignoreTaskBar: {1|0} not on task bar. +\& ignoreUrgentHint: {1|0} ignore urgent hints. +\& ignoreWinList: {1|0} not on window list. +\& ignoreActivationMessages: {1|0} only user can focus window. +\& ignoreOverrideRedirect: {1|0} ignore the override redirect flag. +\& noFocusOnAppRaise: {1|0} no automatic focus on raise. +\& noFocusOnMap: {1|0} do not focus when mapped. +\& noIgnoreTaskBar: {1|0} always show on task bar. +\& startClose: {1|0} close the window immediately. +\& startFullscreen: {1|0} start full screen. +\& startMaximized: {1|0} start maximized. +\& startMaximizedHorz: {1|0} start maximized horizontal. +\& startMaximizedVert: {1|0} start maximized vertical. +\& startMinimized: {1|0} start minimized. +.Ve +.SS EXAMPLES +.IX Subsection "EXAMPLES" +This example uses the WM_WINDOW_ROLE property value \f(CW\*(C`pop\-up\*(C'\fR to deny +input focus to \fIChrome\fR pop-ups and asks to close them immediately. +.PP +.Vb 9 +\& google\-chrome.pop\-up.doNotFocus: 1 +\& google\-chrome.pop\-up.forcedClose: 1 +\& google\-chrome.pop\-up.ignorePagerPreview: 1 +\& google\-chrome.pop\-up.ignoreUrgentHint: 1 +\& google\-chrome.pop\-up.layer: Below +\& google\-chrome.pop\-up.noFocusOnAppRaise: 1 +\& google\-chrome.pop\-up.noFocusOnMap: 1 +\& google\-chrome.pop\-up.startClose: 1 +\& google\-chrome.pop\-up.startMinimized: 1 +.Ve +.PP +IceWM places dockapps in a container automatically, but for those +that fail to comply with the protocol it can also be emulated. +An emulated dockapp should appear on all workspaces, have +no decorations, and always be visible in a fixed location. +.PP +.Vb 8 +\& wmtime.wmtime.allWorkspaces: 1 +\& wmtime.wmtime.ignoreTaskBar: 1 +\& wmtime.wmtime.ignoreQuickSwitch: 1 +\& wmtime.wmtime.ignoreWinList: 1 +\& wmtime.wmtime.layer: Below +\& wmtime.wmtime.dTitleBar: 0 +\& wmtime.wmtime.dBorder: 1 +\& wmtime.wmtime.geometry: 64x64\-74\-100 +.Ve +.PP +Following shows how a shaped output-only application is shown +without titlebar and minimal functionality. +.PP +.Vb 11 +\& xeyes.tray: Exclusive +\& xeyes.ignoreWinList: 0 +\& xeyes.ignoreTaskBar: 1 +\& xeyes.allWorkspaces: 1 +\& xeyes.dTitleBar: 0 +\& xeyes.dBorder: 0 +\& xeyes.dSysMenu: 0 +\& xeyes.dResize: 0 +\& xeyes.dClose: 0 +\& xeyes.dMinimize: 0 +\& xeyes.dMaximize: 0 +.Ve +.SS FILES +.IX Subsection "FILES" +Locations for the \fIwinoptions\fR file are as follows: +.PP +.Vb 5 +\& $ICEWM_PRIVCFG/winoptions +\& $XDG_CONFIG_HOME/icewm/winoptions +\& $HOME/.icewm/winoptions +\& /etc/icewm/winoptions +\& /usr/share/icewm/winoptions +.Ve +.PP +The locations are searched in the order listed; the first file found is +read and the remainder ignored. +.SS "SEE ALSO" +.IX Subsection "SEE ALSO" +\&\fBicewm\fR\|(1), +\&\fBicesh\fR\|(1), +\&\fBicewmhint\fR\|(1), +\&\fBsetxkbmap\fR\|(1), +\&\fBXParseGeometry\fR\|(3). +.SS AUTHOR +.IX Subsection "AUTHOR" +Brian Bidulock . +.SS LICENSE +.IX Subsection "LICENSE" +\&\fBIceWM\fR is licensed under the GNU Library General Public License. +See the \fICOPYING\fR file in the distribution. diff --git a/upstream/fedora-40/man5/idmapd.conf.5 b/upstream/fedora-40/man5/idmapd.conf.5 new file mode 100644 index 00000000..58c2d977 --- /dev/null +++ b/upstream/fedora-40/man5/idmapd.conf.5 @@ -0,0 +1,424 @@ +.\" +.\" idmapd.conf(5) +.\" +.\" COPYRIGHT (c) 2008 +.\" The Regents of the University of Michigan +.\" ALL RIGHTS RESERVED +.\" +.\" Permission is granted to use, copy, create derivative works +.\" and redistribute this software and such derivative works +.\" for any purpose, so long as the name of The University of +.\" Michigan is not used in any advertising or publicity +.\" pertaining to the use of distribution of this software +.\" without specific, written prior authorization. If the +.\" above copyright notice or any other identification of the +.\" University of Michigan is included in any copy of any +.\" portion of this software, then the disclaimer below must +.\" also be included. +.\" +.\" THIS SOFTWARE IS PROVIDED AS IS, WITHOUT REPRESENTATION +.\" FROM THE UNIVERSITY OF MICHIGAN AS TO ITS FITNESS FOR ANY +.\" PURPOSE, AND WITHOUT WARRANTY BY THE UNIVERSITY OF +.\" MICHIGAN OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING +.\" WITHOUT LIMITATION THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE +.\" REGENTS OF THE UNIVERSITY OF MICHIGAN SHALL NOT BE LIABLE +.\" FOR ANY DAMAGES, INCLUDING SPECIAL, INDIRECT, INCIDENTAL, OR +.\" CONSEQUENTIAL DAMAGES, WITH RESPECT TO ANY CLAIM ARISING +.\" OUT OF OR IN CONNECTION WITH THE USE OF THE SOFTWARE, EVEN +.\" IF IT HAS BEEN OR IS HEREAFTER ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGES. +.\" +.TH idmapd.conf 5 "19 Nov 2008" +.SH NAME +idmapd.conf \- configuration file for libnfsidmap +.SH SYNOPSIS +Configuration file for libnfsidmap. Used by idmapd and svcgssd to map NFSv4 name to and from ids. +.SH DESCRIPTION +The +.B idmapd.conf +configuration files consists of several sections, initiated by strings of the +form [General] and [Mapping]. Each section may contain lines of the form +.nf + variable = value +.fi +The recognized sections and their recognized variables are as follows: +.\" +.\" ------------------------------------------------------------------- +.\" The [General] section +.\" ------------------------------------------------------------------- +.\" +.SS "[General] section variables" +.nf + + +.fi +.TP +.B Verbosity +Verbosity level of debugging +(Default: 0) +.TP +.B Domain +The local NFSv4 domain name. An NFSv4 domain is a namespace with +a unique username<->UID and groupname<->GID mapping. +(Default: Host's fully-qualified DNS domain name) +.TP +.B No-Strip +In multi-domain environments, some NFS servers will append the identity +management domain to the owner and owner_group in lieu of a true NFSv4 +domain. This option can facilitate lookups in such environments. If +set to a value other than "none", the nsswitch plugin will first pass +the name to the password/group lookup function without stripping the +domain off. If that mapping fails then the plugin will try again using +the old method (comparing the domain in the string to the Domain value, +stripping it if it matches, and passing the resulting short name to the +lookup function). Valid values are "user", "group", "both", and +"none". +(Default: "none") +.TP +.B Reformat-Group +Winbind has a quirk whereby doing a group lookup in UPN format +(e.g. staff@americas.example.com) will cause the group to be +displayed prefixed with the full domain in uppercase +(e.g. AMERICAS.EXAMPLE.COM\\staff) instead of in the familiar netbios +name format (e.g. AMERICAS\\staff). Setting this option to true +causes the name to be reformatted before passing it to the group +lookup function in order to work around this. This setting is +ignored unless No-Strip is set to either "both" or "group". +(Default: "false") +.TP +.B Local-Realms +A comma-separated list of Kerberos realm names that may be considered equivalent to the +local realm name. For example, users juser@ORDER.EDU and juser@MAIL.ORDER.EDU +may be considered to be the same user in the specified +.B Domain. +(Default: the host's default realm name) +.br +.B Note: +If a value is specified here, the default local realm must be included as well. +.\" +.\" ------------------------------------------------------------------- +.\" The [Mapping] section +.\" ------------------------------------------------------------------- +.\" +.SS "[Mapping] section variables" +.nf + +.fi +.TP +.B Nobody-User +Local user name to be used when a mapping cannot be completed. +.TP +.B Nobody-Group +Local group name to be used when a mapping cannot be completed. +.\" +.\" ------------------------------------------------------------------- +.\" The [Translation] section +.\" ------------------------------------------------------------------- +.\" +.SS "[Translation] section variables" +.nf + +.fi +.TP +.B Method +A comma-separated, ordered list of mapping methods (plug-ins) +to use when mapping between NFSv4 names and local IDs. Each +specified method is tried in order until a mapping is found, +or there are no more methods to try. The methods included in +the default distribution include "nsswitch", "umich_ldap", and +"static". +(Default: nsswitch) +.TP +.B GSS-Methods +An optional comma-separated, ordered list of mapping methods (plug-ins) +to use when mapping between GSS Authenticated names and local IDs. +(Default: the same list as specified for +.B Method) +.\" +.\" ------------------------------------------------------------------- +.\" The [Static] section +.\" ------------------------------------------------------------------- +.\" +.SS "[Static] section variables" +.nf + +.fi +The "static" translation method uses a static list of GSS-Authenticated +names to local user names. Entries in the list are of the form: +.nf + principal@REALM = localusername +.fi +.\" +.\" ------------------------------------------------------------------- +.\" The [REGEX] section +.\" ------------------------------------------------------------------- +.\" +.SS "[REGEX] section variables" +.nf + +.fi +If the "regex" translation method is specified, the following +variables within the [REGEX] section are used to map between NFS4 names and local IDs. +.TP +.B User-Regex +Case-insensitive regular expression that extracts the local user name from an NFSv4 name. Multiple expressions may be concatenated with '|'. The first match will be used. +There is no default. A basic regular expression for domain DOMAIN.ORG and realm MY.DOMAIN.ORG would be: +.nf +^DOMAIN\\([^@]+)@MY.DOMAIN.ORG$ +.fi +.TP +.B Group-Regex +Case-insensitive regular expression that extracts the local group name from an NFSv4 name. Multiple expressions may be concatenated with '|'. The first match will be used. +There is no default. A basic regular expression for domain DOMAIN.ORG and realm MY.DOMAIN.ORG would be: +.nf +^([^@]+)@DOMAIN.ORG@MY.DOMAIN.ORG$|^DOMAIN\\([^@]+)@MY.DOMAIN.ORG$ +.fi +.TP +.B Prepend-Before-User +Constant string to put before a local user name when building an NFSv4 name. Usually this is the short domain name followed by '\'. +(Default: none) +.TP +.B Append-After-User +Constant string to put after a local user name when building an NFSv4 name. Usually this is '@' followed by the default realm. +(Default: none) +.TP +.B Prepend-Before-Group +Constant string to put before a local group name when building an NFSv4 name. Usually not used. +(Default: none) +.TP +.B Append-After-Group +Constant string to put before a local group name when building an NFSv4 name. Usually this is '@' followed by the domain name followed by another '@' and the default realm. +(Default: none) +.TP +.B Group-Name-Prefix +Constant string that is prepended to a local group name when converting it to an NFSv4 name. If an NFSv4 group name has this prefix it is removed when converting it to a local group name. +With this group names of a central directory can be shortened for an isolated organizational unit if all groups have a common prefix. +(Default: none) +.TP +.B Group-Name-No-Prefix-Regex +Case-insensitive regular expression to exclude groups from adding and removing the prefix set by +.BR Group-Name-Prefix . +The regular expression must match both the remote and local group names. Multiple expressions may be concatenated with '|'. +(Default: none) +.\" +.\" ------------------------------------------------------------------- +.\" The [UMICH_SCHEMA] section +.\" ------------------------------------------------------------------- +.\" +.SS "[UMICH_SCHEMA] section variables" +.nf + +.fi +If the "umich_ldap" translation method is specified, the following +variables within the [UMICH_SCHEMA] section are used. +.TP +.B LDAP_server +LDAP server name or address +(Required if using UMICH_LDAP) +.TP +.B LDAP_base +Absolute LDAP search base. +(Required if using UMICH_LDAP) +.TP +.B LDAP_people_base +Absolute LDAP search base for people accounts. +(Default: The +.B LDAP_base +value) +.TP +.B LDAP_group_base +Absolute LDAP search base for group accounts. +(Default: The +.B LDAP_base +value) +.TP +.B LDAP_canonicalize_name +Whether or not to perform name canonicalization on the +name given as +.B LDAP_server +(Default: "true") +.TP +.B LDAP_follow_referrals +Whether or not to follow ldap referrals. (Default: "true") +.TP +.B LDAP_use_ssl +Set to "true" to enable SSL communication with the LDAP server. +(Default: "false") +.TP +.B LDAP_ca_cert +Location of a trusted CA certificate used when SSL is enabled +(Required if +.B LDAP_use_ssl +is true and +.B LDAP_tls_reqcert +is not set to never) +.TP +.B LDAP_tls_reqcert +Controls the LDAP server certificate validation behavior. +It can take the same values as ldap.conf(5)'s +.B TLS_REQCERT +tunable. +(Default: "hard") +.TP +.B LDAP_timeout_seconds +Number of seconds before timing out an LDAP request +(Default: 4) +.TP +.B LDAP_sasl_mech +SASL mechanism to be used for sasl authentication. Required +if SASL auth is to be used (Default: None) +.TP +.B LDAP_realm +SASL realm to be used for sasl authentication. (Default: None) +.TP +.B LDAP_sasl_authcid +Authentication identity to be used for sasl authentication. (Default: None) +.TP +.B LDAP_sasl_authzid +Authorization identity to be used for sasl authentication. (Default: None) +.TP +.B LDAP_sasl_secprops +Cyrus SASL security properties. It can the same values as ldap.conf(5)'s +sasl_secprops. +.TP +.B LDAP_sasl_canonicalize +Specifies whether the LDAP server hostname should be canonicalised. +If set to yes LDAP lib with do a reverse hostname lookup. +If this is not set the LDAP library's default will be used. (Default: +None) +.TP +.B LDAP_sasl_krb5_ccname +Path to kerberos credential cache. If it is not set then the value +of environment variable KRB5CCNAME will be used. If the environment +variable is not set then the default mechanism of kerberos library +will be used. +.TP +.B NFSv4_person_objectclass +The object class name for people accounts in your local LDAP schema +(Default: NFSv4RemotePerson) +.TP +.B NFSv4_name_attr +Your local schema's attribute name to be used for NFSv4 user names +(Default: NFSv4Name) +.TP +.B NFSv4_uid_attr +Your local schema's attribute name to be used for uidNumber +(Default: uidNumber) +.TP +.B GSS_principal_attr +Your local schema's attribute name for GSSAPI Principal names +(Default: GSSAuthName) +.TP +.B NFSv4_acctname_attr +Your local schema's attribute name to be used for account names +(Default: uid) +.TP +.B NFSv4_group_objectclass +The object class name for group accounts in your local LDAP schema +(Default: NFSv4RemoteGroup) +.TP +.B NFSv4_gid_attr +Your local schema's attribute name to be used for gidNumber +(Default: gidNumber) +.TP +.B NFSv4_group_attr +Your local schema's attribute name to be used for NFSv4 group names +(Default: NFSv4Name) +.TP +.B LDAP_use_memberof_for_groups +Some LDAP servers do a better job with indexing where searching +through all the groups searching for the user in the memberuid +list. Others like SunOne directory that search can takes minutes +if there are thousands of groups. So setting +.B LDAP_use_memberof_for_groups +to true in the configuration file will use the memberof lists of +the account and search through only those groups to obtain gids. +(Default: false) +.TP +.B NFSv4_member_attr +If +.B LDAP_use_memberof_for_groups +is true, this is the attribute to be searched for. +(Default: memberUid) +.TP +.B NFSv4_grouplist_filter +An optional search filter for determining group membership. +(No Default) +.\" +.\" ------------------------------------------------------------------- +.\" An Example +.\" ------------------------------------------------------------------- +.\" +.SH EXAMPLES +An example +.I /etc/idmapd.conf +file: +.nf + + +[General] + +Verbosity = 0 +Domain = domain.org +Local-Realms = DOMAIN.ORG,MY.DOMAIN.ORG,YOUR.DOMAIN.ORG + +[Mapping] + +Nobody-User = nfsnobody +Nobody-Group = nfsnobody + +[Translation] + +Method = umich_ldap,regex,nsswitch +GSS-Methods = umich_ldap,regex,static + +[Static] + +johndoe@OTHER.DOMAIN.ORG = johnny + +[Regex] + +User-Regex = ^DOMAIN\\([^@]+)@DOMAIN.ORG$ +Group-Regex = ^([^@]+)@DOMAIN.ORG@DOMAIN.ORG$|^DOMAIN\\([^@]+)@DOMAIN.ORG$ +Prepend-Before-User = DOMAIN\ +Append-After-User = @DOMAIN.ORG +Append-After-Group = @domain.org@domain.org +Group-Name-Prefix = sales- +Group-Name-No-Prefix-Regex = -personal-group$ + +[UMICH_SCHEMA] + +LDAP_server = ldap.domain.org +LDAP_base = dc=org,dc=domain + +.fi +.\" +.\" ------------------------------------------------------------------- +.\" Additional sections +.\" ------------------------------------------------------------------- +.\" +.SH FILES +.I /usr/etc/idmapd.conf +.br +.I /usr/etc/idmapd.conf.d/*.conf +.br +.I /etc/idmapd.conf +.br +.I /etc/idmapd.conf.d/*.conf +.br +.IP +Files are read in the order listed. Later settings override earlier +settings. + +.SH SEE ALSO +.BR idmapd (8) +.BR svcgssd (8) +.\".SH COMPATIBILITY +.\".SH STANDARDS +.\".SH ACKNOWLEDGEMENTS +.\".SH AUTHORS +.\".SH HISTORY +.SH BUGS +Report bugs to +.\".SH CAVEATS diff --git a/upstream/fedora-40/man5/info.5 b/upstream/fedora-40/man5/info.5 new file mode 100644 index 00000000..7e01885f --- /dev/null +++ b/upstream/fedora-40/man5/info.5 @@ -0,0 +1,59 @@ +.\" info(5) +.\" +.\" Copyright 1998, 2005, 2011, 2019 Free Software Foundation, Inc. +.\" +.\" Copying and distribution of this file, with or without modification, +.\" are permitted in any medium without royalty provided the copyright +.\" notice and this notice are preserved. +.\" +.de EX +.nf +.ft CW +.in +5 +.. +.de EE +.in -5 +.ft R +.fi +.. +.TH INFO 5 "GNU Info" "FSF" +.SH NAME +info \- readable online documentation +.SH DESCRIPTION +The Info file format is an easily-parsable representation for online +documents. It can be read by +.B emacs\fR(1) +and +.B info\fR(1) +among other programs. +.PP +Info files are usually created from +.B texinfo\fR(5) +sources by +.B makeinfo\fR(1) , +but can be created from scratch if so desired. +.PP +For a full description of the Texinfo language and associated tools, +please see the Texinfo manual (written in Texinfo itself). Most likely, +running this command from your shell: +.EX +info texinfo +.EE +or this key sequence from inside Emacs: +.EX +M-x info RET m texinfo RET +.EE +will get you there. +.SH AVAILABILITY +http://www.gnu.org/software/texinfo/ +.SH "REPORTING BUGS" +Please send bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +\fBinfo\fR(1), \fBinstall-info\fR(1), \fBmakeinfo\fR(1), \fBtexi2dvi\fR(1), +.br +\fBtexindex\fR(1). +.br +\fBemacs\fR(1), \fBtex\fR(1). +.br +\fBtexinfo\fR(5). diff --git a/upstream/fedora-40/man5/integritytab.5 b/upstream/fedora-40/man5/integritytab.5 new file mode 100644 index 00000000..1272444a --- /dev/null +++ b/upstream/fedora-40/man5/integritytab.5 @@ -0,0 +1,189 @@ +'\" t +.TH "INTEGRITYTAB" "5" "" "systemd 255" "integritytab" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +integritytab \- Configuration for integrity block devices +.SH "SYNOPSIS" +.PP +/etc/integritytab +.SH "DESCRIPTION" +.PP +The +/etc/integritytab +file describes integrity protected block devices that are set up during system boot\&. +.PP +Empty lines and lines starting with the +"#" +character are ignored\&. Each of the remaining lines describes one verity integrity protected block device\&. Fields are delimited by white space\&. +.PP +Each line is in the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIvolume\-name\fR \fIblock\-device\fR + \fI[keyfile|\-]\fR \fI[options|\-]\fR +.fi +.if n \{\ +.RE +.\} +.sp +The first two fields are mandatory, the remaining two are optional and only required if user specified non\-default options during integrity format\&. +.PP +The first field contains the name of the resulting integrity volume; its block device is set up below +/dev/mapper/\&. +.PP +The second field contains a path to the underlying block device, or a specification of a block device via +"UUID=" +followed by the UUID, +"PARTUUID=" +followed by the partition UUID, +"LABEL=" +followed by the label, +"PARTLABEL=" +followed by the partition label\&. +.PP +The third field if present contains an absolute filename path to a key file or a +"\-" +to specify none\&. When the filename is present, the "integrity\-algorithm" defaults to +"hmac\-sha256" +with the key length derived from the number of bytes in the key file\&. At this time the only supported integrity algorithm when using key file is hmac\-sha256\&. The maximum size of the key file is 4096 bytes\&. +.PP +The fourth field, if present, is a comma\-delimited list of options or a +"\-" +to specify none\&. The following options are recognized: +.PP +\fBallow\-discards\fR +.RS 4 +Allow the use of discard (TRIM) requests for the device\&. This option is available since the Linux kernel version 5\&.7\&. +.sp +Added in version 250\&. +.RE +.PP +\fBmode=(journal|bitmap|direct)\fR +.RS 4 +Enable journaled, bitmapped or direct (passthrough) mode\&. Journaled mode is the default when this option is not specified\&. It provides safety against crashes, but can be slow because all data has to be written twice\&. Bitmap mode is more efficient since it requires only a single write, but it is less reliable because if data corruption happens when the machine crashes, it may not be detected\&. Direct mode disables the journal and the bitmap\&. Corresponds to the "direct writes" mode documented in +\m[blue]\fBthe dm\-integrity documentation\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that without a journal, if there is a crash, it is possible that the integrity tags and data will not match\&. If used, the journal\-* options below will have no effect if passed\&. +.sp +Added in version 254\&. +.RE +.PP +\fBjournal\-watermark=[0\&.\&.100]%\fR +.RS 4 +Journal watermark in percent\&. When the journal percentage exceeds this watermark, the journal flush will be started\&. Setting a value of "0%" uses default value\&. +.sp +Added in version 250\&. +.RE +.PP +\fBjournal\-commit\-time=[0\&.\&.N]\fR +.RS 4 +Commit time in milliseconds\&. When this time passes (and no explicit flush operation was issued), the journal is written\&. Setting a value of zero uses default value\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdata\-device=/dev/disk/by\-\&.\&.\&.\fR +.RS 4 +Specify a separate block device that contains existing data\&. The second field specified in the integritytab for block device then will contain calculated integrity tags and journal for data\-device, but not the end user data\&. +.sp +Added in version 250\&. +.RE +.PP +\fBintegrity\-algorithm=[crc32c|crc32|sha1|sha256|hmac\-sha256]\fR +.RS 4 +The algorithm used for integrity checking\&. The default is crc32c\&. Must match option used during format\&. +.sp +Added in version 250\&. +.RE +.PP +At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by +\fBsystemd-integritysetup-generator\fR(8)\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&/etc/integritytab\fR +.PP +Set up two integrity protected block devices\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 \- journal\-commit\-time=10,allow\-discards,journal\-watermark=55% +data PARTUUID=5d4b1808\-be76\-774d\-88af\-03c4c3a41761 \- allow\-discards +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&/etc/integritytab\fR +.PP +Set up 1 integrity protected block device using defaults +.sp +.if n \{\ +.RS 4 +.\} +.nf +home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&/etc/integritytab\fR +.PP +Set up 1 integrity device using existing data block device which contains user data +.sp +.if n \{\ +.RS 4 +.\} +.nf +home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 \- data\-device=/dev/disk/by\-uuid/9276d9c0\-d4e3\-4297\-b4ff\-3307cd0d092f +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&/etc/integritytab\fR +.PP +Set up 1 integrity device using a HMAC key file using defaults +.sp +.if n \{\ +.RS 4 +.\} +.nf +home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 /etc/hmac\&.key +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-integritysetup@.service\fR(8), +\fBsystemd-integritysetup-generator\fR(8), +\fBintegritysetup\fR(8), +.SH "NOTES" +.IP " 1." 4 +the dm-integrity documentation +.RS 4 +\%https://docs.kernel.org/admin-guide/device-mapper/dm-integrity.html +.RE diff --git a/upstream/fedora-40/man5/intro.5 b/upstream/fedora-40/man5/intro.5 new file mode 100644 index 00000000..ada73a01 --- /dev/null +++ b/upstream/fedora-40/man5/intro.5 @@ -0,0 +1,23 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:06:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 14 00:34:09 1996 by Andries Brouwer (aeb@cwi.nl) +.TH intro 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +intro \- introduction to file formats and filesystems +.SH DESCRIPTION +Section 5 of the manual describes various file formats, +as well as the corresponding C structures, if any. +.P +In addition, +this section contains a number of pages that document various filesystems. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR standards (7) diff --git a/upstream/fedora-40/man5/iocost.conf.5 b/upstream/fedora-40/man5/iocost.conf.5 new file mode 100644 index 00000000..112f047f --- /dev/null +++ b/upstream/fedora-40/man5/iocost.conf.5 @@ -0,0 +1,96 @@ +'\" t +.TH "IOCOST\&.CONF" "5" "" "systemd 255" "iocost.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +iocost.conf \- Configuration files for the iocost solution manager +.SH "SYNOPSIS" +.PP +/etc/systemd/iocost\&.conf +/etc/systemd/iocost\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +This file configures the behavior of +"iocost", a tool mostly used by +\fBsystemd-udevd\fR(8) +rules to automatically apply I/O cost solutions to +/sys/fs/cgroup/io\&.cost\&.*\&. +.PP +The qos and model values are calculated based on benchmarks collected on the +\m[blue]\fBiocost\-benchmark\fR\m[]\&\s-2\u[1]\d\s+2 +project and turned into a set of solutions that go from most to least isolated\&. Isolation allows the system to remain responsive in face of high I/O load\&. Which solutions are available for a device can be queried from the udev metadata attached to it\&. By default the naive solution is used, which provides the most bandwidth\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [IOCost] section: +.PP +\fITargetSolution=\fR +.RS 4 +Chooses which I/O cost solution (identified by named string) should be used for the devices in this system\&. The known solutions can be queried from the udev metadata attached to the devices\&. If a device does not have the specified solution, the first one listed in +\fIIOCOST_SOLUTIONS\fR +is used instead\&. +.sp +E\&.g\&. +"TargetSolution=isolated\-bandwidth"\&. +.sp +Added in version 254\&. +.RE +.SH "SEE ALSO" +.PP +\fBudevadm\fR(8), +\m[blue]\fBThe iocost\-benchmarks github project\fR\m[]\&\s-2\u[1]\d\s+2, +\m[blue]\fBThe resctl\-bench documentation details how the values are obtained\fR\m[]\&\s-2\u[2]\d\s+2 +.SH "NOTES" +.IP " 1." 4 +iocost-benchmark +.RS 4 +\%https://github.com/iocost-benchmark/iocost-benchmarks +.RE +.IP " 2." 4 +The resctl-bench documentation details how the values are obtained +.RS 4 +\%https://github.com/facebookexperimental/resctl-demo/tree/main/resctl-bench/doc +.RE diff --git a/upstream/fedora-40/man5/issue.5 b/upstream/fedora-40/man5/issue.5 new file mode 100644 index 00000000..e1d6352c --- /dev/null +++ b/upstream/fedora-40/man5/issue.5 @@ -0,0 +1,24 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:06:22 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH issue 5 2022-10-30 "Linux man-pages 6.06" +.SH NAME +issue \- prelogin message and identification file +.SH DESCRIPTION +.I /etc/issue +is a text file which contains a message or +system identification to be printed before the login prompt. +It may contain various \fB@\fP\fIchar\fP and \fB\e\fP\fIchar\fP +sequences, if supported by the +.BR getty -type +program employed on the system. +.SH FILES +.I /etc/issue +.SH SEE ALSO +.BR motd (5), +.BR agetty (8), +.BR mingetty (8) diff --git a/upstream/fedora-40/man5/journal-remote.conf.5 b/upstream/fedora-40/man5/journal-remote.conf.5 new file mode 100644 index 00000000..a2619006 --- /dev/null +++ b/upstream/fedora-40/man5/journal-remote.conf.5 @@ -0,0 +1,140 @@ +'\" t +.TH "JOURNAL\-REMOTE\&.CONF" "5" "" "systemd 255" "journal-remote.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +journal-remote.conf, journal-remote.conf.d \- Configuration files for the service accepting remote journal uploads +.SH "SYNOPSIS" +.PP +/etc/systemd/journal\-remote\&.conf +.PP +/etc/systemd/journal\-remote\&.conf\&.d/*\&.conf +.PP +/run/systemd/journal\-remote\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/journal\-remote\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These files configure various parameters of +\fBsystemd-journal-remote.service\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [Remote] section: +.PP +\fISeal=\fR +.RS 4 +Periodically sign the data in the journal using Forward Secure Sealing\&. +.sp +Added in version 229\&. +.RE +.PP +\fISplitMode=\fR +.RS 4 +One of +"host" +or +"none"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIServerKeyFile=\fR +.RS 4 +SSL key in PEM format\&. +.sp +Added in version 220\&. +.RE +.PP +\fIServerCertificateFile=\fR +.RS 4 +SSL certificate in PEM format\&. +.sp +Added in version 220\&. +.RE +.PP +\fITrustedCertificateFile=\fR +.RS 4 +SSL CA certificate\&. +.sp +Added in version 220\&. +.RE +.PP +\fIMaxUse=\fR, \fIKeepFree=\fR, \fIMaxFileSize=\fR, \fIMaxFiles=\fR +.RS 4 +These are analogous to +\fISystemMaxUse=\fR, +\fISystemKeepFree=\fR, +\fISystemMaxFileSize=\fR +and +\fISystemMaxFiles=\fR +in +\fBjournald.conf\fR(5)\&. +.sp +\fIMaxUse=\fR +controls how much disk space the +\fBsystemd\-journal\-remote\fR +may use up at most\&. +\fIKeepFree=\fR +controls how much disk space +\fBsystemd\-journal\-remote\fR +shall leave free for other uses\&. +\fBsystemd\-journal\-remote\fR +will respect both limits and use the smaller of the two values\&. +.sp +\fIMaxFiles=\fR +controls how many individual journal files to keep at most\&. Note that only archived files are deleted to reduce the number of files until this limit is reached; active files will stay around\&. This means that, in effect, there might still be more journal files around in total than this limit after a vacuuming operation is complete\&. +.sp +Added in version 253\&. +.RE +.SH "SEE ALSO" +.PP +\fBjournald.conf\fR(5), +\fBsystemd\fR(1), +\fBsystemd-journal-remote.service\fR(8), +\fBsystemd-journald.service\fR(8) diff --git a/upstream/fedora-40/man5/journal-upload.conf.5 b/upstream/fedora-40/man5/journal-upload.conf.5 new file mode 100644 index 00000000..73889f48 --- /dev/null +++ b/upstream/fedora-40/man5/journal-upload.conf.5 @@ -0,0 +1,115 @@ +'\" t +.TH "JOURNAL\-UPLOAD\&.CONF" "5" "" "systemd 255" "journal-upload.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +journal-upload.conf, journal-upload.conf.d \- Configuration files for the journal upload service +.SH "SYNOPSIS" +.PP +/etc/systemd/journal\-upload\&.conf +.PP +/etc/systemd/journal\-upload\&.conf\&.d/*\&.conf +.PP +/run/systemd/journal\-upload\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/journal\-upload\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These files configure various parameters of +\fBsystemd-journal-upload.service\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [Upload] section: +.PP +\fIURL=\fR +.RS 4 +The URL to upload the journal entries to\&. See the description of +\fB\-\-url=\fR +option in +\fBsystemd-journal-upload\fR(8) +for the description of possible values\&. There is no default value, so either this option or the command\-line option must be always present to make an upload\&. +.sp +Added in version 232\&. +.RE +.PP +\fIServerKeyFile=\fR +.RS 4 +SSL key in PEM format\&. +.sp +Added in version 232\&. +.RE +.PP +\fIServerCertificateFile=\fR +.RS 4 +SSL CA certificate in PEM format\&. +.sp +Added in version 232\&. +.RE +.PP +\fITrustedCertificateFile=\fR +.RS 4 +SSL CA certificate\&. +.sp +Added in version 232\&. +.RE +.PP +\fINetworkTimeoutSec=\fR +.RS 4 +When network connectivity to the server is lost, this option configures the time to wait for the connectivity to get restored\&. If the server is not reachable over the network for the configured time, +\fBsystemd\-journal\-upload\fR +exits\&. Takes a value in seconds (or in other time units if suffixed with "ms", "min", "h", etc)\&. For details, see +\fBsystemd.time\fR(5)\&. +.sp +Added in version 249\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd-journal-upload.service\fR(8), +\fBsystemd\fR(1), +\fBsystemd-journald.service\fR(8) diff --git a/upstream/fedora-40/man5/journald.conf.5 b/upstream/fedora-40/man5/journald.conf.5 new file mode 100644 index 00000000..911b6cdf --- /dev/null +++ b/upstream/fedora-40/man5/journald.conf.5 @@ -0,0 +1,509 @@ +'\" t +.TH "JOURNALD\&.CONF" "5" "" "systemd 255" "journald.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +journald.conf, journald.conf.d, journald@.conf \- Journal service configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/journald\&.conf +.PP +/etc/systemd/journald\&.conf\&.d/*\&.conf +.PP +/run/systemd/journald\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/journald\&.conf\&.d/*\&.conf +.PP +/etc/systemd/journald@\fINAMESPACE\fR\&.conf +.PP +/etc/systemd/journald@\fINAMESPACE\fR\&.conf\&.d/*\&.conf +.PP +/run/systemd/journald@\fINAMESPACE\fR\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/journald@\fINAMESPACE\fR\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These files configure various parameters of the systemd journal service, +\fBsystemd-journald.service\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.PP +The +\fBsystemd\-journald\fR +instance managing the default namespace is configured by +/etc/systemd/journald\&.conf +and associated drop\-ins\&. Instances managing other namespaces read +/etc/systemd/journald@\fINAMESPACE\fR\&.conf +and associated drop\-ins with the namespace identifier filled in\&. This allows each namespace to carry a distinct configuration\&. See +\fBsystemd-journald.service\fR(8) +for details about journal namespaces\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [Journal] section: +.PP +\fIStorage=\fR +.RS 4 +Controls where to store journal data\&. One of +"volatile", +"persistent", +"auto" +and +"none"\&. If +"volatile", journal log data will be stored only in memory, i\&.e\&. below the +/run/log/journal +hierarchy (which is created if needed)\&. If +"persistent", data will be stored preferably on disk, i\&.e\&. below the +/var/log/journal +hierarchy (which is created if needed), with a fallback to +/run/log/journal +(which is created if needed), during early boot and if the disk is not writable\&. +"auto" +behaves like +"persistent" +if the +/var/log/journal +directory exists, and +"volatile" +otherwise (the existence of the directory controls the storage mode)\&. +"none" +turns off all storage, all log data received will be dropped (but forwarding to other targets, such as the console, the kernel log buffer, or a syslog socket will still work)\&. Defaults to +"auto" +in the default journal namespace, and +"persistent" +in all others\&. +.sp +Note that journald will initially use volatile storage, until a call to +\fBjournalctl \-\-flush\fR +(or sending +\fBSIGUSR1\fR +to journald) will cause it to switch to persistent logging (under the conditions mentioned above)\&. This is done automatically on boot via +"systemd\-journal\-flush\&.service"\&. +.sp +Note that when this option is changed to +"volatile", existing persistent data is not removed\&. In the other direction, +\fBjournalctl\fR(1) +with the +\fB\-\-flush\fR +option may be used to move volatile data to persistent storage\&. +.sp +When journal namespacing (see +\fILogNamespace=\fR +in +\fBsystemd.exec\fR(5)) is used, setting +\fIStorage=\fR +to +"volatile" +or +"auto" +will not have an effect on the creation of the per\-namespace logs directory in +/var/log/journal/, as the +systemd\-journald@\&.service +service file by default carries +\fILogsDirectory=\fR\&. To turn that off, add a unit file drop\-in file that sets +\fILogsDirectory=\fR +to an empty string\&. +.sp +Note that per\-user journal files are not supported unless persistent storage is enabled, thus making +\fBjournalctl \-\-user\fR +unavailable\&. +.sp +Added in version 186\&. +.RE +.PP +\fICompress=\fR +.RS 4 +Can take a boolean value\&. If enabled (the default), data objects that shall be stored in the journal and are larger than the default threshold of 512 bytes are compressed before they are written to the file system\&. It can also be set to a number of bytes to specify the compression threshold directly\&. Suffixes like K, M, and G can be used to specify larger units\&. +.RE +.PP +\fISeal=\fR +.RS 4 +Takes a boolean value\&. If enabled (the default), and a sealing key is available (as created by +\fBjournalctl\fR(1)\*(Aqs +\fB\-\-setup\-keys\fR +command), Forward Secure Sealing (FSS) for all persistent journal files is enabled\&. FSS is based on +\m[blue]\fBSeekable Sequential Key Generators\fR\m[]\&\s-2\u[1]\d\s+2 +by G\&. A\&. Marson and B\&. Poettering (doi:10\&.1007/978\-3\-642\-40203\-6_7) and may be used to protect journal files from unnoticed alteration\&. +.sp +Added in version 189\&. +.RE +.PP +\fISplitMode=\fR +.RS 4 +Controls whether to split up journal files per user, either +"uid" +or +"none"\&. Split journal files are primarily useful for access control: on UNIX/Linux access control is managed per file, and the journal daemon will assign users read access to their journal files\&. If +"uid", all regular users (with UID outside the range of system users, dynamic service users, and the nobody user) will each get their own journal files, and system users will log to the system journal\&. See +\m[blue]\fBUsers, Groups, UIDs and GIDs on systemd systems\fR\m[]\&\s-2\u[2]\d\s+2 +for more details about UID ranges\&. If +"none", journal files are not split up by user and all messages are instead stored in the single system journal\&. In this mode unprivileged users generally do not have access to their own log data\&. Note that splitting up journal files by user is only available for journals stored persistently\&. If journals are stored on volatile storage (see +\fIStorage=\fR +above), only a single journal file is used\&. Defaults to +"uid"\&. +.sp +Added in version 190\&. +.RE +.PP +\fIRateLimitIntervalSec=\fR, \fIRateLimitBurst=\fR +.RS 4 +Configures the rate limiting that is applied to all messages generated on the system\&. If, in the time interval defined by +\fIRateLimitIntervalSec=\fR, more messages than specified in +\fIRateLimitBurst=\fR +are logged by a service, all further messages within the interval are dropped until the interval is over\&. A message about the number of dropped messages is generated\&. This rate limiting is applied per\-service, so that two services which log do not interfere with each other\*(Aqs limits\&. Defaults to 10000 messages in 30s\&. The time specification for +\fIRateLimitIntervalSec=\fR +may be specified in the following units: +"s", +"min", +"h", +"ms", +"us"\&. To turn off any kind of rate limiting, set either value to 0\&. +.sp +Note that the effective rate limit is multiplied by a factor derived from the available free disk space for the journal\&. Currently, this factor is calculated using the base 2 logarithm\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Example \fIRateLimitBurst=\fR rate modifications by the available disk space +.TS +allbox tab(:); +lB lB. +T{ +Available Disk Space +T}:T{ +Burst Multiplier +T} +.T& +l l +l l +l l +l l +l l +l l. +T{ +<= 1MB +T}:T{ +1 +T} +T{ +<= 16MB +T}:T{ +2 +T} +T{ +<= 256MB +T}:T{ +3 +T} +T{ +<= 4GB +T}:T{ +4 +T} +T{ +<= 64GB +T}:T{ +5 +T} +T{ +<= 1TB +T}:T{ +6 +T} +.TE +.sp 1 +If a service provides rate limits for itself through +\fILogRateLimitIntervalSec=\fR +and/or +\fILogRateLimitBurst=\fR +in +\fBsystemd.exec\fR(5), those values will override the settings specified here\&. +.RE +.PP +\fISystemMaxUse=\fR, \fISystemKeepFree=\fR, \fISystemMaxFileSize=\fR, \fISystemMaxFiles=\fR, \fIRuntimeMaxUse=\fR, \fIRuntimeKeepFree=\fR, \fIRuntimeMaxFileSize=\fR, \fIRuntimeMaxFiles=\fR +.RS 4 +Enforce size limits on the journal files stored\&. The options prefixed with +"System" +apply to the journal files when stored on a persistent file system, more specifically +/var/log/journal\&. The options prefixed with +"Runtime" +apply to the journal files when stored on a volatile in\-memory file system, more specifically +/run/log/journal\&. The former is used only when +/var/ +is mounted, writable, and the directory +/var/log/journal +exists\&. Otherwise, only the latter applies\&. Note that this means that during early boot and if the administrator disabled persistent logging, only the latter options apply, while the former apply if persistent logging is enabled and the system is fully booted up\&. +\fBjournalctl\fR +and +\fBsystemd\-journald\fR +ignore all files with names not ending with +"\&.journal" +or +"\&.journal~", so only such files, located in the appropriate directories, are taken into account when calculating current disk usage\&. +.sp +\fISystemMaxUse=\fR +and +\fIRuntimeMaxUse=\fR +control how much disk space the journal may use up at most\&. +\fISystemKeepFree=\fR +and +\fIRuntimeKeepFree=\fR +control how much disk space systemd\-journald shall leave free for other uses\&. +\fBsystemd\-journald\fR +will respect both limits and use the smaller of the two values\&. +.sp +The first pair defaults to 10% and the second to 15% of the size of the respective file system, but each value is capped to 4G\&. If the file system is nearly full and either +\fISystemKeepFree=\fR +or +\fIRuntimeKeepFree=\fR +are violated when systemd\-journald is started, the limit will be raised to the percentage that is actually free\&. This means that if there was enough free space before and journal files were created, and subsequently something else causes the file system to fill up, journald will stop using more space, but it will not be removing existing files to reduce the footprint again, either\&. Also note that only archived files are deleted to reduce the space occupied by journal files\&. This means that, in effect, there might still be more space used than +\fISystemMaxUse=\fR +or +\fIRuntimeMaxUse=\fR +limit after a vacuuming operation is complete\&. +.sp +\fISystemMaxFileSize=\fR +and +\fIRuntimeMaxFileSize=\fR +control how large individual journal files may grow at most\&. This influences the granularity in which disk space is made available through rotation, i\&.e\&. deletion of historic data\&. Defaults to one eighth of the values configured with +\fISystemMaxUse=\fR +and +\fIRuntimeMaxUse=\fR +capped to 128M, so that usually seven rotated journal files are kept as history\&. If the journal compact mode is enabled (enabled by default), the maximum file size is capped to 4G\&. +.sp +Specify values in bytes or use K, M, G, T, P, E as units for the specified sizes (equal to 1024, 1024\(S2, \&... bytes)\&. Note that size limits are enforced synchronously when journal files are extended, and no explicit rotation step triggered by time is needed\&. +.sp +\fISystemMaxFiles=\fR +and +\fIRuntimeMaxFiles=\fR +control how many individual journal files to keep at most\&. Note that only archived files are deleted to reduce the number of files until this limit is reached; active files will stay around\&. This means that, in effect, there might still be more journal files around in total than this limit after a vacuuming operation is complete\&. This setting defaults to 100\&. +.RE +.PP +\fIMaxFileSec=\fR +.RS 4 +The maximum time to store entries in a single journal file before rotating to the next one\&. Normally, time\-based rotation should not be required as size\-based rotation with options such as +\fISystemMaxFileSize=\fR +should be sufficient to ensure that journal files do not grow without bounds\&. However, to ensure that not too much data is lost at once when old journal files are deleted, it might make sense to change this value from the default of one month\&. Set to 0 to turn off this feature\&. This setting takes time values which may be suffixed with the units +"year", +"month", +"week", +"day", +"h" +or +"m" +to override the default time unit of seconds\&. +.sp +Added in version 195\&. +.RE +.PP +\fIMaxRetentionSec=\fR +.RS 4 +The maximum time to store journal entries\&. This controls whether journal files containing entries older than the specified time span are deleted\&. Normally, time\-based deletion of old journal files should not be required as size\-based deletion with options such as +\fISystemMaxUse=\fR +should be sufficient to ensure that journal files do not grow without bounds\&. However, to enforce data retention policies, it might make sense to change this value from the default of 0 (which turns off this feature)\&. This setting also takes time values which may be suffixed with the units +"year", +"month", +"week", +"day", +"h" +or +" m" +to override the default time unit of seconds\&. +.sp +Added in version 195\&. +.RE +.PP +\fISyncIntervalSec=\fR +.RS 4 +The timeout before synchronizing journal files to disk\&. After syncing, journal files are placed in the OFFLINE state\&. Note that syncing is unconditionally done immediately after a log message of priority CRIT, ALERT or EMERG has been logged\&. This setting hence applies only to messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG\&. The default timeout is 5 minutes\&. +.sp +Added in version 199\&. +.RE +.PP +\fIForwardToSyslog=\fR, \fIForwardToKMsg=\fR, \fIForwardToConsole=\fR, \fIForwardToWall=\fR +.RS 4 +Control whether log messages received by the journal daemon shall be forwarded to a traditional syslog daemon, to the kernel log buffer (kmsg), to the system console, or sent as wall messages to all logged\-in users\&. These options take boolean arguments\&. If forwarding to syslog is enabled but nothing reads messages from the socket, forwarding to syslog has no effect\&. By default, only forwarding to wall is enabled\&. These settings may be overridden at boot time with the kernel command line options +"systemd\&.journald\&.forward_to_syslog", +"systemd\&.journald\&.forward_to_kmsg", +"systemd\&.journald\&.forward_to_console", and +"systemd\&.journald\&.forward_to_wall"\&. If the option name is specified without +"=" +and the following argument, true is assumed\&. Otherwise, the argument is parsed as a boolean\&. +.sp +When forwarding to the console, the TTY to log to can be changed with +\fITTYPath=\fR, described below\&. +.sp +When forwarding to the kernel log buffer (kmsg), make sure to select a suitably large size for the log buffer, for example by adding +"log_buf_len=8M" +to the kernel command line\&. +\fBsystemd\fR +will automatically disable kernel\*(Aqs rate\-limiting applied to userspace processes (equivalent to setting +"printk\&.devkmsg=on")\&. +.PP +Note: Forwarding is performed synchronously within journald, and may significantly affect its performance\&. This is particularly relevant when using ForwardToConsole=yes in cloud environments, where the console is often a slow, virtual serial port\&. Since journald is implemented as a conventional single\-process daemon, forwarding to a completely hung console will block journald\&. This can have a cascading effect resulting in any services synchronously logging to the blocked journal also becoming blocked\&. Unless actively debugging/developing something, it\*(Aqs generally preferable to setup a +\fBjournalctl \-\-follow\fR +style service redirected to the console, instead of ForwardToConsole=yes, for production use\&. +.RE +.PP +\fIMaxLevelStore=\fR, \fIMaxLevelSyslog=\fR, \fIMaxLevelKMsg=\fR, \fIMaxLevelConsole=\fR, \fIMaxLevelWall=\fR +.RS 4 +Controls the maximum log level of messages that are stored in the journal, forwarded to syslog, kmsg, the console or wall (if that is enabled, see above)\&. As argument, takes one of +"emerg", +"alert", +"crit", +"err", +"warning", +"notice", +"info", +"debug", or integer values in the range of 0\(en7 (corresponding to the same levels)\&. Messages equal or below the log level specified are stored/forwarded, messages above are dropped\&. Defaults to +"debug" +for +\fIMaxLevelStore=\fR +and +\fIMaxLevelSyslog=\fR, to ensure that the all messages are stored in the journal and forwarded to syslog\&. Defaults to +"notice" +for +\fIMaxLevelKMsg=\fR, +"info" +for +\fIMaxLevelConsole=\fR, and +"emerg" +for +\fIMaxLevelWall=\fR\&. These settings may be overridden at boot time with the kernel command line options +"systemd\&.journald\&.max_level_store=", +"systemd\&.journald\&.max_level_syslog=", +"systemd\&.journald\&.max_level_kmsg=", +"systemd\&.journald\&.max_level_console=", +"systemd\&.journald\&.max_level_wall="\&. +.sp +Added in version 185\&. +.RE +.PP +\fIReadKMsg=\fR +.RS 4 +Takes a boolean value\&. If enabled +\fBsystemd\-journal\fR +processes +/dev/kmsg +messages generated by the kernel\&. In the default journal namespace this option is enabled by default, it is disabled in all others\&. +.sp +Added in version 235\&. +.RE +.PP +\fIAudit=\fR +.RS 4 +Takes a boolean value\&. If enabled +\fBsystemd\-journald\fR +will turn on kernel auditing on start\-up\&. If disabled it will turn it off\&. If unset it will neither enable nor disable it, leaving the previous state unchanged\&. This means if another tool turns on auditing even if +\fBsystemd\-journald\fR +left it off, it will still collect the generated messages\&. Defaults to on\&. +.sp +Note that this option does not control whether +\fBsystemd\-journald\fR +collects generated audit records, it just controls whether it tells the kernel to generate them\&. If you need to prevent +\fBsystemd\-journald\fR +from collecting the generated messages, the socket unit +"systemd\-journald\-audit\&.socket" +can be disabled and in this case this setting is without effect\&. +.sp +Added in version 246\&. +.RE +.PP +\fITTYPath=\fR +.RS 4 +Change the console TTY to use if +\fIForwardToConsole=yes\fR +is used\&. Defaults to +/dev/console\&. +.sp +Added in version 185\&. +.RE +.PP +\fILineMax=\fR +.RS 4 +The maximum line length to permit when converting stream logs into record logs\&. When a systemd unit\*(Aqs standard output/error are connected to the journal via a stream socket, the data read is split into individual log records at newline ("\en", ASCII 10) and +\fBNUL\fR +characters\&. If no such delimiter is read for the specified number of bytes a hard log record boundary is artificially inserted, breaking up overly long lines into multiple log records\&. Selecting overly large values increases the possible memory usage of the Journal daemon for each stream client, as in the worst case the journal daemon needs to buffer the specified number of bytes in memory before it can flush a new log record to disk\&. Also note that permitting overly large line maximum line lengths affects compatibility with traditional log protocols as log records might not fit anymore into a single +\fBAF_UNIX\fR +or +\fBAF_INET\fR +datagram\&. Takes a size in bytes\&. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively\&. Defaults to 48K, which is relatively large but still small enough so that log records likely fit into network datagrams along with extra room for metadata\&. Note that values below 79 are not accepted and will be bumped to 79\&. +.sp +Added in version 235\&. +.RE +.SH "FORWARDING TO TRADITIONAL SYSLOG DAEMONS" +.PP +Journal events can be transferred to a different logging daemon in two different ways\&. With the first method, messages are immediately forwarded to a socket (/run/systemd/journal/syslog), where the traditional syslog daemon can read them\&. This method is controlled by the +\fIForwardToSyslog=\fR +option\&. With a second method, a syslog daemon behaves like a normal journal client, and reads messages from the journal files, similarly to +\fBjournalctl\fR(1)\&. With this, messages do not have to be read immediately, which allows a logging daemon which is only started late in boot to access all messages since the start of the system\&. In addition, full structured meta\-data is available to it\&. This method of course is available only if the messages are stored in a journal file at all\&. So it will not work if +\fIStorage=none\fR +is set\&. It should be noted that usually the +\fIsecond\fR +method is used by syslog daemons, so the +\fIStorage=\fR +option, and not the +\fIForwardToSyslog=\fR +option, is relevant for them\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-journald.service\fR(8), +\fBjournalctl\fR(1), +\fBsystemd.journal-fields\fR(7), +\fBsystemd-system.conf\fR(5) +.SH "NOTES" +.IP " 1." 4 +Seekable Sequential Key Generators +.RS 4 +\%https://eprint.iacr.org/2013/397 +.RE +.IP " 2." 4 +Users, Groups, UIDs and GIDs on systemd systems +.RS 4 +\%https://systemd.io/UIDS-GIDS +.RE diff --git a/upstream/fedora-40/man5/keymaps.5 b/upstream/fedora-40/man5/keymaps.5 new file mode 100644 index 00000000..bbc62b76 --- /dev/null +++ b/upstream/fedora-40/man5/keymaps.5 @@ -0,0 +1,439 @@ +.\" keymaps.5 - Copyright (C) Andries Brouwer 1998 +.\" May be freely distributed. +.\" @(#)keymaps.5 1.10 940130 aeb +.TH KEYMAPS 5 "24 April 1998" "kbd" +.SH NAME +keymaps \- keyboard table descriptions for loadkeys and dumpkeys +.SH DESCRIPTION +.IX "keymaps" "" "\fLkeymaps\fR \(em keyboard table descriptions for loadkeys and dumpkeys" "" +.IX "loadkeys" "keyboard table descriptions" "\fLloadkeys\fR" "keyboard table descriptions" +.IX "dumpkeys" "keyboard table descriptions" "\fLdumpkeys\fR" "keyboard table descriptions" +.IX keyboard "table descriptions for loadkeys and dumpkeys" keyboard "table descriptions for \fLloadkeys\fR and \fLdumpkeys\fR" +.IX "translation tables" +.LP +These files are used by +.BR loadkeys (1) +to modify the translation tables used by the kernel keyboard driver +and generated by +.BR dumpkeys (1) +from those translation tables. +.LP +The format of these files is vaguely similar to the one accepted by +.BR xmodmap (1). +The file consists of charset or key or string definition lines +interspersed with comments. +.LP +Comments are introduced with +.B ! +or +.B # +characters and continue to the end of the line. Anything following one +of these characters on that line is ignored. Note that comments need +not begin from column one as with +.BR xmodmap (1). +.LP +The syntax of keymap files is line oriented; a complete definition +must fit on a single logical line. Logical lines can, however, be split +into multiple physical lines by ending each subline with the backslash +character (\\). +.SH "INCLUDE FILES" +A keymap can include other keymaps using the syntax +.LP +.RS +include "pathname" +.RE +.LP +.SH "CHARSET DEFINITIONS" +A character set definition line is of the form: +.LP +.RS +.EX +charset "iso-8859-x" +.EE +.RE +.LP +It defines how following keysyms are to be interpreted. +For example, in iso-8859-1 the symbol mu (or micro) has code 0265, +while in iso-8859-7 the letter mu has code 0354. +.SH "COMPLETE KEYCODE DEFINITIONS" +Each complete key definition line is of the form: +.LP +.RS +.nf +.BI keycode " keynumber " = " keysym keysym keysym" \fR... +.fi +.RE +.LP +.I keynumber +is the internal identification number of the key, roughly equivalent to +the scan code of it. +.I keynumber +can be given in decimal, octal or hexadecimal notation. +Octal is denoted by a leading zero and hexadecimal by the prefix +.B 0x. +.LP +Each of the +.I keysyms +represent keyboard actions, of which up to 256 can be bound to a single +key. The actions available include outputting character codes or +character sequences, switching consoles or keymaps, booting the machine +etc. (The complete list can be obtained from +.BR dumpkeys (1) +by saying +.B " dumpkeys -l" +\&.) +.LP +Each +.I keysym +may be prefixed by a '+' (plus sign), in which case this keysym is treated +as a "letter" and therefore affected by the "CapsLock" the same way as by +"Shift" (to be correct, the CapsLock inverts the Shift state). +The ASCII letters ('a'-'z' and 'A'-'Z') are made CapsLock'able by default. +If Shift+CapsLock should not produce a lower case symbol, put lines like +.LP +.RS +.nf +.B "keycode 30 = +a A" +.fi +.RE +.LP +in the map file. +.LP +Which of the actions bound to a given key is taken when it is pressed +depends on what modifiers are in effect at that moment. +The keyboard driver supports 9 modifiers. These modifiers are labeled +(completely arbitrarily) Shift, AltGr, Control, Alt, ShiftL, ShiftR, +CtrlL, CtrlR and CapsShift. +Each of these modifiers has an associated weight of power of two +according to the following table: + +.ev table +.LP +.RS +.TP 20 +.I modifier +.I weight +.P +.ta T 24R +Shift 1 +.br +AltGr 2 +.br +Control 4 +.br +Alt 8 +.br +ShiftL 16 +.br +ShiftR 32 +.br +CtrlL 64 +.br +CtrlR 128 +.br +CapsShift 256 +.RE +.LP +.ev +The effective action of a key is found out by adding up the weights of +all the modifiers in effect. By default, no modifiers are in effect, so +action number zero, i.e. the one in the first column in a key definition +line, is taken when the key is pressed or released. When e.g. Shift and +Alt modifiers are in effect, action number nine (from the 10th column) +is the effective one. +.LP +Changing the state of what modifiers are in effect can be achieved by +binding appropriate key actions to desired keys. For example, binding +the symbol Shift to a key sets the Shift modifier in effect when that +key is pressed and cancels the effect of that modifier when the key is +released. Binding AltGr_Lock to a key sets AltGr in effect when the key +is pressed and cancels the effect when the key is pressed again. +(By default Shift, AltGr, Control and Alt are bound to the keys that bear +a similar label; AltGr may denote the right Alt key.) +.LP +Note that you should be very careful when binding the modifier keys, +otherwise you can end up with an unusable keyboard mapping. If you for +example define a key to have Control in its first column and leave the +rest of the columns to be VoidSymbols, you're in trouble. This is +because pressing the key puts Control modifier in effect and the +following actions are looked up from the fifth column (see the table +above). So, when you release the key, the action from the fifth column +is taken. It has VoidSymbol in it, so nothing happens. This means that +the Control modifier is still in effect, although you have released the key. +Re-pressing and releasing the key has no effect. To avoid this, +you should always define all the columns to have the same modifier +symbol. There is a handy short-hand notation for this, see below. +.LP +.I keysyms +can be given in decimal, octal, hexadecimal, unicode or symbolic notation. +The numeric notations use the same format as with +.IR keynumber . +Unicode notation is "U+" followed by four hexadecimal digits. +The symbolic notation resembles that used by +.BR xmodmap (1). +Notable differences are the number symbols. The numeric +symbols '0', ..., '9' of +.BR xmodmap (1) +are replaced with the corresponding words 'zero', 'one', ... 'nine' to +avoid confusion with the numeric notation. +.LP +It should be noted that using numeric notation for the +.I keysyms +is highly unportable as the key action numbers may vary from one kernel +version to another and the use of numeric notations is thus strongly +discouraged. They are intended to be used only when you know there is a +supported keyboard action in your kernel for which your current version +of +.BR loadkeys (1) +has no symbolic name. +.LP +There is a number of short-hand notations to add readability and reduce +typing work and the probability of typing-errors. +.LP +First of all, you can give a map specification line, of the form +.LP +.RS +.EX +keymaps 0-2,4-5,8,12 +.EE +.RE +.LP +to indicate that the lines of the keymap will not specify all 256 columns, +but only the indicated ones. (In the example: only the plain, Shift, +AltGr, Control, Control+Shift, Alt and Control+Alt maps, that is, 7 columns +instead of 256.) +When no such line is given, the keymaps 0-M will be defined, where +M+1 is the maximum number of entries found in any definition line. +.LP +Next, you can leave off any trailing VoidSymbol entries from a key +definition line. VoidSymbol denotes a keyboard action which produces no +output and has no other effects either. For example, to define key +number 30 to output 'a' unshifted, 'A' when pressed with Shift and do +nothing when pressed with AltGr or other modifiers, you can write +.LP +.RS +.nf +keycode 30 = a A +.fi +.RE +.LP +instead of the more verbose +.LP +.RS +.nf +keycode 30 = a A VoidSymbol VoidSymbol \\ + VoidSymbol VoidSymbol VoidSymbol ... +.fi +.RE +.LP +For added convenience, you can usually get off with still more terse +definitions. If you enter a key definition line with only and exactly +one action code after the equals sign, it has a special meaning. If the +code (numeric or symbolic) is not an ASCII letter, it means the code +is implicitly replicated through all columns being defined. +If, on the other hand, the action code is an ASCII character in the +range 'a', ..., 'z' or 'A', ..., 'Z' in the ASCII collating sequence, +the following definitions are made for the different modifier combinations, +provided these are actually being defined. +(The table lists the two possible cases: +either the single action code is a lower case letter, +denoted by 'x' or an upper case letter, denoted by 'Y'.) +.LP +.RS 4 +.TP 24 +.I modifier +.I symbol +.TP 24 +none +x Y +.PD 0 +.TP 24 +Shift +X y +.TP 24 +AltGr +x Y +.TP 24 +Shift+AltGr +X y +.TP 24 +Control +Control_x Control_y +.TP 24 +Shift+Control +Control_x Control_y +.TP 24 +AltGr+Control +Control_x Control_y +.TP 24 +Shift+AltGr+Control +Control_x Control_y +.TP 24 +Alt +Meta_x Meta_Y +.TP 24 +Shift+Alt +Meta_X Meta_y +.TP 24 +AltGr+Alt +Meta_x Meta_Y +.TP 24 +Shift+AltGr+Alt +Meta_X Meta_y +.TP 24 +Control+Alt +Meta_Control_x Meta_Control_y +.TP 24 +Shift+Control+Alt +Meta_Control_x Meta_Control_y +.TP 24 +AltGr+Control+Alt +Meta_Control_x Meta_Control_y +.TP 24 +Shift+AltGr+Control+Alt +Meta_Control_x Meta_Control_y +.PD +.RE +.LP +.SH "SINGLE MODIFIER DEFINITIONS" +All the previous forms of key definition lines always define all the M+1 +possible modifier combinations being defined, whether the line actually +contains that many action codes or not. +There is, however, a variation of the definition +syntax for defining only single actions to a particular modifier +combination of a key. This is especially useful, if you load a keymap +which doesn't match your needs in only some modifier combinations, like +AltGr+function keys. You can then make a small local file redefining +only those modifier combinations and loading it after the main file. +The syntax of this form is: +.LP +.BR "" { " plain " "| } " keycode +.I keynumber +.B = +.I keysym +.LP +, e.g., +.RS +.EX +.nf +plain keycode 14 = BackSpace +control alt keycode 83 = Boot +alt keycode 105 = Decr_Console +alt keycode 106 = Incr_Console +.fi +.EE +.RE +Using "plain" will define only the base entry of a +key (i.e. the one with no modifiers in effect) without affecting the +bindings of other modifier combinations of that key. +.SH "STRING DEFINITIONS" +In addition to comments and key definition lines, a keymap can +contain string definitions. These are used to define what each function +key action code sends. The syntax of string definitions is: +.LP +.RS +.B string +.I keysym +.B = +.BI """" text """" +.RE +.LP +.I text +can contain literal characters, octal character codes in the format of +backslash followed by up to three octal digits, and the three escape +sequences \fB\\n\fP, \fB\\\\\fP, and \fB\\"\fP, +for newline, backslash and quote, respectively. +.SH "COMPOSE DEFINITIONS" +Then there may also be compose definitions. They have syntax +.LP +.RS +.BI "compose '" char "' '" char "' to '" char "'" +.RE +and describe how two bytes are combined to form a third one +(when a dead accent or compose key is used). +This is used to get accented letters and the like on a standard +keyboard. +.SH ABBREVIATIONS +Various abbreviations can be used with kbd-0.96 and later. +.TP +.B "strings as usual" +Defines the usual values of the strings (but not the keys +they are bound to). +.TP +\fBcompose as usual for "iso-8859-1"\fP +Defines the usual compose combinations. +.LP +To find out what +.I keysyms +there are available for use in keymaps, use the command +.LP +.RS +.nf +.B dumpkeys --long-info +.fi +.RE +.LP +Unfortunately, there is currently no description of what each symbol +does. It has to be guessed from the name or figured out from the kernel +sources. +.LP +.SH EXAMPLES +(Be careful to use a keymaps line, like the first line of `dumpkeys`, +or "keymaps 0-15" or so.) +.LP +The following entry exchanges the left Control key and the Caps Lock +key on the keyboard: +.LP +.RS +.nf +keycode 58 = Control +keycode 29 = Caps_Lock +.fi +.RE +.LP +Key number 58 is normally the Caps Lock key, and key number 29 is +normally the Control key. +.LP +The following entry sets the Shift and Caps Lock keys to behave more +nicely, like in older typewriters. That is, pressing Caps Lock key once +or more sets the keyboard in CapsLock state and pressing either of the +Shift keys releases it. +.LP +.RS +.nf +keycode 42 = Uncaps_Shift +keycode 54 = Uncaps_Shift +keycode 58 = Caps_On +.fi +.RE +.LP +The following entry sets the layout of the edit pad in the enhanced +keyboard to be more like that in the VT200 series terminals: +.LP +.RS +.nf +keycode 102 = Insert +keycode 104 = Remove +keycode 107 = Prior +shift keycode 107 = Scroll_Backward +keycode 110 = Find +keycode 111 = Select +control alt keycode 111 = Boot +control altgr keycode 111 = Boot +.fi +.RE +.LP +Here's an example to bind the string "du\\ndf\\n" to the key AltGr-D. We use +the "spare" action code F100 not normally bound to any key. +.LP +.RS +.nf +altgr keycode 32 = F100 +string F100 = "du\\ndf\\n" +.RE +.LP +.SH "SEE ALSO" +.BR loadkeys (1), +.BR dumpkeys (1), +.BR showkey (1), +.BR xmodmap (1) diff --git a/upstream/fedora-40/man5/lmhosts.5 b/upstream/fedora-40/man5/lmhosts.5 new file mode 100644 index 00000000..ccd4d9c3 --- /dev/null +++ b/upstream/fedora-40/man5/lmhosts.5 @@ -0,0 +1,123 @@ +'\" t +.\" Title: lmhosts +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 02/26/2024 +.\" Manual: File Formats and Conventions +.\" Source: Samba 4.20.0rc3 +.\" Language: English +.\" +.TH "LMHOSTS" "5" "02/26/2024" "Samba 4\&.20\&.0rc3" "File Formats and Conventions" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +lmhosts \- The Samba NetBIOS hosts file +.SH "SYNOPSIS" +.PP +lmhosts +is the +\fBsamba\fR(7) +NetBIOS name to IP address mapping file\&. +.SH "DESCRIPTION" +.PP +This file is part of the +\fBsamba\fR(7) +suite\&. +.PP +lmhosts +is the +\fISamba \fR +NetBIOS name to IP address mapping file\&. It is very similar to the +/etc/hosts +file format, except that the hostname component must correspond to the NetBIOS naming format\&. +.SH "FILE FORMAT" +.PP +It is an ASCII file containing one line for NetBIOS name\&. The two fields on each line are separated from each other by white space\&. Any entry beginning with \*(Aq#\*(Aq is ignored\&. Each line in the lmhosts file contains the following information: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +IP Address \- in dotted decimal format\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +NetBIOS Name \- This name format is a maximum fifteen character host name, with an optional trailing \*(Aq#\*(Aq character followed by the NetBIOS name type as two hexadecimal digits\&. +.sp +If the trailing \*(Aq#\*(Aq is omitted then the given IP address will be returned for all names that match the given name, whatever the NetBIOS name type in the lookup\&. +.RE +.sp +.RE +.PP +An example follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# +# Sample Samba lmhosts file\&. +# +192\&.9\&.200\&.1 TESTPC +192\&.9\&.200\&.20 NTSERVER#20 +192\&.9\&.200\&.21 SAMBASERVER +.fi +.if n \{\ +.RE +.\} +.PP +Contains three IP to NetBIOS name mappings\&. The first and third will be returned for any queries for the names "TESTPC" and "SAMBASERVER" respectively, whatever the type component of the NetBIOS name requested\&. +.PP +The second mapping will be returned only when the "0x20" name type for a name "NTSERVER" is queried\&. Any other name type will not be resolved\&. +.PP +The default location of the +lmhosts +file is in the same directory as the +\fBsmb.conf\fR(5) +file\&. +.SH "FILES" +.PP +lmhosts is loaded from the configuration directory\&. This is usually +/etc/samba +or +/usr/local/samba/lib\&. +.SH "VERSION" +.PP +This man page is part of version 4\&.20\&.0rc3 of the Samba suite\&. +.SH "SEE ALSO" +.PP +\fBsmbclient\fR(1), +\fBsmb.conf\fR(5), and +\fBsmbpasswd\fR(8) +.SH "AUTHOR" +.PP +The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&. diff --git a/upstream/fedora-40/man5/locale.5 b/upstream/fedora-40/man5/locale.5 new file mode 100644 index 00000000..4c6f9a64 --- /dev/null +++ b/upstream/fedora-40/man5/locale.5 @@ -0,0 +1,1316 @@ +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" Copyright (C) 2008 Petr Baudis (pasky@suse.cz) +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-06-17 Petr Baudis +.\" LC_TIME: Describe first_weekday and first_workday +.\" +.TH locale 5 2024-01-28 "Linux man-pages 6.06" +.SH NAME +locale \- describes a locale definition file +.SH DESCRIPTION +The +.B locale +definition file contains all the information that the +.BR localedef (1) +command needs to convert it into the binary locale database. +.P +The definition files consist of sections which each describe a +locale category in detail. +See +.BR locale (7) +for additional details for these categories. +.SS Syntax +The locale definition file starts with a header that may consist +of the following keywords: +.TP +.I escape_char +is followed by a character that should be used as the +escape-character for the rest of the file to mark characters that +should be interpreted in a special way. +It defaults to the backslash (\e). +.TP +.I comment_char +is followed by a character that will be used as the +comment-character for the rest of the file. +It defaults to the number sign (#). +.P +The locale definition has one part for each locale category. +Each part can be copied from another existing locale or +can be defined from scratch. +If the category should be copied, +the only valid keyword in the definition is +.I copy +followed by the name of the locale in double quotes which should be +copied. +The exceptions for this rule are +.B LC_COLLATE +and +.B LC_CTYPE +where a +.I copy +statement can be followed by locale-specific rules and selected overrides. +.P +When defining a locale or a category from scratch, an existing system- +provided locale definition file should be used as a reference to follow +common glibc conventions. +.SS Locale category sections +The following category sections are defined by POSIX: +.IP \[bu] 3 +.B LC_CTYPE +.IP \[bu] +.B LC_COLLATE +.IP \[bu] +.B LC_MESSAGES +.IP \[bu] +.B LC_MONETARY +.IP \[bu] +.B LC_NUMERIC +.IP \[bu] +.B LC_TIME +.P +In addition, since glibc 2.2, +the GNU C library supports the following nonstandard categories: +.IP \[bu] 3 +.B LC_ADDRESS +.IP \[bu] +.B LC_IDENTIFICATION +.IP \[bu] +.B LC_MEASUREMENT +.IP \[bu] +.B LC_NAME +.IP \[bu] +.B LC_PAPER +.IP \[bu] +.B LC_TELEPHONE +.P +See +.BR locale (7) +for a more detailed description of each category. +.SS LC_ADDRESS +The definition starts with the string +.I LC_ADDRESS +in the first column. +.P +The following keywords are allowed: +.TP +.I postal_fmt +followed by a string containing field descriptors that define +the format used for postal addresses in the locale. +The following field descriptors are recognized: +.RS +.TP +%n +Person's name, possibly constructed with the +.B LC_NAME +.I name_fmt +keyword (since glibc 2.24). +.TP 4 +%a +Care of person, or organization. +.TP +%f +Firm name. +.TP +%d +Department name. +.TP +%b +Building name. +.TP +%s +Street or block (e.g., Japanese) name. +.TP +%h +House number or designation. +.TP +%N +Insert an end-of-line if the previous descriptor's value was not an empty +string; otherwise ignore. +.TP +%t +Insert a space if the previous descriptor's value was not an empty string; +otherwise ignore. +.TP +%r +Room number, door designation. +.TP +%e +Floor number. +.TP +%C +Country designation, from the +.I country_post +keyword. +.TP +%l +Local township within town or city (since glibc 2.24). +.TP +%z +Zip number, postal code. +.TP +%T +Town, city. +.TP +%S +State, province, or prefecture. +.TP +%c +Country, as taken from data record. +.P +Each field descriptor may have an \[aq]R\[aq] after +the \[aq]%\[aq] to specify that the +information is taken from a Romanized version string of the +entity. +.RE +.TP +.I country_name +followed by the country name in the language of the current document +(e.g., "Deutschland" for the +.B de_DE +locale). +.TP +.I country_post +followed by the abbreviation of the country (see CERT_MAILCODES). +.TP +.I country_ab2 +followed by the two-letter abbreviation of the country (ISO\~3166). +.TP +.I country_ab3 +followed by the three-letter abbreviation of the country (ISO\~3166). +.TP +.I country_num +followed by the numeric country code (ISO\~3166). +.TP +.I country_car +followed by the international license plate country code. +.TP +.I country_isbn +followed by the ISBN code (for books). +.TP +.I lang_name +followed by the language name in the language of the current document. +.TP +.I lang_ab +followed by the two-letter abbreviation of the language (ISO\~639). +.TP +.I lang_term +followed by the three-letter abbreviation of the language (ISO\~639-2/T). +.TP +.I lang_lib +followed by the three-letter abbreviation of the language for library +use (ISO\~639-2/B). +Applications should in general prefer +.I lang_term +over +.IR lang_lib . +.P +The +.B LC_ADDRESS +definition ends with the string +.IR "END LC_ADDRESS" . +.SS LC_CTYPE +The definition starts with the string +.I LC_CTYPE +in the first column. +.P +The following keywords are allowed: +.TP +.I upper +followed by a list of uppercase letters. +The letters +.B A +through +.B Z +are included automatically. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I lower +followed by a list of lowercase letters. +The letters +.B a +through +.B z +are included automatically. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I alpha +followed by a list of letters. +All character specified as either +.B upper +or +.B lower +are automatically included. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I digit +followed by the characters classified as numeric digits. +Only the +digits +.B 0 +through +.B 9 +are allowed. +They are included by default in this class. +.TP +.I space +followed by a list of characters defined as white-space +characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR graph , +or +.B xdigit +are not allowed. +The characters +.BR , +.BR , +.BR , +.BR , +.BR , +and +.B +are automatically included. +.TP +.I cntrl +followed by a list of control characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR punct , +.BR graph , +.BR print , +or +.B xdigit +are not allowed. +.TP +.I punct +followed by a list of punctuation characters. +Characters also +specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR cntrl , +.BR xdigit , +or the +.B +character are not allowed. +.TP +.I graph +followed by a list of printable characters, not including the +.B +character. +The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +and +.B punct +are automatically included. +Characters also specified as +.B cntrl +are not allowed. +.TP +.I print +followed by a list of printable characters, including the +.B +character. +The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +.BR punct , +and the +.B +character are automatically included. +Characters also specified as +.B cntrl +are not allowed. +.TP +.I xdigit +followed by a list of characters classified as hexadecimal +digits. +The decimal digits must be included followed by one or +more set of six characters in ascending order. +The following +characters are included by default: +.B 0 +through +.BR 9 , +.B a +through +.BR f , +.B A +through +.BR F . +.TP +.I blank +followed by a list of characters classified as +.BR blank . +The characters +.B +and +.B +are automatically included. +.TP +.I charclass +followed by a list of locale-specific character class names +which are then to be defined in the locale. +.TP +.I toupper +followed by a list of mappings from lowercase to uppercase +letters. +Each mapping is a pair of a lowercase and an uppercase letter +separated with a +.B , +and enclosed in parentheses. +.TP +.I tolower +followed by a list of mappings from uppercase to lowercase +letters. +If the keyword tolower is not present, the reverse of the +toupper list is used. +.TP +.I map totitle +followed by a list of mapping pairs of +characters and letters +to be used in titles (headings). +.TP +.I class +followed by a locale-specific character class definition, +starting with the class name followed by the characters +belonging to the class. +.TP +.I charconv +followed by a list of locale-specific character mapping names +which are then to be defined in the locale. +.TP +.I outdigit +followed by a list of alternate output digits for the locale. +.TP +.I map to_inpunct +followed by a list of mapping pairs of +alternate digits and separators +for input digits for the locale. +.TP +.I map to_outpunct +followed by a list of mapping pairs of +alternate separators +for output for the locale. +.TP +.I translit_start +marks the start of the transliteration rules section. +The section can contain the +.I include +keyword in the beginning followed by +locale-specific rules and overrides. +Any rule specified in the locale file +will override any rule +copied or included from other files. +In case of duplicate rule definitions in the locale file, +only the first rule is used. +.IP +A transliteration rule consist of a character to be transliterated +followed by a list of transliteration targets separated by semicolons. +The first target which can be presented in the target character set +is used, if none of them can be used the +.I default_missing +character will be used instead. +.TP +.I include +in the transliteration rules section includes +a transliteration rule file +(and optionally a repertoire map file). +.TP +.I default_missing +in the transliteration rules section +defines the default character to be used for +transliteration where none of the targets cannot be presented +in the target character set. +.TP +.I translit_end +marks the end of the transliteration rules. +.P +The +.B LC_CTYPE +definition ends with the string +.IR "END LC_CTYPE" . +.SS LC_COLLATE +Note that glibc does not support all POSIX-defined options, +only the options described below are supported (as of glibc 2.23). +.P +The definition starts with the string +.I LC_COLLATE +in the first column. +.P +The following keywords are allowed: +.TP +.I coll_weight_max +followed by the number representing used collation levels. +This keyword is recognized but ignored by glibc. +.TP +.I collating\-element +followed by the definition of a collating-element symbol +representing a multicharacter collating element. +.TP +.I collating\-symbol +followed by the definition of a collating symbol +that can be used in collation order statements. +.TP +.I define +followed by +.B string +to be evaluated in an +.I ifdef +.B string +/ +.I else +/ +.I endif +construct. +.TP +.I reorder\-after +followed by a redefinition of a collation rule. +.TP +.I reorder\-end +marks the end of the redefinition of a collation rule. +.TP +.I reorder\-sections\-after +followed by a script name to reorder listed scripts after. +.TP +.I reorder\-sections\-end +marks the end of the reordering of sections. +.TP +.I script +followed by a declaration of a script. +.TP +.I symbol\-equivalence +followed by a collating-symbol to be equivalent to another defined +collating-symbol. +.P +The collation rule definition starts with a line: +.TP +.I order_start +followed by a list of keywords chosen from +.BR forward , +.BR backward , +or +.BR position . +The order definition consists of lines that describe the collation +order and is terminated with the keyword +.IR order_end . +.P +The +.B LC_COLLATE +definition ends with the string +.IR "END LC_COLLATE" . +.SS LC_IDENTIFICATION +The definition starts with the string +.I LC_IDENTIFICATION +in the first column. +.P +The following keywords are allowed: +.TP +.I title +followed by the title of the locale document +(e.g., "Maori language locale for New Zealand"). +.TP +.I source +followed by the name of the organization that maintains this document. +.TP +.I address +followed by the address of the organization that maintains this document. +.TP +.I contact +followed by the name of the contact person at +the organization that maintains this document. +.TP +.I email +followed by the email address of the person or +organization that maintains this document. +.TP +.I tel +followed by the telephone number (in international format) +of the organization that maintains this document. +As of glibc 2.24, this keyword is deprecated in favor of +other contact methods. +.TP +.I fax +followed by the fax number (in international format) +of the organization that maintains this document. +As of glibc 2.24, this keyword is deprecated in favor of +other contact methods. +.TP +.I language +followed by the name of the language to which this document applies. +.TP +.I territory +followed by the name of the country/geographic extent +to which this document applies. +.TP +.I audience +followed by a description of the audience for which this document is +intended. +.TP +.I application +followed by a description of any special application +for which this document is intended. +.TP +.I abbreviation +followed by the short name for provider of the source of this document. +.TP +.I revision +followed by the revision number of this document. +.TP +.I date +followed by the revision date of this document. +.P +In addition, for each of the categories defined by the document, +there should be a line starting with the keyword +.IR category , +followed by: +.IP (1) 5 +a string that identifies this locale category definition, +.IP (2) +a semicolon, and +.IP (3) +one of the +.B LC_* +identifiers. +.P +The +.B LC_IDENTIFICATION +definition ends with the string +.IR "END LC_IDENTIFICATION" . +.SS LC_MESSAGES +The definition starts with the string +.I LC_MESSAGES +in the first column. +.P +The following keywords are allowed: +.TP +.I yesexpr +followed by a regular expression that describes possible +yes-responses. +.TP +.I noexpr +followed by a regular expression that describes possible +no-responses. +.TP +.I yesstr +followed by the output string corresponding to "yes". +.TP +.I nostr +followed by the output string corresponding to "no". +.P +The +.B LC_MESSAGES +definition ends with the string +.IR "END LC_MESSAGES" . +.SS LC_MEASUREMENT +The definition starts with the string +.I LC_MEASUREMENT +in the first column. +.P +The following keywords are allowed: +.TP +.I measurement +followed by number identifying the standard used for measurement. +The following values are recognized: +.RS +.TP 4 +.B 1 +Metric. +.TP +.B 2 +US customary measurements. +.RE +.P +The +.B LC_MEASUREMENT +definition ends with the string +.IR "END LC_MEASUREMENT" . +.SS LC_MONETARY +The definition starts with the string +.I LC_MONETARY +in the first column. +.P +The following keywords are allowed: +.TP +.I int_curr_symbol +followed by the international currency symbol. +This must be a +4-character string containing the international currency symbol as +defined by the ISO\~4217 standard (three characters) followed by a +separator. +.TP +.I currency_symbol +followed by the local currency symbol. +.TP +.I mon_decimal_point +followed by the single-character string that will be used as the +decimal delimiter when formatting monetary quantities. +.TP +.I mon_thousands_sep +followed by the single-character string that will be used as a group +separator when formatting monetary quantities. +.TP +.I mon_grouping +followed by a sequence of integers separated by semicolons that +describe the formatting of monetary quantities. +See +.I grouping +below for details. +.TP +.I positive_sign +followed by a string that is used to indicate a positive sign for +monetary quantities. +.TP +.I negative_sign +followed by a string that is used to indicate a negative sign for +monetary quantities. +.TP +.I int_frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.IR int_curr_symbol . +.TP +.I frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.IR currency_symbol . +.TP +.I p_cs_precedes +followed by an integer that indicates the placement of +.I currency_symbol +for a nonnegative formatted monetary quantity: +.RS +.TP 4 +.B 0 +the symbol succeeds the value. +.TP +.B 1 +the symbol precedes the value. +.RE +.TP +.I p_sep_by_space +followed by an integer that indicates the separation of +.IR currency_symbol , +the sign string, and the value for a nonnegative formatted monetary quantity. +The following values are recognized: +.RS +.TP 4 +.B 0 +No space separates the currency symbol and the value. +.TP +.B 1 +If the currency symbol and the sign string are adjacent, +a space separates them from the value; +otherwise a space separates the currency symbol and the value. +.TP +.B 2 +If the currency symbol and the sign string are adjacent, +a space separates them from the value; +otherwise a space separates the sign string and the value. +.RE +.TP +.I n_cs_precedes +followed by an integer that indicates the placement of +.I currency_symbol +for a negative formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I n_sep_by_space +followed by an integer that indicates the separation of +.IR currency_symbol , +the sign string, and the value for a negative formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I p_sign_posn +followed by an integer that indicates where the +.I positive_sign +should be placed for a nonnegative monetary quantity: +.RS +.TP 4 +.B 0 +Parentheses enclose the quantity and the +.I currency_symbol +or +.IR int_curr_symbol . +.TP +.B 1 +The sign string precedes the quantity and the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 2 +The sign string succeeds the quantity and the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 3 +The sign string precedes the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 4 +The sign string succeeds the +.I currency_symbol +or the +.IR int_curr_symbol . +.RE +.TP +.I n_sign_posn +followed by an integer that indicates where the +.I negative_sign +should be placed for a negative monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.TP +.I int_p_cs_precedes +followed by an integer that indicates the placement of +.I int_curr_symbol +for a nonnegative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I int_n_cs_precedes +followed by an integer that indicates the placement of +.I int_curr_symbol +for a negative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I int_p_sep_by_space +followed by an integer that indicates the separation of +.IR int_curr_symbol , +the sign string, +and the value for a nonnegative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I int_n_sep_by_space +followed by an integer that indicates the separation of +.IR int_curr_symbol , +the sign string, +and the value for a negative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I int_p_sign_posn +followed by an integer that indicates where the +.I positive_sign +should be placed for a nonnegative +internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.TP +.I int_n_sign_posn +followed by an integer that indicates where the +.I negative_sign +should be placed for a negative +internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.P +The +.B LC_MONETARY +definition ends with the string +.IR "END LC_MONETARY" . +.SS LC_NAME +The definition starts with the string +.I LC_NAME +in the first column. +.P +Various keywords are allowed, but only +.I name_fmt +is mandatory. +Other keywords are needed only if there is common convention to +use the corresponding salutation in this locale. +The allowed keywords are as follows: +.TP +.I name_fmt +followed by a string containing field descriptors that define +the format used for names in the locale. +The following field descriptors are recognized: +.RS +.TP 4 +%f +Family name(s). +.TP +%F +Family names in uppercase. +.TP +%g +First given name. +.TP +%G +First given initial. +.TP +%l +First given name with Latin letters. +.TP +%o +Other shorter name. +.TP +%m +Additional given name(s). +.TP +%M +Initials for additional given name(s). +.TP +%p +Profession. +.TP +%s +Salutation, such as "Doctor". +.TP +%S +Abbreviated salutation, such as "Mr." or "Dr.". +.TP +%d +Salutation, using the FDCC-sets conventions. +.\" 1 for the name_gen +.\" In glibc 2.19, %d1 is used in only: +.\" /home/mtk/ARCHIVE/GLIBC/glibc-2.19/localedata/locales/bem_ZM +.\" /home/mtk/ARCHIVE/GLIBC/glibc-2.19/localedata/locales/zh_HK +.\" In glibc 2.19, %d[2-5] appear to be not used at all +.\" 2 for name_mr +.\" 3 for name_mrs +.\" 4 for name_miss +.\" 5 for name_ms +.TP +%t +If the preceding field descriptor resulted in an empty string, +then the empty string, otherwise a space character. +.RE +.TP +.I name_gen +followed by the general salutation for any gender. +.TP +.I name_mr +followed by the salutation for men. +.TP +.I name_mrs +followed by the salutation for married women. +.TP +.I name_miss +followed by the salutation for unmarried women. +.TP +.I name_ms +followed by the salutation valid for all women. +.P +The +.B LC_NAME +definition ends with the string +.IR "END LC_NAME" . +.SS LC_NUMERIC +The definition starts with the string +.I LC_NUMERIC +in the first column. +.P +The following keywords are allowed: +.TP +.I decimal_point +followed by the single-character string that will be used as the +decimal delimiter when formatting numeric quantities. +.TP +.I thousands_sep +followed by the single-character string that will be used as a group +separator when formatting numeric quantities. +.TP +.I grouping +followed by a sequence of integers separated by semicolons +that describe the formatting of numeric quantities. +.IP +Each integer specifies the number of digits in a group. +The first integer defines the size of the group immediately +to the left of the decimal delimiter. +Subsequent integers define succeeding groups to the +left of the previous group. +If the last integer is not \-1, then the size of the previous group +(if any) is repeatedly used for the remainder of the digits. +If the last integer is \-1, then no further grouping is performed. +.P +The +.B LC_NUMERIC +definition ends with the string +.IR "END LC_NUMERIC" . +.SS LC_PAPER +The definition starts with the string +.I LC_PAPER +in the first column. +.P +The following keywords are allowed: +.TP +.I height +followed by the height, in millimeters, of the standard paper format. +.TP +.I width +followed by the width, in millimeters, of the standard paper format. +.P +The +.B LC_PAPER +definition ends with the string +.IR "END LC_PAPER" . +.SS LC_TELEPHONE +The definition starts with the string +.I LC_TELEPHONE +in the first column. +.P +The following keywords are allowed: +.TP +.I tel_int_fmt +followed by a string that contains field descriptors that identify +the format used to dial international numbers. +The following field descriptors are recognized: +.RS +.TP 4 +%a +Area code without nationwide prefix (the prefix is often "00"). +.TP +%A +Area code including nationwide prefix. +.TP +%l +Local number (within area code). +.TP +%e +Extension (to local number). +.TP +%c +Country code. +.TP +%C +Alternate carrier service code used for dialing abroad. +.TP +%t +If the preceding field descriptor resulted in an empty string, +then the empty string, otherwise a space character. +.RE +.TP +.I tel_dom_fmt +followed by a string that contains field descriptors that identify +the format used to dial domestic numbers. +The recognized field descriptors are the same as for +.IR tel_int_fmt . +.TP +.I int_select +followed by the prefix used to call international phone numbers. +.TP +.I int_prefix +followed by the prefix used from other countries to dial this country. +.P +The +.B LC_TELEPHONE +definition ends with the string +.IR "END LC_TELEPHONE" . +.SS LC_TIME +The definition starts with the string +.I LC_TIME +in the first column. +.P +The following keywords are allowed: +.TP +.I abday +followed by a list of abbreviated names of the days of the week. +The list starts with the first day of the week +as specified by +.I week +(Sunday by default). +See NOTES. +.TP +.I day +followed by a list of names of the days of the week. +The list starts with the first day of the week +as specified by +.I week +(Sunday by default). +See NOTES. +.TP +.I abmon +followed by a list of abbreviated month names. +.TP +.I mon +followed by a list of month names. +.TP +.I d_t_fmt +followed by the appropriate date and time format +(for syntax, see +.BR strftime (3)). +.TP +.I d_fmt +followed by the appropriate date format +(for syntax, see +.BR strftime (3)). +.TP +.I t_fmt +followed by the appropriate time format +(for syntax, see +.BR strftime (3)). +.TP +.I am_pm +followed by the appropriate representation of the +.B am +and +.B pm +strings. +This should be left empty for locales not using AM/PM convention. +.TP +.I t_fmt_ampm +followed by the appropriate time format +(for syntax, see +.BR strftime (3)) +when using 12h clock format. +This should be left empty for locales not using AM/PM convention. +.TP +.I era +followed by semicolon-separated strings that define how years are +counted and displayed for each era in the locale. +Each string has the following format: +.RS +.P +.IR direction ":" offset ":" start_date ":" end_date ":" era_name ":" era_format +.P +The fields are to be defined as follows: +.TP 4 +.I direction +Either +.B + +or +.BR \- . +.B + +means the years closer to +.I start_date +have lower numbers than years closer to +.IR end_date . +.B \- +means the opposite. +.TP +.I offset +The number of the year closest to +.I start_date +in the era, corresponding to the +.I %Ey +descriptor (see +.BR strptime (3)). +.TP +.I start_date +The start of the era in the form of +.IR yyyy/mm/dd . +Years prior AD 1 are represented as negative numbers. +.TP +.I end_date +The end of the era in the form of +.IR yyyy/mm/dd , +or one of the two special values of +.B \-* +or +.BR +* . +.B \-* +means the ending date is the beginning of time. +.B +* +means the ending date is the end of time. +.TP +.I era_name +The name of the era corresponding to the +.I %EC +descriptor (see +.BR strptime (3)). +.TP +.I era_format +The format of the year in the era corresponding to the +.I %EY +descriptor (see +.BR strptime (3)). +.RE +.TP +.I era_d_fmt +followed by the format of the date in alternative era notation, +corresponding to the +.I %Ex +descriptor (see +.BR strptime (3)). +.TP +.I era_t_fmt +followed by the format of the time in alternative era notation, +corresponding to the +.I %EX +descriptor (see +.BR strptime (3)). +.TP +.I era_d_t_fmt +followed by the format of the date and time in alternative era notation, +corresponding to the +.I %Ec +descriptor (see +.BR strptime (3)). +.TP +.I alt_digits +followed by the alternative digits used for date and time in the locale. +.TP +.I week +followed by a list of three values separated by semicolons: +The number of days in a week (by default 7), +a date of beginning of the week (by default corresponds to Sunday), +and the minimal length of the first week in year (by default 4). +Regarding the start of the week, +.B 19971130 +shall be used for Sunday and +.B 19971201 +shall be used for Monday. +See NOTES. +.TP +.IR first_weekday " (since glibc 2.2)" +followed by the number of the day from the +.I day +list to be shown as the first day of the week in calendar applications. +The default value of +.B 1 +corresponds to either Sunday or Monday depending +on the value of the second +.I week +list item. +See NOTES. +.TP +.IR first_workday " (since glibc 2.2)" +followed by the number of the first working day from the +.I day +list. +The default value is +.BR 2 . +See NOTES. +.TP +.I cal_direction +followed by a number value that indicates the direction for the +display of calendar dates, as follows: +.RS +.TP 4 +.B 1 +Left-right from top. +.TP +.B 2 +Top-down from left. +.TP +.B 3 +Right-left from top. +.RE +.TP +.I date_fmt +followed by the appropriate date representation for +.BR date (1) +(for syntax, see +.BR strftime (3)). +.P +The +.B LC_TIME +definition ends with the string +.IR "END LC_TIME" . +.SH FILES +.TP +.I /usr/lib/locale/locale\-archive +Usual default locale archive location. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.SH STANDARDS +POSIX.2. +.SH NOTES +The collective GNU C library community wisdom regarding +.IR abday , +.IR day , +.IR week , +.IR first_weekday , +and +.I first_workday +states at +https://sourceware.org/glibc/wiki/Locales +the following: +.IP \[bu] 3 +The value of the second +.I week +list item specifies the base of the +.I abday +and +.I day +lists. +.IP \[bu] +.I first_weekday +specifies the offset of the first day-of-week in the +.I abday +and +.I day +lists. +.IP \[bu] +For compatibility reasons, all glibc locales should set the value of the +second +.I week +list item to +.B 19971130 +(Sunday) and base the +.I abday +and +.I day +lists appropriately, and set +.I first_weekday +and +.I first_workday +to +.B 1 +or +.BR 2 , +depending on whether the week and work week actually starts on Sunday or +Monday for the locale. +.\" .SH AUTHOR +.\" Jochen Hein (Hein@Student.TU-Clausthal.de) +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR localeconv (3), +.BR newlocale (3), +.BR setlocale (3), +.BR strftime (3), +.BR strptime (3), +.BR uselocale (3), +.BR charmap (5), +.BR charsets (7), +.BR locale (7), +.BR unicode (7), +.BR utf\-8 (7) diff --git a/upstream/fedora-40/man5/locale.conf.5 b/upstream/fedora-40/man5/locale.conf.5 new file mode 100644 index 00000000..531a8d8f --- /dev/null +++ b/upstream/fedora-40/man5/locale.conf.5 @@ -0,0 +1,115 @@ +'\" t +.TH "LOCALE\&.CONF" "5" "" "systemd 255" "locale.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +locale.conf \- Configuration file for locale settings +.SH "SYNOPSIS" +.PP +/etc/locale\&.conf +.SH "DESCRIPTION" +.PP +The +/etc/locale\&.conf +file configures system\-wide locale settings\&. It is read at early boot by +\fBsystemd\fR(1)\&. +.PP +The format of +locale\&.conf +is a newline\-separated list of environment\-like shell\-compatible variable assignments, ignoring comments and empty lines\&. It is possible to source the configuration from shell scripts, however, beyond mere variable assignments, no shell features are supported, allowing applications to read the file without implementing a shell compatible execution engine\&. See +\fBos-release\fR(5) +for a detailed description of the format\&. +.PP +Note that the kernel command line options +\fIlocale\&.LANG=\fR, +\fIlocale\&.LANGUAGE=\fR, +\fIlocale\&.LC_CTYPE=\fR, +\fIlocale\&.LC_NUMERIC=\fR, +\fIlocale\&.LC_TIME=\fR, +\fIlocale\&.LC_COLLATE=\fR, +\fIlocale\&.LC_MONETARY=\fR, +\fIlocale\&.LC_MESSAGES=\fR, +\fIlocale\&.LC_PAPER=\fR, +\fIlocale\&.LC_NAME=\fR, +\fIlocale\&.LC_ADDRESS=\fR, +\fIlocale\&.LC_TELEPHONE=\fR, +\fIlocale\&.LC_MEASUREMENT=\fR, +\fIlocale\&.LC_IDENTIFICATION=\fR +may be used to override the locale settings at boot\&. +.PP +The locale settings configured in +/etc/locale\&.conf +are system\-wide and are inherited by every service or user, unless overridden or unset by individual programs or users\&. +.PP +Depending on the operating system, other configuration files might be checked for locale configuration as well, however only as fallback\&. +.PP +/etc/locale\&.conf +can be updated using +\fBsystemd-localed.service\fR(8)\&. +\fBlocalectl\fR(1) +may be used to alter the settings in this file during runtime from the command line\&. Use +\fBsystemd-firstboot\fR(1) +to customize them on mounted (but not booted) system images\&. +.SH "OPTIONS" +.PP +The following locale settings may be set using +/etc/locale\&.conf: +\fILANG=\fR, +\fILANGUAGE=\fR, +\fILC_CTYPE=\fR, +\fILC_NUMERIC=\fR, +\fILC_TIME=\fR, +\fILC_COLLATE=\fR, +\fILC_MONETARY=\fR, +\fILC_MESSAGES=\fR, +\fILC_PAPER=\fR, +\fILC_NAME=\fR, +\fILC_ADDRESS=\fR, +\fILC_TELEPHONE=\fR, +\fILC_MEASUREMENT=\fR, +\fILC_IDENTIFICATION=\fR\&. Note that +\fILC_ALL\fR +may not be configured in this file\&. For details about the meaning and semantics of these settings, refer to +\fBlocale\fR(7)\&. +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&German locale with English messages\fR +.PP +/etc/locale\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Custom settings + +LANG=de_DE\&.UTF\-8 +LC_MESSAGES=en_US\&.UTF\-8 +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBlocale\fR(7), +\fBlocalectl\fR(1), +\fBsystemd-localed.service\fR(8), +\fBsystemd-firstboot\fR(1) diff --git a/upstream/fedora-40/man5/localtime.5 b/upstream/fedora-40/man5/localtime.5 new file mode 100644 index 00000000..091dfcc0 --- /dev/null +++ b/upstream/fedora-40/man5/localtime.5 @@ -0,0 +1,67 @@ +'\" t +.TH "LOCALTIME" "5" "" "systemd 255" "localtime" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +localtime \- Local timezone configuration file +.SH "SYNOPSIS" +.PP +/etc/localtime +\-> +\&.\&./usr/share/zoneinfo/\&... +.SH "DESCRIPTION" +.PP +The +/etc/localtime +file configures the system\-wide timezone of the local system that is used by applications for presentation to the user\&. It should be an absolute or relative symbolic link pointing to +/usr/share/zoneinfo/, followed by a timezone identifier such as +"Europe/Berlin" +or +"Etc/UTC"\&. The resulting link should lead to the corresponding binary +\fBtzfile\fR(5) +timezone data for the configured timezone\&. +.PP +Because the timezone identifier is extracted from the symlink target name of +/etc/localtime, this file may not be a normal file or hardlink\&. +.PP +If +/etc/localtime +is missing, the default +"UTC" +timezone is used\&. +.PP +The timezone may be overridden for individual programs by using the +\fI$TZ\fR +environment variable\&. See +\fBenviron\fR(7)\&. +.PP +You may use +\fBtimedatectl\fR(1) +to change the settings of this file from the command line during runtime\&. Use +\fBsystemd-firstboot\fR(1) +to initialize the time zone on mounted (but not booted) system images\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBtzset\fR(3), +\fBlocaltime\fR(3), +\fBtimedatectl\fR(1), +\fBsystemd-timedated.service\fR(8), +\fBsystemd-firstboot\fR(1) diff --git a/upstream/fedora-40/man5/logind.conf.5 b/upstream/fedora-40/man5/logind.conf.5 new file mode 100644 index 00000000..5089cb9c --- /dev/null +++ b/upstream/fedora-40/man5/logind.conf.5 @@ -0,0 +1,370 @@ +'\" t +.TH "LOGIND\&.CONF" "5" "" "systemd 255" "logind.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +logind.conf, logind.conf.d \- Login manager configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/logind\&.conf +.PP +/etc/systemd/logind\&.conf\&.d/*\&.conf +.PP +/run/systemd/logind\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/logind\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These files configure various parameters of the systemd login manager, +\fBsystemd-logind.service\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [Login] section: +.PP +\fINAutoVTs=\fR +.RS 4 +Takes a positive integer\&. Configures how many virtual terminals (VTs) to allocate by default that, when switched to and are previously unused, +"autovt" +services are automatically spawned on\&. These services are instantiated from the template unit +autovt@\&.service +for the respective VT TTY name, for example, +autovt@tty4\&.service\&. By default, +autovt@\&.service +is linked to +getty@\&.service\&. In other words, login prompts are started dynamically as the user switches to unused virtual terminals\&. Hence, this parameter controls how many login +"gettys" +are available on the VTs\&. If a VT is already used by some other subsystem (for example, a graphical login), this kind of activation will not be attempted\&. Note that the VT configured in +\fIReserveVT=\fR +is always subject to this kind of activation, even if it is not one of the VTs configured with the +\fINAutoVTs=\fR +directive\&. Defaults to 6\&. When set to 0, automatic spawning of +"autovt" +services is disabled\&. +.RE +.PP +\fIReserveVT=\fR +.RS 4 +Takes a positive integer\&. Identifies one virtual terminal that shall unconditionally be reserved for +autovt@\&.service +activation (see above)\&. The VT selected with this option will be marked busy unconditionally, so that no other subsystem will allocate it\&. This functionality is useful to ensure that, regardless of how many VTs are allocated by other subsystems, one login +"getty" +is always available\&. Defaults to 6 (in other words, there will always be a +"getty" +available on Alt\-F6\&.)\&. When set to 0, VT reservation is disabled\&. +.sp +Added in version 190\&. +.RE +.PP +\fIKillUserProcesses=\fR +.RS 4 +Takes a boolean argument\&. Configures whether the processes of a user should be killed when the user logs out\&. If true, the scope unit corresponding to the session and all processes inside that scope will be terminated\&. If false, the scope is "abandoned", see +\fBsystemd.scope\fR(5), and processes are not killed\&. Defaults to +"no", but see the options +\fIKillOnlyUsers=\fR +and +\fIKillExcludeUsers=\fR +below\&. +.sp +In addition to session processes, user process may run under the user manager unit +user@\&.service\&. Depending on the linger settings, this may allow users to run processes independent of their login sessions\&. See the description of +\fBenable\-linger\fR +in +\fBloginctl\fR(1)\&. +.sp +Note that setting +\fIKillUserProcesses=yes\fR +will break tools like +\fBscreen\fR(1) +and +\fBtmux\fR(1), unless they are moved out of the session scope\&. See example in +\fBsystemd-run\fR(1)\&. +.RE +.PP +\fIKillOnlyUsers=\fR, \fIKillExcludeUsers=\fR +.RS 4 +These settings take space\-separated lists of usernames that override the +\fIKillUserProcesses=\fR +setting\&. A user name may be added to +\fIKillExcludeUsers=\fR +to exclude the processes in the session scopes of that user from being killed even if +\fIKillUserProcesses=yes\fR +is set\&. If +\fIKillExcludeUsers=\fR +is not set, the +"root" +user is excluded by default\&. +\fIKillExcludeUsers=\fR +may be set to an empty value to override this default\&. If a user is not excluded, +\fIKillOnlyUsers=\fR +is checked next\&. If this setting is specified, only the processes in the session scopes of those users will be killed\&. Otherwise, users are subject to the +\fIKillUserProcesses=yes\fR +setting\&. +.RE +.PP +\fIIdleAction=\fR +.RS 4 +Configures the action to take when the system is idle\&. Takes one of +"ignore", +"poweroff", +"reboot", +"halt", +"kexec", +"suspend", +"hibernate", +"hybrid\-sleep", +"suspend\-then\-hibernate", and +"lock"\&. Defaults to +"ignore"\&. +.sp +Note that this requires that user sessions correctly report the idle status to the system\&. The system will execute the action after all sessions report that they are idle, no idle inhibitor lock is active, and subsequently, the time configured with +\fIIdleActionSec=\fR +(see below) has expired\&. +.sp +Added in version 198\&. +.RE +.PP +\fIIdleActionSec=\fR +.RS 4 +Configures the delay after which the action configured in +\fIIdleAction=\fR +(see above) is taken after the system is idle\&. +.sp +Added in version 198\&. +.RE +.PP +\fIInhibitDelayMaxSec=\fR +.RS 4 +Specifies the maximum time a system shutdown or sleep request is delayed due to an inhibitor lock of type +"delay" +being active before the inhibitor is ignored and the operation executes anyway\&. Defaults to 5\&. +.RE +.PP +\fIUserStopDelaySec=\fR +.RS 4 +Specifies how long to keep the user record and per\-user service +user@\&.service +around for a user after they logged out fully\&. If set to zero, the per\-user service is terminated immediately when the last session of the user has ended\&. If this option is configured to non\-zero rapid logout/login cycles are sped up, as the user\*(Aqs service manager is not constantly restarted\&. If set to +"infinity" +the per\-user service for a user is never terminated again after first login, and continues to run until system shutdown\&. Defaults to 10s\&. +.sp +Added in version 240\&. +.RE +.PP +\fIHandlePowerKey=\fR, \fIHandlePowerKeyLongPress=\fR, \fIHandleRebootKey=\fR, \fIHandleRebootKeyLongPress=\fR, \fIHandleSuspendKey=\fR, \fIHandleSuspendKeyLongPress=\fR, \fIHandleHibernateKey=\fR, \fIHandleHibernateKeyLongPress=\fR, \fIHandleLidSwitch=\fR, \fIHandleLidSwitchExternalPower=\fR, \fIHandleLidSwitchDocked=\fR +.RS 4 +Controls how logind shall handle the system power, reboot and sleep keys and the lid switch to trigger actions such as system power\-off, reboot or suspend\&. Can be one of +"ignore", +"poweroff", +"reboot", +"halt", +"kexec", +"suspend", +"hibernate", +"hybrid\-sleep", +"suspend\-then\-hibernate", +"lock", and +"factory\-reset"\&. If +"ignore", +\fBsystemd\-logind\fR +will never handle these keys\&. If +"lock", all running sessions will be screen\-locked; otherwise, the specified action will be taken in the respective event\&. Only input devices with the +"power\-switch" +udev tag will be watched for key/lid switch events\&. +.sp +\fIHandlePowerKey=\fR +defaults to +"poweroff", +\fIHandleRebootKey=\fR +defaults to +"reboot", +\fIHandleSuspendKey=\fR +defaults to +"suspend", +\fIHandleHibernateKey=\fR +defaults to +"hibernate", +\fIHandlePowerKeyLongPress=\fR +defaults to +"ignore", +\fIHandleRebootKeyLongPress=\fR +defaults to +"poweroff", +\fIHandleSuspendKeyLongPress=\fR +defaults to +"hibernate", +\fIHandleHibernateKeyLongPress=\fR +defaults to +"ignore"\&. +\fIHandleLidSwitch=\fR +defaults to +"suspend"\&. +\fIHandleLidSwitchExternalPower=\fR +is completely ignored by default (for backwards compatibility) \(em an explicit value must be set before it will be used to determine behaviour\&. +\fIHandleLidSwitchDocked=\fR +defaults to +"ignore"\&. If the system is inserted in a docking station, or if more than one display is connected, the action specified by +\fIHandleLidSwitchDocked=\fR +occurs; if the system is on external power the action (if any) specified by +\fIHandleLidSwitchExternalPower=\fR +occurs; otherwise the +\fIHandleLidSwitch=\fR +action occurs\&. +.sp +A different application may disable logind\*(Aqs handling of system power and sleep keys and the lid switch by taking a low\-level inhibitor lock ("handle\-power\-key", +"handle\-suspend\-key", +"handle\-hibernate\-key", +"handle\-lid\-switch", +"handle\-reboot\-key")\&. This is most commonly used by graphical desktop environments to take over suspend and hibernation handling, and to use their own configuration mechanisms\&. If a low\-level inhibitor lock is taken, logind will not take any action when that key or switch is triggered and the +\fIHandle*=\fR +settings are irrelevant\&. +.sp +Added in version 184\&. +.RE +.PP +\fIPowerKeyIgnoreInhibited=\fR, \fISuspendKeyIgnoreInhibited=\fR, \fIHibernateKeyIgnoreInhibited=\fR, \fILidSwitchIgnoreInhibited=\fR, \fIRebootKeyIgnoreInhibited=\fR +.RS 4 +Controls whether actions that +\fBsystemd\-logind\fR +takes when the power, reboot and sleep keys and the lid switch are triggered are subject to high\-level inhibitor locks ("shutdown", "reboot", "sleep", "idle")\&. Low level inhibitor locks ("handle\-power\-key", +"handle\-suspend\-key", +"handle\-hibernate\-key", +"handle\-lid\-switch", +"handle\-reboot\-key"), are always honored, irrespective of this setting\&. +.sp +These settings take boolean arguments\&. If +"no", the inhibitor locks taken by applications are respected\&. If +"yes", "shutdown", "reboot" "sleep", and "idle" inhibitor locks are ignored\&. +\fIPowerKeyIgnoreInhibited=\fR, +\fISuspendKeyIgnoreInhibited=\fR, +\fIHibernateKeyIgnoreInhibited=\fR +and +\fIRebootKeyIgnoreInhibited=\fR +default to +"no"\&. +\fILidSwitchIgnoreInhibited=\fR +defaults to +"yes"\&. This means that when +\fBsystemd\-logind\fR +is handling events by itself (no low level inhibitor locks are taken by another application), the lid switch does not respect suspend blockers by default, but the power and sleep keys do\&. +.sp +Added in version 190\&. +.RE +.PP +\fIHoldoffTimeoutSec=\fR +.RS 4 +Specifies a period of time after system startup or system resume in which systemd will hold off on reacting to lid events\&. This is required for the system to properly detect any hotplugged devices so systemd can ignore lid events if external monitors, or docks, are connected\&. If set to 0, systemd will always react immediately, possibly before the kernel fully probed all hotplugged devices\&. This is safe, as long as you do not care for systemd to account for devices that have been plugged or unplugged while the system was off\&. Defaults to 30s\&. +.sp +Added in version 220\&. +.RE +.PP +\fIRuntimeDirectorySize=\fR +.RS 4 +Sets the size limit on the +\fI$XDG_RUNTIME_DIR\fR +runtime directory for each user who logs in\&. Takes a size in bytes, optionally suffixed with the usual K, G, M, and T suffixes, to the base 1024 (IEC)\&. Alternatively, a numerical percentage suffixed by +"%" +may be specified, which sets the size limit relative to the amount of physical RAM\&. Defaults to 10%\&. Note that this size is a safety limit only\&. As each runtime directory is a tmpfs file system, it will only consume as much memory as is needed\&. +.sp +Added in version 211\&. +.RE +.PP +\fIRuntimeDirectoryInodesMax=\fR +.RS 4 +Sets the limit on number of inodes for the +\fI$XDG_RUNTIME_DIR\fR +runtime directory for each user who logs in\&. Takes a number, optionally suffixed with the usual K, G, M, and T suffixes, to the base 1024 (IEC)\&. Defaults to +\fIRuntimeDirectorySize=\fR +divided by 4096\&. Note that this size is a safety limit only\&. As each runtime directory is a tmpfs file system, it will only consume as much memory as is needed\&. +.sp +Added in version 246\&. +.RE +.PP +\fIInhibitorsMax=\fR +.RS 4 +Controls the maximum number of concurrent inhibitors to permit\&. Defaults to 8192 (8K)\&. +.sp +Added in version 230\&. +.RE +.PP +\fISessionsMax=\fR +.RS 4 +Controls the maximum number of concurrent user sessions to manage\&. Defaults to 8192 (8K)\&. Depending on how the +pam_systemd\&.so +module is included in the PAM stack configuration, further login sessions will either be refused, or permitted but not tracked by +systemd\-logind\&. +.sp +Added in version 230\&. +.RE +.PP +\fIRemoveIPC=\fR +.RS 4 +Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the user fully logs out\&. Takes a boolean argument\&. If enabled, the user may not consume IPC resources after the last of the user\*(Aqs sessions terminated\&. This covers System V semaphores, shared memory and message queues, as well as POSIX shared memory and message queues\&. Note that IPC objects of the root user and other system users are excluded from the effect of this setting\&. Defaults to +"yes"\&. +.sp +Added in version 212\&. +.RE +.PP +\fIStopIdleSessionSec=\fR +.RS 4 +Specifies a timeout in seconds, or a time span value after which +systemd\-logind +checks the idle state of all sessions\&. Every session that is idle for longer then the timeout will be stopped\&. Defaults to +"infinity" +(systemd\-logind +is not checking the idle state of sessions)\&. For details about the syntax of time spans, see +\fBsystemd.time\fR(7)\&. +.sp +Added in version 252\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-logind.service\fR(8), +\fBloginctl\fR(1), +\fBsystemd-system.conf\fR(5) diff --git a/upstream/fedora-40/man5/machine-id.5 b/upstream/fedora-40/man5/machine-id.5 new file mode 100644 index 00000000..a85e524b --- /dev/null +++ b/upstream/fedora-40/man5/machine-id.5 @@ -0,0 +1,253 @@ +'\" t +.TH "MACHINE\-ID" "5" "" "systemd 255" "machine-id" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +machine-id \- Local machine ID configuration file +.SH "SYNOPSIS" +.PP +/etc/machine\-id +.SH "DESCRIPTION" +.PP +The +/etc/machine\-id +file contains the unique machine ID of the local system that is set during installation or boot\&. The machine ID is a single newline\-terminated, hexadecimal, 32\-character, lowercase ID\&. When decoded from hexadecimal, this corresponds to a 16\-byte/128\-bit value\&. This ID may not be all zeros\&. +.PP +The machine ID is usually generated from a random source during system installation or first boot and stays constant for all subsequent boots\&. Optionally, for stateless systems, it is generated during runtime during early boot if necessary\&. +.PP +The machine ID may be set, for example when network booting, with the +\fIsystemd\&.machine_id=\fR +kernel command line parameter or by passing the option +\fB\-\-machine\-id=\fR +to systemd\&. An ID specified in this manner has higher priority and will be used instead of the ID stored in +/etc/machine\-id\&. +.PP +The machine ID does not change based on local or network configuration or when hardware is replaced\&. Due to this and its greater length, it is a more useful replacement for the +\fBgethostid\fR(3) +call that POSIX specifies\&. +.PP +This machine ID adheres to the same format and logic as the D\-Bus machine ID\&. +.PP +This ID uniquely identifies the host\&. It should be considered "confidential", and must not be exposed in untrusted environments, in particular on the network\&. If a stable unique identifier that is tied to the machine is needed for some application, the machine ID or any part of it must not be used directly\&. Instead the machine ID should be hashed with a cryptographic, keyed hash function, using a fixed, application\-specific key\&. That way the ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve the original machine ID from the application\-specific one\&. The +\fBsd_id128_get_machine_app_specific\fR(3) +API provides an implementation of such an algorithm\&. +.SH "INITIALIZATION" +.PP +Each machine should have a non\-empty ID in normal operation\&. The ID of each machine should be unique\&. To achieve those objectives, +/etc/machine\-id +can be initialized in a few different ways\&. +.PP +For normal operating system installations, where a custom image is created for a specific machine, +/etc/machine\-id +should be populated during installation\&. +.PP +\fBsystemd-machine-id-setup\fR(1) +may be used by installer tools to initialize the machine ID at install time, but +/etc/machine\-id +may also be written using any other means\&. +.PP +For operating system images which are created once and used on multiple machines, for example for containers or in the cloud, +/etc/machine\-id +should be either missing or an empty file in the generic file system image (the difference between the two options is described under "First Boot Semantics" below)\&. An ID will be generated during boot and saved to this file if possible\&. Having an empty file in place is useful because it allows a temporary file to be bind\-mounted over the real file, in case the image is used read\-only\&. Also see +\m[blue]\fBSafely Building Images\fR\m[]\&\s-2\u[1]\d\s+2\&. +.PP +\fBsystemd-firstboot\fR(1) +may be used to initialize +/etc/machine\-id +on mounted (but not booted) system images\&. +.PP +When a machine is booted with +\fBsystemd\fR(1) +the ID of the machine will be established\&. If +\fIsystemd\&.machine_id=\fR +or +\fB\-\-machine\-id=\fR +options (see first section) are specified, this value will be used\&. Otherwise, the value in +/etc/machine\-id +will be used\&. If this file is empty or missing, +systemd +will attempt to use the D\-Bus machine ID from +/var/lib/dbus/machine\-id, the value of the kernel command line option +\fIcontainer_uuid\fR, the KVM DMI +product_uuid +or the devicetree +vm,uuid +(on KVM systems), and finally a randomly generated UUID\&. +.PP +After the machine ID is established, +\fBsystemd\fR(1) +will attempt to save it to +/etc/machine\-id\&. If this fails, it will attempt to bind\-mount a temporary file over +/etc/machine\-id\&. It is an error if the file system is read\-only and does not contain a (possibly empty) +/etc/machine\-id +file\&. +.PP +\fBsystemd-machine-id-commit.service\fR(8) +will attempt to write the machine ID to the file system if +/etc/machine\-id +or +/etc/ +are read\-only during early boot but become writable later on\&. +.SH "FIRST BOOT SEMANTICS" +.PP +/etc/machine\-id +is used to decide whether a boot is the first one\&. The rules are as follows: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +The kernel command argument +\fIsystemd\&.condition\-first\-boot=\fR +may be used to override the autodetection logic, see +\fBkernel-command-line\fR(7)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Otherwise, if +/etc/machine\-id +does not exist, this is a first boot\&. During early boot, +\fBsystemd\fR +will write +"uninitialized\en" +to this file and overmount a temporary file which contains the actual machine ID\&. Later (after +first\-boot\-complete\&.target +has been reached), the real machine ID will be written to disk\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +If +/etc/machine\-id +contains the string +"uninitialized", a boot is also considered the first boot\&. The same mechanism as above applies\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +If +/etc/machine\-id +exists and is empty, a boot is +\fInot\fR +considered the first boot\&. +\fBsystemd\fR +will still bind\-mount a file containing the actual machine\-id over it and later try to commit it to disk (if +/etc/ +is writable)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +If +/etc/machine\-id +already contains a valid machine\-id, this is not a first boot\&. +.RE +.PP +If according to the above rules a first boot is detected, units with +\fIConditionFirstBoot=yes\fR +will be run and +\fBsystemd\fR +will perform additional initialization steps, in particular presetting units\&. +.SH "RELATION TO OSF UUIDS" +.PP +Note that the machine ID historically is not an OSF UUID as defined by +\m[blue]\fBRFC 4122\fR\m[]\&\s-2\u[2]\d\s+2, nor a Microsoft GUID; however, starting with systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122\&. +.PP +In order to maintain compatibility with existing installations, an application requiring a strictly RFC 4122 compliant UUID should decode the machine ID, and then (non\-reversibly) apply the following operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID\&. With +"id" +being an unsigned character array: +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Set UUID version to 4 \-\-\- truly random generation */ +id[6] = (id[6] & 0x0F) | 0x40; +/* Set the UUID variant to DCE */ +id[8] = (id[8] & 0x3F) | 0x80; +.fi +.if n \{\ +.RE +.\} +.PP +(This code is inspired by +"generate_random_uuid()" +of +drivers/char/random\&.c +from the Linux kernel sources\&.) +.SH "HISTORY" +.PP +The simple configuration file format of +/etc/machine\-id +originates in the +/var/lib/dbus/machine\-id +file introduced by D\-Bus\&. In fact, this latter file might be a symlink to +/etc/machine\-id\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-machine-id-setup\fR(1), +\fBgethostid\fR(3), +\fBhostname\fR(5), +\fBmachine-info\fR(5), +\fBos-release\fR(5), +\fBsd-id128\fR(3), +\fBsd_id128_get_machine\fR(3), +\fBsystemd-firstboot\fR(1) +.SH "NOTES" +.IP " 1." 4 +Safely Building Images +.RS 4 +\%https://systemd.io/BUILDING_IMAGES +.RE +.IP " 2." 4 +RFC 4122 +.RS 4 +\%https://tools.ietf.org/html/rfc4122 +.RE diff --git a/upstream/fedora-40/man5/machine-info.5 b/upstream/fedora-40/man5/machine-info.5 new file mode 100644 index 00000000..f77dc12b --- /dev/null +++ b/upstream/fedora-40/man5/machine-info.5 @@ -0,0 +1,157 @@ +'\" t +.TH "MACHINE\-INFO" "5" "" "systemd 255" "machine-info" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +machine-info \- Local machine information file +.SH "SYNOPSIS" +.PP +/etc/machine\-info +.SH "DESCRIPTION" +.PP +The +/etc/machine\-info +file contains machine metadata\&. +.PP +The format of +machine\-info +is a newline\-separated list of environment\-like shell\-compatible variable assignments, ignoring comments and empty lines\&. It is possible to source the configuration from shell scripts, however, beyond mere variable assignments no shell features are supported, allowing applications to read the file without implementing a shell compatible execution engine\&. See +\fBos-release\fR(5) +for a detailed description of the format\&. +.PP +/etc/machine\-info +contains metadata about the machine that is set by the user or administrator\&. The settings configured here have the highest precedence\&. When not set, appropriate values may be determined automatically, based on the information about the hardware or other configuration files\&. It is thus completely fine for this file to not be present\&. +.PP +You may use +\fBhostnamectl\fR(1) +to change the settings of this file from the command line\&. +.SH "OPTIONS" +.PP +The following machine metadata parameters may be set using +/etc/machine\-info: +.PP +\fIPRETTY_HOSTNAME=\fR +.RS 4 +A pretty human\-readable UTF\-8 machine identifier string\&. This should contain a name like +"Lennart\*(Aqs Laptop" +which is useful to present to the user and does not suffer by the syntax limitations of internet domain names\&. If possible, the internet hostname as configured in +/etc/hostname +should be kept similar to this one\&. Example: if this value is +"Lennart\*(Aqs Computer" +an Internet hostname of +"lennarts\-computer" +might be a good choice\&. If this parameter is not set, an application should fall back to the Internet hostname for presentation purposes\&. +.RE +.PP +\fIICON_NAME=\fR +.RS 4 +An icon identifying this machine according to the +\m[blue]\fBXDG Icon Naming Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. If this parameter is not set, an application should fall back to +"computer" +or a similar icon name\&. +.RE +.PP +\fICHASSIS=\fR +.RS 4 +The chassis type\&. Currently, the following chassis types are defined: +"desktop", +"laptop", +"convertible", +"server", +"tablet", +"handset", +"watch", and +"embedded", as well as the special chassis types +"vm" +and +"container" +for virtualized systems that lack an immediate physical chassis\&. +.sp +Note that most systems allow detection of the chassis type automatically (based on firmware information or suchlike)\&. This setting should only be used to override a misdetection or to manually configure the chassis type where automatic detection is not available\&. +.sp +Added in version 197\&. +.RE +.PP +\fIDEPLOYMENT=\fR +.RS 4 +Describes the system deployment environment\&. One of the following is suggested: +"development", +"integration", +"staging", +"production"\&. +.sp +Added in version 216\&. +.RE +.PP +\fILOCATION=\fR +.RS 4 +Describes the system location if applicable and known\&. Takes a human\-friendly, free\-form string\&. This may be as generic as +"Berlin, Germany" +or as specific as +"Left Rack, 2nd Shelf"\&. +.sp +Added in version 216\&. +.RE +.PP +\fIHARDWARE_VENDOR=\fR +.RS 4 +Specifies the hardware vendor\&. If unspecified, the hardware vendor set in DMI or +\fBhwdb\fR(7) +will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fIHARDWARE_MODEL=\fR +.RS 4 +Specifies the hardware model\&. If unspecified, the hardware model set in DMI or +\fBhwdb\fR(7) +will be used\&. +.sp +Added in version 251\&. +.RE +.SH "EXAMPLE" +.sp +.if n \{\ +.RS 4 +.\} +.nf +PRETTY_HOSTNAME="Lennart\*(Aqs Tablet" +ICON_NAME=computer\-tablet +CHASSIS=tablet +DEPLOYMENT=production +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBos-release\fR(5), +\fBhostname\fR(5), +\fBmachine-id\fR(5), +\fBhostnamectl\fR(1), +\fBsystemd-hostnamed.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +XDG Icon Naming Specification +.RS 4 +\%https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html +.RE diff --git a/upstream/fedora-40/man5/makepkg.conf.5 b/upstream/fedora-40/man5/makepkg.conf.5 new file mode 100644 index 00000000..7c5fe2de --- /dev/null +++ b/upstream/fedora-40/man5/makepkg.conf.5 @@ -0,0 +1,548 @@ +'\" t +.\" Title: makepkg.conf +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2024-01-25 +.\" Manual: Pacman Manual +.\" Source: Pacman 6.0.2 +.\" Language: English +.\" +.TH "MAKEPKG\&.CONF" "5" "2024\-01\-25" "Pacman 6\&.0\&.2" "Pacman Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +makepkg.conf \- makepkg configuration file +.SH "SYNOPSIS" +.sp +/etc/makepkg\&.conf, $XDG_CONFIG_HOME/pacman/makepkg\&.conf, ~/\&.makepkg\&.conf +.SH "DESCRIPTION" +.sp +Configuration options for makepkg are stored in makepkg\&.conf\&. This file is sourced so you can include any special compiler flags you wish to use\&. This is helpful when building for different architectures or with different optimizations\&. However, only the variables described below are exported to the build environment\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +This does not guarantee that all package Makefiles will use your exported variables\&. Some of them are non\-standard\&. +.sp .5v +.RE +.sp +The system\-wide configuration file is found in /etc/makepkg\&.conf\&. Individual options can be overridden (or added to) on a per\-user basis in $XDG_CONFIG_HOME/pacman/makepkg\&.conf or ~/\&.makepkg\&.conf, with the former taking priority\&. +.sp +The default file is fairly well commented, so it may be easiest to simply follow directions given there for customization\&. +.SH "OPTIONS" +.PP +\fBDLAGENTS=(\fR\*(Aqprotocol::/path/to/command [options]\*(Aq \&...\fB)\fR +.RS 4 +Sets the download agents used to fetch source files specified with a URL in the +\fBPKGBUILD\fR(5) +file\&. Options can be specified for each command as well, and any protocol can have a download agent\&. Any spaces in option arguments are required to be escaped to avoid being split\&. Several examples are provided in the default makepkg\&.conf\&. + +If present, +%u +will be replaced with the download URL\&. Otherwise, the download URL will be placed on the end of the command\&. If present, +%o +will be replaced with the local file name, plus a \(lq\&.part\(rq extension, which allows makepkg to handle resuming file downloads\&. +.RE +.PP +\fBVCSCLIENTS=(\fR\*(Aqprotocol::package\*(Aq \&...\fB)\fR +.RS 4 +Sets the packages required to fetch version controlled source files\&. When required, makepkg will check that these packages are installed or are included in the +depends +or +makedepends +arrays in the PKGBUILD\&. +.RE +.PP +\fBCARCH=\fR"carch" +.RS 4 +Specifies your computer architecture; possible values include such things as \(lqi686\(rq, \(lqx86_64\(rq, \(lqppc\(rq, etc\&. This should be automatically set on installation\&. +.RE +.PP +\fBCHOST=\fR"chost" +.RS 4 +A string such as \(lqi686\-pc\-linux\-gnu\(rq; do not touch this unless you know what you are doing\&. This can be commented out by most users if desired\&. +.RE +.PP +\fBCPPFLAGS=\fR"cppflags" +.RS 4 +Flags used for the C preprocessor; see CFLAGS for more information\&. +.RE +.PP +\fBCFLAGS=\fR"cflags" +.RS 4 +Flags used for the C compiler\&. This is a key part to the use of makepkg\&. Usually several options are specified, and the most common string resembles something like this: \(lq\-march=i686 \-O2 \-pipe\(rq\&. Another useful option may be +\-mcpu +in place of +\-march\&. Read gcc(1) for more details on the wide variety of compiler flags available\&. +.RE +.PP +\fBCXXFLAGS=\fR"cxxflags" +.RS 4 +Flags used for the C++ compiler; see CFLAGS for more info\&. +.RE +.PP +\fBRUSTFLAGS=\fR"rustflags" +.RS 4 +Flags used for the Rust compiler, similar in spirit to CFLAGS\&. Read +\fBrustc\fR(1) +for more details on the available flags\&. +.RE +.PP +\fBLDFLAGS=\fR"ldflags" +.RS 4 +Flags used for the linker\&. Several options may be specified with common usage resembling \(lq\-Wl,\-\-hash\-style=gnu\(rq\&. Read ld(1) for more details on available linker flags\&. +.RE +.PP +\fBLTOFLAGS=\fR"ltoflags" +.RS 4 +Additional compiler and linker flags appended to +CFLAGS, +CXXFLAGS +and +LDFLAGS +when building with link time optimization\&. If empty, \(lq\-flto\(rq is used\&. +.RE +.PP +\fBMAKEFLAGS=\fR"makeflags" +.RS 4 +This is often used to set the number of jobs used; for example, +\-j2\&. Other flags that make accepts can also be passed\&. +.RE +.PP +\fBDEBUG_CFLAGS=\fR"debug_cflags" +.RS 4 +Additional compiler flags appended to +CFLAGS +for use in debugging\&. Usually this would include: \(lq\-g\(rq\&. Read gcc(1) for more details on the wide variety of compiler flags available\&. +.RE +.PP +\fBDEBUG_CXXFLAGS=\fR"debug_cxxflags" +.RS 4 +Debug flags used for the C++ compiler; see DEBUG_CFLAGS for more info\&. +.RE +.PP +\fBDEBUG_RUSTFLAGS=\fR"debug_rustflags" +.RS 4 +Additional compiler flags appended to +RUSTFLAGS +for use in debugging\&. Usually this would include: \(lq\-C debuginfo=2\(rq\&. Read +\fBrustc\fR(1) +for more details on the available flags\&. +.RE +.PP +\fBBUILDENV=(\fR!distcc !color !ccache check !sign\fB)\fR +.RS 4 +This array contains options that affect the build environment; the defaults are shown here\&. All options should always be left in the array; to enable or disable an option, simply remove or add an \(lq!\(rq at the front of the option\&. If an option is specified multiple times, the final value takes precedence\&. Each option works as follows: +.PP +\fBdistcc\fR +.RS 4 +Use the distributed C/C++/ObjC compiler to spread compilation among multiple machines\&. If this is enabled, +DISTCC_HOSTS +must be specified as well\&. +.RE +.PP +\fBcolor\fR +.RS 4 +Colorize output messages, making output easier to read\&. +.RE +.PP +\fBccache\fR +.RS 4 +Use ccache to cache compilation by default\&. This allows for faster compiles if you are continuously recompiling the same packages\&. It can be disabled for individual packages by placing +!ccache +in the PKGBUILD options array\&. +.RE +.PP +\fBcheck\fR +.RS 4 +Run the check() function if present in the PKGBUILD\&. This can be enabled or disabled for individual packages through the use of makepkg\(cqs +\fI\-\-check\fR +and +\fI\-\-nocheck\fR +options, respectively\&. +.RE +.PP +\fBsign\fR +.RS 4 +Generate a PGP signature file using GnuPG\&. This will execute +\fIgpg \-\-detach\-sign \-\-use\-agent\fR +on the built package to generate a detached signature file, using the GPG agent, if it is available\&. The signature file will be the entire file name of the package with a \(lq\&.sig\(rq extension\&. +.RE +.RE +.PP +\fBDISTCC_HOSTS=\fR"host1 \&..." +.RS 4 +If using DistCC, this is used to specify a space\-delimited list of hosts running in the DistCC cluster\&. In addition, you will want to modify your +MAKEFLAGS\&. +.RE +.PP +\fBBUILDDIR=\fR"/path/to/directory" +.RS 4 +If this value is not set, packages will, by default, be built in subdirectories of the directory that makepkg is called from\&. This option allows setting the build location to another directory\&. Incorrect use of +$startdir +in a PKGBUILD may cause building with this option to fail\&. +.RE +.PP +\fBGPGKEY=\fR"" +.RS 4 +Specify a key to use for GPG signing instead of the default key in the keyring\&. Can be overridden with makepkg\(cqs +\fI\-\-key\fR +option\&. +.RE +.PP +\fBOPTIONS=(\fR!strip docs libtool staticlibs emptydirs !zipman !purge !debug\fB)\fR +.RS 4 +This array contains options that affect default packaging\&. They are equivalent to options that can be placed in the PKGBUILD; the defaults are shown here\&. All options should always be left in the array; to enable or disable an option, simply remove or add an \(lq!\(rq at the front of the option\&. If an option is specified multiple times, the final value takes precedence\&. Each option works as follows: +.PP +\fBstrip\fR +.RS 4 +Strip symbols from binaries and libraries\&. If you frequently use a debugger on programs or libraries, it may be helpful to disable this option\&. +.RE +.PP +\fBdocs\fR +.RS 4 +Save doc directories\&. If you wish to delete doc directories, specify +!docs +in the array\&. The directories affected are specified by the +DOC_DIRS +variable\&. +.RE +.PP +\fBlibtool\fR +.RS 4 +Leave libtool (\&.la) files in packages\&. Specify +!libtool +to remove them\&. +.RE +.PP +\fBstaticlibs\fR +.RS 4 +Leave static library (\&.a) files in packages\&. Specify +!staticlibs +to remove them, if they have a shared counterpart\&. +.RE +.PP +\fBemptydirs\fR +.RS 4 +Leave empty directories in packages\&. +.RE +.PP +\fBzipman\fR +.RS 4 +Compress manual (man and info) pages with gzip\&. The directories affected are specified by the +MAN_DIRS +variable\&. +.RE +.PP +\fBpurge\fR +.RS 4 +Remove files specified by the +PURGE_TARGETS +variable from the package\&. +.RE +.PP +\fBdebug\fR +.RS 4 +Add the user\-specified debug flags as specified in DEBUG_CFLAGS and DEBUG_CXXFLAGS to their counterpart buildflags\&. Creates a separate package containing the debug symbols when used with \(oqstrip\(cq\&. +.RE +.PP +\fBlto\fR +.RS 4 +Enable building packages using link time optimization\&. Adds the flags specified in LTOFLAGS to CFLAGS, CXXFLAGS and LDFLAGS (or \(lq\-flto\(rq if LTOFLAGS is empty)\&. +.RE +.RE +.PP +\fBINTEGRITY_CHECK=(\fRcheck1 \&...\fB)\fR +.RS 4 +File integrity checks to use\&. Multiple checks may be specified; this affects both generation and checking\&. The current valid options are: +ck, +md5, +sha1, +sha224, +sha256, +sha384, +sha512, and +b2\&. +.RE +.PP +\fBSTRIP_BINARIES=\fR"\-\-strip\-all" +.RS 4 +Options to be used when stripping binaries\&. See +\fBstrip\fR(1) +for details\&. +.RE +.PP +\fBSTRIP_SHARED=\fR"\-\-strip\-unneeded" +.RS 4 +Options to be used when stripping shared libraries or PIE executables\&. See +\fBstrip\fR(1) +for details\&. +.RE +.PP +\fBSTRIP_STATIC=\fR"\-\-strip\-debug" +.RS 4 +Options to be used when stripping static libraries\&. See +\fBstrip\fR(1) +for details\&. +.RE +.PP +\fBMAN_DIRS=(\fR{usr{,/local}{,/share},opt/*}/{man,info} \&...\fB)\fR +.RS 4 +If +zipman +is specified in the +OPTIONS +array, this variable will instruct makepkg where to look to compress manual (man and info) pages\&. If you build packages that are located in opt/, you may need to add the directory to this array\&. +\fBNOTE:\fR +Do not add the leading slash to the directory name\&. +.RE +.PP +\fBDOC_DIRS=(\fRusr/{,share/}{doc,gtk\-doc} \&...\fB)\fR +.RS 4 +If +!docs +is specified in the +OPTIONS +array, this variable will instruct makepkg where to look to remove docs\&. If you build packages that are located in opt/, you may need to add the directory to this array\&. +\fBNOTE:\fR +Do not add the leading slash to the directory name\&. +.RE +.PP +\fBPURGE_TARGETS=(\fRusr/{,share}/info/dir \&.podlist *\&.pod\&...\fB)\fR +.RS 4 +If +purge +is specified in the +OPTIONS +array, this variable will instruct makepkg which files to remove from the package\&. This is useful for index files that are added by multiple packages\&. +.RE +.PP +\fBDBGSRCDIR=\fR"/usr/src/debug" +.RS 4 +If +strip +and +debug +are specified in the +OPTIONS +array, this variable will instruct makepkg where to place source files for installed binaries\&. The binaries will be modified to link this directory for the debugger search path\&. +.RE +.PP +\fBPKGDEST=\fR"/path/to/directory" +.RS 4 +If this value is not set, packages will, by default, be placed in the current directory (location of the +\fBPKGBUILD\fR(5))\&. Many people like to keep all their packages in one place so this option allows for this behavior\&. A common location is \(lq/home/packages\(rq\&. +.RE +.PP +\fBSRCDEST=\fR"/path/to/directory" +.RS 4 +If this value is not set, downloaded source files will only be stored in the current directory\&. Many people like to keep all source files in a central location for easy cleanup, so this path can be set here\&. +.RE +.PP +\fBSRCPKGDEST=\fR"/path/to/directory" +.RS 4 +If this value is not set, source package files will be stored in in the current directory\&. Many people like to keep all source package files in a central location for easy cleanup, so this path can be set here\&. +.RE +.PP +\fBLOGDEST=\fR"/path/to/directory" +.RS 4 +If this value is not set, log files are written to the current directory\&. This centralizes the log location, facilitating cleanup and compression\&. +.RE +.PP +\fBPACKAGER=\fR"John Doe " +.RS 4 +This value is used when querying a package to see who was the builder\&. The given format is required for PGP key lookup through WKD\&. It is recommended to change this to your name and email address\&. +.RE +.PP +\fBCOMPRESSGZ=\fR"(gzip \-c \-f \-n)", \fBCOMPRESSBZ2=\fR"(bzip2 \-c \-f)", \fBCOMPRESSXZ=\fR"(xz \-c \-z \-)", \fBCOMPRESSZST=\fR"(zstd \-c \-z \-)", \fBCOMPRESSLZO\fR"(lzop \-q)", \fBCOMPRESSLRZ=\fR"(lrzip \-q)", \fBCOMPRESSLZ4=\fR"(lz4 \-q)", \fBCOMPRESSZ=\fR"(compress \-c \-f)", \fBCOMPRESSLZ=\fR"(lzip \-c \-f)" +.RS 4 +Sets the command and options used when compressing compiled or source packages in the named format\&. +.RE +.PP +\fBPKGEXT=\fR"\&.pkg\&.tar\&.gz", \fBSRCEXT=\fR"\&.src\&.tar\&.gz" +.RS 4 +Sets the compression used when making compiled or source packages\&. Valid suffixes are +\&.tar\&.gz, +\&.tar\&.bz2, +\&.tar\&.xz, +\&.tar\&.zst, +\&.tar\&.lzo, +\&.tar\&.lrz, +\&.tar\&.lz4, +\&.tar\&.lz +and +\&.tar\&.Z, or simply +\&.tar +to disable compression entirely\&. +.RE +.PP +\fBPACMAN_AUTH=()\fR +.RS 4 +Specify a command prefix for running pacman as root\&. If unset, makepkg will check for the presence of sudo(8) and su(1) in turn, and try the first one it finds\&. + +If present, +%c +will be replaced with the shell\-quoted form of the command to run\&. Otherwise, the command to run is appended to the auth command\&. +.RE +.SH "SEE ALSO" +.sp +\fBmakepkg\fR(8), \fBpacman\fR(8), \fBPKGBUILD\fR(5) +.sp +See the pacman website at https://archlinux\&.org/pacman/ for current information on pacman and its related tools\&. +.SH "BUGS" +.sp +Bugs? You must be kidding; there are no bugs in this software\&. But if we happen to be wrong, submit a bug report with as much detail as possible at the Arch Linux Bug Tracker in the Pacman section\&. +.SH "AUTHORS" +.sp +Current maintainers: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Allan McRae +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Andrew Gregory +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Eli Schwartz +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Morgan Adamiec +.RE +.sp +Past major contributors: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Judd Vinet +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aurelien Foret +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aaron Griffin +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dan McGee +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Xavier Chantry +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Nagy Gabor +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dave Reisner +.RE +.sp +For additional contributors, use git shortlog \-s on the pacman\&.git repository\&. diff --git a/upstream/fedora-40/man5/mke2fs.conf.5 b/upstream/fedora-40/man5/mke2fs.conf.5 new file mode 100644 index 00000000..04a1aca1 --- /dev/null +++ b/upstream/fedora-40/man5/mke2fs.conf.5 @@ -0,0 +1,566 @@ +.\" -*- nroff -*- +.\" Copyright 2006 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH mke2fs.conf 5 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +mke2fs.conf \- Configuration file for mke2fs +.SH DESCRIPTION +.I mke2fs.conf +is the configuration file for +.BR mke2fs (8). +It controls the default parameters used by +.BR mke2fs (8) +when it is creating ext2, ext3, or ext4 file systems. +.PP +The +.I mke2fs.conf +file uses an INI-style format. Stanzas, or top-level sections, are +delimited by square braces: [ ]. Within each section, each line +defines a relation, which assigns tags to values, or to a subsection, +which contains further relations or subsections. +.\" Tags can be assigned multiple values +An example of the INI-style format used by this configuration file +follows below: +.P + [section1] +.br + tag1 = value_a +.br + tag1 = value_b +.br + tag2 = value_c +.P + [section 2] +.br + tag3 = { +.br + subtag1 = subtag_value_a +.br + subtag1 = subtag_value_b +.br + subtag2 = subtag_value_c +.br + } +.br + tag1 = value_d +.br + tag2 = value_e +.br + } +.P +Comments are delimited by a semicolon (';') or a hash ('#') character +at the beginning of the comment, and are terminated by the end of +line character. +.P +Tags and values must be quoted using double quotes if they contain +spaces. Within a quoted string, the standard backslash interpretations +apply: "\en" (for the newline character), +"\et" (for the tab character), "\eb" (for the backspace character), +and "\e\e" (for the backslash character). +.P +Some relations expect a boolean value. The parser is quite liberal on +recognizing ``yes'', '`y'', ``true'', ``t'', ``1'', ``on'', etc. as a +boolean true value, and ``no'', ``n'', ``false'', ``nil'', ``0'', +``off'' as a boolean false value. +.P +The following stanzas are used in the +.I mke2fs.conf +file. They will be described in more detail in future sections of this +document. +.TP +.I [options] +Contains relations which influence how mke2fs behaves. +.TP +.I [defaults] +Contains relations which define the default parameters +used by +.BR mke2fs (8). +In general, these defaults may be overridden by a definition in the +.B fs_types +stanza, or by a command-line option provided by the user. +.TP +.I [fs_types] +Contains relations which define defaults that should be used for specific +file system and usage types. The file system type and usage type can be +specified explicitly using +the +.BR \-t and \-T +options to +.BR mke2fs (8), +respectively. +.TP +.I [devices] +Contains relations which define defaults for specific devices. +.SH THE [options] STANZA +The following relations are defined in the +.I [options] +stanza. +.TP +.I proceed_delay +If this relation is set to a positive integer, then mke2fs will +wait +.I proceed_delay +seconds after asking the user for permission to proceed and +then continue, even if the +user has not answered the question. Defaults to 0, which means to wait +until the user answers the question one way or another. +.TP +.I sync_kludge +If this relation is set to a positive integer, then while writing the +inode table, mke2fs will request the operating system flush out pending +writes to initialize the inode table every +.I sync_kludge +block groups. This is needed to work around buggy kernels that don't +handle writeback throttling correctly. +.SH THE [defaults] STANZA +The following relations are defined in the +.I [defaults] +stanza. +.TP +.I creator_os +This relation specifies the "creator operating system" for the +file system unless it is overridden on the command line. +The default value is the OS for which the +.B mke2fs +executable was compiled. +.TP +.I fs_type +This relation specifies the default file system type if the user does not +specify it via the +.B \-t +option, or if +.B mke2fs +is not started using a program name of the form +.BI mkfs. fs-type\fR. +If both the user and the +.B mke2fs.conf +file do not specify a default file system type, mke2fs will use a +default file system type of +.I ext3 +if a journal was requested via a command-line option, or +.I ext2 +if not. +.TP +.I undo_dir +This relation specifies the directory where the undo file should be +stored. It can be overridden via the +.B E2FSPROGS_UNDO_DIR +environment variable. If the directory location is set to the value +.IR none , +.B mke2fs +will not create an undo file. +.PP +In addition, any tags that can be specified in a per-file system tags +subsection as defined below (e.g., +.IR blocksize , +.IR hash_alg , +.IR inode_ratio , +.IR inode_size , +.IR reserved_ratio , +etc.) can also be specified in the +.I defaults +stanza to specify the default value to be used if the user does not +specify one on the command line, and the file system-type +specific section of the configuration file does not specify a default value. +.SH THE [fs_types] STANZA +Each tag in the +.I [fs_types] +stanza names a file system type or usage type which can be specified via the +.B \-t +or +.B \-T +options to +.BR mke2fs (8), +respectively. +.P +The +.B mke2fs +program constructs a list of fs_types by concatenating the file system +type (i.e., ext2, ext3, etc.) with the usage type list. For most +configuration options, +.B mke2fs +will look for a subsection in the +.I [fs_types] +stanza corresponding with each entry in the constructed list, with later +entries overriding earlier file system or usage types. +For +example, consider the following +.B mke2fs.conf +fragment: +.P +[defaults] +.br + base_features = sparse_super,filetype,resize_inode,dir_index +.br + blocksize = 4096 +.br + inode_size = 256 +.br + inode_ratio = 16384 +.br + +.br +[fs_types] +.br + ext3 = { +.br + features = has_journal +.br + } +.br + ext4 = { +.br + features = extents,flex_bg +.br + inode_size = 256 +.br + } +.br + small = { +.br + blocksize = 1024 +.br + inode_ratio = 4096 +.br + } +.br + floppy = { +.br + features = ^resize_inode +.br + blocksize = 1024 +.br + inode_size = 128 +.br + } +.P +If mke2fs started with a program name of +.BR mke2fs.ext4 , +then the file system type of ext4 will be used. If the file system is +smaller than 3 megabytes, and no usage type is specified, then +.B mke2fs +will use a default +usage type of +.IR floppy . +This results in an fs_types list of "ext4, floppy". Both the ext4 +subsection and the floppy subsection define an +.I inode_size +relation, but since the later entries in the fs_types list supersede +earlier ones, the configuration parameter for fs_types.floppy.inode_size +will be used, so the file system will have an inode size of 128. +.P +The exception to this resolution is the +.I features +tag, which specifies a set of changes to the features used by the +file system, and which is cumulative. So in the above example, first +the configuration relation defaults.base_features would enable an +initial feature set with the sparse_super, filetype, resize_inode, and +dir_index features enabled. Then configuration relation +fs_types.ext4.features would enable the extents and flex_bg +features, and finally the configuration relation +fs_types.floppy.features would remove +the resize_inode feature, resulting in a file system feature set +consisting of the sparse_super, filetype, dir_index, +extents_and flex_bg features. +.P +For each file system type, the following tags may be used in that +fs_type's subsection. These tags may also be used in the +.I default +section: +.TP +.I base_features +This relation specifies the features which are initially enabled for this +file system type. Only one +.I base_features +will be used, so if there are multiple entries in the fs_types list +whose subsections define the +.I base_features +relation, only the last will be used by +.BR mke2fs (8). +.TP +.I enable_periodic_fsck +This boolean relation specifies whether periodic file system checks should be +enforced at boot time. If set to true, checks will be forced every +180 days, or after a random number of mounts. These values may +be changed later via the +.B -i +and +.B -c +command-line options to +.BR tune2fs (8). +.TP +.I errors +Change the behavior of the kernel code when errors are detected. +In all cases, a file system error will cause +.BR e2fsck (8) +to check the file system on the next boot. +.I errors +can be one of the following: +.RS 1.2i +.TP 1.2i +.B continue +Continue normal execution. +.TP +.B remount-ro +Remount file system read-only. +.TP +.B panic +Cause a kernel panic. +.RE +.TP +.I features +This relation specifies a comma-separated list of features edit +requests which modify the feature set +used by the newly constructed file system. The syntax is the same as the +.B -O +command-line option to +.BR mke2fs (8); +that is, a feature can be prefixed by a caret ('^') symbol to disable +a named feature. Each +.I feature +relation specified in the fs_types list will be applied in the order +found in the fs_types list. +.TP +.I force_undo +This boolean relation, if set to a value of true, forces +.B mke2fs +to always try to create an undo file, even if the undo file might be +huge and it might extend the time to create the file system image +because the inode table isn't being initialized lazily. +.TP +.I default_features +This relation specifies set of features which should be enabled or +disabled after applying the features listed in the +.I base_features +and +.I features +relations. It may be overridden by the +.B -O +command-line option to +.BR mke2fs (8). +.TP +.I auto_64-bit_support +This relation is a boolean which specifies whether +.BR mke2fs (8) +should automatically add the 64bit feature if the number of blocks for +the file system requires this feature to be enabled. The resize_inode +feature is also automatically disabled since it doesn't support 64-bit +block numbers. +.TP +.I default_mntopts +This relation specifies the set of mount options which should be enabled +by default. These may be changed at a later time with the +.B -o +command-line option to +.BR tune2fs (8). +.TP +.I blocksize +This relation specifies the default blocksize if the user does not +specify a blocksize on the command line. +.TP +.I lazy_itable_init +This boolean relation specifies whether the inode table should +be lazily initialized. It only has meaning if the uninit_bg feature is +enabled. If lazy_itable_init is true and the uninit_bg feature is +enabled, the inode table will +not be fully initialized by +.BR mke2fs (8). +This speeds up file system +initialization noticeably, but it requires the kernel to finish +initializing the file system in the background when the file system is +first mounted. +.TP +.I lazy_journal_init +This boolean relation specifies whether the journal inode should be +lazily initialized. It only has meaning if the has_journal feature is +enabled. If lazy_journal_init is true, the journal inode will not be +fully zeroed out by +.BR mke2fs . +This speeds up file system initialization noticeably, but carries some +small risk if the system crashes before the journal has been overwritten +entirely one time. +.TP +.I journal_location +This relation specifies the location of the journal. +.TP +.I num_backup_sb +This relation indicates whether file systems with the +.B sparse_super2 +feature enabled should be created with 0, 1, or 2 backup superblocks. +.TP +.I packed_meta_blocks +This boolean relation specifies whether the allocation bitmaps, inode +table, and journal should be located at the beginning of the file system. +.TP +.I inode_ratio +This relation specifies the default inode ratio if the user does not +specify one on the command line. +.TP +.I inode_size +This relation specifies the default inode size if the user does not +specify one on the command line. +.TP +.I reserved_ratio +This relation specifies the default percentage of file system blocks +reserved for the super-user, if the user does not specify one on the command +line. +.TP +.I hash_alg +This relation specifies the default hash algorithm used for the +new file systems with hashed b-tree directories. Valid algorithms +accepted are: +.IR legacy , +.IR half_md4 , +and +.IR tea . +.TP +.I flex_bg_size +This relation specifies the number of block groups that will be packed +together to create one large virtual block group on an ext4 file system. +This improves meta-data locality and performance on meta-data heavy +workloads. The number of groups must be a power of 2 and may only be +specified if the flex_bg file system feature is enabled. +.TP +.I options +This relation specifies additional extended options which should be +treated by +.BR mke2fs (8) +as if they were prepended to the argument of the +.B -E +option. This can be used to configure the default extended options used +by +.BR mke2fs (8) +on a per-file system type basis. +.TP +.I discard +This boolean relation specifies whether the +.BR mke2fs (8) +should attempt to discard device prior to file system creation. +.TP +.I cluster_size +This relation specifies the default cluster size if the bigalloc file +system feature is enabled. It can be overridden via the +.B \-C +command line option to +.BR mke2fs (8) +.TP +.I make_hugefiles +This boolean relation enables the creation of pre-allocated files as +part of formatting the file system. The extent tree blocks for these +pre-allocated files will be placed near the beginning of the file +system, so that if all of the other metadata blocks are also configured +to be placed near the beginning of the file system (by disabling the +backup superblocks, using the packed_meta_blocks option, etc.), the data +blocks of the pre-allocated files will be contiguous. +.TP +.I hugefiles_dir +This relation specifies the directory where huge files are created, +relative to the file system root. +.TP +.I hugefiles_uid +This relation controls the user ownership for all of the files and +directories created by the +.I make_hugefiles +feature. +.TP +.I hugefiles_gid +This relation controls the group ownership for all of the files and +directories created by the +.I make_hugefiles +feature. +.TP +.I hugefiles_umask +This relation specifies the umask used when creating the files and +directories by the +.I make_hugefiles +feature. +.TP +.I num_hugefiles +This relation specifies the number of huge files to be created. If this +relation is not specified, or is set to zero, and the +.I hugefiles_size +relation is non-zero, then +.I make_hugefiles +will create as many huge files as can fit to fill the entire file system. +.TP +.I hugefiles_slack +This relation specifies how much space should be reserved for other +files. +.TP +.I hugefiles_size +This relation specifies the size of the huge files. If this relation is +not specified, the default is to fill the entire file system. +.TP +.I hugefiles_align +This relation specifies the alignment for the start block of the huge +files. It also forces the size of huge files to be a multiple of the +requested alignment. If this relation is not specified, no alignment +requirement will be imposed on the huge files. +.TP +.I hugefiles_align_disk +This relations specifies whether the alignment should be relative to the +beginning of the hard drive (assuming that the starting offset of the +partition is available to mke2fs). The default value is false, which +will cause hugefile alignment to be relative to the beginning of the +file system. +.TP +.I hugefiles_name +This relation specifies the base file name for the huge files. +.TP +.I hugefiles_digits +This relation specifies the (zero-padded) width of the field for the +huge file number. +.TP +.I warn_y2038_dates +This boolean relation specifies whether mke2fs will issue a warning +when creating a file system with 128 byte inodes (and so therefore will +not support dates after January 19th, 2038). The default value is true, +except for file systems created for the GNU Hurd since it only supports +128-byte inodes. +.TP +.I zero_hugefiles +This boolean relation specifies whether or not zero blocks will be +written to the hugefiles while +.BR mke2fs (8) +is creating them. By default, zero blocks will be written to the huge +files to avoid stale data from being made available to potentially +untrusted user programs, unless the device supports a discard/trim +operation which will take care of zeroing the device blocks. By setting +.I zero_hugefiles +to false, this step will always be skipped, which can be useful if it is +known that the disk has been previously erased, or if the user programs +that will have access to the huge files are trusted to not reveal stale +data. +.TP +.I encoding +This relation defines the file name encoding to be used if the casefold +feature is enabled. Currently the only valid encoding is utf8-12.1 or +utf8, which requests the most recent Unicode version; since 12.1 is the only +available Unicode version, utf8 and utf8-12.1 have the same result. +.I encoding_flags +This relation defines encoding-specific flags. For utf8 encodings, the +only available flag is strict, which will cause attempts to create file +names containing invalid Unicode characters to be rejected by the +kernel. Strict mode is not enabled by default. +.SH THE [devices] STANZA +Each tag in the +.I [devices] +stanza names device name so that per-device defaults can be specified. +.TP +.I fs_type +This relation specifies the default parameter for the +.B \-t +option, if this option isn't specified on the command line. +.TP +.I usage_types +This relation specifies the default parameter for the +.B \-T +option, if this option isn't specified on the command line. +.SH FILES +.TP +.I /etc/mke2fs.conf +The configuration file for +.BR mke2fs (8). +.SH SEE ALSO +.BR mke2fs (8) diff --git a/upstream/fedora-40/man5/mlocate.db.5 b/upstream/fedora-40/man5/mlocate.db.5 new file mode 100644 index 00000000..60814d6b --- /dev/null +++ b/upstream/fedora-40/man5/mlocate.db.5 @@ -0,0 +1,131 @@ +.\" A man page for mlocate.db. -*- nroff -*- +.\" +.\" Copyright (C) 2005, 2007 Red Hat, Inc. All rights reserved. +.\" +.\" This copyrighted material is made available to anyone wishing to use, +.\" modify, copy, or redistribute it subject to the terms and conditions of the +.\" GNU General Public License v.2. +.\" +.\" This program is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +.\" more details. +.\" +.\" You should have received a copy of the GNU General Public License along +.\" with this program; if not, write to the Free Software Foundation, Inc., +.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +.\" +.\" Author: Miloslav Trmac +.TH mlocate.db 5 "Jan 2007" mlocate + +.SH NAME +mlocate.db \- a mlocate database + +.SH DESCRIPTION +A mlocate database starts with a file header: +8 bytes for a magic number (\fB"\\0mlocate"\fR like a C literal), +4 bytes for the +.I configuration block +size in big endian, +1 byte for file format version (\fB0\fR), +1 byte for the \*(lqrequire visibility\*(rq flag (\fB0\fR or \fB1\fR), +2 bytes padding, +and a \f(SMNUL\fR-terminated path name of the root of the database. + +The header is followed by a \fIconfiguration block\fR, +included to ensure databases are not reused +if some configuration changes +could affect their contents. +The size of the configuration block in bytes is stored in the file header. +The configuration block is a sequence of \fIvariable assignments\fR, +ordered by variable name. +Each +.I variable assignment +consists of a \f(SMNUL\fR-terminated variable name +and an ordered list of \f(SMNUL\fR-terminated values. +The value list is terminated by one more +.SM NUL +character. +The ordering used is defined by the +.B strcmp () +function. + +Currently defined variables are: +.TP +\fBprune_bind_mounts\fR +A single entry, the value of \fbPRUNE_BIND_MOUNTS\fR; one of the strings +.B 0 +or \fB1\fR. + +.TP +\fBprunefs\fR +The value of \fBPRUNEFS\fR, each entry is converted to uppercase. + +.TP +\fBprunepaths\fR +The value of \fBPRUNEPATHS\fR. + +.P +The rest of the file until +.SM EOF +describes directories and their contents. +Each directory starts with a header: +8 bytes for +.I directory time +(seconds) in big endian, +4 bytes for +.I directory time +(nanoseconds) in big endian (0 if unknown, less than 1,000,000,000), +4 bytes padding, +and a \f(SMNUL\fR-terminated path name of the the directory. +Directory contents, a sequence of +.I file entries +sorted by name, follow. + +.I Directory time +is the maximum of +.B st_ctime +and +.B st_mtime +of the directory. +.BR updatedb (8) +uses the original data if the +.I directory time +in the database and in the file system match exactly. +.I Directory time +equal to 0 always causes rescanning of the directory: +this is necessary to handle directories +which were being updated while building the database. + +Each +.I file entry +starts with a single byte, marking its type: +.TP +\fB0\fR +A non-directory file. +Followed by a \f(SMNUL\fR-terminated file (not path) name. + +.TP +\fB1\fR +A subdirectory. +Followed by a \f(SMNUL\fR-terminated file (not path) name. + +.TP +\fB2\fR +Marks the end of the current directory. + +.P +.BR locate(1) +only reports file entries, +directory names are not reported +because they are reported as an entry in their parent directory. +The only exception is the root directory of the database, +which is stored in the file header. + +.SH AUTHOR +Miloslav Trmac + +.SH SEE ALSO +.BR locate (1), +.BR updatedb.conf (5), +.BR updatedb (8) diff --git a/upstream/fedora-40/man5/modprobe.d.5 b/upstream/fedora-40/man5/modprobe.d.5 new file mode 100644 index 00000000..26442caf --- /dev/null +++ b/upstream/fedora-40/man5/modprobe.d.5 @@ -0,0 +1,174 @@ +'\" t +.\" Title: modprobe.d +.\" Author: Jon Masters +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 01/25/2024 +.\" Manual: modprobe.d +.\" Source: kmod +.\" Language: English +.\" +.TH "MODPROBE\&.D" "5" "01/25/2024" "kmod" "modprobe.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +modprobe.d \- Configuration directory for modprobe +.SH "SYNOPSIS" +.PP +/lib/modprobe\&.d/*\&.conf +.PP +/usr/lib/modprobe\&.d/*\&.conf +.PP +/usr/local/lib/modprobe\&.d/*\&.conf +.PP +/run/modprobe\&.d/*\&.conf +.PP +/etc/modprobe\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +Because the +\fBmodprobe\fR +command can add or remove more than one module, due to modules having dependencies, we need a method of specifying what options are to be used with those modules\&. All files underneath the +/etc/modprobe\&.d +directory which end with the +\&.conf +extension specify those options as required\&. They can also be used to create convenient aliases: alternate names for a module, or they can override the normal +\fBmodprobe\fR +behavior altogether for those with special requirements (such as inserting more than one module)\&. +.PP +Note that module and alias names (like other module names) can have \- or _ in them: both are interchangeable throughout all the module commands as underscore conversion happens automatically\&. +.PP +The format of files under +modprobe\&.d +is simple: one command per line, with blank lines and lines starting with \*(Aq#\*(Aq ignored (useful for adding comments)\&. A \*(Aq\e\*(Aq at the end of a line causes it to continue on the next line, which makes the file a bit neater\&. +.SH "COMMANDS" +.PP +alias \fIwildcard\fR \fImodulename\fR +.RS 4 +This allows you to give alternate names for a module\&. For example: "alias my\-mod really_long_modulename" means you can use "modprobe my\-mod" instead of "modprobe really_long_modulename"\&. You can also use shell\-style wildcards, so "alias my\-mod* really_long_modulename" means that "modprobe my\-mod\-something" has the same effect\&. You can\*(Aqt have aliases to other aliases (that way lies madness), but aliases can have options, which will be added to any other options\&. +.sp +Note that modules can also contain their own aliases, which you can see using +\fBmodinfo\fR\&. These aliases are used as a last resort (ie\&. if there is no real module, +\fBinstall\fR, +\fBremove\fR, or +\fBalias\fR +command in the configuration)\&. +.RE +.PP +blacklist \fImodulename\fR +.RS 4 +Modules can contain their own aliases: usually these are aliases describing the devices they support, such as "pci:123\&.\&.\&."\&. These "internal" aliases can be overridden by normal "alias" keywords, but there are cases where two or more modules both support the same devices, or a module invalidly claims to support a device that it does not: the +\fBblacklist\fR +keyword indicates that all of that particular module\*(Aqs internal aliases are to be ignored\&. +.RE +.PP +install \fImodulename\fR \fIcommand\&.\&.\&.\fR +.RS 4 +This command instructs +\fBmodprobe\fR +to run your command instead of inserting the module in the kernel as normal\&. The command can be any shell command: this allows you to do any kind of complex processing you might wish\&. For example, if the module "fred" works better with the module "barney" already installed (but it doesn\*(Aqt depend on it, so +\fBmodprobe\fR +won\*(Aqt automatically load it), you could say "install fred /sbin/modprobe barney; /sbin/modprobe \-\-ignore\-install fred", which would do what you wanted\&. Note the +\fB\-\-ignore\-install\fR, which stops the second +\fBmodprobe\fR +from running the same +\fBinstall\fR +command again\&. See also +\fBremove\fR +below\&. +.sp +The long term future of this command as a solution to the problem of providing additional module dependencies is not assured and it is intended to replace this command with a warning about its eventual removal or deprecation at some point in a future release\&. Its use complicates the automated determination of module dependencies by distribution utilities, such as mkinitrd (because these now need to somehow interpret what the +\fBinstall\fR +commands might be doing\&. In a perfect world, modules would provide all dependency information without the use of this command and work is underway to implement soft dependency support within the Linux kernel\&. +.sp +If you use the string "$CMDLINE_OPTS" in the command, it will be replaced by any options specified on the modprobe command line\&. This can be useful because users expect "modprobe fred opt=1" to pass the "opt=1" arg to the module, even if there\*(Aqs an install command in the configuration file\&. So our above example becomes "install fred /sbin/modprobe barney; /sbin/modprobe \-\-ignore\-install fred $CMDLINE_OPTS" +.RE +.PP +options \fImodulename\fR \fIoption\&.\&.\&.\fR +.RS 4 +This command allows you to add options to the module +\fImodulename\fR +(which might be an alias) every time it is inserted into the kernel: whether directly (using +\fBmodprobe \fR +\fImodulename\fR) or because the module being inserted depends on this module\&. +.sp +All options are added together: they can come from an +\fBoption\fR +for the module itself, for an alias, and on the command line\&. +.RE +.PP +remove \fImodulename\fR \fIcommand\&.\&.\&.\fR +.RS 4 +This is similar to the +\fBinstall\fR +command above, except it is invoked when "modprobe \-r" is run\&. +.RE +.PP +softdep \fImodulename\fR pre: \fImodules\&.\&.\&.\fR post: \fImodules\&.\&.\&.\fR +.RS 4 +The +\fBsoftdep\fR +command allows you to specify soft, or optional, module dependencies\&. +\fImodulename\fR +can be used without these optional modules installed, but usually with some features missing\&. For example, a driver for a storage HBA might require another module be loaded in order to use management features\&. +.sp +pre\-deps and post\-deps modules are lists of names and/or aliases of other modules that modprobe will attempt to install (or remove) in order before and after the main module given in the +\fImodulename\fR +argument\&. +.sp +Example: Assume "softdep c pre: a b post: d e" is provided in the configuration\&. Running "modprobe c" is now equivalent to "modprobe a b c d e" without the softdep\&. Flags such as \-\-use\-blacklist are applied to all the specified modules, while module parameters only apply to module c\&. +.sp +Note: if there are +\fBinstall\fR +or +\fBremove\fR +commands with the same +\fImodulename\fR +argument, +\fBsoftdep\fR +takes precedence\&. +.RE +.SH "COMPATIBILITY" +.PP +A future version of kmod will come with a strong warning to avoid use of the +\fBinstall\fR +as explained above\&. This will happen once support for soft dependencies in the kernel is complete\&. That support will complement the existing softdep support within this utility by providing such dependencies directly within the modules\&. +.SH "COPYRIGHT" +.PP +This manual page originally Copyright 2004, Rusty Russell, IBM Corporation\&. Maintained by Jon Masters and others\&. +.SH "SEE ALSO" +.PP +\fBmodprobe\fR(8), +\fBmodules.dep\fR(5) +.SH "AUTHORS" +.PP +\fBJon Masters\fR <\&jcm@jonmasters\&.org\&> +.RS 4 +Developer +.RE +.PP +\fBRobby Workman\fR <\&rworkman@slackware\&.com\&> +.RS 4 +Developer +.RE +.PP +\fBLucas De Marchi\fR <\&lucas\&.de\&.marchi@gmail\&.com\&> +.RS 4 +Developer +.RE diff --git a/upstream/fedora-40/man5/modules-load.d.5 b/upstream/fedora-40/man5/modules-load.d.5 new file mode 100644 index 00000000..1570e788 --- /dev/null +++ b/upstream/fedora-40/man5/modules-load.d.5 @@ -0,0 +1,90 @@ +'\" t +.TH "MODULES\-LOAD\&.D" "5" "" "systemd 255" "modules-load.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +modules-load.d \- Configure kernel modules to load at boot +.SH "SYNOPSIS" +.PP +/etc/modules\-load\&.d/*\&.conf +.PP +/run/modules\-load\&.d/*\&.conf +.PP +/usr/lib/modules\-load\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +\fBsystemd-modules-load.service\fR(8) +reads files from the above directories which contain kernel modules to load during boot in a static list\&. Each configuration file is named in the style of +/etc/modules\-load\&.d/\fIprogram\fR\&.conf\&. Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar triggers encoded in the kernel modules themselves instead of static configuration like this\&. In fact, most modern kernel modules are prepared for automatic loading already\&. +.SH "CONFIGURATION FORMAT" +.PP +The configuration files should simply contain a list of kernel module names to load, separated by newlines\&. Empty lines and lines whose first non\-whitespace character is # or ; are ignored\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +Configuration files are read from directories in +/etc/, +/run/, +/usr/local/lib/, and +/usr/lib/, in order of precedence, as listed in the SYNOPSIS section above\&. Files must have the +"\&.conf" +extension\&. Files in +/etc/ +override files with the same name in +/run/, +/usr/local/lib/, and +/usr/lib/\&. Files in +/run/ +override files with the same name under +/usr/\&. +.PP +All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence\&. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later)\&. +.PP +Packages should install their configuration files in +/usr/lib/ +(distribution packages) or +/usr/local/lib/ +(local installs)\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. It is recommended to prefix all filenames with a two\-digit number and a dash, to simplify the ordering of the files\&. +.PP +If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. If the vendor configuration file is included in the initrd image, the image has to be regenerated\&. +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&/etc/modules\-load\&.d/virtio\-net\&.conf example:\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Load virtio\-net\&.ko at boot +virtio\-net +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-modules-load.service\fR(8), +\fBsystemd-delta\fR(1), +\fBmodprobe\fR(8) diff --git a/upstream/fedora-40/man5/modules.dep.5 b/upstream/fedora-40/man5/modules.dep.5 new file mode 100644 index 00000000..ac9e2846 --- /dev/null +++ b/upstream/fedora-40/man5/modules.dep.5 @@ -0,0 +1,70 @@ +'\" t +.\" Title: modules.dep +.\" Author: Jon Masters +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 02/09/2023 +.\" Manual: modules.dep +.\" Source: kmod +.\" Language: English +.\" +.TH "MODULES\&.DEP" "5" "02/09/2023" "kmod" "modules.dep" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +modules.dep, modules.dep.bin \- Module dependency information +.SH "SYNOPSIS" +.PP +/lib/modules/modules\&.dep +.PP +/lib/modules/modules\&.dep\&.bin +.SH "DESCRIPTION" +.PP +modules\&.dep\&.bin +is a binary file generated by +\fBdepmod\fR +listing the dependencies for every module in the directories under +/lib/modules/\fIversion\fR\&. It is used by kmod tools such as +\fBmodprobe\fR +and libkmod\&. +.PP +Its text counterpart is located in the same directory with the name +modules\&.dep\&. The text version is maintained only for easy of reading by humans and is in no way used by any kmod tool\&. +.PP +These files are not intended for editing or use by any additional utilities as their format is subject to change in the future\&. You should use the +\fBmodinfo\fR(8) +command to obtain information about modules in a future proof and compatible fashion rather than touching these files\&. +.SH "COPYRIGHT" +.PP +This manual page originally Copyright 2002, Rusty Russell, IBM Corporation\&. Maintained by Jon Masters and others\&. +.SH "SEE ALSO" +.PP +\fBdepmod\fR(8), +\fBmodprobe\fR(8) +.SH "AUTHORS" +.PP +\fBJon Masters\fR <\&jcm@jonmasters\&.org\&> +.RS 4 +Developer +.RE +.PP +\fBLucas De Marchi\fR <\&lucas\&.de\&.marchi@gmail\&.com\&> +.RS 4 +Developer +.RE diff --git a/upstream/fedora-40/man5/moduli.5 b/upstream/fedora-40/man5/moduli.5 new file mode 100644 index 00000000..6dffdc7e --- /dev/null +++ b/upstream/fedora-40/man5/moduli.5 @@ -0,0 +1,126 @@ +.\" $OpenBSD: moduli.5,v 1.19 2022/04/16 04:30:10 dtucker Exp $ +.\" +.\" Copyright (c) 2008 Damien Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.Dd $Mdocdate: April 16 2022 $ +.Dt MODULI 5 +.Os +.Sh NAME +.Nm moduli +.Nd Diffie-Hellman moduli +.Sh DESCRIPTION +The +.Pa /etc/ssh/moduli +file contains prime numbers and generators for use by +.Xr sshd 8 +in the Diffie-Hellman Group Exchange key exchange method. +.Pp +New moduli may be generated with +.Xr ssh-keygen 1 +using a two-step process. +An initial +.Em candidate generation +pass, using +.Ic ssh-keygen -M generate , +calculates numbers that are likely to be useful. +A second +.Em primality testing +pass, using +.Ic ssh-keygen -M screen , +provides a high degree of assurance that the numbers are prime and are +safe for use in Diffie-Hellman operations by +.Xr sshd 8 . +This +.Nm +format is used as the output from each pass. +.Pp +The file consists of newline-separated records, one per modulus, +containing seven space-separated fields. +These fields are as follows: +.Bl -tag -width Description -offset indent +.It timestamp +The time that the modulus was last processed as YYYYMMDDHHMMSS. +.It type +Decimal number specifying the internal structure of the prime modulus. +Supported types are: +.Pp +.Bl -tag -width 0x00 -compact +.It 0 +Unknown, not tested. +.It 2 +"Safe" prime; (p-1)/2 is also prime. +.It 4 +Sophie Germain; 2p+1 is also prime. +.El +.Pp +Moduli candidates initially produced by +.Xr ssh-keygen 1 +are Sophie Germain primes (type 4). +Further primality testing with +.Xr ssh-keygen 1 +produces safe prime moduli (type 2) that are ready for use in +.Xr sshd 8 . +Other types are not used by OpenSSH. +.It tests +Decimal number indicating the type of primality tests that the number +has been subjected to represented as a bitmask of the following values: +.Pp +.Bl -tag -width 0x00 -compact +.It 0x00 +Not tested. +.It 0x01 +Composite number \(en not prime. +.It 0x02 +Sieve of Eratosthenes. +.It 0x04 +Probabilistic Miller-Rabin primality tests. +.El +.Pp +The +.Xr ssh-keygen 1 +moduli candidate generation uses the Sieve of Eratosthenes (flag 0x02). +Subsequent +.Xr ssh-keygen 1 +primality tests are Miller-Rabin tests (flag 0x04). +.It trials +Decimal number indicating the number of primality trials +that have been performed on the modulus. +.It size +Decimal number indicating the size of the prime in bits. +.It generator +The recommended generator for use with this modulus (hexadecimal). +.It modulus +The modulus itself in hexadecimal. +.El +.Pp +When performing Diffie-Hellman Group Exchange, +.Xr sshd 8 +first estimates the size of the modulus required to produce enough +Diffie-Hellman output to sufficiently key the selected symmetric cipher. +.Xr sshd 8 +then randomly selects a modulus from +.Fa /etc/ssh/moduli +that best meets the size requirement. +.Sh SEE ALSO +.Xr ssh-keygen 1 , +.Xr sshd 8 +.Sh STANDARDS +.Rs +.%A M. Friedl +.%A N. Provos +.%A W. Simpson +.%D March 2006 +.%R RFC 4419 +.%T Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol +.Re diff --git a/upstream/fedora-40/man5/motd.5 b/upstream/fedora-40/man5/motd.5 new file mode 100644 index 00000000..e530f542 --- /dev/null +++ b/upstream/fedora-40/man5/motd.5 @@ -0,0 +1,25 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:08:16 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH motd 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +motd \- message of the day +.SH DESCRIPTION +The contents of +.I /etc/motd +are displayed by +.BR login (1) +after a successful login but just before it executes the login shell. +.P +The abbreviation "motd" stands for "message of the day", and this file +has been traditionally used for exactly that (it requires much less disk +space than mail to all users). +.SH FILES +.I /etc/motd +.SH SEE ALSO +.BR login (1), +.BR issue (5) diff --git a/upstream/fedora-40/man5/mtools.5 b/upstream/fedora-40/man5/mtools.5 new file mode 100644 index 00000000..166aa901 --- /dev/null +++ b/upstream/fedora-40/man5/mtools.5 @@ -0,0 +1,575 @@ +'\" t +.TH mtools 5 "21Mar23" MTOOLS MTOOLS +.SH Name +mtools.conf - mtools configuration files +'\" t +.de TQ +.br +.ns +.TP \\$1 +.. + +.tr \(is' +.tr \(if` +.tr \(pd" + +.ds St Mtools\ 4.0.43 +.PP +.SH Description +.PP +This manual page describes the configuration files for mtools. They +are called \fR\&\f(CW\(if/etc/mtools.conf\(is\fR and \fR\&\f(CW\(if~/.mtoolsrc\(is\fR. If +the environmental variable \fR\&\f(CWMTOOLSRC\fR is set, its contents is used +as the filename for a third configuration file. These configuration +files describe the following items: +.TP +* \ Global\ configuration\ flags\ and\ variables\ +.TP +* \ Per\ drive\ flags\ and\ variables\ +.PP +.SS Location\ of\ the\ configuration\ files +.PP +.PP +\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR is the system-wide configuration file, +and \fR\&\f(CW\(if~/.mtoolsrc\(is\fR is the user's private configuration file. +.PP +On some systems, the system-wide configuration file is called +\&\fR\&\f(CW\(if/etc/default/mtools.conf\(is\fR instead. +.PP +.SS \ \ General\ configuration\ file\ syntax +.PP +The configuration files is made up of sections. Each section starts +with a keyword identifying the section followed by a colon. +Then follow variable assignments and flags. Variable assignments take +the following form: +.ft I +.nf +name=value +.fi +.ft R + +Flags are lone keywords without an equal sign and value following +them. A section either ends at the end of the file or where the next +section begins. +.PP +Lines starting with a hash (\fR\&\f(CW#\fR) are comments. Newline characters +are equivalent to whitespace (except where ending a comment). The +configuration file is case insensitive, except for item enclosed in +quotes (such as filenames). +.PP +.SS Default\ values +For most platforms, mtools contains reasonable compiled-in defaults for +physical floppy drives. Thus, you usually don't need to bother with the +configuration file, if all you want to do with mtools is to access your +floppy drives. On the other hand, the configuration file is needed if +you also want to use mtools to access your hard disk partitions and +DOSEMU image files. +.PP +.SS Global\ variables +.PP +Global flags may be set to 1 or to 0. +.PP +The following global flags are recognized: +.TP +\&\fR\&\f(CWMTOOLS_SKIP_CHECK\fR\ +If this is set to 1, mtools skips most of its sanity checks. This is +needed to read some Atari disks which have been made with the earlier +ROMs, and which would not be recognized otherwise. +.TP +\&\fR\&\f(CWMTOOLS_FAT_COMPATIBILITY\fR\ +If this is set to 1, mtools skips the fat size checks. Some disks have +a bigger FAT than they really need to. These are rejected if this +option is not set. +.TP +\&\fR\&\f(CWMTOOLS_LOWER_CASE\fR\ +If this is set to 1, mtools displays all-upper-case short filenames as +lowercase. This has been done to allow a behavior which is consistent +with older versions of mtools which didn't know about the case bits. +.TP +\&\fR\&\f(CWMTOOLS_NO_VFAT\fR\ +If this is set to 1, mtools won't generate VFAT entries for filenames +which are mixed-case, but otherwise legal dos filenames. This is useful +when working with DOS versions which can't grok VFAT long names, such as +FreeDOS. +.TP +\&\fR\&\f(CWMTOOLS_DOTTED_DIR\fR\ +In a wide directory, prints the short name with a dot instead of spaces +separating the basename and the extension. +.TP +\&\fR\&\f(CWMTOOLS_NAME_NUMERIC_TAIL\fR\ +If this is set to one (default), generate numeric tails for all long +names (~1). If set to zero, only generate numeric tails if otherwise a +clash would have happened. +.TP +\&\fR\&\f(CWMTOOLS_TWENTY_FOUR_HOUR_CLOCK\fR\ +If 1, uses the European notation for times (twenty four hour clock), +else uses the UK/US notation (am/pm) +.TP +\&\fR\&\f(CWMTOOLS_LOCK_TIMEOUT\fR\ +How long, in seconds, to wait for a locked device to become free. +Defaults to 30. +.PP +Example: +Inserting the following line into your configuration file instructs +mtools to skip the sanity checks: + +.nf +.ft 3 +.in +0.3i + MTOOLS_SKIP_CHECK=1 +.fi +.in -0.3i +.ft R +.PP + +\&\fR +.PP +Global variables may also be set via the environment: + +.nf +.ft 3 +.in +0.3i + export MTOOLS_SKIP_CHECK=1 +.fi +.in -0.3i +.ft R +.PP + +\&\fR +.PP +Global string variables may be set to any value: +.TP +\&\fR\&\f(CWMTOOLS_DATE_STRING\fR\ +The format used for printing dates of files. By default, is dd-mm-yyyy. +.PP +.SS Per\ drive\ flags\ and\ variables +.PP +.SS \ \ General\ information +.PP +Per drive flags and values may be described in a drive section. A +drive section starts with +\&\fR\&\f(CWdrive\fR "\fIdriveletter\fR" : +.PP +Then follow variable-value pairs and flags. +.PP +This is a sample drive description: + +.nf +.ft 3 +.in +0.3i + drive a: + file="/dev/fd0" use_xdf=1 +.fi +.in -0.3i +.ft R +.PP + +\&\fR +.PP +.SS \ \ Location\ information +.PP +For each drive, you need to describe where its data is physically +stored (image file, physical device, partition, offset). +.TP +\&\fR\&\f(CWfile\fR\ +The name of the file or device holding the disk image. This is +mandatory. The file name should be enclosed in quotes. +.TP +\&\fR\&\f(CWpartition\fR\ +Tells mtools to treat the drive as a partitioned device, and to use the +given partition. Only primary partitions are accessible using this +method, and they are numbered from 1 to 4. For logical partitions, use +the more general \fR\&\f(CWoffset\fR variable. The \fR\&\f(CWpartition\fR variable +is intended for removable media such as Syquest disks, ZIP drives, and +magneto-optical disks. Although traditional DOS sees Syquest disks and +magneto-optical disks as \fR\&\f(CW\(ifgiant floppy disks\(is\fR which are +unpartitioned, OS/2 and Windows NT treat them like hard disks, +i.e. partitioned devices. The \fR\&\f(CWpartition\fR flag is also useful DOSEMU +hdimages. It is not recommended for hard disks for which direct access +to partitions is available through mounting. +.TP +\&\fR\&\f(CWoffset\fR\ +Describes where in the file the MS-DOS file system starts. This is useful +for logical partitions in DOSEMU hdimages, and for ATARI ram disks. By +default, this is zero, meaning that the file system starts right at the +beginning of the device or file. +.PP +.SS \ \ Disk\ Geometry\ Configuration +.PP +Geometry information describes the physical characteristics about the +disk. Its has three purposes: +.TP +formatting\ +The geometry information is written into the boot sector of the newly +made disk. However, you may also describe the geometry information on +the command line. See section mformat, for details. +.TP +filtering\ +On some Unixes there are device nodes which only support one physical +geometry. For instance, you might need a different node to access a disk +as high density or as low density. The geometry is compared to the +actual geometry stored on the boot sector to make sure that this device +node is able to correctly read the disk. If the geometry doesn't match, +this drive entry fails, and the next drive entry bearing the same drive +letter is tried. See section multiple descriptions, for more details on +supplying several descriptions for one drive letter. +.IP +If no geometry information is supplied in the configuration file, all +disks are accepted. On Linux (and on SPARC) there exist device nodes +with configurable geometry (\fR\&\f(CW\(if/dev/fd0\(is\fR, \fR\&\f(CW\(if/dev/fd1\(is\fR etc), +and thus filtering is not needed (and ignored) for disk drives. (Mtools +still does do filtering on plain files (disk images) in Linux: this is +mainly intended for test purposes, as I don't have access to a Unix +which would actually need filtering). +.IP +If you do not need filtering, but want still a default geometry for +mformatting, you may switch off filtering using the \fR\&\f(CWmformat_only\fR +flag. +.IP +If you want filtering, you should supply the \fR\&\f(CWfilter\fR flag. If you +supply a geometry, you must supply one of both flags. +.TP +initial\ geometry\ +On devices that support it (usually floppy devices), the geometry +information is also used to set the initial geometry. This initial +geometry is applied while reading the boot sector, which contains the +real geometry. If no geometry information is supplied in the +configuration file, or if the \fR\&\f(CWmformat_only\fR flag is supplied, no +initial configuration is done. +.IP +On Linux, initial geometry is not really needed, as the configurable +devices are able to auto-detect the disk type accurately enough (for +most common formats) to read the boot sector. +.PP +Wrong geometry information may lead to very bizarre errors. That's why I +strongly recommend that you add the \fR\&\f(CWmformat_only\fR flag to your +drive description, unless you really need filtering or initial geometry. +.PP +The following geometry related variables are available: +.TP +\&\fR\&\f(CWcylinders\fR\ +.TQ +\&\fR\&\f(CWtracks\fR +The number of cylinders. (\fR\&\f(CWcylinders\fR is the preferred form, +\&\fR\&\f(CWtracks\fR is considered obsolete) +.TP +\&\fR\&\f(CWheads\fR\ +The number of heads (sides). +.TP +\&\fR\&\f(CWsectors\fR\ +The number of sectors per track. +.PP +Example: the following drive section describes a 1.44M drive: +.PP + +.nf +.ft 3 +.in +0.3i + drive a: + file="/dev/fd0H1440" + fat_bits=12 + cylinders=80 heads=2 sectors=18 + mformat_only +.fi +.in -0.3i +.ft R +.PP + +\&\fR +.PP +The following shorthand geometry descriptions are available: +.TP +\&\fR\&\f(CW1.44m\fR\ +high density 3 1/2 disk. Equivalent to: +\&\fR\&\f(CWfat_bits=12 cylinders=80 heads=2 sectors=18\fR +.TP +\&\fR\&\f(CW1.2m\fR\ +high density 5 1/4 disk. Equivalent to: +\&\fR\&\f(CWfat_bits=12 cylinders=80 heads=2 sectors=15\fR +.TP +\&\fR\&\f(CW720k\fR\ +double density 3 1/2 disk. Equivalent to: +\&\fR\&\f(CWfat_bits=12 cylinders=80 heads=2 sectors=9\fR +.TP +\&\fR\&\f(CW360k\fR\ +double density 5 1/4 disk. Equivalent to: +\&\fR\&\f(CWfat_bits=12 cylinders=40 heads=2 sectors=9\fR +.PP +The shorthand format descriptions may be amended. For example, +\&\fR\&\f(CW360k sectors=8\fR +describes a 320k disk and is equivalent to: +\&\fR\&\f(CWfat_bits=12 cylinders=40 heads=2 sectors=8\fR +.PP +.SS \ \ Open\ Flags +.PP +Moreover, the following flags are available: +.TP +\&\fR\&\f(CWsync\fR\ +All i/o operations are done synchronously +.TP +\&\fR\&\f(CWnodelay\fR\ +The device or file is opened with the O_NDELAY flag. This is needed on +some non-Linux architectures. +.TP +\&\fR\&\f(CWexclusive\fR\ +The device or file is opened with the O_EXCL flag. On Linux, this +ensures exclusive access to the floppy drive. On most other +architectures, and for plain files it has no effect at all. +.PP +.SS \ \ General\ Purpose\ Drive\ Variables +.PP +The following general purpose drive variables are available. +Depending to their type, these variables can be set to a string +(precmd, postcmd) or an integer (all others) +.TP +\&\fR\&\f(CWfat_bits\fR\ +The number of FAT bits. This may be 12 or 16. This is very rarely +needed, as it can almost always be deduced from information in the +boot sector. On the contrary, describing the number of fat bits may +actually be harmful if you get it wrong. You should only use it if +mtools gets the auto-detected number of fat bits wrong, or if you want +to mformat a disk with a weird number of fat bits. +.TP +\&\fR\&\f(CWcodepage\fR\ +Describes the DOS code page used for short filenames. This is a number +between 1 and 999. By default, code page 850 is used. The reason for +this is because this code page contains most of the characters that are +also available in ISO-Latin-1. You may also specify a global code page +for all drives by using the global \fR\&\f(CWdefault_codepage\fR parameter +(outside of any drive description). This parameters exists starting at +version 4.0.0 +.TP +\&\fR\&\f(CWdata_map\fR\ +Remaps data from image file. This is useful for image files which +might need additional zero-filled sectors to be inserted. Such is the +case for instance for IBM 3174 floppy images. These images represent +floppy disks with fewer sectors on their first cylinder. These missing +sectors are not stored in the image, but are still counted in the +filesystem layout. The data_map allows to fake these missing sectors +for the upper layers of mtools. A data_map is a comma-separated +sequence of source type and size. Source type may be \fR\&\f(CWzero\fR for +zero-filled sectors created by map, \fR\&\f(CWskip\fR for data in raw image +to be ignored (skipped), and nothing for data to be used as is +(copied) from the raw image. Datamap is automatically complemented by +an implicit last element of data to be used as is from current offset +to end of file. Each size is a number followed by a unit: \fR\&\f(CWs\fR for +a 512 byte sector, \fR\&\f(CWK\fR for Kbytes, \fR\&\f(CWM\fR for megabytes, +\&\fR\&\f(CWG\fR for gigabytes, and nothing for single bytes. +.IP +Example: +.IP +\&\fR\&\f(CWdata_map=1s,zero31s,28s,skip1s\fR would be a map for use with IBM +3174 floppy images. First sector (\fR\&\f(CW1s\fR, boot sector) is used as +is. Then follow 31 fake zero-filled sectors (\fR\&\f(CWzero31s\fR), then the +next 28 sectors from image (\fR\&\f(CW28s\fR) are used as is (they contain +FAT and root directory), then one sector from image is skipped +(\fR\&\f(CWskip1s\fR), and finally the rest of image is used as is +(implicit) +.IP +.TP +\&\fR\&\f(CWprecmd\fR\ +Executes the given command before opening the device. +On some variants of Solaris, it is necessary to call 'volcheck -v' +before opening a floppy device, in order for the system to notice that +there is indeed a disk in the drive. \fR\&\f(CWprecmd="volcheck -v"\fR in the +drive clause establishes the desired behavior. +.TP +\&\fR\&\f(CWpostcmd\fR\ +Executes the given command after closing the device. +May be useful if mtools shares the image file with some other application, +in order to release the image file to that application. +.TP +\&\fR\&\f(CWblocksize\fR\ +This parameter represents a default block size to be always used on this +device. All I/O is done with multiples of this block size, +independently of the sector size registered in the file system's boot +sector. This is useful for character devices whose sector size is not +512, such as for example CD-ROM drives on Solaris. +.PP +Only the \fR\&\f(CWfile\fR variable is mandatory. The other parameters may +be left out. In that case a default value or an auto-detected value is +used. +.PP +.SS \ \ General\ Purpose\ Drive\ Flags +.PP +A flag can either be set to 1 (enabled) or 0 (disabled). If the value is +omitted, it is enabled. For example, \fR\&\f(CWscsi\fR is equivalent to +\&\fR\&\f(CWscsi=1\fR +.TP +\&\fR\&\f(CWnolock\fR\ +Instruct mtools to not use locking on this drive. This is needed on +systems with buggy locking semantics. However, enabling this makes +operation less safe in cases where several users may access the same +drive at the same time. +.TP +\&\fR\&\f(CWscsi\fR\ +When set to 1, this option tells mtools to use raw SCSI I/O instead of +the standard read/write calls to access the device. Currently, this is +supported on HP-UX, Solaris and SunOS. This is needed because on some +architectures, such as SunOS or Solaris, PC media can't be accessed +using the \fR\&\f(CWread\fR and \fR\&\f(CWwrite\fR system calls, because the OS expects +them to contain a Sun specific "disk label". +.IP +As raw SCSI access always uses the whole device, you need to specify the +"partition" flag in addition +.IP +On some architectures, such as Solaris, mtools needs root privileges to +be able to use the \fR\&\f(CWscsi\fR option. Thus mtools should be installed +setuid root on Solaris if you want to access Zip/Jaz drives. Thus, if +the \fR\&\f(CWscsi\fR flag is given, \fR\&\f(CWprivileged\fR is automatically +implied, unless explicitly disabled by \fR\&\f(CWprivileged=0\fR +.IP +Mtools uses its root privileges to open the device, and to issue the +actual SCSI I/O calls. Moreover, root privileges are only used for +drives described in a system-wide configuration file such as +\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR, and not for those described in +\&\fR\&\f(CW\(if~/.mtoolsrc\(is\fR or \fR\&\f(CW\(if$MTOOLSRC\(is\fR. +.TP +\&\fR\&\f(CWprivileged\fR\ +When set to 1, this instructs mtools to use its setuid and setgid +privileges for opening the given drive. This option is only valid for +drives described in the system-wide configuration files (such as +\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR, not \fR\&\f(CW\(if~/.mtoolsrc\(is\fR or +\&\fR\&\f(CW\(if$MTOOLSRC\(is\fR). Obviously, this option is also a no op if mtools is +not installed setuid or setgid. This option is implied by 'scsi=1', but +again only for drives defined in system-wide configuration files. +Privileged may also be set explicitly to 0, in order to tell mtools not +to use its privileges for a given drive even if \fR\&\f(CWscsi=1\fR is set. +.IP +Mtools only needs to be installed setuid if you use the +\&\fR\&\f(CWprivileged\fR or \fR\&\f(CWscsi\fR drive variables. If you do not use +these options, mtools works perfectly well even when not installed +setuid root. +.TP +\&\fR\&\f(CWvold\fR\ +.IP +Instructs mtools to interpret the device name as a vold identifier +rather than as a filename. The vold identifier is translated into a +real filename using the \fR\&\f(CWmedia_findname()\fR and +\&\fR\&\f(CWmedia_oldaliases()\fR functions of the \fR\&\f(CWvolmgt\fR library. This +flag is only available if you configured mtools with the +\&\fR\&\f(CW--enable-new-vold\fR option before compilation. +.TP +\&\fR\&\f(CWswap\fR\ +.IP +Consider the media as a word-swapped Atari disk. +.TP +\&\fR\&\f(CWuse_xdf\fR\ +If this is set to a non-zero value, mtools also tries to access this +disk as an XDF disk. XDF is a high capacity format used by OS/2. This +is off by default. See section XDF, for more details. +.TP +\&\fR\&\f(CWmformat_only\fR\ +Tells mtools to use the geometry for this drive only for mformatting and +not for filtering. +.TP +\&\fR\&\f(CWfilter\fR\ +Tells mtools to use the geometry for this drive both for mformatting and +filtering. +.TP +\&\fR\&\f(CWremote\fR\ +Tells mtools to connect to floppyd (see section floppyd). +.PP +.SS \ \ Supplying\ multiple\ descriptions\ for\ a\ drive +.PP +It is possible to supply multiple descriptions for a drive. In that +case, the descriptions are tried in order until one is found that +fits. Descriptions may fail for several reasons: +.TP +1.\ +because the geometry is not appropriate, +.TP +2.\ +because there is no disk in the drive, +.TP +3.\ +or because of other problems. +.PP +Multiple definitions are useful when using physical devices which are +only able to support one single disk geometry. +Example: + +.nf +.ft 3 +.in +0.3i + drive a: file="/dev/fd0H1440" 1.44m + drive a: file="/dev/fd0H720" 720k +.fi +.in -0.3i +.ft R +.PP + +\&\fR +.PP +This instructs mtools to use /dev/fd0H1440 for 1.44m (high density) +disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this +feature is not really needed, as the /dev/fd0 device is able to handle +any geometry. +.PP +You may also use multiple drive descriptions to access both of your +physical drives through one drive letter: +.PP + +.nf +.ft 3 +.in +0.3i + drive z: file="/dev/fd0" + drive z: file="/dev/fd1" +.fi +.in -0.3i +.ft R +.PP + +\&\fR +.PP +With this description, \fR\&\f(CWmdir z:\fR accesses your first physical +drive if it contains a disk. If the first drive doesn't contain a disk, +mtools checks the second drive. +.PP +When using multiple configuration files, drive descriptions in the files +parsed last override descriptions for the same drive in earlier +files. In order to avoid this, use the \fR\&\f(CWdrive+\fR or \fR\&\f(CW+drive\fR +keywords instead of \fR\&\f(CWdrive\fR. The first adds a description to the +end of the list (i.e. it will be tried last), and the first adds it to +the start of the list. +.PP +.SS Location\ of\ configuration\ files\ and\ parsing\ order +.PP +The configuration files are parsed in the following order: +.TP +1.\ +compiled-in defaults +.TP +2.\ +\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR +.TP +3.\ +\&\fR\&\f(CW\(if~/.mtoolsrc\(is\fR. +.TP +4.\ +\&\fR\&\f(CW\(if$MTOOLSRC\(is\fR (file pointed by the \fR\&\f(CWMTOOLSRC\fR environmental +variable) +.PP +Options described in the later files override those described in the +earlier files. Drives defined in earlier files persist if they are not +overridden in the later files. For instance, drives A and B may be +defined in \fR\&\f(CW\(if/etc/mtools.conf\(is\fR and drives C and D may be +defined in \fR\&\f(CW\(if~/.mtoolsrc\(is\fR However, if \fR\&\f(CW\(if~/.mtoolsrc\(is\fR also +defines drive A, this new description would override the description of +drive A in \fR\&\f(CW\(if/etc/mtools.conf\(is\fR instead of adding to it. If +you want to add a new description to a drive already described in an +earlier file, you need to use either the \fR\&\f(CW+drive\fR or \fR\&\f(CWdrive+\fR +keyword. +.PP +.SS Backwards\ compatibility\ with\ old\ configuration\ file\ syntax +.PP +The syntax described herein is new for version \fR\&\f(CWmtools-3.0\fR. The +old line-oriented syntax is still supported. Each line beginning with a +single letter is considered to be a drive description using the old +syntax. Old style and new style drive sections may be mixed within the +same configuration file, in order to make upgrading easier. Support for +the old syntax will be phased out eventually, and in order to discourage +its use, I purposefully omit its description here. +.PP +.SH See also +mtools diff --git a/upstream/fedora-40/man5/muttrc.5 b/upstream/fedora-40/man5/muttrc.5 new file mode 100644 index 00000000..5b7e55c0 --- /dev/null +++ b/upstream/fedora-40/man5/muttrc.5 @@ -0,0 +1,8134 @@ +'\" t +.\" -*-nroff-*- +.\" +.\" Copyright (C) 1996-2000 Michael R. Elkins +.\" Copyright (C) 1999-2000 Thomas Roessler +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +.\" +.de EX +.nf +.ft CW +.. +.de EE +.ft +.fi +.. +.TH muttrc 5 "January 2019" Unix "User Manuals" +.SH NAME +muttrc \- Configuration file for the Mutt Mail User Agent +.SH DESCRIPTION +.PP +A mutt configuration file consists of a series of \(lqcommands\(rq. +Each line of the file may contain one or more commands. When +multiple commands are used, they must be separated by a semicolon +(\(lq\fB;\fP\(rq). +.PP +The hash mark, or pound sign (\(lq\fB#\fP\(rq), is used as a +\(lqcomment\(rq character. You can use it to annotate your +initialization file. All text after the comment character to the end +of the line is ignored. +.PP +Single quotes (\(lq\fB'\fP\(rq) and double quotes (\(lq\fB"\fP\(rq) +can be used to quote strings which contain spaces or other special +characters. The difference between the two types of quotes is +similar to that of many popular shell programs, namely that a single +quote is used to specify a literal string (one that is not +interpreted for shell variables or quoting with a backslash [see +next paragraph]), while double quotes indicate a string which +should be evaluated. For example, backticks are evaluated inside of +double quotes, but not single quotes. +.PP +\fB\(rs\fP quotes the next character, just as in shells such as bash and zsh. +For example, if want to put quotes (\(lq\fB"\fP\(rq) inside of a +string, you can use \(lq\fB\(rs\fP\(rq to force the next character +to be a literal instead of interpreted character. +.PP +\(lq\fB\(rs\(rs\fP\(rq means to insert a literal \(lq\fB\(rs\fP\(rq into the +line. \(lq\fB\(rsn\fP\(rq and \(lq\fB\(rsr\fP\(rq have their usual +C meanings of linefeed and carriage-return, respectively. +.PP +A \(lq\fB\(rs\fP\(rq at the end of a line can be used to split commands over +multiple lines, provided that the split points don't appear in the +middle of command names. +.PP +It is also possible to substitute the output of a Unix command in an +initialization file. This is accomplished by enclosing the command +in backticks (\fB`\fP\fIcommand\fP\fB`\fP). +.PP +UNIX environment variables can be accessed like the way it is done in shells +like sh and bash: Prepend the name of the variable by a dollar +(\(lq\fB\(Do\fP\(rq) sign. +. +. +.PP +.SH COMMANDS +. +.PP +.nf +\fBalias\fP [\fB-group\fP \fIname\fP [...]] \fIkey\fP \fIaddress\fP [\fB,\fP \fIaddress\fP [ ... ]] +\fBunalias\fP [\fB * \fP | \fIkey\fP ] +.fi +.IP +\fBalias\fP defines an alias \fIkey\fP for the given addresses. Each +\fIaddress\fP will be resolved into either an email address (user@example.com) +or a named email address (User Name ). The address may be specified in either format, or in the format \(lquser@example.com (User +Name)\(rq. +\fBunalias\fP removes the alias corresponding to the given \fIkey\fP or +all aliases when \(lq\fB*\fP\(rq is used as an argument. The optional +\fB-group\fP argument to \fBalias\fP causes the aliased address(es) to be +added to the named \fIgroup\fP. +. +.PP +.nf +\fBgroup\fP [\fB-group\fP \fIname\fP] [\fB-rx\fP \fIEXPR\fP [ \fI...\fP ]] [\fB-addr\fP \fIaddress\fP [ \fI...\fP ]] +\fBungroup\fP [\fB-group\fP \fIname\fP ] [ \fB*\fP | [[\fB-rx\fP \fIEXPR\fP [ \fI...\fP ]] [\fB-addr\fP \fIaddress\fP [ \fI...\fP ]]] +.fi +.IP +\fBgroup\fP is used to directly add either addresses or regular expressions to +the specified group or groups. The different categories of arguments to the +\fBgroup\fP command can be in any order. The flags \fI-rx\fP and \fI-addr\fP +specify what the following strings (that cannot begin with a hyphen) should be +interpreted as: either a regular expression or an email address, respectively. +\fBungroup\fP is used to remove addresses or regular expressions from the +specified group or groups. The syntax is similar to the \fBgroup\fP command, +however the special character \fB*\fP can be used to empty a group of all of +its contents. +.IP +These address groups can also be created implicitly by the \fBalias\fP, \fBlists\fP, +\fBsubscribe\fP and \fBalternates\fP commands by specifying the optional \fI-group\fP +option. +.IP +Once defined, these address groups can be used in patterns to search for and limit the +display to messages matching a group. +. +.PP +.nf +\fBalternates\fP [\fB-group\fP \fIname\fP] \fIregexp\fP [ \fIregexp\fP [ ... ]] +\fBunalternates\fP [\fB * \fP | \fIregexp\fP [ \fIregexp\fP [ ... ]] ] +.fi +.IP +\fBalternates\fP is used to inform mutt about alternate addresses +where you receive mail; you can use regular expressions to specify +alternate addresses. This affects mutt's idea about messages +from you, and messages addressed to you. \fBunalternates\fP removes +a regular expression from the list of known alternates. The \fB-group\fP flag +causes all of the subsequent regular expressions to be added to the named group. +. +.PP +.nf +\fBalternative_order\fP \fItype\fP[\fB/\fP\fIsubtype\fP] [ ... ] +\fBunalternative_order\fP [\fB * \fP | \fItype\fP/\fIsubtype\fP] [...] +.fi +.IP +\fBalternative_order\fP command permits you to define an order of preference which is +used by mutt to determine which part of a +\fBmultipart/alternative\fP body to display. +A subtype of \(lq\fB*\fP\(rq matches any subtype, as does an empty +subtype. \fBunalternative_order\fP removes entries from the +ordered list or deletes the entire list when \(lq\fB*\fP\(rq is used +as an argument. +. +.PP +.nf +\fBattachments\fP [ \fB+\fP | \fB-\fP ]\fIdisposition\fP \fImime-type\fP +\fBunattachments\fP [ \fB+\fP | \fB-\fP ]\fIdisposition\fI \fImime-type\fP +\fBattachments\fP \fB?\fP +\fBunattachments\fP \fB*\fP +.fi +.IP +\fBattachments\fP specifies what kinds of attachments are used for Mutt's +attachment counting and searching support. +.IP +\fIdisposition\fP is the attachment's Content-Disposition type - either +inline or attachment. You can abbreviate this to I or A. +.IP +The first part of a message or multipart group, if inline, is counted +separately than other inline parts. Specify root or R for disposition +to count these as attachments. If this first part is of type +multipart/alternative, note that its top-level inline parts are also +counted via root disposition (if $count_alternatives is set). +.IP +\fIdisposition\fP is prefixed by either a \fB+\fP symbol or a \fB-\fP +symbol. If it's a \fB+\fP, you're saying that you want to allow this +disposition and MIME type to qualify. If it's a \fB-\fP, you're saying +that this disposition and MIME type is an exception to previous \fB+\fP +rules. +.IP +\fImime-type\fP is the MIME type of the attachment you want the +command to affect. A MIME type is always of the format major/minor, +where major describes the broad category of document you're looking +at, and minor describes the specific type within that category. The +major part of mime-type must be literal text (or the special token +\fB*\fP), but the minor part may be a regular expression. (Therefore, +\fB*/.*\fP matches any MIME type.) +.IP +The MIME types you give to the attachments directive are a kind of +pattern. When you use the attachments directive, the patterns you +specify are added to a list. When you use unattachments, the pattern +is removed from the list. The patterns are not expanded and matched to +specific MIME types at this time - they're just text in a +list. They're only matched when actually evaluating a message. +. +.PP +.nf +\fBauto_view\fP \fItype\fP[\fB/\fP\fIsubtype\fP] [ ... ] +\fBunauto_view\fP \fItype\fP[\fB/\fP\fIsubtype\fP] [ ... ] +.fi +.IP +This commands permits you to specify that mutt should automatically +convert the given MIME types to text/plain when displaying messages. +For this to work, there must be a +.BR mailcap (5) +entry for the given MIME type with the +.B copiousoutput +flag set. A subtype of \(lq\fB*\fP\(rq +matches any subtype, as does an empty subtype. +. +.PP +.nf +\fBmime_lookup\fP \fItype\fP[\fB/\fP\fIsubtype\fP] [ ... ] +\fBunmime_lookup\fP \fItype\fP[\fB/\fP\fIsubtype\fP] [ ... ] +.fi +.IP +This command permits you to define a list of "data" MIME content +types for which mutt will try to determine the actual file type from +the file name, and not use a +.BR mailcap (5) +entry given for the original MIME type. For instance, you may add +the \fBapplication/octet-stream\fP MIME type to this list. +. +.TP +\fBbind\fP \fImap1,map2,...\fP \fIkey\fP \fIfunction\fP +This command binds the given \fIkey\fP for the given \fImap\fP or maps +to the given \fIfunction\fP. Multiple maps may be specified by +separating them with commas (no whitespace is allowed). +.IP +Valid maps are: +.BR generic ", " alias ", " attach ", " +.BR browser ", " editor ", " +.BR index ", " compose ", " +.BR pager ", " pgp ", " postpone ", " +.BR mix . +.IP +For more information on keys and functions, please consult the Mutt +Manual. Note that the function name is to be specified without +angle brackets. +. +.TP +\fBaccount-hook\fP [\fB!\fP]\fIregexp\fP \fIcommand\fP +This hook is executed whenever you access a remote mailbox. Useful +to adjust configuration settings to different IMAP or POP servers. +. +.TP +\fBcharset-hook\fP \fIalias\fP \fIcharset\fP +This command defines an alias for a character set. This is useful +to properly display messages which are tagged with a character set +name not known to mutt. +. +.TP +\fBiconv-hook\fP \fIcharset\fP \fIlocal-charset\fP +This command defines a system-specific name for a character set. +This is useful when your system's +.BR iconv (3) +implementation does not understand MIME character set names (such as +.BR iso-8859-1 ), +but instead insists on being fed with implementation-specific +character set names (such as +.BR 8859-1 ). +In this specific case, you'd put this into your configuration file: +.IP +.B "iconv-hook iso-8859-1 8859-1" +. +.TP +\fBmessage-hook\fP [\fB!\fP]\fIpattern\fP \fIcommand\fP +Before mutt displays (or formats for replying or forwarding) a +message which matches the given \fIpattern\fP (or, when it is +preceded by an exclamation mark, does not match the \fIpattern\fP), +the given \fIcommand\fP is executed. When multiple +\fBmessage-hook\fPs match, they are executed in the order in +which they occur in the configuration file. +. +.TP +\fBfolder-hook\fP [\fB!\fP]\fIregexp\fP \fIcommand\fP +When mutt enters a folder which matches \fIregexp\fP (or, when +\fIregexp\fP is preceded by an exclamation mark, does not match +\fIregexp\fP), the given \fIcommand\fP is executed. +.IP +When several \fBfolder-hook\fPs match a given mail folder, they are +executed in the order given in the configuration file. +. +.TP +\fBmacro\fP \fImap\fP \fIkey\fP \fIsequence\fP [ \fIdescription\fP ] +This command binds the given \fIsequence\fP of keys to the given +\fIkey\fP in the given \fImap\fP or maps. For valid maps, see \fBbind\fP. To +specify multiple maps, put only a comma between the maps. +.PP +.nf +\fBcolor\fP \fIobject\fP [ \fIattribute\fP ... ] \fIforeground\fP \fIbackground\fP [ \fIregexp\fP ] +\fBcolor\fP index [ \fIattribute\fP ... ] \fIforeground\fP \fIbackground\fP [ \fIpattern\fP ] +\fBcolor\fP compose \fIcomposeobject\fP [ \fIattribute\fP ... ] \fIforeground\fP \fIbackground\fP +\fBuncolor\fP index \fIpattern\fP [ \fIpattern\fP ... ] +.fi +.IP +If your terminal supports color, these commands can be used to +assign \fIforeground\fP/\fIbackground\fP combinations to certain +objects. Valid objects are: +.BR attachment ", " body ", " bold ", " error ", " header ", " +.BR hdrdefault ", " index ", " indicator ", " markers ", " +.BR message ", " normal ", " prompt ", " quoted ", " quoted\fIN\fP ", " +.BR search ", " signature ", " status ", " tilde ", " tree ", " +.BR underline . +If the sidebar is enabled the following objects are also valid: +.BR sidebar_divider ", " sidebar_flagged ", " sidebar_highlight ", " +.BR sidebar_indicator ", " sidebar_new ", " sidebar_spoolfile . +The +.BR body " and " header +objects allow you to restrict the colorization to a regular +expression. The \fBindex\fP object permits you to select colored +messages by pattern. +.IP +Valid composeobjects include +.BR header ", " security_encrypt ", " security_sign ", " +.BR security_both ", " security_none . +.IP +Valid colors include: +.BR white ", " black ", " green ", " magenta ", " blue ", " +.BR cyan ", " yellow ", " red ", " default ", " color\fIN\fP . +.IP +Valid attributes include: +.BR none ", " bold ", " underline ", " +.BR reverse ", and " standout . +. +.PP +.nf +\fBmono\fP \fIobject\fP \fIattribute\fP [ \fIregexp\fP ] +\fBmono\fP index \fIattribute\fP [ \fIpattern\fP ] +.fi +.IP +For terminals which don't support color, you can still assign +attributes to objects. +. +.TP +[\fBun\fP]\fBignore\fP \fIpattern\fP [ \fIpattern\fP ... ] +The \fBignore\fP command permits you to specify header fields which +you usually don't wish to see. Any header field whose tag +\fIbegins\fP with an \(lqignored\(rq pattern will be ignored. +.IP +The \fBunignore\fP command permits you to define exceptions from +the above mentioned list of ignored headers. +. +.PP +.nf +\fBlists\fP [\fB-group\fP \fIname\fP] \fIregexp\fP [ \fIregexp\fP ... ] +\fBunlists\fP \fIregexp\fP [ \fIregexp\fP ... ] +\fBsubscribe\fP [\fB-group\fP \fIname\fP] \fIregexp\fP [ \fIregexp\fP ... ] +\fBunsubscribe\fP \fIregexp\fP [ \fIregexp\fP ... ] +.fi +.IP +Mutt maintains two lists of mailing list address patterns, a list of +subscribed mailing lists, and a list of known mailing lists. All +subscribed mailing lists are known. Patterns use regular expressions. +.IP +The \fBlists\fP command adds a mailing list address to the list of +known mailing lists. The \fBunlists\fP command removes a mailing +list from the lists of known and subscribed mailing lists. The +\fBsubscribe\fP command adds a mailing list to the lists of known +and subscribed mailing lists. The \fBunsubscribe\fP command removes +it from the list of subscribed mailing lists. The \fB-group\fP flag +adds all of the subsequent regular expressions to the named group. +. +.TP +\fBmbox-hook\fP [\fB!\fP]\fIregexp\fP \fImailbox\fP +When mutt changes to a mail folder which matches \fIregexp\fP, +\fImailbox\fP will be used as the \(lqmbox\(rq folder, i.e., read +messages will be moved to that folder when the mail folder is left. +.IP +The first matching \fBmbox-hook\fP applies. +. +.PP +.nf +\fBmailboxes\fP [[\fB-notify\fP | \fB-nonotify\fP] + [\fB-poll\fP | \fB-nopoll\fP] + [[\fB-label\fP \fIlabel\fP] | \fB-nolabel\fP] + \fIfilename\fP] [ ... ] +\fBunmailboxes\fP [ \fB*\fP | \fIfilename\fP ... ] +.fi +.IP +The \fBmailboxes\fP specifies folders which can receive mail and which will +be checked for new messages. When changing folders, pressing space +will cycle through folders with new mail. The \fBunmailboxes\fP +command is used to remove a file name from the list of folders which +can receive mail. If "\fB*\fP" is specified as the file name, the +list is emptied. +. +.PP +.nf +\fBmy_hdr\fP \fIstring\fP +\fBunmy_hdr\fP \fIfield\fP +.fi +.IP +Using \fBmy_hdr\fP, you can define headers which will be added to +the messages you compose. \fBunmy_hdr\fP will remove the given +user-defined headers. +. +.TP +\fBhdr_order\fP \fIheader1\fP \fIheader2\fP [ ... ] +With this command, you can specify an order in which mutt will +attempt to present headers to you when viewing messages. +. +.TP +\fBsave-hook\fP [\fB!\fP]\fIpattern\fP \fIfilename\fP +When a message matches \fIpattern\fP, the default file name when +saving it will be the given \fIfilename\fP. +. +.TP +\fBfcc-hook\fP [\fB!\fP]\fIpattern\fP \fIfilename\fP +When an outgoing message matches \fIpattern\fP, the default file +name for storing a copy (fcc) will be the given \fIfilename\fP. +. +.TP +\fBfcc-save-hook\fP [\fB!\fP]\fIpattern\fP \fIfilename\fP +This command is an abbreviation for identical \fBfcc-hook\fP and +\fBsave-hook\fP commands. +. +.TP +\fBsend-hook\fP [\fB!\fP]\fIpattern\fP \fIcommand\fP +When composing a message matching \fIpattern\fP, \fIcommand\fP is +executed. When multiple \fBsend-hook\fPs match, they are executed +in the order in which they occur in the configuration file. +. +.TP +\fBsend2-hook\fP [\fB!\fP]\fIpattern\fP \fIcommand\fP +Whenever a message matching \fIpattern\fP is changed (either by +editing it or by using the compose menu), \fIcommand\fP +is executed. When multiple \fBsend2-hook\fPs match, they are +executed in the order in which they occur in the configuration file. +Possible applications include setting the $sendmail variable when a +message's from header is changed. +.IP +\fBsend2-hook\fP execution is not triggered by use of +\fBenter-command\fP from the compose menu. +. +.TP +\fBreply-hook\fP [\fB!\fP]\fIpattern\fP \fIcommand\fP +When replying to a message matching \fIpattern\fP, \fIcommand\fP is +executed. When multiple \fBreply-hook\fPs match, they are executed +in the order in which they occur in the configuration file, but all +\fBreply-hook\fPs are matched and executed before \fBsend-hook\fPs, +regardless of their order in the configuration file. +. +.TP +\fBcrypt-hook\fP \fIregexp\fP \fIkey-id\fP +The crypt-hook command provides a method by which you can +specify the ID of the public key to be used when encrypting messages +to a certain recipient. The meaning of "key ID" is to be taken +broadly: This can be a different e-mail address, a numerical key ID, +or even just an arbitrary search string. +You may use multiple +\fBcrypt-hook\fPs with the same \fIregexp\fP; multiple matching +\fBcrypt-hook\fPs result in the use of multiple \fIkey-id\fPs for +a recipient. +. +.TP +\fBindex-format-hook\fP \fIname\fP [\fB!\fP]\fIpattern\fP \fIformat-string\fP +This command is used to inject format strings dynamically into +$index_format based on pattern matching against the current message. +.IP +The $index_format expando \fI%@name@\fP specifies a placeholder for +the injection. Index-format-hooks with the same \fIname\fP are matched +using \fIpattern\fP against the current message. Matching is done in +the order specified in the .muttrc, with the first match being +used. The hook's \fIformat-string\fP is then substituted and evaluated. +. +.PP +.nf +\fBopen-hook\fP \fIregexp\fP "\fIcommand\fP" +\fBclose-hook\fP \fIregexp\fP "\fIcommand\fP" +\fBappend-hook\fP \fIregexp\fP "\fIcommand\fP" +.fi +.IP +These commands provide a way to handle compressed folders. The given +\fBregexp\fP specifies which folders are taken as compressed (e.g. +"\fI\\\\.gz$\fP"). The commands tell Mutt how to uncompress a folder +(\fBopen-hook\fP), compress a folder (\fBclose-hook\fP) or append a +compressed mail to a compressed folder (\fBappend-hook\fP). The +\fIcommand\fP string is the +.BR printf (3) +like format string, and it should accept two parameters: \fB%f\fP, +which is replaced with the (compressed) folder name, and \fB%t\fP +which is replaced with the name of the temporary folder to which to +write. +. +.PP +.nf +\fBpush\fP \fIstring\fP +\fBexec\fP \fIfunction\fP [ ... ] +.fi +.IP +\fBpush\fP adds the named \fIstring\fP to the keyboard buffer. +\(lqexec function\(rq is equivalent to \(lqpush \(rq. +. +.TP +\fBrun\fP \fIMuttLisp\fP +.IP +The \fBrun\fP command evaluates the \fIMuttLisp\fP argument. The +output of the \fIMuttLisp\fP is then executed as a Mutt command, as if it +were typed in the muttrc instead. +. +.PP +.nf +\fBscore\fP \fIpattern\fP \fIvalue\fP +\fBunscore\fP [ \fB*\fP | \fIpattern\fP ... ] +.fi +.IP +The \fBscore\fP commands adds \fIvalue\fP to a message's score if +\fIpattern\fP matches it. The \fBunscore\fP command removes score +entries from the list. +. +.PP +.nf +\fBset\fP [\fBno\fP|\fBinv\fP|\fB&\fP|\fB?\fP]\fIvariable\fP[=\fIvalue\fP] [ ... ] +\fBtoggle\fP \fIvariable\fP [ ... ] +\fBunset\fP \fIvariable\fP [ ... ] +\fBreset\fP \fIvariable\fP [ ... ] +.fi +.IP +These commands are used to set and manipulate configuration +variables. +.IP +Mutt knows four basic types of variables: boolean, number, string +and quadoption. Boolean variables can be \fBset\fP (true), +\fBunset\fP (false), or \fBtoggle\fPd. Number variables can be assigned +a positive integer value. +.IP +String variables consist of any number of printable characters. +Strings must be enclosed in quotes if they contain spaces or tabs. +You may also use the \(lqC\(rq escape sequences \fB\\n\fP and +\fB\\t\fP for newline and tab, respectively. +.IP +Quadoption variables are used to control whether or not to be +prompted for certain actions, or to specify a default action. A +value of \fByes\fP will cause the action to be carried out automatically +as if you had answered yes to the question. Similarly, a value of +\fBno\fP will cause the action to be carried out as if you had +answered \(lqno.\(rq A value of \fBask-yes\fP will cause a prompt +with a default answer of \(lqyes\(rq and \fBask-no\fP will provide a +default answer of \(lqno.\(rq +.IP +The \fBreset\fP command resets all given variables to the compile +time defaults. If you reset the special variable \fBall\fP, all +variables will reset to their compile time defaults. +. +.PP +.nf +\fBsetenv\fP [\fB?\fP]\fIvariable\fP [ \fIvalue\fP ] +\fBunsetenv\fP \fIvariable\fP +.fi +.IP +These alter the environment that Mutt passes on to its child +processes. You can also query current environment values by prefixing +a “?” character. +. +.PP +.nf +\fBsidebar_whitelist\fP \fImailbox\fP [ \fImailbox\fP ...] +\fBunsidebar_whitelist\fP [ \fB*\fP | \fImailbox\fP ... ] +.fi +.IP +\fBsidebar_whitelist\fP specifies mailboxes that will always be +displayed in the sidebar, even if $sidebar_new_mail_only is set and +the mailbox does not contain new mail. +.IP +\fBunsidebar_whitelist\fP is used to remove a mailbox from the list of +whitelisted mailboxes. Use \fBunsidebar_whitelist *\fP to remove all +mailboxes. +. +.TP +\fBsource\fP \fIfilename\fP +The given file will be evaluated as a configuration file. +. +.PP +.nf +\fBspam\fP \fIpattern\fP \fIformat\fP +\fBnospam\fP \fIpattern\fP +.fi +.IP +These commands define spam-detection patterns from external spam +filters, so that mutt can sort, limit, and search on +``spam tags'' or ``spam attributes'', or display them +in the index. See the Mutt manual for details. +. +.PP +.nf +\fBsubjectrx\fP \fIpattern\fP \fIreplacement\fP +\fBunsubjectrx\fP [ \fB*\fP | \fIpattern\fP ] +.fi +.IP +\fBsubjectrx\fP specifies a regular expression \fIpattern\fP which, if +detected in a message subject, causes the subject to be replaced with +the \fIreplacement\fP value. The \fIreplacement\fP is subject to +substitutions in the same way as for the \fBspam\fP command: %L for +the text to the left of the match, %R for text to the right of the +match, and %1 for the first subgroup in the match (etc). If you simply +want to erase the match, set it to \(lq%L%R\(rq. Any number of +\fBsubjectrx\fP commands may coexist. +.IP +Note this well: the \fIreplacement\fP value replaces the entire +subject, not just the match! +.IP +\fBunsubjectrx\fP removes a given \fBsubjectrx\fP from the +substitution list. If \fB*\fP is used as the pattern, all +substitutions will be removed. +. +.TP +\fBunhook\fP [\fB * \fP | \fIhook-type\fP ] +This command will remove all hooks of a given type, or all hooks +when \(lq\fB*\fP\(rq is used as an argument. \fIhook-type\fP +can be any of the \fB-hook\fP commands documented above. +. +.PP +.nf +\fBmailto_allow\fP \fIheader-field\fP [ ... ] +\fBunmailto_allow\fP [ \fB*\fP | \fIheader-field\fP ... ] +.fi +.IP +These commands allow the user to modify the list of allowed header +fields in a \fImailto:\fP URL that Mutt will include in the +the generated message. By default the list contains only +\fBsubject\fP and \fBbody\fP, as specified by RFC2368. +. +.TP +\fBecho\fP \fImessage\fP +Prints \fImessage\fP to the message window. After printing the +message, echo will pause for the number of seconds specified by +$sleep_time. +. +.TP +\fBcd\fP \fIdirectory\fP +Changes the current working directory. +. +. +.SH PATTERNS +.PP +In various places with mutt, including some of the above mentioned +\fBhook\fP commands, you can specify patterns to match messages. +.SS Constructing Patterns +.PP +A simple pattern consists of a modifier of the form +\(lq\fB~\fP\fIcharacter\fP\(rq, possibly followed by a parameter +against which mutt is supposed to match the object specified by +this modifier. For some \fIcharacter\fPs, the \fB~\fP may be +replaced by another character to alter the behavior of the match. +These are described in the list of modifiers, below. +.PP +With some of these modifiers, the object to be matched consists of +several e-mail addresses. In these cases, the object is matched if +at least one of these e-mail addresses matches. You can prepend a +hat (\(lq\fB^\fP\(rq) character to such a pattern to indicate that +\fIall\fP addresses must match in order to match the object. +.PP +You can construct complex patterns by combining simple patterns with +logical operators. Logical AND is specified by simply concatenating +two simple patterns, for instance \(lq~C mutt-dev ~s bug\(rq. +Logical OR is specified by inserting a vertical bar (\(lq\fB|\fP\(rq) +between two patterns, for instance \(lq~C mutt-dev | ~s bug\(rq. +Additionally, you can negate a pattern by prepending a bang +(\(lq\fB!\fP\(rq) character. For logical grouping, use braces +(\(lq()\(rq). Example: \(lq!(~t mutt|~c mutt) ~f elkins\(rq. +.SS Simple Patterns +.PP +Mutt understands the following simple patterns: +.P +.PD 0 +.TP 12 +~A +all messages +.TP +~b \fIEXPR\fP +messages which contain \fIEXPR\fP in the message body. +.TP +=b \fISTRING\fP +If IMAP is enabled, like ~b but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. +.TP +~B \fIEXPR\fP +messages which contain \fIEXPR\fP in the whole message. +.TP +=B \fISTRING\fP +If IMAP is enabled, like ~B but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. +.TP +~c \fIEXPR\fP +messages carbon-copied to \fIEXPR\fP +.TP +%c \fIGROUP\fP +messages carbon-copied to any member of \fIGROUP\fP +.TP +~C \fIEXPR\fP +messages either to: or cc: \fIEXPR\fP +.TP +%C \fIGROUP\fP +messages either to: or cc: to any member of \fIGROUP\fP +.TP +~d \fIMIN\fP-\fIMAX\fP +messages with \(lqdate-sent\(rq in a Date range +.TP +~D +deleted messages +.TP +~e \fIEXPR\fP +messages which contain \fIEXPR\fP in the \(lqSender\(rq field +.TP +%e \fIGROUP\fP +messages which contain a member of \fIGROUP\fP in the \(lqSender\(rq field +.TP +~E +expired messages +.TP +~f \fIEXPR\fP +messages originating from \fIEXPR\fP +.TP +%f \fIGROUP\fP +messages originating from any member of \fIGROUP\fP +.TP +~F +flagged messages +.TP +~g +PGP signed messages +.TP +~G +PGP encrypted messages +.TP +~h \fIEXPR\fP +messages which contain \fIEXPR\fP in the message header +.TP +=h \fISTRING\fP +If IMAP is enabled, like ~h but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. \fISTRING\fP must be of the form \(lqheader: substring\(rq +.TP +~H \fIEXPR\fP +messages with spam tags matching \fIEXPR\fP +.TP +~i \fIEXPR\fP +messages which match \fIEXPR\fP in the \(lqMessage-ID\(rq field +.TP +~k +messages containing PGP key material +.TP +~l +messages addressed to a known mailing list (defined by either \fBsubscribe\fP or \fBlist\fP) +.TP +~L \fIEXPR\fP +messages either originated or received by \fIEXPR\fP +.TP +%L \fIGROUP\fP +messages either originated or received by any member of \fIGROUP\fP +.TP +~m \fIMIN\fP-\fIMAX\fP +message in the range \fIMIN\fP to \fIMAX\fP +.TP +~M \fIEXPR\fP +messages which contain a mime Content-Type matching \fIEXPR\fP +.TP +~n \fIMIN\fP-\fIMAX\fP +messages with a score in the range \fIMIN\fP to \fIMAX\fP +.TP +~N +new messages +.TP +~O +old messages +.TP +~p +messages addressed to you (consults $from, \fBalternates\fP, and local account/hostname information) +.TP +~P +messages from you (consults $from, \fBalternates\fP, and local account/hostname information) +.TP +~Q +messages which have been replied to +.TP +~r \fIMIN\fP-\fIMAX\fP +messages with \(lqdate-received\(rq in a Date range +.TP +~R +read messages +.TP +~s \fIEXPR\fP +messages having \fIEXPR\fP in the \(lqSubject\(rq field. +.TP +~S +superseded messages +.TP +~t \fIEXPR\fP +messages addressed to \fIEXPR\fP +.TP +~T +tagged messages +.TP +~u +messages addressed to a subscribed mailing list (defined by \fBsubscribe\fP commands) +.TP +~U +unread messages +.TP +~v +message is part of a collapsed thread. +.TP +~V +cryptographically verified messages +.TP +~x \fIEXPR\fP +messages which contain \fIEXPR\fP in the \(lqReferences\(rq or \(lqIn-Reply-To\(rq field +.TP +~X \fIMIN\fP-\fIMAX\fP +messages with MIN - MAX attachments +.TP +~y \fIEXPR\fP +messages which contain \fIEXPR\fP in the \(lqX-Label\(rq field +.TP +~z \fIMIN\fP-\fIMAX\fP +messages with a size in the range \fIMIN\fP to \fIMAX\fP +.TP +~= +duplicated messages (see $duplicate_threads) +.TP +~$ +unreferenced message (requires threaded view) +.TP +~(PATTERN) +messages in threads containing messages matching a certain pattern, e.g. all threads containing messages from you: ~(~P) +.TP +~<(PATTERN) +messages whose immediate parent matches PATTERN, e.g. replies to your messages: ~<(~P) +.TP +~>(PATTERN) +messages having an immediate child matching PATTERN, e.g. messages you replied to: ~>(~P) +.PD 1 +.DT +.PP +In the above, \fIEXPR\fP is a regular expression. +.PP +With the \fB~d\fP, \fB~m\fP, \fB~n\fP, \fB~r\fP, \fB~X\fP, and \fB~z\fP modifiers, you can also +specify ranges in the forms \fB<\fP\fIMAX\fP, \fB>\fP\fIMIN\fP, +\fIMIN\fP\fB-\fP, and \fB-\fP\fIMAX\fP. +.PP +With the \fB~z\fP modifier, the suffixes \(lqK\(rq and \(lqM\(rq are allowed to specify +kilobyte and megabyte respectively. +.PP +The \fB~b\fP, \fB~B\fP, \fB~h\fP, \fB~M\fP, and \fB~X\fP modifiers +require reading each message in, which can be much slower. +.PP +You can force Mutt to treat \fIEXPR\fP as a simple string instead of a +regular expression by using = instead of ~ in the pattern name. +.SS Matching dates +.PP +The \fB~d\fP and \fB~r\fP modifiers are used to match date ranges, +which are interpreted to be given in your local time zone. +.PP +A date is of the form +\fIDD\fP[\fB/\fP\fIMM\fP[\fB/\fP[\fIcc\fP]\fIYY\fP]], that is, a +two-digit date, optionally followed by a two-digit month, optionally +followed by a year specifications. Omitted fields default to the +current month and year. +.PP +Mutt understands either two or four digit year specifications. When +given a two-digit year, mutt will interpret values less than 70 as +lying in the 21st century (i.e., \(lq38\(rq means 2038 and not 1938, +and \(lq00\(rq is interpreted as 2000), and values +greater than or equal to 70 as lying in the 20th century. +.PP +Note that this behavior \fIis\fP Y2K compliant, but that mutt +\fIdoes\fP have a Y2.07K problem. +.PP +Alternatively, you may use \fIYYYYMMDD\fP to specify a date. +.PP +If a date range consists of a single date, the modifier in question +will match that precise date. If the date range consists of a dash +(\(lq\fB-\fP\(rq), followed by a date, this range will match any +date before and up to the date given. Similarly, a date followed by +a dash matches the date given and any later point of time. Two +dates, separated by a dash, match any date which lies in the given +range of time. +.PP +You can also modify any absolute date by giving an error range. An +error range consists of one of the characters +.BR + , +.BR - , +.BR * , +followed by a positive number, followed by one of the unit +characters +.BR y , +.BR m , +.BR w ", or" +.BR d , +specifying a unit of years, months, weeks, or days. +.B + +increases the maximum date matched by the given interval of time, +.B - +decreases the minimum date matched by the given interval of time, and +.B * +increases the maximum date and decreases the minimum date matched by +the given interval of time. It is possible to give multiple error +margins, which cumulate. Example: +.B "1/1/2001-1w+2w*3d" +.PP +You can also specify offsets relative to the current date. An +offset is specified as one of the characters +.BR < , +.BR > , +.BR = , +followed by a positive number, followed by one of the unit +characters +.BR y , +.BR m , +.BR w , +.BR d , +.BR H , +.BR M ", or" +.BR S . +.B > +matches dates which are older than the specified amount of time, an +offset which begins with the character +.B < +matches dates which are more recent than the specified amount of time, +and an offset which begins with the character +.B = +matches points of time which are precisely the given amount of time +ago. +.SH CONFIGURATION VARIABLES + +.TP +.B abort_noattach +.nf +Type: quadoption +Default: no +.fi +.IP +When the body of the message matches $abort_noattach_regexp and +there are no attachments, this quadoption controls whether to +abort sending the message. + + +.TP +.B abort_noattach_regexp +.nf +Type: regular expression +Default: \(lqattach\(rq +.fi +.IP +Specifies a regular expression to match against the body of the +message, to determine if an attachment was mentioned but +mistakenly forgotten. If it matches, $abort_noattach will be +consulted to determine if message sending will be aborted. +.IP +Like other regular expressions in Mutt, the search is case +sensitive if the pattern contains at least one upper case letter, +and case insensitive otherwise. + + +.TP +.B abort_nosubject +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +If set to \fIyes\fP, when composing messages and no subject is given +at the subject prompt, composition will be aborted. If set to +\fIno\fP, composing messages with no subject given at the subject +prompt will never be aborted. + + +.TP +.B abort_unmodified +.nf +Type: quadoption +Default: yes +.fi +.IP +If set to \fIyes\fP, composition will automatically abort after +editing the message body if no changes are made to the file (this +check only happens after the \fIfirst\fP edit of the file). When set +to \fIno\fP, composition will never be aborted. + + +.TP +.B alias_file +.nf +Type: path +Default: \(lq~/.muttrc\(rq +.fi +.IP +The default file in which to save aliases created by the +\fB\fP function. Entries added to this file are +encoded in the character set specified by $config_charset if it +is \fIset\fP or the current character set otherwise. +.IP +\fBNote:\fP Mutt will not automatically source this file; you must +explicitly use the \(lqsource\(rq command for it to be executed in case +this option points to a dedicated alias file. +.IP +The default for this option is the currently used muttrc file, or +\(lq~/.muttrc\(rq if no user muttrc was found. + + +.TP +.B alias_format +.nf +Type: string +Default: \(lq%4n %2f %t %\-10a %r\(rq +.fi +.IP +Specifies the format of the data displayed for the \(lqalias\(rq menu. The +following \fBprintf(3)\fP\-style sequences are available: +.RS +.PD 0 +.TP +%a +alias name +.TP +%f +flags \- currently, a \(lqd\(rq for an alias marked for deletion +.TP +%n +index number +.TP +%r +address which alias expands to +.TP +%t +character which indicates if the alias is tagged for inclusion +.RE +.PD 1 + +.TP +.B allow_8bit +.nf +Type: boolean +Default: yes +.fi +.IP +Controls whether 8\-bit data is converted to 7\-bit using either Quoted\- +Printable or Base64 encoding when sending mail. + + +.TP +.B allow_ansi +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether ANSI color codes in messages (and color tags in +rich text messages) are to be interpreted. +Messages containing these codes are rare, but if this option is \fIset\fP, +their text will be colored accordingly. Note that this may override +your color choices, and even present a security problem, since a +message could include a line like + +.IP +.EX +[\-\- PGP output follows ... + +.EE +.IP +and give it the same color as your attachment color (see also +$crypt_timestamp). + + +.TP +.B arrow_cursor +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, an arrow (\(lq\->\(rq) will be used to indicate the current entry +in menus instead of highlighting the whole line. On slow network or modem +links this will make response faster because there is less that has to +be redrawn on the screen when moving to the next or previous entries +in the menu. + + +.TP +.B ascii_chars +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, Mutt will use plain ASCII characters when displaying thread +and attachment trees, instead of the default \fIACS\fP characters. + + +.TP +.B askbcc +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, Mutt will prompt you for blind\-carbon\-copy (Bcc) recipients +before editing an outgoing message. + + +.TP +.B askcc +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, Mutt will prompt you for carbon\-copy (Cc) recipients before +editing the body of an outgoing message. + + +.TP +.B assumed_charset +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This variable is a colon\-separated list of character encoding +schemes for messages without character encoding indication. +Header field values and message body content without character encoding +indication would be assumed that they are written in one of this list. +By default, all the header fields and message body without any charset +indication are assumed to be in \(lqus\-ascii\(rq. +.IP +For example, Japanese users might prefer this: + +.IP +.EX +set assumed_charset=\(rqiso\-2022\-jp:euc\-jp:shift_jis:utf\-8\(rq + +.EE +.IP +However, only the first content is valid for the message body. + + +.TP +.B attach_charset +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This variable is a colon\-separated list of character encoding +schemes for text file attachments. Mutt uses this setting to guess +which encoding files being attached are encoded in to convert them to +a proper character set given in $send_charset. +.IP +If \fIunset\fP, the value of $charset will be used instead. +For example, the following configuration would work for Japanese +text handling: + +.IP +.EX +set attach_charset=\(rqiso\-2022\-jp:euc\-jp:shift_jis:utf\-8\(rq + +.EE +.IP +Note: for Japanese users, \(lqiso\-2022\-*\(rq must be put at the head +of the value as shown above if included. + + +.TP +.B attach_format +.nf +Type: string +Default: \(lq%u%D%I %t%4n %T%.40d%> [%.7m/%.10M, %.6e%?C?, %C?, %s] \(rq +.fi +.IP +This variable describes the format of the \(lqattachment\(rq menu. The +following \fBprintf(3)\fP\-style sequences are understood: +.RS +.PD 0 +.TP +%C +charset +.TP +%c +requires charset conversion (\(lqn\(rq or \(lqc\(rq) +.TP +%D +deleted flag +.TP +%d +description (if none, falls back to %F) +.TP +%e +MIME content\-transfer\-encoding +.TP +%F +filename in content\-disposition header (if none, falls back to %f) +.TP +%f +filename +.TP +%I +disposition (\(lqI\(rq for inline, \(lqA\(rq for attachment) +.TP +%m +major MIME type +.TP +%M +MIME subtype +.TP +%n +attachment number +.TP +%Q +\(lqQ\(rq, if MIME part qualifies for attachment counting +.TP +%s +size (see formatstrings-size) +.TP +%t +tagged flag +.TP +%T +graphic tree characters +.TP +%u +unlink (=to delete) flag +.TP +%X +number of qualifying MIME parts in this part and its children +(please see the \(lqattachments\(rq section for possible speed effects) +.TP +%>X +right justify the rest of the string and pad with character \(lqX\(rq +.TP +%|X +pad to the end of the line with character \(lqX\(rq +.TP +%*X +soft\-fill with character \(lqX\(rq as pad +.RE +.PD 1 +.IP +For an explanation of \(lqsoft\-fill\(rq, see the $index_format documentation. + + +.TP +.B attach_save_charset_convert +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +When saving received text\-type attachments, this quadoption +prompts to convert the character set if the encoding of the +attachment (or $assumed_charset if none is specified) differs +from charset. + + +.TP +.B attach_save_dir +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +The default directory to save attachments from the \(lqattachment\(rq menu. +If it doesn't exist, Mutt will prompt to create the directory before +saving. +.IP +If the path is invalid (e.g. not a directory, or cannot be +chdir'ed to), Mutt will fall back to using the current directory. + + +.TP +.B attach_sep +.nf +Type: string +Default: \(lq\\n\(rq +.fi +.IP +The separator to add between attachments when operating (saving, +printing, piping, etc) on a list of tagged attachments. + + +.TP +.B attach_split +.nf +Type: boolean +Default: yes +.fi +.IP +If this variable is \fIunset\fP, when operating (saving, printing, piping, +etc) on a list of tagged attachments, Mutt will concatenate the +attachments and will operate on them as a single attachment. The +$attach_sep separator is added after each attachment. When \fIset\fP, +Mutt will operate on the attachments one by one. + + +.TP +.B attribution +.nf +Type: string (localized) +Default: \(lqOn %d, %n wrote:\(rq +.fi +.IP +This is the string that will precede a message which has been included +in a reply. For a full listing of defined \fBprintf(3)\fP\-like sequences see +the section on $index_format. + + +.TP +.B attribution_locale +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +The locale used by \fBstrftime(3)\fP to format dates in the +attribution string. Legal values are the strings your system +accepts for the locale environment variable \fB$LC_TIME\fP. +.IP +This variable is to allow the attribution date format to be +customized by recipient or folder using hooks. By default, Mutt +will use your locale environment, so there is no need to set +this except to override that default. + + +.TP +.B auto_subscribe +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, Mutt assumes the presence of a List\-Post header +means the recipient is subscribed to the list. Unless the mailing list +is in the \(lqunsubscribe\(rq or \(lqunlist\(rq lists, it will be added +to the \(lqsubscribe\(rq list. Parsing and checking these things slows +header reading down, so this option is disabled by default. + + +.TP +.B auto_tag +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, functions in the \fIindex\fP menu which affect a message +will be applied to all tagged messages (if there are any). When +unset, you must first use the \fB\fP function (bound to \(lq;\(rq +by default) to make the next function apply to all tagged messages. + + +.TP +.B autocrypt +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, enables autocrypt, which provides +passive encryption protection with keys exchanged via headers. +See \(lqautocryptdoc\(rq for more details. +(Autocrypt only) + + +.TP +.B autocrypt_acct_format +.nf +Type: string +Default: \(lq%4n %\-30a %20p %10s\(rq +.fi +.IP +This variable describes the format of the \(lqautocrypt account\(rq menu. +The following \fBprintf(3)\fP\-style sequences are understood +.RS +.PD 0 +.TP +%a +email address +.TP +%k +gpg keyid +.TP +%n +current entry number +.TP +%p +prefer\-encrypt flag +.TP +%s +status flag (active/inactive) +.RE +.PD 1 +.IP +(Autocrypt only) + + +.TP +.B autocrypt_dir +.nf +Type: path +Default: \(lq~/.mutt/autocrypt\(rq +.fi +.IP +This variable sets where autocrypt files are stored, including the GPG +keyring and sqlite database. See \(lqautocryptdoc\(rq for more details. +(Autocrypt only) + + +.TP +.B autocrypt_reply +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, replying to an autocrypt email automatically +enables autocrypt in the reply. You may want to unset this if you're using +the same key for autocrypt as normal web\-of\-trust, so that autocrypt +isn't forced on for all encrypted replies. +(Autocrypt only) + + +.TP +.B autoedit +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP along with $edit_headers, Mutt will skip the initial +send\-menu (prompting for subject and recipients) and allow you to +immediately begin editing the body of your +message. The send\-menu may still be accessed once you have finished +editing the body of your message. +.IP +\fBNote:\fP when this option is \fIset\fP, you cannot use send\-hooks that depend +on the recipients when composing a new (non\-reply) message, as the initial +list of recipients is empty. +.IP +Also see $fast_reply. + + +.TP +.B background_edit +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, Mutt will run $editor in the background during +message composition. A landing page will display, waiting for +the $editor to exit. The landing page may be exited, allowing +perusal of the mailbox, or even for other messages to be +composed. Backgrounded sessions may be returned to via the +\fB\fP function. +.IP +For background editing to work properly, $editor must be set to +an editor that does not try to use the Mutt terminal: for example +a graphical editor, or a script launching (and waiting for) the +editor in another Gnu Screen window. +.IP +For more details, see \(lqbgedit\(rq (\(rqBackground Editing\(rq in the manual). + + +.TP +.B background_confirm_quit +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, if there are any background edit sessions, you +will be prompted to confirm exiting Mutt, in addition to the +$quit prompt. + + +.TP +.B background_format +.nf +Type: string +Default: \(lq%10S %7p %s\(rq +.fi +.IP +This variable describes the format of the \(lqbackground compose\(rq +menu. The following \fBprintf(3)\fP\-style sequences are +understood: +.RS +.PD 0 +.TP +%i +parent message id (for replies and forwarded messages) +.TP +%n +the running number on the menu +.TP +%p +pid of the $editor process +.TP +%r +comma separated list of \(lqTo:\(rq recipients +.TP +%R +comma separated list of \(lqCc:\(rq recipients +.TP +%s +subject of the message +.TP +%S +status of the $editor process: running/finished +.RE +.PD 1 + +.TP +.B beep +.nf +Type: boolean +Default: yes +.fi +.IP +When this variable is \fIset\fP, mutt will beep when an error occurs. + + +.TP +.B beep_new +.nf +Type: boolean +Default: no +.fi +.IP +When this variable is \fIset\fP, mutt will beep whenever it prints a message +notifying you of new mail. This is independent of the setting of the +$beep variable. + + +.TP +.B bounce +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +Controls whether you will be asked to confirm bouncing messages. +If set to \fIyes\fP you don't get asked if you want to bounce a +message. Setting this variable to \fIno\fP is not generally useful, +and thus not recommended, because you are unable to bounce messages. + + +.TP +.B bounce_delivered +.nf +Type: boolean +Default: yes +.fi +.IP +When this variable is \fIset\fP, mutt will include Delivered\-To headers when +bouncing messages. Postfix users may wish to \fIunset\fP this variable. + + +.TP +.B braille_friendly +.nf +Type: boolean +Default: no +.fi +.IP +When this variable is \fIset\fP, mutt will place the cursor at the beginning +of the current line in menus, even when the $arrow_cursor variable +is \fIunset\fP, making it easier for blind persons using Braille displays to +follow these menus. The option is \fIunset\fP by default because many +visual terminals don't permit making the cursor invisible. + + +.TP +.B browser_abbreviate_mailboxes +.nf +Type: boolean +Default: yes +.fi +.IP +When this variable is \fIset\fP, mutt will abbreviate mailbox +names in the browser mailbox list, using '~' and '=' +shortcuts. +.IP +The default \fB\(rqalpha\(rq\fP setting of $sort_browser uses +locale\-based sorting (using \fBstrcoll(3)\fP), which ignores some +punctuation. This can lead to some situations where the order +doesn't make intuitive sense. In those cases, it may be +desirable to \fIunset\fP this variable. + + +.TP +.B browser_sticky_cursor +.nf +Type: boolean +Default: yes +.fi +.IP +When this variable is \fIset\fP, the browser will attempt to keep +the cursor on the same mailbox when performing various functions. +These include moving up a directory, toggling between mailboxes +and directory listing, creating/renaming a mailbox, toggling +subscribed mailboxes, and entering a new mask. + + +.TP +.B certificate_file +.nf +Type: path +Default: \(lq~/.mutt_certificates\(rq +.fi +.IP +This variable specifies the file where the certificates you trust +are saved. When an unknown certificate is encountered, you are asked +if you accept it or not. If you accept it, the certificate can also +be saved in this file and further connections are automatically +accepted. +.IP +You can also manually add CA certificates in this file. Any server +certificate that is signed with one of these CA certificates is +also automatically accepted. +.IP +Example: + +.IP +.EX +set certificate_file=~/.mutt/certificates + +.EE +.IP +(OpenSSL and GnuTLS only) + + +.TP +.B change_folder_next +.nf +Type: boolean +Default: no +.fi +.IP +When this variable is \fIset\fP, the \fB\fP function +mailbox suggestion will start at the next folder in your \(lqmailboxes\(rq +list, instead of starting at the first folder in the list. + + +.TP +.B charset +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Character set your terminal uses to display and enter textual data. +It is also the fallback for $send_charset. +.IP +Upon startup Mutt tries to derive this value from environment variables +such as \fB$LC_CTYPE\fP or \fB$LANG\fP. +.IP +\fBNote:\fP It should only be set in case Mutt isn't able to determine the +character set used correctly. + + +.TP +.B check_mbox_size +.nf +Type: boolean +Default: no +.fi +.IP +When this variable is \fIset\fP, mutt will use file size attribute instead of +access time when checking for new mail in mbox and mmdf folders. +.IP +This variable is \fIunset\fP by default and should only be enabled when +new mail detection for these folder types is unreliable or doesn't work. +.IP +Note that enabling this variable should happen before any \(lqmailboxes\(rq +directives occur in configuration files regarding mbox or mmdf folders +because mutt needs to determine the initial new mail status of such a +mailbox by performing a fast mailbox scan when it is defined. +Afterwards the new mail status is tracked by file size changes. + + +.TP +.B check_new +.nf +Type: boolean +Default: yes +.fi +.IP +\fBNote:\fP this option only affects \fImaildir\fP and \fIMH\fP style +mailboxes. +.IP +When \fIset\fP, Mutt will check for new mail delivered while the +mailbox is open. Especially with MH mailboxes, this operation can +take quite some time since it involves scanning the directory and +checking each file to see if it has already been looked at. If +this variable is \fIunset\fP, no check for new mail is performed +while the mailbox is open. + + +.TP +.B collapse_unread +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIunset\fP, Mutt will not collapse a thread if it contains any +unread messages. + + +.TP +.B compose_confirm_detach_first +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will prompt for confirmation when trying to +use \fB\fP on the first entry in the compose menu. +This is to help prevent irreversible loss of the typed message by +accidentally hitting 'D' in the menu. +.IP +Note: Mutt only prompts for the first entry. It doesn't keep +track of which message is the typed message if the entries are +reordered, or if the first entry was already deleted. + + +.TP +.B compose_format +.nf +Type: string (localized) +Default: \(lq\-\- Mutt: Compose [Approx. msg size: %l Atts: %a]%>\-\(rq +.fi +.IP +Controls the format of the status line displayed in the \(lqcompose\(rq +menu. This string is similar to $status_format, but has its own +set of \fBprintf(3)\fP\-like sequences: +.RS +.PD 0 +.TP +%a +total number of attachments +.TP +%h +local hostname +.TP +%l +approximate size (in bytes) of the current message (see formatstrings-size) +.TP +%v +Mutt version string +.RE +.PD 1 +.IP +See the text describing the $status_format option for more +information on how to set $compose_format. + + +.TP +.B config_charset +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +When defined, Mutt will recode commands in rc files from this +encoding to the current character set as specified by $charset +and aliases written to $alias_file from the current character set. +.IP +Please note that if setting $charset it must be done before +setting $config_charset. +.IP +Recoding should be avoided as it may render unconvertable +characters as question marks which can lead to undesired +side effects (for example in regular expressions). + + +.TP +.B confirmappend +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will prompt for confirmation when appending messages to +an existing mailbox. + + +.TP +.B confirmcreate +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will prompt for confirmation when saving messages to a +mailbox which does not yet exist before creating it. + + +.TP +.B connect_timeout +.nf +Type: number +Default: 30 +.fi +.IP +Causes Mutt to timeout a network connection (for IMAP, POP or SMTP) after this +many seconds if the connection is not able to be established. A negative +value causes Mutt to wait indefinitely for the connection attempt to succeed. + + +.TP +.B content_type +.nf +Type: string +Default: \(lqtext/plain\(rq +.fi +.IP +Sets the default Content\-Type for the body of newly composed messages. + + +.TP +.B copy +.nf +Type: quadoption +Default: yes +.fi +.IP +This variable controls whether or not copies of your outgoing messages +will be saved for later references. Also see $record, +$save_name, $force_name and \(lqfcc-hook\(rq. + + +.TP +.B copy_decode_weed +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether Mutt will weed headers when invoking the +\fB\fP or \fB\fP functions. + + +.TP +.B count_alternatives +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, Mutt will recurse inside multipart/alternatives while +performing attachment searching and counting (see attachments). +.IP +Traditionally, multipart/alternative parts have simply represented +different encodings of the main content of the email. Unfortunately, +some mail clients have started to place email attachments inside +one of alternatives. Setting this will allow Mutt to find +and count matching attachments hidden there, and include them +in the index via %X or through ~X pattern matching. + + +.TP +.B cursor_overlay +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, Mutt will overlay the indicator, tree, +sidebar_highlight, and sidebar_indicator colors onto the currently +selected line. This will allow \fBdefault\fP colors in those +to be overridden, and for attributes to be merged between +the layers. + + +.TP +.B crypt_autoencrypt +.nf +Type: boolean +Default: no +.fi +.IP +Setting this variable will cause Mutt to always attempt to PGP +encrypt outgoing messages. This is probably only useful in +connection to the \(lqsend-hook\(rq command. It can be overridden +by use of the pgp menu, when encryption is not required or +signing is requested as well. If $smime_is_default is \fIset\fP, +then OpenSSL is used instead to create S/MIME messages and +settings can be overridden by use of the smime menu instead. +(Crypto only) + + +.TP +.B crypt_autopgp +.nf +Type: boolean +Default: yes +.fi +.IP +This variable controls whether or not mutt may automatically enable +PGP encryption/signing for messages. See also $crypt_autoencrypt, +$crypt_replyencrypt, +$crypt_autosign, $crypt_replysign and $smime_is_default. + + +.TP +.B crypt_autosign +.nf +Type: boolean +Default: no +.fi +.IP +Setting this variable will cause Mutt to always attempt to +cryptographically sign outgoing messages. This can be overridden +by use of the pgp menu, when signing is not required or +encryption is requested as well. If $smime_is_default is \fIset\fP, +then OpenSSL is used instead to create S/MIME messages and settings can +be overridden by use of the smime menu instead of the pgp menu. +(Crypto only) + + +.TP +.B crypt_autosmime +.nf +Type: boolean +Default: yes +.fi +.IP +This variable controls whether or not mutt may automatically enable +S/MIME encryption/signing for messages. See also $crypt_autoencrypt, +$crypt_replyencrypt, +$crypt_autosign, $crypt_replysign and $smime_is_default. + + +.TP +.B crypt_confirmhook +.nf +Type: boolean +Default: yes +.fi +.IP +If set, then you will be prompted for confirmation of keys when using +the \fIcrypt\-hook\fP command. If unset, no such confirmation prompt will +be presented. This is generally considered unsafe, especially where +typos are concerned. + + +.TP +.B crypt_opportunistic_encrypt +.nf +Type: boolean +Default: no +.fi +.IP +Setting this variable will cause Mutt to automatically enable and +disable encryption, based on whether all message recipient keys +can be located by Mutt. +.IP +When this option is enabled, Mutt will enable/disable encryption +each time the TO, CC, and BCC lists are edited. If +$edit_headers is set, Mutt will also do so each time the message +is edited. +.IP +While this is set, encryption can't be manually enabled/disabled. +The pgp or smime menus provide a selection to temporarily disable +this option for the current message. +.IP +If $crypt_autoencrypt or $crypt_replyencrypt enable encryption for +a message, this option will be disabled for that message. It can +be manually re\-enabled in the pgp or smime menus. +(Crypto only) + + +.TP +.B crypt_opportunistic_encrypt_strong_keys +.nf +Type: boolean +Default: no +.fi +.IP +When set, this modifies the behavior of $crypt_opportunistic_encrypt +to only search for \(rqstrong keys\(rq, that is, keys with full validity +according to the web\-of\-trust algorithm. A key with marginal or no +validity will not enable opportunistic encryption. +.IP +For S/MIME, the behavior depends on the backend. Classic S/MIME will +filter for certificates with the 't' (trusted) flag in the .index file. +The GPGME backend will use the same filters as with OpenPGP, and depends +on GPGME's logic for assigning the GPGME_VALIDITY_FULL and +GPGME_VALIDITY_ULTIMATE validity flag. + + +.TP +.B crypt_protected_headers_read +.nf +Type: boolean +Default: yes +.fi +.IP +When set, Mutt will display protected headers in the pager, +and will update the index and header cache with revised headers. +Protected headers are stored inside the encrypted or signed part of an +an email, to prevent disclosure or tampering. +For more information see https://github.com/autocrypt/protected\-headers. +Currently Mutt only supports the Subject header. +.IP +Encrypted messages using protected headers often substitute the exposed +Subject header with a dummy value (see $crypt_protected_headers_subject). +Mutt will update its concept of the correct subject \fBafter\fP the +message is opened, i.e. via the \fB\fP function. +If you reply to a message before opening it, Mutt will end up using +the dummy Subject header, so be sure to open such a message first. +(Crypto only) + + +.TP +.B crypt_protected_headers_save +.nf +Type: boolean +Default: no +.fi +.IP +When $crypt_protected_headers_read is set, and a message with a +protected Subject is opened, Mutt will save the updated Subject +into the header cache by default. This allows searching/limiting +based on the protected Subject header if the mailbox is +re\-opened, without having to re\-open the message each time. +However, for mbox/mh mailbox types, or if header caching is not +set up, you would need to re\-open the message each time the +mailbox was reopened before you could see or search/limit on the +protected subject again. +.IP +When this variable is set, Mutt additionally saves the protected +Subject back \fBin the clear\-text message headers\fP. This +provides better usability, but with the tradeoff of reduced +security. The protected Subject header, which may have +previously been encrypted, is now stored in clear\-text in the +message headers. Copying the message elsewhere, via Mutt or +external tools, could expose this previously encrypted data. +Please make sure you understand the consequences of this before +you enable this variable. +(Crypto only) + + +.TP +.B crypt_protected_headers_subject +.nf +Type: string +Default: \(lq...\(rq +.fi +.IP +When $crypt_protected_headers_write is set, and the message is marked +for encryption, this will be substituted into the Subject field in the +message headers. +To prevent a subject from being substituted, unset this variable, or set it +to the empty string. +(Crypto only) + + +.TP +.B crypt_protected_headers_write +.nf +Type: boolean +Default: no +.fi +.IP +When set, Mutt will generate protected headers for signed and +encrypted emails. +Protected headers are stored inside the encrypted or signed part of an +an email, to prevent disclosure or tampering. +For more information see https://github.com/autocrypt/protected\-headers. +Currently Mutt only supports the Subject header. +(Crypto only) + + +.TP +.B crypt_replyencrypt +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, automatically PGP or OpenSSL encrypt replies to messages which are +encrypted. +(Crypto only) + + +.TP +.B crypt_replysign +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, automatically PGP or OpenSSL sign replies to messages which are +signed. +.IP +\fBNote:\fP this does not work on messages that are encrypted +\fIand\fP signed! +(Crypto only) + + +.TP +.B crypt_replysignencrypted +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, automatically PGP or OpenSSL sign replies to messages +which are encrypted. This makes sense in combination with +$crypt_replyencrypt, because it allows you to sign all +messages which are automatically encrypted. This works around +the problem noted in $crypt_replysign, that mutt is not able +to find out whether an encrypted message is also signed. +(Crypto only) + + +.TP +.B crypt_timestamp +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, mutt will include a time stamp in the lines surrounding +PGP or S/MIME output, so spoofing such lines is more difficult. +If you are using colors to mark these lines, and rely on these, +you may \fIunset\fP this setting. +(Crypto only) + + +.TP +.B crypt_use_gpgme +.nf +Type: boolean +Default: no +.fi +.IP +This variable controls the use of the GPGME\-enabled crypto backends. +If it is \fIset\fP and Mutt was built with gpgme support, the gpgme code for +S/MIME and PGP will be used instead of the classic code. Note that +you need to set this option in .muttrc; it won't have any effect when +used interactively. +.IP +Note that the GPGME backend does not support creating old\-style inline +(traditional) PGP encrypted or signed messages (see $pgp_autoinline). + + +.TP +.B crypt_use_pka +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether mutt uses PKA +(see http://www.g10code.de/docs/pka\-intro.de.pdf) during signature +verification (only supported by the GPGME backend). + + +.TP +.B crypt_verify_sig +.nf +Type: quadoption +Default: yes +.fi +.IP +If \fI\(lqyes\(rq\fP, always attempt to verify PGP or S/MIME signatures. +If \fI\(lqask\-*\(rq\fP, ask whether or not to verify the signature. +If \fI\(lqno\(rq\fP, never attempt to verify cryptographic signatures. +(Crypto only) + + +.TP +.B date_format +.nf +Type: string +Default: \(lq!%a, %b %d, %Y at %I:%M:%S%p %Z\(rq +.fi +.IP +This variable controls the format of the date printed by the \(lq%d\(rq +sequence in $index_format. This is passed to the \fBstrftime(3)\fP +function to process the date, see the man page for the proper syntax. +.IP +Unless the first character in the string is a bang (\(lq!\(rq), the month +and week day names are expanded according to the locale. +If the first character in the string is a +bang, the bang is discarded, and the month and week day names in the +rest of the string are expanded in the \fIC\fP locale (that is in US +English). + + +.TP +.B default_hook +.nf +Type: string +Default: \(lq~f %s !~P | (~P ~C %s)\(rq +.fi +.IP +This variable controls how \(lqmessage-hook\(rq, \(lqreply-hook\(rq, \(lqsend-hook\(rq, +\(lqsend2-hook\(rq, \(lqsave-hook\(rq, and \(lqfcc-hook\(rq will +be interpreted if they are specified with only a simple regexp, +instead of a matching pattern. The hooks are expanded when they are +declared, so a hook will be interpreted according to the value of this +variable at the time the hook is declared. +.IP +The default value matches +if the message is either from a user matching the regular expression +given, or if it is from you (if the from address matches +\(lqalternates\(rq) and is to or cc'ed to a user matching the given +regular expression. + + +.TP +.B delete +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +Controls whether or not messages are really deleted when closing or +synchronizing a mailbox. If set to \fIyes\fP, messages marked for +deleting will automatically be purged without prompting. If set to +\fIno\fP, messages marked for deletion will be kept in the mailbox. +.IP +This option is ignored for maildir\-style mailboxes when $maildir_trash +is set. + + +.TP +.B delete_untag +.nf +Type: boolean +Default: yes +.fi +.IP +If this option is \fIset\fP, mutt will untag messages when marking them +for deletion. This applies when you either explicitly delete a message, +or when you save it to another folder. + + +.TP +.B digest_collapse +.nf +Type: boolean +Default: yes +.fi +.IP +If this option is \fIset\fP, mutt's received\-attachments menu will not show the subparts of +individual messages in a multipart/digest. To see these subparts, press \(lqv\(rq on that menu. + + +.TP +.B display_filter +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +When set, specifies a command used to filter messages. When a message +is viewed it is passed as standard input to $display_filter, and the +filtered message is read from the standard output. + + +.TP +.B dotlock_program +.nf +Type: path +Default: \(lq/usr/bin/mutt_dotlock\(rq +.fi +.IP +Contains the path of the \fBmutt_dotlock(1)\fP binary to be used by +mutt. + + +.TP +.B dsn_notify +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This variable sets the request for when notification is returned. The +string consists of a comma separated list (no spaces!) of one or more +of the following: \fInever\fP, to never request notification, +\fIfailure\fP, to request notification on transmission failure, +\fIdelay\fP, to be notified of message delays, \fIsuccess\fP, to be +notified of successful transmission. +.IP +Example: + +.IP +.EX +set dsn_notify=\(rqfailure,delay\(rq + +.EE +.IP +\fBNote:\fP when using $sendmail for delivery, you should not enable +this unless you are either using Sendmail 8.8.x or greater or a MTA +providing a \fBsendmail(1)\fP\-compatible interface supporting the \fB\-N\fP option +for DSN. For SMTP delivery, DSN support is auto\-detected so that it +depends on the server whether DSN will be used or not. + + +.TP +.B dsn_return +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This variable controls how much of your message is returned in DSN +messages. It may be set to either \fIhdrs\fP to return just the +message header, or \fIfull\fP to return the full message. +.IP +Example: + +.IP +.EX +set dsn_return=hdrs + +.EE +.IP +\fBNote:\fP when using $sendmail for delivery, you should not enable +this unless you are either using Sendmail 8.8.x or greater or a MTA +providing a \fBsendmail(1)\fP\-compatible interface supporting the \fB\-R\fP option +for DSN. For SMTP delivery, DSN support is auto\-detected so that it +depends on the server whether DSN will be used or not. + + +.TP +.B duplicate_threads +.nf +Type: boolean +Default: yes +.fi +.IP +This variable controls whether mutt, when $sort is set to \fIthreads\fP, threads +messages with the same Message\-Id together. If it is \fIset\fP, it will indicate +that it thinks they are duplicates of each other with an equals sign +in the thread tree. + + +.TP +.B edit_headers +.nf +Type: boolean +Default: no +.fi +.IP +This option allows you to edit the header of your outgoing messages +along with the body of your message. +.IP +Although the compose menu may have localized header labels, the +labels passed to your editor will be standard RFC 2822 headers, +(e.g. To:, Cc:, Subject:). Headers added in your editor must +also be RFC 2822 headers, or one of the pseudo headers listed in +\(lqedit-header\(rq. Mutt will not understand localized header +labels, just as it would not when parsing an actual email. +.IP +\fBNote\fP that changes made to the References: and Date: headers are +ignored for interoperability reasons. + + +.TP +.B editor +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +This variable specifies which editor is used by mutt. +It defaults to the value of the \fB$VISUAL\fP, or \fB$EDITOR\fP, environment +variable, or to the string \(lqvi\(rq if neither of those are set. +.IP +The \fB$editor\fP string may contain a \fI%s\fP escape, which will be replaced by the name +of the file to be edited. If the \fI%s\fP escape does not appear in \fB$editor\fP, a +space and the name to be edited are appended. +.IP +The resulting string is then executed by running + +.IP +.EX +sh \-c 'string' + +.EE +.IP +where \fIstring\fP is the expansion of \fB$editor\fP described above. + + +.TP +.B encode_from +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will quoted\-printable encode messages when +they contain the string \(lqFrom \(rq (note the trailing space) in the beginning of a line. +This is useful to avoid the tampering certain mail delivery and transport +agents tend to do with messages (in order to prevent tools from +misinterpreting the line as a mbox message separator). + + +.TP +.B entropy_file +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +The file which includes random data that is used to initialize SSL +library functions. (OpenSSL only) + + +.TP +.B envelope_from_address +.nf +Type: e-mail address +Default: \(lq\(rq +.fi +.IP +Manually sets the \fIenvelope\fP sender for outgoing messages. +This value is ignored if $use_envelope_from is \fIunset\fP. + + +.TP +.B error_history +.nf +Type: number +Default: 30 +.fi +.IP +This variable controls the size (in number of strings remembered) +of the error messages displayed by mutt. These can be shown with +the \fB\fP function. The history is cleared each +time this variable is set. + + +.TP +.B escape +.nf +Type: string +Default: \(lq~\(rq +.fi +.IP +Escape character to use for functions in the built\-in editor. + + +.TP +.B fast_reply +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, the initial prompt for recipients and subject are skipped +when replying to messages, and the initial prompt for subject is +skipped when forwarding messages. +.IP +\fBNote:\fP this variable has no effect when the $autoedit +variable is \fIset\fP. + + +.TP +.B fcc_attach +.nf +Type: quadoption +Default: yes +.fi +.IP +This variable controls whether or not attachments on outgoing messages +are saved along with the main body of your message. +.IP +Note: $fcc_before_send forces the default (set) behavior of this option. + + +.TP +.B fcc_before_send +.nf +Type: boolean +Default: no +.fi +.IP +When this variable is \fIset\fP, FCCs will occur before sending +the message. Before sending, the message cannot be manipulated, +so it will be stored the exact same as sent: +$fcc_attach and $fcc_clear will be ignored (using their default +values). +.IP +When \fIunset\fP, the default, FCCs will occur after sending. +Variables $fcc_attach and $fcc_clear will be respected, allowing +it to be stored without attachments or encryption/signing if +desired. + + +.TP +.B fcc_clear +.nf +Type: boolean +Default: no +.fi +.IP +When this variable is \fIset\fP, FCCs will be stored unencrypted and +unsigned, even when the actual message is encrypted and/or +signed. +.IP +Note: $fcc_before_send forces the default (unset) behavior of this option. +(PGP only) +.IP +See also $pgp_self_encrypt, $smime_self_encrypt. + + +.TP +.B fcc_delimiter +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +When specified, this allows the ability to Fcc to more than one +mailbox. The fcc value will be split by this delimiter and Mutt +will evaluate each part as a mailbox separately. +.IP +See $record, \(lqfcc-hook\(rq, and \(lqfcc-save-hook\(rq. + + +.TP +.B flag_safe +.nf +Type: boolean +Default: no +.fi +.IP +If set, flagged messages cannot be deleted. + + +.TP +.B folder +.nf +Type: path +Default: \(lq~/Mail\(rq +.fi +.IP +Specifies the default location of your mailboxes. A \(lq+\(rq or \(lq=\(rq at the +beginning of a pathname will be expanded to the value of this +variable. Note that if you change this variable (from the default) +value you need to make sure that the assignment occurs \fIbefore\fP +you use \(lq+\(rq or \(lq=\(rq for any other variables since expansion takes place +when handling the \(lqmailboxes\(rq command. + + +.TP +.B folder_format +.nf +Type: string +Default: \(lq%2C %t %N %F %2l %\-8.8u %\-8.8g %8s %d %f\(rq +.fi +.IP +This variable allows you to customize the file browser display to your +personal taste. This string is similar to $index_format, but has +its own set of \fBprintf(3)\fP\-like sequences: +.RS +.PD 0 +.TP +%C +current file number +.TP +%d +date/time folder was last modified +.TP +%D +date/time folder was last modified using $date_format. +.TP +%f +filename (\(lq/\(rq is appended to directory names, +\(lq@\(rq to symbolic links and \(lq*\(rq to executable +files) +.TP +%F +file permissions +.TP +%g +group name (or numeric gid, if missing) +.TP +%l +number of hard links +.TP +%m +number of messages in the mailbox * +.TP +%n +number of unread messages in the mailbox * +.TP +%N +N if mailbox has new mail, blank otherwise +.TP +%s +size in bytes (see formatstrings-size) +.TP +%t +\(lq*\(rq if the file is tagged, blank otherwise +.TP +%u +owner name (or numeric uid, if missing) +.TP +%>X +right justify the rest of the string and pad with character \(lqX\(rq +.TP +%|X +pad to the end of the line with character \(lqX\(rq +.TP +%*X +soft\-fill with character \(lqX\(rq as pad +.RE +.PD 1 +.IP +For an explanation of \(lqsoft\-fill\(rq, see the $index_format documentation. +.IP +* = can be optionally printed if nonzero +.IP +%m, %n, and %N only work for monitored mailboxes. +%m requires $mail_check_stats to be set. +%n requires $mail_check_stats to be set (except for IMAP mailboxes). + + +.TP +.B followup_to +.nf +Type: boolean +Default: yes +.fi +.IP +Controls whether or not the \(lqMail\-Followup\-To:\(rq header field is +generated when sending mail. When \fIset\fP, Mutt will generate this +field when you are replying to a known mailing list, specified with +the \(lqsubscribe\(rq or \(lqlists\(rq commands. +.IP +This field has two purposes. First, preventing you from +receiving duplicate copies of replies to messages which you send +to mailing lists, and second, ensuring that you do get a reply +separately for any messages sent to known lists to which you are +not subscribed. +.IP +The header will contain only the list's address +for subscribed lists, and both the list address and your own +email address for unsubscribed lists. Without this header, a +group reply to your message sent to a subscribed list will be +sent to both the list and your address, resulting in two copies +of the same email for you. + + +.TP +.B force_name +.nf +Type: boolean +Default: no +.fi +.IP +This variable is similar to $save_name, except that Mutt will +store a copy of your outgoing message by the username of the address +you are sending to even if that mailbox does not exist. +.IP +Also see the $record variable. + + +.TP +.B forward_attachments +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +When forwarding inline (i.e. $mime_forward \fIunset\fP or +answered with \(lqno\(rq and $forward_decode \fIset\fP), attachments +which cannot be decoded in a reasonable manner will be attached +to the newly composed message if this quadoption is \fIset\fP or +answered with \(lqyes\(rq. + + +.TP +.B forward_attribution_intro +.nf +Type: string (localized) +Default: \(lq\-\-\-\-\- Forwarded message from %f \-\-\-\-\-\(rq +.fi +.IP +This is the string that will precede a message which has been forwarded +in the main body of a message (when $mime_forward is unset). +For a full listing of defined \fBprintf(3)\fP\-like sequences see +the section on $index_format. See also $attribution_locale. + + +.TP +.B forward_attribution_trailer +.nf +Type: string (localized) +Default: \(lq\-\-\-\-\- End forwarded message \-\-\-\-\-\(rq +.fi +.IP +This is the string that will follow a message which has been forwarded +in the main body of a message (when $mime_forward is unset). +For a full listing of defined \fBprintf(3)\fP\-like sequences see +the section on $index_format. See also $attribution_locale. + + +.TP +.B forward_decode +.nf +Type: boolean +Default: yes +.fi +.IP +Controls the decoding of complex MIME messages into \fBtext/plain\fP when +forwarding a message. The message header is also RFC2047 decoded. +This variable is only used, if $mime_forward is \fIunset\fP, +otherwise $mime_forward_decode is used instead. + + +.TP +.B forward_decrypt +.nf +Type: quadoption +Default: yes +.fi +.IP +This quadoption controls the handling of encrypted messages when +forwarding or attaching a message. When set to or answered +\(lqyes\(rq, the outer layer of encryption is stripped off. +.IP +This variable is used if $mime_forward is \fIset\fP and +$mime_forward_decode is \fIunset\fP. It is also used when +attaching a message via \fB\fP in the compose +menu. (PGP only) + + +.TP +.B forward_edit +.nf +Type: quadoption +Default: yes +.fi +.IP +This quadoption controls whether or not the user is automatically +placed in the editor when forwarding messages. For those who always want +to forward with no modification, use a setting of \(lqno\(rq. + + +.TP +.B forward_format +.nf +Type: string +Default: \(lq[%a: %s]\(rq +.fi +.IP +This variable controls the default subject when forwarding a message. +It uses the same format sequences as the $index_format variable. + + +.TP +.B forward_quote +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, forwarded messages included in the main body of the +message (when $mime_forward is \fIunset\fP) will be quoted using +$indent_string. + + +.TP +.B from +.nf +Type: e-mail address +Default: \(lq\(rq +.fi +.IP +When \fIset\fP, this variable contains a default from address. It +can be overridden using \(lqmy_hdr\(rq (including from a \(lqsend-hook\(rq) and +$reverse_name. This variable is ignored if $use_from is \fIunset\fP. +.IP +This setting defaults to the contents of the environment variable \fB$EMAIL\fP. + + +.TP +.B gecos_mask +.nf +Type: regular expression +Default: \(lq^[^,]*\(rq +.fi +.IP +A regular expression used by mutt to parse the GECOS field of a password +entry when expanding the alias. The default value +will return the string up to the first \(lq,\(rq encountered. +If the GECOS field contains a string like \(lqlastname, firstname\(rq then you +should set it to \(lq\fB.*\fP\(rq. +.IP +This can be useful if you see the following behavior: you address an e\-mail +to user ID \(lqstevef\(rq whose full name is \(lqSteve Franklin\(rq. If mutt expands +\(lqstevef\(rq to \(lq\(rqFranklin\(rq stevef@foo.bar\(rq then you should set the $gecos_mask to +a regular expression that will match the whole name so mutt will expand +\(lqFranklin\(rq to \(lqFranklin, Steve\(rq. + + +.TP +.B hdrs +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIunset\fP, the header fields normally added by the \(lqmy_hdr\(rq +command are not created. This variable \fImust\fP be unset before +composing a new message or replying in order to take effect. If \fIset\fP, +the user defined header fields are added to every new message. + + +.TP +.B header +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, this variable causes Mutt to include the header +of the message you are replying to into the edit buffer. +The $weed setting applies. + + +.TP +.B header_cache +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +This variable points to the header cache database. +If pointing to a directory Mutt will contain a header cache +database file per folder, if pointing to a file that file will +be a single global header cache. By default it is \fIunset\fP so no header +caching will be used. If pointing to a directory, it must be +created in advance. +.IP +Header caching can greatly improve speed when opening POP, IMAP +MH or Maildir folders, see \(lqcaching\(rq for details. + + +.TP +.B header_cache_compress +.nf +Type: boolean +Default: yes +.fi +.IP +When mutt is compiled with qdbm, tokyocabinet, or kyotocabinet as header +cache backend, this option determines whether the database will be compressed. +Compression results in database files roughly being one fifth +of the usual diskspace, but the decompression can result in a +slower opening of cached folder(s) which in general is still +much faster than opening non header cached folders. + + +.TP +.B header_cache_pagesize +.nf +Type: number (long) +Default: 16384 +.fi +.IP +When mutt is compiled with either gdbm or bdb4 as the header cache backend, +this option changes the database page size. Too large or too small +values can waste space, memory, or CPU time. The default should be more +or less optimal for most use cases. + + +.TP +.B header_color_partial +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, color header regexps behave like color body regexps: +color is applied to the exact text matched by the regexp. When +\fIunset\fP, color is applied to the entire header. +.IP +One use of this option might be to apply color to just the header labels. +.IP +See \(lqcolor\(rq for more details. + + +.TP +.B help +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, help lines describing the bindings for the major functions +provided by each menu are displayed on the first line of the screen. +.IP +\fBNote:\fP The binding will not be displayed correctly if the +function is bound to a sequence rather than a single keystroke. Also, +the help line may not be updated if a binding is changed while Mutt is +running. Since this variable is primarily aimed at new users, neither +of these should present a major problem. + + +.TP +.B hidden_host +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will skip the host name part of $hostname variable +when adding the domain part to addresses. This variable does not +affect the generation of Message\-IDs, and it will not lead to the +cut\-off of first\-level domains. + + +.TP +.B hide_limited +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will not show the presence of messages that are hidden +by limiting, in the thread tree. + + +.TP +.B hide_missing +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will not show the presence of missing messages in the +thread tree. + + +.TP +.B hide_thread_subject +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will not show the subject of messages in the thread +tree that have the same subject as their parent or closest previously +displayed sibling. + + +.TP +.B hide_top_limited +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will not show the presence of messages that are hidden +by limiting, at the top of threads in the thread tree. Note that when +$hide_limited is \fIset\fP, this option will have no effect. + + +.TP +.B hide_top_missing +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will not show the presence of missing messages at the +top of threads in the thread tree. Note that when $hide_missing is +\fIset\fP, this option will have no effect. + + +.TP +.B history +.nf +Type: number +Default: 10 +.fi +.IP +This variable controls the size (in number of strings remembered) of +the string history buffer per category. The buffer is cleared each time the +variable is set. + + +.TP +.B history_file +.nf +Type: path +Default: \(lq~/.mutthistory\(rq +.fi +.IP +The file in which Mutt will save its history. +.IP +Also see $save_history. + + +.TP +.B history_remove_dups +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, all of the string history will be scanned for duplicates +when a new entry is added. Duplicate entries in the $history_file will +also be removed when it is periodically compacted. + + +.TP +.B honor_disposition +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, Mutt will not display attachments with a +disposition of \(lqattachment\(rq inline even if it could +render the part to plain text. These MIME parts can only +be viewed from the attachment menu. +.IP +If \fIunset\fP, Mutt will render all MIME parts it can +properly transform to plain text. + + +.TP +.B honor_followup_to +.nf +Type: quadoption +Default: yes +.fi +.IP +This variable controls whether or not a Mail\-Followup\-To header is +honored when group\-replying to a message. + + +.TP +.B hostname +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Specifies the fully\-qualified hostname of the system mutt is running on +containing the host's name and the DNS domain it belongs to. It is used +as the domain part (after \(lq@\(rq) for local email addresses as well as +Message\-Id headers. +.IP +Its value is determined at startup as follows: the node's +hostname is first determined by the \fBuname(3)\fP function. The +domain is then looked up using the \fBgethostname(2)\fP and +\fBgetaddrinfo(3)\fP functions. If those calls are unable to +determine the domain, the full value returned by uname is used. +Optionally, Mutt can be compiled with a fixed domain name in +which case a detected one is not used. +.IP +Starting in Mutt 2.0, the operations described in the previous +paragraph are performed after the muttrc is processed, instead of +beforehand. This way, if the DNS operations are creating delays +at startup, you can avoid those by manually setting the value in +your muttrc. +.IP +Also see $use_domain and $hidden_host. + + +.TP +.B idn_decode +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will show you international domain names decoded. +Note: You can use IDNs for addresses even if this is \fIunset\fP. +This variable only affects decoding. (IDN only) + + +.TP +.B idn_encode +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will encode international domain names using +IDN. Unset this if your SMTP server can handle newer (RFC 6531) +UTF\-8 encoded domains. (IDN only) + + +.TP +.B ignore_linear_white_space +.nf +Type: boolean +Default: no +.fi +.IP +This option replaces linear\-white\-space between encoded\-word +and text to a single space to prevent the display of MIME\-encoded +\(lqSubject:\(rq field from being divided into multiple lines. + + +.TP +.B ignore_list_reply_to +.nf +Type: boolean +Default: no +.fi +.IP +Affects the behavior of the \fB\fP function when replying to +messages from mailing lists (as defined by the \(lqsubscribe\(rq or +\(lqlists\(rq commands). When \fIset\fP, if the \(lqReply\-To:\(rq field is +set to the same value as the \(lqTo:\(rq field, Mutt assumes that the +\(lqReply\-To:\(rq field was set by the mailing list to automate responses +to the list, and will ignore this field. To direct a response to the +mailing list when this option is \fIset\fP, use the \fB\fP +function; \fB\fP will reply to both the sender and the +list. + + +.TP +.B imap_authenticators +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This is a colon\-delimited list of authentication methods mutt may +attempt to use to log in to an IMAP server, in the order mutt should +try them. Authentication methods are either \(lqlogin\(rq or the right +side of an IMAP \(lqAUTH=xxx\(rq capability string, e.g. \(lqdigest\-md5\(rq, \(lqgssapi\(rq +or \(lqcram\-md5\(rq. This option is case\-insensitive. If it's +\fIunset\fP (the default) mutt will try all available methods, +in order from most\-secure to least\-secure. +.IP +Example: + +.IP +.EX +set imap_authenticators=\(rqgssapi:cram\-md5:login\(rq + +.EE +.IP +\fBNote:\fP Mutt will only fall back to other authentication methods if +the previous methods are unavailable. If a method is available but +authentication fails, mutt will not connect to the IMAP server. + + +.TP +.B imap_check_subscribed +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will fetch the set of subscribed folders from +your server on connection, and add them to the set of mailboxes +it polls for new mail just as if you had issued individual \(lqmailboxes\(rq +commands. + + +.TP +.B imap_condstore +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will use the CONDSTORE extension (RFC 7162) +if advertised by the server. Mutt's current implementation is basic, +used only for initial message fetching and flag updates. +.IP +For some IMAP servers, enabling this will slightly speed up +downloading initial messages. Unfortunately, Gmail is not one +those, and displays worse performance when enabled. Your +mileage may vary. + + +.TP +.B imap_deflate +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will use the COMPRESS=DEFLATE extension (RFC +4978) if advertised by the server. +.IP +In general a good compression efficiency can be achieved, which +speeds up reading large mailboxes also on fairly good connections. + + +.TP +.B imap_delim_chars +.nf +Type: string +Default: \(lq/.\(rq +.fi +.IP +This contains the list of characters which you would like to treat +as folder separators for displaying IMAP paths. In particular it +helps in using the \(lq=\(rq shortcut for your \fIfolder\fP variable. + + +.TP +.B imap_fetch_chunk_size +.nf +Type: number (long) +Default: 0 +.fi +.IP +When set to a value greater than 0, new headers will be +downloaded in groups of this many headers per request. If you +have a very large mailbox, this might prevent a timeout and +disconnect when opening the mailbox, by sending a FETCH per set +of this many headers, instead of a single FETCH for all new +headers. + + +.TP +.B imap_headers +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Mutt requests these header fields in addition to the default headers +(\(lqDate:\(rq, \(lqFrom:\(rq, \(lqSender:\(rq, \(lqSubject:\(rq, \(lqTo:\(rq, \(lqCc:\(rq, \(lqMessage\-Id:\(rq, +\(lqReferences:\(rq, \(lqContent\-Type:\(rq, \(lqContent\-Description:\(rq, \(lqIn\-Reply\-To:\(rq, +\(lqReply\-To:\(rq, \(lqLines:\(rq, \(lqList\-Post:\(rq, \(lqX\-Label:\(rq) from IMAP +servers before displaying the index menu. You may want to add more +headers for spam detection. +.IP +\fBNote:\fP This is a space separated list, items should be uppercase +and not contain the colon, e.g. \(lqX\-BOGOSITY X\-SPAM\-STATUS\(rq for the +\(lqX\-Bogosity:\(rq and \(lqX\-Spam\-Status:\(rq header fields. + + +.TP +.B imap_idle +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will attempt to use the IMAP IDLE extension +to check for new mail in the current mailbox. Some servers +(dovecot was the inspiration for this option) react badly +to mutt's implementation. If your connection seems to freeze +up periodically, try unsetting this. + + +.TP +.B imap_keepalive +.nf +Type: number +Default: 300 +.fi +.IP +This variable specifies the maximum amount of time in seconds that mutt +will wait before polling open IMAP connections, to prevent the server +from closing them before mutt has finished with them. The default is +well within the RFC\-specified minimum amount of time (30 minutes) before +a server is allowed to do this, but in practice the RFC does get +violated every now and then. Reduce this number if you find yourself +getting disconnected from your IMAP server due to inactivity. + + +.TP +.B imap_list_subscribed +.nf +Type: boolean +Default: no +.fi +.IP +This variable configures whether IMAP folder browsing will look for +only subscribed folders or all folders. This can be toggled in the +IMAP browser with the \fB\fP function. + + +.TP +.B imap_login +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Your login name on the IMAP server. +.IP +This variable defaults to the value of $imap_user. + + +.TP +.B imap_oauth_refresh_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +The command to run to generate an OAUTH refresh token for +authorizing your connection to your IMAP server. This command will be +run on every connection attempt that uses the OAUTHBEARER authentication +mechanism. See \(lqoauth\(rq for details. + + +.TP +.B imap_pass +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Specifies the password for your IMAP account. If \fIunset\fP, Mutt will +prompt you for your password when you invoke the \fB\fP function +or try to open an IMAP folder. +.IP +\fBWarning\fP: you should only use this option when you are on a +fairly secure machine, because the superuser can read your muttrc even +if you are the only one who can read the file. + + +.TP +.B imap_passive +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will not open new IMAP connections to check for new +mail. Mutt will only check for new mail over existing IMAP +connections. This is useful if you don't want to be prompted for +user/password pairs on mutt invocation, or if opening the connection +is slow. + + +.TP +.B imap_peek +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will avoid implicitly marking your mail as read whenever +you fetch a message from the server. This is generally a good thing, +but can make closing an IMAP folder somewhat slower. This option +exists to appease speed freaks. + + +.TP +.B imap_pipeline_depth +.nf +Type: number +Default: 15 +.fi +.IP +Controls the number of IMAP commands that may be queued up before they +are sent to the server. A deeper pipeline reduces the amount of time +mutt must wait for the server, and can make IMAP servers feel much +more responsive. But not all servers correctly handle pipelined commands, +so if you have problems you might want to try setting this variable to 0. +.IP +\fBNote:\fP Changes to this variable have no effect on open connections. + + +.TP +.B imap_poll_timeout +.nf +Type: number +Default: 15 +.fi +.IP +This variable specifies the maximum amount of time in seconds +that mutt will wait for a response when polling IMAP connections +for new mail, before timing out and closing the connection. Set +to 0 to disable timing out. + + +.TP +.B imap_qresync +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will use the QRESYNC extension (RFC 7162) +if advertised by the server. Mutt's current implementation is basic, +used only for initial message fetching and flag updates. +.IP +Note: this feature is currently experimental. If you experience +strange behavior, such as duplicate or missing messages please +file a bug report to let us know. + + +.TP +.B imap_servernoise +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will display warning messages from the IMAP +server as error messages. Since these messages are often +harmless, or generated due to configuration problems on the +server which are out of the users' hands, you may wish to suppress +them at some point. + + +.TP +.B imap_user +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +The name of the user whose mail you intend to access on the IMAP +server. +.IP +This variable defaults to your user name on the local machine. + + +.TP +.B implicit_autoview +.nf +Type: boolean +Default: no +.fi +.IP +If set to \(lqyes\(rq, mutt will look for a mailcap entry with the +\(lq\fBcopiousoutput\fP\(rq flag set for \fIevery\fP MIME attachment it doesn't have +an internal viewer defined for. If such an entry is found, mutt will +use the viewer defined in that entry to convert the body part to text +form. + + +.TP +.B include +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +Controls whether or not a copy of the message(s) you are replying to +is included in your reply. + + +.TP +.B include_encrypted +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether or not Mutt includes separately encrypted attachment +contents when replying. +.IP +This variable was added to prevent accidental exposure of encrypted +contents when replying to an attacker. If a previously encrypted message +were attached by the attacker, they could trick an unwary recipient into +decrypting and including the message in their reply. + + +.TP +.B include_onlyfirst +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether or not Mutt includes only the first attachment +of the message you are replying. + + +.TP +.B indent_string +.nf +Type: string +Default: \(lq> \(rq +.fi +.IP +Specifies the string to prepend to each line of text quoted in a +message to which you are replying. You are strongly encouraged not to +change this value, as it tends to agitate the more fanatical netizens. +.IP +The value of this option is ignored if $text_flowed is set, because +the quoting mechanism is strictly defined for format=flowed. +.IP +This option is a format string, please see the description of +$index_format for supported \fBprintf(3)\fP\-style sequences. + + +.TP +.B index_format +.nf +Type: string +Default: \(lq%4C %Z %{%b %d} %\-15.15L (%?l?%4l&%4c?) %s\(rq +.fi +.IP +This variable allows you to customize the message index display to +your personal taste. +.IP +\(lqFormat strings\(rq are similar to the strings used in the C +function \fBprintf(3)\fP to format output (see the man page for more details). +For an explanation of the %? construct, see the $status_format description. +The following sequences are defined in Mutt: +.RS +.PD 0 +.TP +%a +address of the author +.TP +%A +reply\-to address (if present; otherwise: address of author) +.TP +%b +filename of the original message folder (think mailbox) +.TP +%B +the list to which the letter was sent, or else the folder name (%b). +.TP +%c +number of characters (bytes) in the message (see formatstrings-size) +.TP +%C +current message number +.TP +%d +date and time of the message in the format specified by +$date_format converted to sender's time zone +.TP +%D +date and time of the message in the format specified by +$date_format converted to the local time zone +.TP +%e +current message number in thread +.TP +%E +number of messages in current thread +.TP +%f +sender (address + real name), either From: or Return\-Path: +.TP +%F +author name, or recipient name if the message is from you +.TP +%H +spam attribute(s) of this message +.TP +%i +message\-id of the current message +.TP +%l +number of lines in the unprocessed message (may not work with +maildir, mh, and IMAP folders) +.TP +%L +If an address in the \(lqTo:\(rq or \(lqCc:\(rq header field matches an address +defined by the users \(lqsubscribe\(rq command, this displays +\(rqTo \(rq, otherwise the same as %F. +.TP +%m +total number of message in the mailbox +.TP +%M +number of hidden messages if the thread is collapsed. +.TP +%N +message score +.TP +%n +author's real name (or address if missing) +.TP +%O +original save folder where mutt would formerly have +stashed the message: list name or recipient name +if not sent to a list +.TP +%P +progress indicator for the built\-in pager (how much of the file has been displayed) +.TP +%r +comma separated list of \(lqTo:\(rq recipients +.TP +%R +comma separated list of \(lqCc:\(rq recipients +.TP +%s +subject of the message +.TP +%S +single character status of the message (\(lqN\(rq/\(lqO\(rq/\(lqD\(rq/\(lqd\(rq/\(lq!\(rq/\(lqr\(rq/\(lq*\(rq) +.TP +%t +\(lqTo:\(rq field (recipients) +.TP +%T +the appropriate character from the $to_chars string +.TP +%u +user (login) name of the author +.TP +%v +first name of the author, or the recipient if the message is from you +.TP +%X +number of attachments +(please see the \(lqattachments\(rq section for possible speed effects) +.TP +%y +\(lqX\-Label:\(rq field, if present +.TP +%Y +\(lqX\-Label:\(rq field, if present, and \fI(1)\fP not at part of a thread tree, +\fI(2)\fP at the top of a thread, or \fI(3)\fP \(lqX\-Label:\(rq is different from +preceding message's \(lqX\-Label:\(rq. +.TP +%Z +a three character set of message status flags. +the first character is new/read/replied flags (\(lqn\(rq/\(lqo\(rq/\(lqr\(rq/\(lqO\(rq/\(lqN\(rq). +the second is deleted or encryption flags (\(lqD\(rq/\(lqd\(rq/\(lqS\(rq/\(lqP\(rq/\(lqs\(rq/\(lqK\(rq). +the third is either tagged/flagged (\(lq*\(rq/\(lq!\(rq), or one of the characters +listed in $to_chars. +.TP +%@name@ +insert and evaluate format\-string from the matching +\(lqindex-format-hook\(rq command +.TP +%{fmt} +the date and time of the message is converted to sender's +time zone, and \(lqfmt\(rq is expanded by the library function +\fBstrftime(3)\fP; a leading bang disables locales +.TP +%[fmt] +the date and time of the message is converted to the local +time zone, and \(lqfmt\(rq is expanded by the library function +\fBstrftime(3)\fP; a leading bang disables locales +.TP +%(fmt) +the local date and time when the message was received. +\(lqfmt\(rq is expanded by the library function \fBstrftime(3)\fP; +a leading bang disables locales +.TP +% +the current local time. \(lqfmt\(rq is expanded by the library +function \fBstrftime(3)\fP; a leading bang disables locales. +.TP +%>X +right justify the rest of the string and pad with character \(lqX\(rq +.TP +%|X +pad to the end of the line with character \(lqX\(rq +.TP +%*X +soft\-fill with character \(lqX\(rq as pad +.RE +.PD 1 +.IP +Note that for mbox/mmdf, \(lq%l\(rq applies to the unprocessed message, and +for maildir/mh, the value comes from the \(lqLines:\(rq header field when +present (the meaning is normally the same). Thus the value depends on +the encodings used in the different parts of the message and has little +meaning in practice. +.IP +\(lqSoft\-fill\(rq deserves some explanation: Normal right\-justification +will print everything to the left of the \(lq%>\(rq, displaying padding and +whatever lies to the right only if there's room. By contrast, +soft\-fill gives priority to the right\-hand side, guaranteeing space +to display it and showing padding only if there's still room. If +necessary, soft\-fill will eat text leftwards to make room for +rightward text. +.IP +Note that these expandos are supported in +\(lqsave-hook\(rq, \(lqfcc-hook\(rq, \(lqfcc-save-hook\(rq, and +\(lqindex-format-hook\(rq. +.IP +They are also supported in the configuration variables $attribution, +$forward_attribution_intro, $forward_attribution_trailer, +$forward_format, $indent_string, $message_format, $pager_format, +and $post_indent_string. + + +.TP +.B ispell +.nf +Type: path +Default: \(lq/usr/bin/hunspell\(rq +.fi +.IP +How to invoke ispell (GNU's spell\-checking software). + + +.TP +.B keep_flagged +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, read messages marked as flagged will not be moved +from your spool mailbox to your $mbox mailbox, or as a result of +a \(lqmbox-hook\(rq command. + + +.TP +.B local_date_header +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, the date in the Date header of emails that you send will be in +your local timezone. If unset a UTC date will be used instead to avoid +leaking information about your current location. + + +.TP +.B mail_check +.nf +Type: number +Default: 5 +.fi +.IP +This variable configures how often (in seconds) mutt should look for +new mail. Also see the $timeout variable. + + +.TP +.B mail_check_recent +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will only notify you about new mail that has been received +since the last time you opened the mailbox. When \fIunset\fP, Mutt will notify you +if any new mail exists in the mailbox, regardless of whether you have visited it +recently. + + +.TP +.B mail_check_stats +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will periodically calculate message +statistics of a mailbox while polling for new mail. It will +check for unread, flagged, and total message counts. +(Note: IMAP mailboxes only support unread and total counts). +.IP +Because this operation is more performance intensive, it defaults +to \fIunset\fP, and has a separate option, +$mail_check_stats_interval, to control how often to update these +counts. +.IP +Message statistics can also be explicitly calculated by invoking the +\fB\fP +function. + + +.TP +.B mail_check_stats_interval +.nf +Type: number +Default: 60 +.fi +.IP +When $mail_check_stats is \fIset\fP, this variable configures +how often (in seconds) mutt will update message counts. + + +.TP +.B mailcap_path +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This variable specifies which files to consult when attempting to +display MIME bodies not directly supported by Mutt. The default value +is generated during startup: see the \(lqmailcap\(rq section of the manual. + + +.TP +.B mailcap_sanitize +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, mutt will restrict possible characters in mailcap % expandos +to a well\-defined set of safe characters. This is the safe setting, +but we are not sure it doesn't break some more advanced MIME stuff. +.IP +\fBDON'T CHANGE THIS SETTING UNLESS YOU ARE REALLY SURE WHAT YOU ARE +DOING!\fP + + +.TP +.B maildir_header_cache_verify +.nf +Type: boolean +Default: yes +.fi +.IP +Check for Maildir unaware programs other than mutt having modified maildir +files when the header cache is in use. This incurs one \fBstat(2)\fP per +message every time the folder is opened (which can be very slow for NFS +folders). + + +.TP +.B maildir_trash +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, messages marked as deleted will be saved with the maildir +trashed flag instead of unlinked. \fBNote:\fP this only applies +to maildir\-style mailboxes. Setting it will have no effect on other +mailbox types. + + +.TP +.B maildir_check_cur +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, mutt will poll both the new and cur directories of +a maildir folder for new messages. This might be useful if other +programs interacting with the folder (e.g. dovecot) are moving new +messages to the cur directory. Note that setting this option may +slow down polling for new messages in large folders, since mutt has +to scan all cur messages. + + +.TP +.B mark_macro_prefix +.nf +Type: string +Default: \(lq'\(rq +.fi +.IP +Prefix for macros created using mark\-message. A new macro +automatically generated with \fIa\fP will be composed +from this prefix and the letter \fIa\fP. + + +.TP +.B mark_old +.nf +Type: boolean +Default: yes +.fi +.IP +Controls whether or not mutt marks \fInew\fP \fBunread\fP +messages as \fIold\fP if you exit a mailbox without reading them. +With this option \fIset\fP, the next time you start mutt, the messages +will show up with an \(lqO\(rq next to them in the index menu, +indicating that they are old. + + +.TP +.B markers +.nf +Type: boolean +Default: yes +.fi +.IP +Controls the display of wrapped lines in the internal pager. If set, a +\(lq+\(rq marker is displayed at the beginning of wrapped lines. +.IP +Also see the $smart_wrap variable. + + +.TP +.B mask +.nf +Type: regular expression +Default: \(lq!^\\.[^.]\(rq +.fi +.IP +A regular expression used in the file browser, optionally preceded by +the \fInot\fP operator \(lq!\(rq. Only files whose names match this mask +will be shown. The match is always case\-sensitive. + + +.TP +.B mbox +.nf +Type: path +Default: \(lq~/mbox\(rq +.fi +.IP +This specifies the folder into which read mail in your $spoolfile +folder will be appended. +.IP +Also see the $move variable. + + +.TP +.B mbox_type +.nf +Type: folder magic +Default: mbox +.fi +.IP +The default mailbox type used when creating new folders. May be any of +\(lqmbox\(rq, \(lqMMDF\(rq, \(lqMH\(rq and \(lqMaildir\(rq. This is overridden by the +\fB\-m\fP command\-line option. + + +.TP +.B menu_context +.nf +Type: number +Default: 0 +.fi +.IP +This variable controls the number of lines of context that are given +when scrolling through menus. (Similar to $pager_context.) + + +.TP +.B menu_move_off +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIunset\fP, the bottom entry of menus will never scroll up past +the bottom of the screen, unless there are less entries than lines. +When \fIset\fP, the bottom entry may move off the bottom. + + +.TP +.B menu_scroll +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, menus will be scrolled up or down one line when you +attempt to move across a screen boundary. If \fIunset\fP, the screen +is cleared and the next or previous page of the menu is displayed +(useful for slow links to avoid many redraws). + + +.TP +.B message_cache_clean +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, mutt will clean out obsolete entries from the message cache when +the mailbox is synchronized. You probably only want to set it +every once in a while, since it can be a little slow +(especially for large folders). + + +.TP +.B message_cachedir +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +Set this to a directory and mutt will cache copies of messages from +your IMAP and POP servers here. You are free to remove entries at any +time. +.IP +When setting this variable to a directory, mutt needs to fetch every +remote message only once and can perform regular expression searches +as fast as for local folders. +.IP +Also see the $message_cache_clean variable. + + +.TP +.B message_format +.nf +Type: string +Default: \(lq%s\(rq +.fi +.IP +This is the string displayed in the \(lqattachment\(rq menu for +attachments of type \fBmessage/rfc822\fP. For a full listing of defined +\fBprintf(3)\fP\-like sequences see the section on $index_format. + + +.TP +.B message_id_format +.nf +Type: string +Default: \(lq<%z@%f>\(rq +.fi +.IP +This variable describes the format of the Message\-ID generated +when sending messages. Mutt 2.0 introduced a more compact +format, but this variable allows the ability to choose your own +format. The value may end in \(lq|\(rq to invoke an external filter. +See formatstrings-filters. +.IP +Please note that the Message\-ID value follows a strict syntax, +and you are responsible for ensuring correctness if you change +this from the default. In particular, the value must follow the +syntax in RFC 5322: \(lq\fB\(rq<\(rq id\-left \(rq@\(rq id\-right \(rq>\(rq\fP\(rq. No +spaces are allowed, and \fBid\-left\fP should follow the +dot\-atom\-text syntax in the RFC. The \fBid\-right\fP should +generally be left at %f. +.IP +The old Message\-ID format can be used by setting this to: +\(lq\fB<%Y%02m%02d%02H%02M%02S.G%c%p@%f>\fP\(rq +.IP +The following \fBprintf(3)\fP\-style sequences are understood: +.RS +.PD 0 +.TP +%c +step counter looping from \(lqA\(rq to \(lqZ\(rq +.TP +%d +current day of the month (GMT) +.TP +%f +$hostname +.TP +%H +current hour using a 24\-hour clock (GMT) +.TP +%m +current month number (GMT) +.TP +%M +current minute of the hour (GMT) +.TP +%p +pid of the running mutt process +.TP +%r +3 bytes of pseudorandom data encoded in Base64 +.TP +%S +current second of the minute (GMT) +.TP +%x +1 byte of pseudorandom data hex encoded (example: '1b') +.TP +%Y +current year using 4 digits (GMT) +.TP +%z +4 byte timestamp + 8 bytes of pseudorandom data encoded in Base64 +.RE +.PD 1 + +.TP +.B meta_key +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, forces Mutt to interpret keystrokes with the high bit (bit 8) +set as if the user had pressed the Esc key and whatever key remains +after having the high bit removed. For example, if the key pressed +has an ASCII value of \fB0xf8\fP, then this is treated as if the user had +pressed Esc then \(lqx\(rq. This is because the result of removing the +high bit from \fB0xf8\fP is \fB0x78\fP, which is the ASCII character +\(lqx\(rq. + + +.TP +.B metoo +.nf +Type: boolean +Default: no +.fi +.IP +If \fIunset\fP, Mutt will remove your address (see the \(lqalternates\(rq +command) from the list of recipients when replying to a message. + + +.TP +.B mh_purge +.nf +Type: boolean +Default: no +.fi +.IP +When \fIunset\fP, mutt will mimic mh's behavior and rename deleted messages +to \fI,\fP in mh folders instead of really deleting +them. This leaves the message on disk but makes programs reading the folder +ignore it. If the variable is \fIset\fP, the message files will simply be +deleted. +.IP +This option is similar to $maildir_trash for Maildir folders. + + +.TP +.B mh_seq_flagged +.nf +Type: string +Default: \(lqflagged\(rq +.fi +.IP +The name of the MH sequence used for flagged messages. + + +.TP +.B mh_seq_replied +.nf +Type: string +Default: \(lqreplied\(rq +.fi +.IP +The name of the MH sequence used to tag replied messages. + + +.TP +.B mh_seq_unseen +.nf +Type: string +Default: \(lqunseen\(rq +.fi +.IP +The name of the MH sequence used for unseen messages. + + +.TP +.B mime_forward +.nf +Type: quadoption +Default: no +.fi +.IP +When \fIset\fP, the message you are forwarding will be attached as a +separate \fBmessage/rfc822\fP MIME part instead of included in the main body of the +message. This is useful for forwarding MIME messages so the receiver +can properly view the message as it was delivered to you. If you like +to switch between MIME and not MIME from mail to mail, set this +variable to \(lqask\-no\(rq or \(lqask\-yes\(rq. +.IP +Also see $forward_decode and $mime_forward_decode. + + +.TP +.B mime_forward_decode +.nf +Type: boolean +Default: no +.fi +.IP +Controls the decoding of complex MIME messages into \fBtext/plain\fP when +forwarding a message while $mime_forward is \fIset\fP. Otherwise +$forward_decode is used instead. + + +.TP +.B mime_forward_rest +.nf +Type: quadoption +Default: yes +.fi +.IP +When forwarding multiple attachments of a MIME message from the attachment +menu, attachments which cannot be decoded in a reasonable manner will +be attached to the newly composed message if this option is \fIset\fP. + + +.TP +.B mime_type_query_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This specifies a command to run, to determine the mime type of a +new attachment when composing a message. Unless +$mime_type_query_first is set, this will only be run if the +attachment's extension is not found in the mime.types file. +.IP +The string may contain a \(lq%s\(rq, which will be substituted with the +attachment filename. Mutt will add quotes around the string substituted +for \(lq%s\(rq automatically according to shell quoting rules, so you should +avoid adding your own. If no \(lq%s\(rq is found in the string, Mutt will +append the attachment filename to the end of the string. +.IP +The command should output a single line containing the +attachment's mime type. +.IP +Suggested values are \(lqxdg\-mime query filetype\(rq or +\(lqfile \-bi\(rq. + + +.TP +.B mime_type_query_first +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, the $mime_type_query_command will be run before the +mime.types lookup. + + +.TP +.B mix_entry_format +.nf +Type: string +Default: \(lq%4n %c %\-16s %a\(rq +.fi +.IP +This variable describes the format of a remailer line on the mixmaster +chain selection screen. The following \fBprintf(3)\fP\-like sequences are +supported: +.RS +.PD 0 +.TP +%n +The running number on the menu. +.TP +%c +Remailer capabilities. +.TP +%s +The remailer's short name. +.TP +%a +The remailer's e\-mail address. +.RE +.PD 1 +.IP +(Mixmaster only) + + +.TP +.B mixmaster +.nf +Type: path +Default: \(lqmixmaster\(rq +.fi +.IP +This variable contains the path to the Mixmaster binary on your +system. It is used with various sets of parameters to gather the +list of known remailers, and to finally send a message through the +mixmaster chain. (Mixmaster only) + + +.TP +.B move +.nf +Type: quadoption +Default: no +.fi +.IP +Controls whether or not Mutt will move read messages +from your spool mailbox to your $mbox mailbox, or as a result of +a \(lqmbox-hook\(rq command. + + +.TP +.B muttlisp_inline_eval +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, Mutt will evaluate bare parenthesis arguments to commands +as MuttLisp expressions. + + +.TP +.B narrow_tree +.nf +Type: boolean +Default: no +.fi +.IP +This variable, when \fIset\fP, makes the thread tree narrower, allowing +deeper threads to fit on the screen. + + +.TP +.B net_inc +.nf +Type: number +Default: 10 +.fi +.IP +Operations that expect to transfer a large amount of data over the +network will update their progress every $net_inc kilobytes. +If set to 0, no progress messages will be displayed. +.IP +See also $read_inc, $write_inc and $net_inc. + + +.TP +.B new_mail_command +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +If \fIset\fP, Mutt will call this command after a new message is received. +See the $status_format documentation for the values that can be formatted +into this command. + + +.TP +.B pager +.nf +Type: path +Default: \(lqbuiltin\(rq +.fi +.IP +This variable specifies which pager you would like to use to view +messages. The value \(lqbuiltin\(rq means to use the built\-in pager, otherwise this +variable should specify the pathname of the external pager you would +like to use. +.IP +The string may contain a \(lq%s\(rq, which will be substituted with +the generated message filename. Mutt will add quotes around the +string substituted for \(lq%s\(rq automatically according to shell +quoting rules, so you should avoid adding your own. If no \(lq%s\(rq +is found in the string, Mutt will append the message filename to +the end of the string. +.IP +Using an external pager may have some disadvantages: Additional +keystrokes are necessary because you can't call mutt functions +directly from the pager, and screen resizes cause lines longer than +the screen width to be badly formatted in the help menu. +.IP +When using an external pager, also see $prompt_after which defaults +\fIset\fP. + + +.TP +.B pager_context +.nf +Type: number +Default: 0 +.fi +.IP +This variable controls the number of lines of context that are given +when displaying the next or previous page in the internal pager. By +default, Mutt will display the line after the last one on the screen +at the top of the next page (0 lines of context). +.IP +This variable also specifies the amount of context given for search +results. If positive, this many lines will be given before a match, +if 0, the match will be top\-aligned. + + +.TP +.B pager_format +.nf +Type: string +Default: \(lq\-%Z\- %C/%m: %\-20.20n %s%* \-\- (%P)\(rq +.fi +.IP +This variable controls the format of the one\-line message \(lqstatus\(rq +displayed before each message in either the internal or an external +pager. The valid sequences are listed in the $index_format +section. + + +.TP +.B pager_index_lines +.nf +Type: number +Default: 0 +.fi +.IP +Determines the number of lines of a mini\-index which is shown when in +the pager. The current message, unless near the top or bottom of the +folder, will be roughly one third of the way down this mini\-index, +giving the reader the context of a few messages before and after the +message. This is useful, for example, to determine how many messages +remain to be read in the current thread. One of the lines is reserved +for the status bar from the index, so a setting of 6 +will only show 5 lines of the actual index. A value of 0 results in +no index being shown. If the number of messages in the current folder +is less than $pager_index_lines, then the index will only use as +many lines as it needs. + + +.TP +.B pager_skip_quoted_context +.nf +Type: number +Default: 0 +.fi +.IP +Determines the number of lines of context to show before the +unquoted text when using \fB\fP. When set to a +positive number at most that many lines of the previous quote are +displayed. If the previous quote is shorter the whole quote is +displayed. + + +.TP +.B pager_stop +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, the internal\-pager will \fBnot\fP move to the next message +when you are at the end of a message and invoke the \fB\fP +function. + + +.TP +.B pattern_format +.nf +Type: string +Default: \(lq%2n %\-15e %d\(rq +.fi +.IP +This variable describes the format of the \(lqpattern completion\(rq menu. The +following \fBprintf(3)\fP\-style sequences are understood: +.RS +.PD 0 +.TP +%d +pattern description +.TP +%e +pattern expression +.TP +%n +index number +.RE +.PD 1 +.IP + + +.TP +.B pgp_auto_decode +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, mutt will automatically attempt to decrypt traditional PGP +messages whenever the user performs an operation which ordinarily would +result in the contents of the message being operated on. For example, +if the user displays a pgp\-traditional message which has not been manually +checked with the \fB\fP function, mutt will automatically +check the message for traditional pgp. + + +.TP +.B pgp_autoinline +.nf +Type: boolean +Default: no +.fi +.IP +This option controls whether Mutt generates old\-style inline +(traditional) PGP encrypted or signed messages under certain +circumstances. This can be overridden by use of the pgp menu, +when inline is not required. The GPGME backend does not support +this option. +.IP +Note that Mutt might automatically use PGP/MIME for messages +which consist of more than a single MIME part. Mutt can be +configured to ask before sending PGP/MIME messages when inline +(traditional) would not work. +.IP +Also see the $pgp_mime_auto variable. +.IP +Also note that using the old\-style PGP message format is \fBstrongly\fP +\fBdeprecated\fP. +(PGP only) + + +.TP +.B pgp_check_exit +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, mutt will check the exit code of the PGP subprocess when +signing or encrypting. A non\-zero exit code means that the +subprocess failed. +(PGP only) + + +.TP +.B pgp_check_gpg_decrypt_status_fd +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, mutt will check the status file descriptor output +of $pgp_decrypt_command and $pgp_decode_command for GnuPG status codes +indicating successful decryption. This will check for the presence of +DECRYPTION_OKAY, absence of DECRYPTION_FAILED, and that all +PLAINTEXT occurs between the BEGIN_DECRYPTION and END_DECRYPTION +status codes. +.IP +If \fIunset\fP, mutt will instead match the status fd output +against $pgp_decryption_okay. +(PGP only) + + +.TP +.B pgp_clearsign_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This format is used to create an old\-style \(lqclearsigned\(rq PGP +message. Note that the use of this format is \fBstrongly\fP +\fBdeprecated\fP. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_decode_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This format strings specifies a command which is used to decode +application/pgp attachments. +.IP +The PGP command formats have their own set of \fBprintf(3)\fP\-like sequences: +.RS +.PD 0 +.TP +%p +Expands to PGPPASSFD=0 when a pass phrase is needed, to an empty +string otherwise. Note: This may be used with a %? construct. +.TP +%f +Expands to the name of a file containing a message. +.TP +%s +Expands to the name of a file containing the signature part + of a \fBmultipart/signed\fP attachment when verifying it. +.TP +%a +The value of $pgp_sign_as if set, otherwise the value +of $pgp_default_key. +.TP +%r +One or more key IDs (or fingerprints if available). +.RE +.PD 1 +.IP +For examples on how to configure these formats for the various versions +of PGP which are floating around, see the pgp and gpg sample configuration files in +the \fBsamples/\fP subdirectory which has been installed on your system +alongside the documentation. +(PGP only) + + +.TP +.B pgp_decrypt_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to decrypt a PGP encrypted message. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_decryption_okay +.nf +Type: regular expression +Default: \(lq\(rq +.fi +.IP +If you assign text to this variable, then an encrypted PGP +message is only considered successfully decrypted if the output +from $pgp_decrypt_command contains the text. This is used to +protect against a spoofed encrypted message, with multipart/encrypted +headers but containing a block that is not actually encrypted. +(e.g. simply signed and ascii armored text). +.IP +Note that if $pgp_check_gpg_decrypt_status_fd is set, this variable +is ignored. +(PGP only) + + +.TP +.B pgp_default_key +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This is the default key\-pair to use for PGP operations. It will be +used for encryption (see $postpone_encrypt and $pgp_self_encrypt). +.IP +It will also be used for signing unless $pgp_sign_as is set. +.IP +The (now deprecated) \fIpgp_self_encrypt_as\fP is an alias for this +variable, and should no longer be used. +(PGP only) + + +.TP +.B pgp_encrypt_only_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to encrypt a body part without signing it. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_encrypt_sign_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to both sign and encrypt a body part. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_entry_format +.nf +Type: string +Default: \(lq%4n %t%f %4l/0x%k %\-4a %2c %u\(rq +.fi +.IP +This variable allows you to customize the PGP key selection menu to +your personal taste. This string is similar to $index_format, but +has its own set of \fBprintf(3)\fP\-like sequences: +.RS +.PD 0 +.TP +%n +number +.TP +%k +key id +.TP +%u +user id +.TP +%a +algorithm +.TP +%l +key length +.TP +%f +flags +.TP +%c +capabilities +.TP +%t +trust/validity of the key\-uid association +.TP +%[] +date of the key where is an \fBstrftime(3)\fP expression +.RE +.PD 1 +.IP +(PGP only) + + +.TP +.B pgp_export_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to export a public key from the user's +key ring. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_getkeys_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is invoked whenever Mutt needs to fetch the public key associated with +an email address. Of the sequences supported by $pgp_decode_command, %r is +the only \fBprintf(3)\fP\-like sequence used with this format. Note that +in this case, %r expands to the email address, not the public key ID (the key ID is +unknown, which is why Mutt is invoking this command). +(PGP only) + + +.TP +.B pgp_good_sign +.nf +Type: regular expression +Default: \(lq\(rq +.fi +.IP +If you assign a text to this variable, then a PGP signature is only +considered verified if the output from $pgp_verify_command contains +the text. Use this variable if the exit code from the command is 0 +even for bad signatures. +(PGP only) + + +.TP +.B pgp_ignore_subkeys +.nf +Type: boolean +Default: yes +.fi +.IP +Setting this variable will cause Mutt to ignore OpenPGP subkeys. Instead, +the principal key will inherit the subkeys' capabilities. \fIUnset\fP this +if you want to play interesting key selection games. +(PGP only) + + +.TP +.B pgp_import_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to import a key from a message into +the user's public key ring. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_list_pubring_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to list the public key ring's contents. The +output format must be analogous to the one used by + +.IP +.EX +gpg \-\-list\-keys \-\-with\-colons \-\-with\-fingerprint + +.EE +.IP +This format is also generated by the \fBmutt_pgpring\fP utility which comes +with mutt. +.IP +Note: gpg's \fBfixed\-list\-mode\fP option should not be used. It +produces a different date format which may result in mutt showing +incorrect key generation dates. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +Note that in this case, %r expands to the search string, which is a list of +one or more quoted values such as email address, name, or keyid. +(PGP only) + + +.TP +.B pgp_list_secring_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to list the secret key ring's contents. The +output format must be analogous to the one used by: + +.IP +.EX +gpg \-\-list\-keys \-\-with\-colons \-\-with\-fingerprint + +.EE +.IP +This format is also generated by the \fBmutt_pgpring\fP utility which comes +with mutt. +.IP +Note: gpg's \fBfixed\-list\-mode\fP option should not be used. It +produces a different date format which may result in mutt showing +incorrect key generation dates. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +Note that in this case, %r expands to the search string, which is a list of +one or more quoted values such as email address, name, or keyid. +(PGP only) + + +.TP +.B pgp_long_ids +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, use 64 bit PGP key IDs, if \fIunset\fP use the normal 32 bit key IDs. +NOTE: Internally, Mutt has transitioned to using fingerprints (or long key IDs +as a fallback). This option now only controls the display of key IDs +in the key selection menu and a few other places. +(PGP only) + + +.TP +.B pgp_mime_auto +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +This option controls whether Mutt will prompt you for +automatically sending a (signed/encrypted) message using +PGP/MIME when inline (traditional) fails (for any reason). +.IP +Also note that using the old\-style PGP message format is \fBstrongly\fP +\fBdeprecated\fP. +(PGP only) + + +.TP +.B pgp_replyinline +.nf +Type: boolean +Default: no +.fi +.IP +Setting this variable will cause Mutt to always attempt to +create an inline (traditional) message when replying to a +message which is PGP encrypted/signed inline. This can be +overridden by use of the pgp menu, when inline is not +required. This option does not automatically detect if the +(replied\-to) message is inline; instead it relies on Mutt +internals for previously checked/flagged messages. +.IP +Note that Mutt might automatically use PGP/MIME for messages +which consist of more than a single MIME part. Mutt can be +configured to ask before sending PGP/MIME messages when inline +(traditional) would not work. +.IP +Also see the $pgp_mime_auto variable. +.IP +Also note that using the old\-style PGP message format is \fBstrongly\fP +\fBdeprecated\fP. +(PGP only) + + +.TP +.B pgp_retainable_sigs +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, signed and encrypted messages will consist of nested +\fBmultipart/signed\fP and \fBmultipart/encrypted\fP body parts. +.IP +This is useful for applications like encrypted and signed mailing +lists, where the outer layer (\fBmultipart/encrypted\fP) can be easily +removed, while the inner \fBmultipart/signed\fP part is retained. +(PGP only) + + +.TP +.B pgp_self_encrypt +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, PGP encrypted messages will also be encrypted +using the key in $pgp_default_key. +(PGP only) + + +.TP +.B pgp_show_unusable +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, mutt will display non\-usable keys on the PGP key selection +menu. This includes keys which have been revoked, have expired, or +have been marked as \(lqdisabled\(rq by the user. +(PGP only) + + +.TP +.B pgp_sign_as +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +If you have a different key pair to use for signing, you should +set this to the signing key. Most people will only need to set +$pgp_default_key. It is recommended that you use the keyid form +to specify your key (e.g. \fB0x00112233\fP). +(PGP only) + + +.TP +.B pgp_sign_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to create the detached PGP signature for a +\fBmultipart/signed\fP PGP/MIME body part. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_sort_keys +.nf +Type: sort order +Default: address +.fi +.IP +Specifies how the entries in the pgp menu are sorted. The +following are legal values: +.RS +.PD 0 +.TP +address +sort alphabetically by user id +.TP +keyid +sort alphabetically by key id +.TP +date +sort by key creation date +.TP +trust +sort by the trust of the key +.RE +.PD 1 +.IP +If you prefer reverse order of the above values, prefix it with +\(lqreverse\-\(rq. +(PGP only) + + +.TP +.B pgp_strict_enc +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, Mutt will automatically encode PGP/MIME signed messages as +quoted\-printable. Please note that unsetting this variable may +lead to problems with non\-verifyable PGP signatures, so only change +this if you know what you are doing. +(PGP only) + + +.TP +.B pgp_timeout +.nf +Type: number (long) +Default: 300 +.fi +.IP +The number of seconds after which a cached passphrase will expire if +not used. +(PGP only) + + +.TP +.B pgp_use_gpg_agent +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, mutt expects a \fBgpg\-agent(1)\fP process will handle +private key passphrase prompts. If \fIunset\fP, mutt will prompt +for the passphrase and pass it via stdin to the pgp command. +.IP +Note that as of version 2.1, GnuPG automatically spawns an agent +and requires the agent be used for passphrase management. Since +that version is increasingly prevalent, this variable now +defaults \fIset\fP. +.IP +Mutt works with a GUI or curses pinentry program. A TTY pinentry +should not be used. +.IP +If you are using an older version of GnuPG without an agent running, +or another encryption program without an agent, you will need to +\fIunset\fP this variable. +(PGP only) + + +.TP +.B pgp_verify_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to verify PGP signatures. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pgp_verify_key_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to verify key information from the key selection +menu. +.IP +This is a format string, see the $pgp_decode_command command for +possible \fBprintf(3)\fP\-like sequences. +(PGP only) + + +.TP +.B pipe_decode +.nf +Type: boolean +Default: no +.fi +.IP +Used in connection with the \fB\fP function. When \fIunset\fP, +Mutt will pipe the messages without any preprocessing. When \fIset\fP, Mutt +will attempt to decode the messages first. +.IP +Also see $pipe_decode_weed, which controls whether headers will +be weeded when this is \fIset\fP. + + +.TP +.B pipe_decode_weed +.nf +Type: boolean +Default: yes +.fi +.IP +For \fB\fP, when $pipe_decode is set, this further +controls whether Mutt will weed headers. + + +.TP +.B pipe_sep +.nf +Type: string +Default: \(lq\\n\(rq +.fi +.IP +The separator to add between messages when piping a list of tagged +messages to an external Unix command. + + +.TP +.B pipe_split +.nf +Type: boolean +Default: no +.fi +.IP +Used in connection with the \fB\fP function following +\fB\fP. If this variable is \fIunset\fP, when piping a list of +tagged messages Mutt will concatenate the messages and will pipe them +all concatenated. When \fIset\fP, Mutt will pipe the messages one by one. +In both cases the messages are piped in the current sorted order, +and the $pipe_sep separator is added after each message. + + +.TP +.B pop_auth_try_all +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, Mutt will try all available authentication methods. +When \fIunset\fP, Mutt will only fall back to other authentication +methods if the previous methods are unavailable. If a method is +available but authentication fails, Mutt will not connect to the POP server. + + +.TP +.B pop_authenticators +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This is a colon\-delimited list of authentication methods mutt may +attempt to use to log in to an POP server, in the order mutt should +try them. Authentication methods are either \(lquser\(rq, \(lqapop\(rq or any +SASL mechanism, e.g. \(lqdigest\-md5\(rq, \(lqgssapi\(rq or \(lqcram\-md5\(rq. +This option is case\-insensitive. If this option is \fIunset\fP +(the default) mutt will try all available methods, in order from +most\-secure to least\-secure. +.IP +Example: + +.IP +.EX +set pop_authenticators=\(rqdigest\-md5:apop:user\(rq + +.EE + + +.TP +.B pop_checkinterval +.nf +Type: number +Default: 60 +.fi +.IP +This variable configures how often (in seconds) mutt should look for +new mail in the currently selected mailbox if it is a POP mailbox. + + +.TP +.B pop_delete +.nf +Type: quadoption +Default: ask\-no +.fi +.IP +If \fIset\fP, Mutt will delete successfully downloaded messages from the POP +server when using the \fB\fP function. When \fIunset\fP, Mutt will +download messages but also leave them on the POP server. + + +.TP +.B pop_host +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +The name of your POP server for the \fB\fP function. You +can also specify an alternative port, username and password, i.e.: + +.IP +.EX +[pop[s]://][username[:password]@]popserver[:port] + +.EE +.IP +where \(lq[...]\(rq denotes an optional part. + + +.TP +.B pop_last +.nf +Type: boolean +Default: no +.fi +.IP +If this variable is \fIset\fP, mutt will try to use the \(lq\fBLAST\fP\(rq POP command +for retrieving only unread messages from the POP server when using +the \fB\fP function. + + +.TP +.B pop_oauth_refresh_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +The command to run to generate an OAUTH refresh token for +authorizing your connection to your POP server. This command will be +run on every connection attempt that uses the OAUTHBEARER authentication +mechanism. See \(lqoauth\(rq for details. + + +.TP +.B pop_pass +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Specifies the password for your POP account. If \fIunset\fP, Mutt will +prompt you for your password when you open a POP mailbox. +.IP +\fBWarning\fP: you should only use this option when you are on a +fairly secure machine, because the superuser can read your muttrc +even if you are the only one who can read the file. + + +.TP +.B pop_reconnect +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +Controls whether or not Mutt will try to reconnect to the POP server if +the connection is lost. + + +.TP +.B pop_user +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Your login name on the POP server. +.IP +This variable defaults to your user name on the local machine. + + +.TP +.B post_indent_string +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Similar to the $attribution variable, Mutt will append this +string after the inclusion of a message which is being replied to. +For a full listing of defined \fBprintf(3)\fP\-like sequences see +the section on $index_format. + + +.TP +.B postpone +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +Controls whether or not messages are saved in the $postponed +mailbox when you elect not to send immediately. +.IP +Also see the $recall variable. + + +.TP +.B postponed +.nf +Type: path +Default: \(lq~/postponed\(rq +.fi +.IP +Mutt allows you to indefinitely \(lqpostpone sending a message\(rq which +you are editing. When you choose to postpone a message, Mutt saves it +in the mailbox specified by this variable. +.IP +Also see the $postpone variable. + + +.TP +.B postpone_encrypt +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, postponed messages that are marked for encryption will be +self\-encrypted. Mutt will first try to encrypt using the value specified +in $pgp_default_key or $smime_default_key. If those are not +set, it will try the deprecated $postpone_encrypt_as. +(Crypto only) + + +.TP +.B postpone_encrypt_as +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This is a deprecated fall\-back variable for $postpone_encrypt. +Please use $pgp_default_key or $smime_default_key. +(Crypto only) + + +.TP +.B preconnect +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +If \fIset\fP, a shell command to be executed if mutt fails to establish +a connection to the server. This is useful for setting up secure +connections, e.g. with \fBssh(1)\fP. If the command returns a nonzero +status, mutt gives up opening the server. Example: + +.IP +.EX +set preconnect=\(rqssh \-f \-q \-L 1234:mailhost.net:143 mailhost.net \\ +sleep 20 < /dev/null > /dev/null\(rq + +.EE +.IP +Mailbox \(lqfoo\(rq on \(lqmailhost.net\(rq can now be reached +as \(lq{localhost:1234}foo\(rq. +.IP +Note: For this example to work, you must be able to log in to the +remote machine without having to enter a password. + + +.TP +.B print +.nf +Type: quadoption +Default: ask\-no +.fi +.IP +Controls whether or not Mutt really prints messages. +This is set to \(lqask\-no\(rq by default, because some people +accidentally hit \(lqp\(rq often. + + +.TP +.B print_command +.nf +Type: path +Default: \(lqlpr\(rq +.fi +.IP +This specifies the command pipe that should be used to print messages. + + +.TP +.B print_decode +.nf +Type: boolean +Default: yes +.fi +.IP +Used in connection with the \fB\fP function. If this +option is \fIset\fP, the message is decoded before it is passed to the +external command specified by $print_command. If this option +is \fIunset\fP, no processing will be applied to the message when +printing it. The latter setting may be useful if you are using +some advanced printer filter which is able to properly format +e\-mail messages for printing. +.IP +Also see $print_decode_weed, which controls whether headers will +be weeded when this is \fIset\fP. + + +.TP +.B print_decode_weed +.nf +Type: boolean +Default: yes +.fi +.IP +For \fB\fP, when $print_decode is set, this +further controls whether Mutt will weed headers. + + +.TP +.B print_split +.nf +Type: boolean +Default: no +.fi +.IP +Used in connection with the \fB\fP function. If this option +is \fIset\fP, the command specified by $print_command is executed once for +each message which is to be printed. If this option is \fIunset\fP, +the command specified by $print_command is executed only once, and +all the messages are concatenated, with a form feed as the message +separator. +.IP +Those who use the \fBenscript\fP(1) program's mail\-printing mode will +most likely want to \fIset\fP this option. + + +.TP +.B prompt_after +.nf +Type: boolean +Default: yes +.fi +.IP +If you use an \fIexternal\fP $pager, setting this variable will +cause Mutt to prompt you for a command when the pager exits rather +than returning to the index menu. If \fIunset\fP, Mutt will return to the +index menu when the external pager exits. + + +.TP +.B query_command +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +This specifies the command Mutt will use to make external address +queries. The string may contain a \(lq%s\(rq, which will be substituted +with the query string the user types. Mutt will add quotes around the +string substituted for \(lq%s\(rq automatically according to shell quoting +rules, so you should avoid adding your own. If no \(lq%s\(rq is found in +the string, Mutt will append the user's query to the end of the string. +See \(lqquery\(rq for more information. + + +.TP +.B query_format +.nf +Type: string +Default: \(lq%4c %t %\-25.25a %\-25.25n %?e?(%e)?\(rq +.fi +.IP +This variable describes the format of the \(lqquery\(rq menu. The +following \fBprintf(3)\fP\-style sequences are understood: +.RS +.PD 0 +.TP +%a +destination address +.TP +%c +current entry number +.TP +%e +extra information * +.TP +%n +destination name +.TP +%t +\(lq*\(rq if current entry is tagged, a space otherwise +.TP +%>X +right justify the rest of the string and pad with \(lqX\(rq +.TP +%|X +pad to the end of the line with \(lqX\(rq +.TP +%*X +soft\-fill with character \(lqX\(rq as pad +.RE +.PD 1 +.IP +For an explanation of \(lqsoft\-fill\(rq, see the $index_format documentation. +.IP +* = can be optionally printed if nonzero, see the $status_format documentation. + + +.TP +.B quit +.nf +Type: quadoption +Default: yes +.fi +.IP +This variable controls whether \(lqquit\(rq and \(lqexit\(rq actually quit +from mutt. If this option is \fIset\fP, they do quit, if it is \fIunset\fP, they +have no effect, and if it is set to \fIask\-yes\fP or \fIask\-no\fP, you are +prompted for confirmation when you try to quit. + + +.TP +.B quote_regexp +.nf +Type: regular expression +Default: \(lq^([ \\t]*[|>:}#])+\(rq +.fi +.IP +A regular expression used in the internal pager to determine quoted +sections of text in the body of a message. Quoted text may be filtered +out using the \fB\fP command, or colored according to the +\(lqcolor quoted\(rq family of directives. +.IP +Higher levels of quoting may be colored differently (\(lqcolor quoted1\(rq, +\(lqcolor quoted2\(rq, etc.). The quoting level is determined by removing +the last character from the matched text and recursively reapplying +the regular expression until it fails to produce a match. +.IP +Match detection may be overridden by the $smileys regular expression. + + +.TP +.B read_inc +.nf +Type: number +Default: 10 +.fi +.IP +If set to a value greater than 0, Mutt will display which message it +is currently on when reading a mailbox or when performing search actions +such as search and limit. The message is printed after +this many messages have been read or searched (e.g., if set to 25, Mutt will +print a message when it is at message 25, and then again when it gets +to message 50). This variable is meant to indicate progress when +reading or searching large mailboxes which may take some time. +When set to 0, only a single message will appear before the reading +the mailbox. +.IP +Also see the $write_inc, $net_inc and $time_inc variables and the +\(lqtuning\(rq section of the manual for performance considerations. + + +.TP +.B read_only +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, all folders are opened in read\-only mode. + + +.TP +.B realname +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This variable specifies what \(lqreal\(rq or \(lqpersonal\(rq name should be used +when sending messages. +.IP +By default, this is the GECOS field from \fB/etc/passwd\fP. Note that this +variable will \fInot\fP be used when the user has set a real name +in the $from variable. + + +.TP +.B recall +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +Controls whether or not Mutt recalls postponed messages +when composing a new message. +.IP +Setting this variable to \fIyes\fP is not generally useful, and thus not +recommended. Note that the \fB\fP function can be used +to manually recall postponed messages. +.IP +Also see $postponed variable. + + +.TP +.B record +.nf +Type: path +Default: \(lq~/sent\(rq +.fi +.IP +This specifies the file into which your outgoing messages should be +appended. (This is meant as the primary method for saving a copy of +your messages, but another way to do this is using the \(lqmy_hdr\(rq +command to create a \(lqBcc:\(rq field with your email address in it.) +.IP +The value of \fI$record\fP is overridden by the $force_name and +$save_name variables, and the \(lqfcc-hook\(rq command. Also see $copy +and $write_bcc. +.IP +Multiple mailboxes may be specified if $fcc_delimiter is +set to a string delimiter. + + +.TP +.B reflow_space_quotes +.nf +Type: boolean +Default: yes +.fi +.IP +This option controls how quotes from format=flowed messages are displayed +in the pager and when replying (with $text_flowed \fIunset\fP). +When set, this option adds spaces after each level of quote marks, turning +\(rq>>>foo\(rq into \(rq> > > foo\(rq. +.IP +\fBNote:\fP If $reflow_text is \fIunset\fP, this option has no effect. +Also, this option does not affect replies when $text_flowed is \fIset\fP. + + +.TP +.B reflow_text +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will reformat paragraphs in text/plain +parts marked format=flowed. If \fIunset\fP, Mutt will display paragraphs +unaltered from how they appear in the message body. See RFC3676 for +details on the \fIformat=flowed\fP format. +.IP +Also see $reflow_wrap, and $wrap. + + +.TP +.B reflow_wrap +.nf +Type: number +Default: 78 +.fi +.IP +This variable controls the maximum paragraph width when reformatting text/plain +parts when $reflow_text is \fIset\fP. When the value is 0, paragraphs will +be wrapped at the terminal's right margin. A positive value sets the +paragraph width relative to the left margin. A negative value set the +paragraph width relative to the right margin. +.IP +Also see $wrap. + + +.TP +.B reply_regexp +.nf +Type: regular expression (localized) +Default: \(lq^(re)(\\[[0\-9]+\\])*:[ \\t]*\(rq +.fi +.IP +A regular expression used to recognize reply messages when +threading and replying. The default value corresponds to the +standard Latin \(rqRe:\(rq prefix. +.IP +This value may have been localized by the translator for your +locale, adding other prefixes that are common in the locale. You +can add your own prefixes by appending inside \fB\(rq^(re)\(rq\fP. For +example: \fB\(rq^(re|se)\(rq\fP or \fB\(rq^(re|aw|se)\(rq\fP. +.IP +The second parenthesized expression matches zero or more +bracketed numbers following the prefix, such as \fB\(rqRe[1]: \(rq\fP. +The initial \fB\(rq\\\\[\(rq\fP means a literal left\-bracket character. +Note the backslash must be doubled when used inside a double +quoted string in the muttrc. \fB\(rq[0\-9]+\(rq\fP means one or more +numbers. \fB\(rq\\\\]\(rq\fP means a literal right\-bracket. Finally the +whole parenthesized expression has a \fB\(rq*\(rq\fP suffix, meaning it +can occur zero or more times. +.IP +The last part matches a colon followed by an optional space or +tab. Note \fB\(rq\\t\(rq\fP is converted to a literal tab inside a +double quoted string. If you use a single quoted string, you +would have to type an actual tab character, and would need to +convert the double\-backslashes to single backslashes. +.IP +Note: the result of this regexp match against the subject is +stored in the header cache. Mutt isn't smart enough to +invalidate a header cache entry based on changing $reply_regexp, +so if you aren't seeing correct values in the index, try +temporarily turning off the header cache. If that fixes the +problem, then once the variable is set to your liking, remove +your stale header cache files and turn the header cache back on. + + +.TP +.B reply_self +.nf +Type: boolean +Default: no +.fi +.IP +If \fIunset\fP and you are replying to a message sent by you, Mutt will +assume that you want to reply to the recipients of that message rather +than to yourself. +.IP +Also see the \(lqalternates\(rq command. + + +.TP +.B reply_to +.nf +Type: quadoption +Default: ask\-yes +.fi +.IP +If \fIset\fP, when replying to a message, Mutt will use the address listed +in the Reply\-to: header as the recipient of the reply. If \fIunset\fP, +it will use the address in the From: header field instead. This +option is useful for reading a mailing list that sets the Reply\-To: +header field to the list address and you want to send a private +message to the author of a message. + + +.TP +.B resolve +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, the cursor will be automatically advanced to the next +(possibly undeleted) message whenever a command that modifies the +current message is executed. + + +.TP +.B resume_draft_files +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, draft files (specified by \fB\-H\fP on the command +line) are processed similarly to when resuming a postponed +message. Recipients are not prompted for; send\-hooks are not +evaluated; no alias expansion takes place; user\-defined headers +and signatures are not added to the message. + + +.TP +.B resume_edited_draft_files +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, draft files previously edited (via \fB\-E \-H\fP on +the command line) will have $resume_draft_files automatically +set when they are used as a draft file again. +.IP +The first time a draft file is saved, mutt will add a header, +X\-Mutt\-Resume\-Draft to the saved file. The next time the draft +file is read in, if mutt sees the header, it will set +$resume_draft_files. +.IP +This option is designed to prevent multiple signatures, +user\-defined headers, and other processing effects from being +made multiple times to the draft file. + + +.TP +.B reverse_alias +.nf +Type: boolean +Default: no +.fi +.IP +This variable controls whether or not Mutt will display the \(lqpersonal\(rq +name from your aliases in the index menu if it finds an alias that +matches the message's sender. For example, if you have the following +alias: + +.IP +.EX +alias juser abd30425@somewhere.net (Joe User) + +.EE +.IP +and then you receive mail which contains the following header: + +.IP +.EX +From: abd30425@somewhere.net + +.EE +.IP +It would be displayed in the index menu as \(lqJoe User\(rq instead of +\(lqabd30425@somewhere.net.\(rq This is useful when the person's e\-mail +address is not human friendly. + + +.TP +.B reverse_name +.nf +Type: boolean +Default: no +.fi +.IP +It may sometimes arrive that you receive mail to a certain machine, +move the messages to another machine, and reply to some the messages +from there. If this variable is \fIset\fP, the default \fIFrom:\fP line of +the reply messages is built using the address where you received the +messages you are replying to \fBif\fP that address matches your +\(lqalternates\(rq. If the variable is \fIunset\fP, or the address that would be +used doesn't match your \(lqalternates\(rq, the \fIFrom:\fP line will use +your address on the current machine. +.IP +Also see the \(lqalternates\(rq command and $reverse_realname. + + +.TP +.B reverse_realname +.nf +Type: boolean +Default: yes +.fi +.IP +This variable fine\-tunes the behavior of the $reverse_name feature. +.IP +When it is \fIunset\fP, Mutt will remove the real name part of a +matching address. This allows the use of the email address +without having to also use what the sender put in the real name +field. +.IP +When it is \fIset\fP, Mutt will use the matching address as\-is. +.IP +In either case, a missing real name will be filled in afterwards +using the value of $realname. + + +.TP +.B rfc2047_parameters +.nf +Type: boolean +Default: yes +.fi +.IP +When this variable is \fIset\fP, Mutt will decode RFC2047\-encoded MIME +parameters. You want to set this variable when mutt suggests you +to save attachments to files named like: + +.IP +.EX +=?iso\-8859\-1?Q?file=5F=E4=5F991116=2Ezip?= + +.EE +.IP +When this variable is \fIset\fP interactively, the change won't be +active until you change folders. +.IP +Note that this use of RFC2047's encoding is explicitly +prohibited by the standard, but nevertheless encountered in the +wild. +.IP +Also note that setting this parameter will \fInot\fP have the effect +that mutt \fIgenerates\fP this kind of encoding. Instead, mutt will +unconditionally use the encoding specified in RFC2231. + + +.TP +.B save_address +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, mutt will take the sender's full address when choosing a +default folder for saving a mail. If $save_name or $force_name +is \fIset\fP too, the selection of the Fcc folder will be changed as well. + + +.TP +.B save_empty +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIunset\fP, mailboxes which contain no saved messages will be removed +when closed (the exception is $spoolfile which is never removed). +If \fIset\fP, mailboxes are never removed. +.IP +\fBNote:\fP This only applies to mbox and MMDF folders, Mutt does not +delete MH and Maildir directories. + + +.TP +.B save_history +.nf +Type: number +Default: 0 +.fi +.IP +This variable controls the size of the history (per category) saved in the +$history_file file. + + +.TP +.B save_name +.nf +Type: boolean +Default: no +.fi +.IP +This variable controls how copies of outgoing messages are saved. +When \fIset\fP, a check is made to see if a mailbox specified by the +recipient address exists (this is done by searching for a mailbox in +the $folder directory with the \fIusername\fP part of the +recipient address). If the mailbox exists, the outgoing message will +be saved to that mailbox, otherwise the message is saved to the +$record mailbox. +.IP +Also see the $force_name variable. + + +.TP +.B score +.nf +Type: boolean +Default: yes +.fi +.IP +When this variable is \fIunset\fP, scoring is turned off. This can +be useful to selectively disable scoring for certain folders when the +$score_threshold_delete variable and related are used. + + +.TP +.B score_threshold_delete +.nf +Type: number +Default: \-1 +.fi +.IP +Messages which have been assigned a score equal to or lower than the value +of this variable are automatically marked for deletion by mutt. Since +mutt scores are always greater than or equal to zero, the default setting +of this variable will never mark a message for deletion. + + +.TP +.B score_threshold_flag +.nf +Type: number +Default: 9999 +.fi +.IP +Messages which have been assigned a score greater than or equal to this +variable's value are automatically marked \(rqflagged\(rq. + + +.TP +.B score_threshold_read +.nf +Type: number +Default: \-1 +.fi +.IP +Messages which have been assigned a score equal to or lower than the value +of this variable are automatically marked as read by mutt. Since +mutt scores are always greater than or equal to zero, the default setting +of this variable will never mark a message read. + + +.TP +.B search_context +.nf +Type: number +Default: 0 +.fi +.IP +For the pager, this variable specifies the number of lines shown +before search results. By default, search results will be top\-aligned. + + +.TP +.B send_charset +.nf +Type: string +Default: \(lqus\-ascii:iso\-8859\-1:utf\-8\(rq +.fi +.IP +A colon\-delimited list of character sets for outgoing messages. Mutt will use the +first character set into which the text can be converted exactly. +If your $charset is not \(lqiso\-8859\-1\(rq and recipients may not +understand \(lqUTF\-8\(rq, it is advisable to include in the list an +appropriate widely used standard character set (such as +\(lqiso\-8859\-2\(rq, \(lqkoi8\-r\(rq or \(lqiso\-2022\-jp\(rq) either instead of or after +\(lqiso\-8859\-1\(rq. +.IP +In case the text cannot be converted into one of these exactly, +mutt uses $charset as a fallback. + + +.TP +.B send_multipart_alternative +.nf +Type: quadoption +Default: no +.fi +.IP +If \fIset\fP, Mutt will generate a multipart/alternative +container and an alternative part using the filter script specified in +$send_multipart_alternative_filter. +See the section \(lqMIME Multipart/Alternative\(rq (alternative-order). +.IP +Note that enabling multipart/alternative is not compatible with inline +PGP encryption. Mutt will prompt to use PGP/MIME in that case. + + +.TP +.B send_multipart_alternative_filter +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +This specifies a filter script, which will convert the main +(composed) message of the email to an alternative format. The +message will be piped to the filter's stdin. The expected output +of the filter is the generated mime type, e.g. text/html, +followed by a blank line, and then the converted content. +See the section \(lqMIME Multipart/Alternative\(rq (alternative-order). + + +.TP +.B sendmail +.nf +Type: path +Default: \(lq/usr/sbin/sendmail \-oem \-oi\(rq +.fi +.IP +Specifies the program and arguments used to deliver mail sent by Mutt. +Mutt expects that the specified program interprets additional +arguments as recipient addresses. Mutt appends all recipients after +adding a \fB\-\-\fP delimiter (if not already present). Additional +flags, such as for $use_8bitmime, $use_envelope_from, +$dsn_notify, or $dsn_return will be added before the delimiter. +.IP +\fBNote:\fP This command is invoked differently from most other +commands in Mutt. It is tokenized by space, and invoked directly +via \fBexecvp(3)\fP with an array of arguments \- so commands or +arguments with spaces in them are not supported. The shell is +not used to run the command, so shell quoting is also not +supported. +.IP +\fBSee also:\fP $write_bcc. + + +.TP +.B sendmail_wait +.nf +Type: number +Default: 0 +.fi +.IP +Specifies the number of seconds to wait for the $sendmail process +to finish before giving up and putting delivery in the background. +.IP +Mutt interprets the value of this variable as follows: +.RS +.PD 0 +.TP +>0 +number of seconds to wait for sendmail to finish before continuing +.TP +0 +wait forever for sendmail to finish +.TP +<0 +always put sendmail in the background without waiting +.RE +.PD 1 +.IP +Note that if you specify a value other than 0, the output of the child +process will be put in a temporary file. If there is some error, you +will be informed as to where to find the output. + + +.TP +.B shell +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +Command to use when spawning a subshell. By default, the user's login +shell from \fB/etc/passwd\fP is used. + + +.TP +.B sidebar_delim_chars +.nf +Type: string +Default: \(lq/.\(rq +.fi +.IP +This contains the list of characters which you would like to treat +as folder separators for displaying paths in the sidebar. +.IP +Local mail is often arranged in directories: `dir1/dir2/mailbox'. + +.IP +.EX +set sidebar_delim_chars='/' + +.EE +.IP +IMAP mailboxes are often named: `folder1.folder2.mailbox'. + +.IP +.EX +set sidebar_delim_chars='.' + +.EE +.IP +\fBSee also:\fP $sidebar_short_path, $sidebar_folder_indent, $sidebar_indent_string. + + +.TP +.B sidebar_divider_char +.nf +Type: string +Default: \(lq|\(rq +.fi +.IP +This specifies the characters to be drawn between the sidebar (when +visible) and the other Mutt panels. ASCII and Unicode line\-drawing +characters are supported. + + +.TP +.B sidebar_folder_indent +.nf +Type: boolean +Default: no +.fi +.IP +Set this to indent mailboxes in the sidebar. +.IP +\fBSee also:\fP $sidebar_short_path, $sidebar_indent_string, $sidebar_delim_chars. + + +.TP +.B sidebar_format +.nf +Type: string +Default: \(lq%B%* %n\(rq +.fi +.IP +This variable allows you to customize the sidebar display. This string is +similar to $index_format, but has its own set of \fBprintf(3)\fP\-like +sequences: +.RS +.PD 0 +.TP +%B +Name of the mailbox +.TP +%S +* Size of mailbox (total number of messages) +.TP +%N +* Number of unread messages in the mailbox +.TP +%n +N if mailbox has new mail, blank otherwise +.TP +%F +* Number of Flagged messages in the mailbox +.TP +%! +\(lq!\(rq : one flagged message; +\(lq!!\(rq : two flagged messages; +\(lqn!\(rq : n flagged messages (for n > 2). +Otherwise prints nothing. +.TP +%d +* @ Number of deleted messages +.TP +%L +* @ Number of messages after limiting +.TP +%t +* @ Number of tagged messages +.TP +%>X +right justify the rest of the string and pad with \(lqX\(rq +.TP +%|X +pad to the end of the line with \(lqX\(rq +.TP +%*X +soft\-fill with character \(lqX\(rq as pad +.RE +.PD 1 +.IP +* = Can be optionally printed if nonzero +@ = Only applicable to the current folder +.IP +In order to use %S, %N, %F, and %!, $mail_check_stats must +be \fIset\fP. When thus set, a suggested value for this option is +\(rq%B%?F? [%F]?%* %?N?%N/?%S\(rq. + + +.TP +.B sidebar_indent_string +.nf +Type: string +Default: \(lq \(rq +.fi +.IP +This specifies the string that is used to indent mailboxes in the sidebar. +It defaults to two spaces. +.IP +\fBSee also:\fP $sidebar_short_path, $sidebar_folder_indent, $sidebar_delim_chars. + + +.TP +.B sidebar_new_mail_only +.nf +Type: boolean +Default: no +.fi +.IP +When set, the sidebar will only display mailboxes containing new, or +flagged, mail. +.IP +\fBSee also:\fP sidebar_whitelist. + + +.TP +.B sidebar_next_new_wrap +.nf +Type: boolean +Default: no +.fi +.IP +When set, the \fB\fP command will not stop and the end of +the list of mailboxes, but wrap around to the beginning. The +\fB\fP command is similarly affected, wrapping around to +the end of the list. + + +.TP +.B sidebar_relative_shortpath_indent +.nf +Type: boolean +Default: no +.fi +.IP +When set, this option changes how $sidebar_short_path and +$sidebar_folder_indent perform shortening and indentation: both +will look at the previous sidebar entries and shorten/indent +relative to the most recent parent. +.IP +An example of this option set/unset for mailboxes listed in this +order, with $sidebar_short_path=yes, +$sidebar_folder_indent=yes, and $sidebar_indent_string=\(rq→\(rq: +.RS +.PD 0 +.TP +\fBmailbox\fP +\fBset\fP +\fBunset\fP +.TP +\fB=a.b\fP +\fB=a.b\fP +\fB→b\fP +.TP +\fB=a.b.c.d\fP +\fB→c.d\fP +\fB→→→d\fP +.TP +\fB=a.b.e\fP +\fB→e\fP +\fB→→e\fP +.RE +.PD 1 +.IP +The second line illustrates most clearly. With this option set, +\fB=a.b.c.d\fP is shortened relative to \fB=a.b\fP, becoming +\fBc.d\fP; it is also indented one place relative to \fB=a.b\fP. +With this option unset \fB=a.b.c.d\fP is always shortened to the +last part of the mailbox, \fBd\fP and is indented three places, +with respect to $folder (represented by '='). +.IP +When set, the third line will also be indented and shortened +relative to the first line. + + +.TP +.B sidebar_short_path +.nf +Type: boolean +Default: no +.fi +.IP +By default the sidebar will show the mailbox's path, relative to the +$folder variable. Setting \fBsidebar_shortpath=yes\fP will shorten the +names relative to the previous name. Here's an example: +.RS +.PD 0 +.TP +\fBshortpath=no\fP +\fBshortpath=yes\fP +\fBshortpath=yes, folderindent=yes, indentstr=\(rq..\(rq\fP +.TP +\fBfruit\fP +\fBfruit\fP +\fBfruit\fP +.TP +\fBfruit.apple\fP +\fBapple\fP +\fB..apple\fP +.TP +\fBfruit.banana\fP +\fBbanana\fP +\fB..banana\fP +.TP +\fBfruit.cherry\fP +\fBcherry\fP +\fB..cherry\fP +.RE +.PD 1 +.IP +\fBSee also:\fP $sidebar_delim_chars, $sidebar_folder_indent, $sidebar_indent_string. + + +.TP +.B sidebar_sort_method +.nf +Type: sort order +Default: unsorted +.fi +.IP +Specifies how to sort mailbox entries in the sidebar. By default, the +entries are sorted alphabetically. Valid values: +.RS +.PD 0 +.TP +\(hy alpha (alphabetically) +.TP +\(hy count (all message count) +.TP +\(hy flagged (flagged message count) +.TP +\(hy name (alphabetically) +.TP +\(hy new (unread message count) +.TP +\(hy path (alphabetically) +.TP +\(hy unread (unread message count) +.TP +\(hy unsorted +.RE +.PD 1 +.IP +You may optionally use the \(lqreverse\-\(rq prefix to specify reverse sorting +order (example: \(lq\fBset sidebar_sort_method=reverse\-alpha\fP\(rq). + + +.TP +.B sidebar_use_mailbox_shortcuts +.nf +Type: boolean +Default: no +.fi +.IP +When set, sidebar mailboxes will be displayed with mailbox shortcut prefixes +\(rq=\(rq or \(rq~\(rq. +.IP +When unset, the sidebar will trim off a matching $folder prefix +but otherwise not use mailbox shortcuts. + + +.TP +.B sidebar_visible +.nf +Type: boolean +Default: no +.fi +.IP +This specifies whether or not to show sidebar. The sidebar shows a list of +all your mailboxes. +.IP +\fBSee also:\fP $sidebar_format, $sidebar_width + + +.TP +.B sidebar_width +.nf +Type: number +Default: 30 +.fi +.IP +This controls the width of the sidebar. It is measured in screen columns. +For example: sidebar_width=20 could display 20 ASCII characters, or 10 +Chinese characters. + + +.TP +.B sig_dashes +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, a line containing \(lq\-\- \(rq (note the trailing space) will be inserted before your +$signature. It is \fBstrongly\fP recommended that you not \fIunset\fP +this variable unless your signature contains just your name. The +reason for this is because many software packages use \(lq\-\- \\n\(rq to +detect your signature. For example, Mutt has the ability to highlight +the signature in a different color in the built\-in pager. + + +.TP +.B sig_on_top +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, the signature will be included before any quoted or forwarded +text. It is \fBstrongly\fP recommended that you do not set this variable +unless you really know what you are doing, and are prepared to take +some heat from netiquette guardians. + + +.TP +.B signature +.nf +Type: path +Default: \(lq~/.signature\(rq +.fi +.IP +Specifies the filename of your signature, which is appended to all +outgoing messages. If the filename ends with a pipe (\(lq|\(rq), it is +assumed that filename is a shell command and input should be read from +its standard output. + + +.TP +.B simple_search +.nf +Type: string +Default: \(lq~f %s | ~s %s\(rq +.fi +.IP +Specifies how Mutt should expand a simple search into a real search +pattern. A simple search is one that does not contain any of the \(lq~\(rq pattern +modifiers. See \(lqpatterns\(rq for more information on search patterns. +.IP +For example, if you simply type \(lqjoe\(rq at a search or limit prompt, Mutt +will automatically expand it to the value specified by this variable by +replacing \(lq%s\(rq with the supplied string. +For the default value, \(lqjoe\(rq would be expanded to: \(lq~f joe | ~s joe\(rq. + + +.TP +.B size_show_bytes +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, message sizes will display bytes for values less than +1 kilobyte. See formatstrings-size. + + +.TP +.B size_show_fractions +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, message sizes will be displayed with a single decimal value +for sizes from 0 to 10 kilobytes and 1 to 10 megabytes. +See formatstrings-size. + + +.TP +.B size_show_mb +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP, message sizes will display megabytes for values greater than +or equal to 1 megabyte. See formatstrings-size. + + +.TP +.B size_units_on_left +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, message sizes units will be displayed to the left of the number. +See formatstrings-size. + + +.TP +.B sleep_time +.nf +Type: number +Default: 1 +.fi +.IP +Specifies time, in seconds, to pause while displaying certain informational +messages, while moving from folder to folder and after expunging +messages from the current folder. The default is to pause one second, so +a value of zero for this option suppresses the pause. + + +.TP +.B smart_wrap +.nf +Type: boolean +Default: yes +.fi +.IP +Controls the display of lines longer than the screen width in the +internal pager. If \fIset\fP, long lines are wrapped at a word boundary. If +\fIunset\fP, lines are simply wrapped at the screen edge. Also see the +$markers variable. + + +.TP +.B smileys +.nf +Type: regular expression +Default: \(lq(>From )|(:[\-^]?[][)(><}{|/DP])\(rq +.fi +.IP +The \fIpager\fP uses this variable to catch some common false +positives of $quote_regexp, most notably smileys and not consider +a line quoted text if it also matches $smileys. This mostly +happens at the beginning of a line. + + +.TP +.B smime_ask_cert_label +.nf +Type: boolean +Default: yes +.fi +.IP +This flag controls whether you want to be asked to enter a label +for a certificate about to be added to the database or not. It is +\fIset\fP by default. +(S/MIME only) + + +.TP +.B smime_ca_location +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +This variable contains the name of either a directory, or a file which +contains trusted certificates for use with OpenSSL. +(S/MIME only) + + +.TP +.B smime_certificates +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +Since for S/MIME there is no pubring/secring as with PGP, mutt has to handle +storage and retrieval of keys by itself. This is very basic right +now, and keys and certificates are stored in two different +directories, both named as the hash\-value retrieved from +OpenSSL. There is an index file which contains mailbox\-address +keyid pairs, and which can be manually edited. This option points to +the location of the certificates. +(S/MIME only) + + +.TP +.B smime_decrypt_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This format string specifies a command which is used to decrypt +\fBapplication/x\-pkcs7\-mime\fP attachments. +.IP +The OpenSSL command formats have their own set of \fBprintf(3)\fP\-like sequences +similar to PGP's: +.RS +.PD 0 +.TP +%f +Expands to the name of a file containing a message. +.TP +%s +Expands to the name of a file containing the signature part + of a \fBmultipart/signed\fP attachment when verifying it. +.TP +%k +The key\-pair specified with $smime_default_key +.TP +%c +One or more certificate IDs. +.TP +%a +The algorithm used for encryption. +.TP +%d +The message digest algorithm specified with $smime_sign_digest_alg. +.TP +%C +CA location: Depending on whether $smime_ca_location + points to a directory or file, this expands to + \(lq\-CApath $smime_ca_location\(rq or \(lq\-CAfile $smime_ca_location\(rq. +.RE +.PD 1 +.IP +For examples on how to configure these formats, see the \fBsmime.rc\fP in +the \fBsamples/\fP subdirectory which has been installed on your system +alongside the documentation. +(S/MIME only) + + +.TP +.B smime_decrypt_use_default_key +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP (default) this tells mutt to use the default key for decryption. Otherwise, +if managing multiple certificate\-key\-pairs, mutt will try to use the mailbox\-address +to determine the key to use. It will ask you to supply a key, if it can't find one. +(S/MIME only) + + +.TP +.B smime_default_key +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This is the default key\-pair to use for S/MIME operations, and must be +set to the keyid (the hash\-value that OpenSSL generates) to work properly. +.IP +It will be used for encryption (see $postpone_encrypt and +$smime_self_encrypt). If GPGME is enabled, this is the key id displayed +by gpgsm. +.IP +It will be used for decryption unless $smime_decrypt_use_default_key +is \fIunset\fP. +.IP +It will also be used for signing unless $smime_sign_as is set. +.IP +The (now deprecated) \fIsmime_self_encrypt_as\fP is an alias for this +variable, and should no longer be used. +(S/MIME only) + + +.TP +.B smime_encrypt_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to create encrypted S/MIME messages. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_encrypt_with +.nf +Type: string +Default: \(lqaes256\(rq +.fi +.IP +This sets the algorithm that should be used for encryption. +Valid choices are \(lqaes128\(rq, \(lqaes192\(rq, \(lqaes256\(rq, \(lqdes\(rq, \(lqdes3\(rq, \(lqrc2\-40\(rq, \(lqrc2\-64\(rq, \(lqrc2\-128\(rq. +(S/MIME only) + + +.TP +.B smime_get_cert_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to extract X509 certificates from a PKCS7 structure. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_get_cert_email_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to extract the mail address(es) used for storing +X509 certificates, and for verification purposes (to check whether the +certificate was issued for the sender's mailbox). +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_get_signer_cert_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to extract only the signers X509 certificate from a S/MIME +signature, so that the certificate's owner may get compared to the +email's \(lqFrom:\(rq field. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_import_cert_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to import a certificate via smime_keys. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_is_default +.nf +Type: boolean +Default: no +.fi +.IP +The default behavior of mutt is to use PGP on all auto\-sign/encryption +operations. To override and to use OpenSSL instead this must be \fIset\fP. +However, this has no effect while replying, since mutt will automatically +select the same application that was used to sign/encrypt the original +message. (Note that this variable can be overridden by unsetting $crypt_autosmime.) +(S/MIME only) + + +.TP +.B smime_keys +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +Since for S/MIME there is no pubring/secring as with PGP, mutt has to handle +storage and retrieval of keys/certs by itself. This is very basic right now, +and stores keys and certificates in two different directories, both +named as the hash\-value retrieved from OpenSSL. There is an index file +which contains mailbox\-address keyid pair, and which can be manually +edited. This option points to the location of the private keys. +(S/MIME only) + + +.TP +.B smime_pk7out_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to extract PKCS7 structures of S/MIME signatures, +in order to extract the public X509 certificate(s). +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_self_encrypt +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, S/MIME encrypted messages will also be encrypted +using the certificate in $smime_default_key. +(S/MIME only) + + +.TP +.B smime_sign_as +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +If you have a separate key to use for signing, you should set this +to the signing key. Most people will only need to set $smime_default_key. +(S/MIME only) + + +.TP +.B smime_sign_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to created S/MIME signatures of type +\fBmultipart/signed\fP, which can be read by all mail clients. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. NOTE: %c and %k will default +to $smime_sign_as if set, otherwise $smime_default_key. +(S/MIME only) + + +.TP +.B smime_sign_digest_alg +.nf +Type: string +Default: \(lqsha256\(rq +.fi +.IP +This sets the algorithm that should be used for the signature message digest. +Valid choices are \(lqmd5\(rq, \(lqsha1\(rq, \(lqsha224\(rq, \(lqsha256\(rq, \(lqsha384\(rq, \(lqsha512\(rq. +(S/MIME only) + + +.TP +.B smime_sign_opaque_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to created S/MIME signatures of type +\fBapplication/x\-pkcs7\-signature\fP, which can only be handled by mail +clients supporting the S/MIME extension. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_timeout +.nf +Type: number (long) +Default: 300 +.fi +.IP +The number of seconds after which a cached passphrase will expire if +not used. +(S/MIME only) + + +.TP +.B smime_verify_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to verify S/MIME signatures of type \fBmultipart/signed\fP. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smime_verify_opaque_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This command is used to verify S/MIME signatures of type +\fBapplication/x\-pkcs7\-mime\fP. +.IP +This is a format string, see the $smime_decrypt_command command for +possible \fBprintf(3)\fP\-like sequences. +(S/MIME only) + + +.TP +.B smtp_authenticators +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +This is a colon\-delimited list of authentication methods mutt may +attempt to use to log in to an SMTP server, in the order mutt should +try them. Authentication methods are any SASL mechanism, e.g. +\(lqdigest\-md5\(rq, \(lqgssapi\(rq or \(lqcram\-md5\(rq. +This option is case\-insensitive. If it is \(lqunset\(rq +(the default) mutt will try all available methods, in order from +most\-secure to least\-secure. +.IP +Example: + +.IP +.EX +set smtp_authenticators=\(rqdigest\-md5:cram\-md5\(rq + +.EE + + +.TP +.B smtp_oauth_refresh_command +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +The command to run to generate an OAUTH refresh token for +authorizing your connection to your SMTP server. This command will be +run on every connection attempt that uses the OAUTHBEARER authentication +mechanism. See \(lqoauth\(rq for details. + + +.TP +.B smtp_pass +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Specifies the password for your SMTP account. If \fIunset\fP, Mutt will +prompt you for your password when you first send mail via SMTP. +See $smtp_url to configure mutt to send mail via SMTP. +.IP +\fBWarning\fP: you should only use this option when you are on a +fairly secure machine, because the superuser can read your muttrc even +if you are the only one who can read the file. + + +.TP +.B smtp_url +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Defines the SMTP smarthost where sent messages should relayed for +delivery. This should take the form of an SMTP URL, e.g.: + +.IP +.EX +smtp[s]://[user[:pass]@]host[:port] + +.EE +.IP +where \(lq[...]\(rq denotes an optional part. +Setting this variable overrides the value of the $sendmail +variable. +.IP +Also see $write_bcc. + + +.TP +.B sort +.nf +Type: sort order +Default: date +.fi +.IP +Specifies how to sort messages in the \(lqindex\(rq menu. Valid values +are: +.RS +.PD 0 +.TP +\(hy date or date\-sent +.TP +\(hy date\-received +.TP +\(hy from +.TP +\(hy mailbox\-order (unsorted) +.TP +\(hy score +.TP +\(hy size +.TP +\(hy spam +.TP +\(hy subject +.TP +\(hy threads +.TP +\(hy to +.RE +.PD 1 +.IP +You may optionally use the \(lqreverse\-\(rq prefix to specify reverse sorting +order (example: \(lq\fBset sort=reverse\-date\-sent\fP\(rq). +.IP +For values except \(lqthreads\(rq, this provides the primary sort +method. When two message sort values are equal, $sort_aux will +be used for a secondary sort. +.IP +When set to \(lqthreads\(rq, Mutt threads messages in the index. It +uses the variable $sort_thread_groups to sort between threads +(at the top/root level), and $sort_aux to sort sub\-threads and +children. + + +.TP +.B sort_alias +.nf +Type: sort order +Default: alias +.fi +.IP +Specifies how the entries in the \(lqalias\(rq menu are sorted. The +following are legal values: +.RS +.PD 0 +.TP +\(hy address (sort alphabetically by email address) +.TP +\(hy alias (sort alphabetically by alias name) +.TP +\(hy unsorted (leave in order specified in .muttrc) +.RE +.PD 1 + +.TP +.B sort_aux +.nf +Type: sort order +Default: date +.fi +.IP +For non\-threaded mode, this provides a secondary sort for +messages in the \(lqindex\(rq menu, used when the $sort value is +equal for two messages. +.IP +When sorting by threads, this variable controls how the branches +of the thread trees are sorted. This can be set to any value +that $sort can, except \(lqthreads\(rq (in that case, mutt will just +use \(lqdate\-sent\(rq). You can also specify the \(lqlast\-\(rq prefix in +addition to the \(lqreverse\-\(rq prefix, but \(lqlast\-\(rq must come +after \(lqreverse\-\(rq. The \(lqlast\-\(rq prefix causes messages to be +sorted against its siblings by which has the last descendant, +using the rest of $sort_aux as an ordering. For instance, + +.IP +.EX +set sort_aux=last\-date\-received + +.EE +.IP +would mean that if a new message is received in a sub\-thread, +that sub\-thread becomes the last one displayed. +.IP +Note: For reversed\-threads $sort +order, $sort_aux is reversed again (which is not the right thing to do, +but kept to not break any existing configuration setting). + + +.TP +.B sort_browser +.nf +Type: sort order +Default: alpha +.fi +.IP +Specifies how to sort entries in the file browser. By default, the +entries are sorted alphabetically. Valid values: +.RS +.PD 0 +.TP +\(hy alpha (alphabetically) +.TP +\(hy count +.TP +\(hy date +.TP +\(hy size +.TP +\(hy unread +.TP +\(hy unsorted +.RE +.PD 1 +.IP +You may optionally use the \(lqreverse\-\(rq prefix to specify reverse sorting +order (example: \(lq\fBset sort_browser=reverse\-date\fP\(rq). + + +.TP +.B sort_browser_mailboxes +.nf +Type: sort order +Default: unsorted +.fi +.IP +Specifies how to sort entries in the mailbox browser. By default, the +entries are unsorted, displayed in the same order as listed +in the \(lqmailboxes\(rq command. Valid values: +.RS +.PD 0 +.TP +\(hy alpha (alphabetically) +.TP +\(hy count +.TP +\(hy date +.TP +\(hy size +.TP +\(hy unread +.TP +\(hy unsorted +.RE +.PD 1 +.IP +You may optionally use the \(lqreverse\-\(rq prefix to specify reverse sorting +order (example: \(lq\fBset sort_browser_mailboxes=reverse\-alpha\fP\(rq). + + +.TP +.B sort_re +.nf +Type: boolean +Default: yes +.fi +.IP +This variable is only useful when sorting by threads with +$strict_threads \fIunset\fP. In that case, it changes the heuristic +mutt uses to thread messages by subject. With $sort_re \fIset\fP, mutt will +only attach a message as the child of another message by subject if +the subject of the child message starts with a substring matching the +setting of $reply_regexp. With $sort_re \fIunset\fP, mutt will attach +the message whether or not this is the case, as long as the +non\-$reply_regexp parts of both messages are identical. + + +.TP +.B sort_thread_groups +.nf +Type: sort order +Default: aux +.fi +.IP +When sorting by threads, this variable controls how threads are +sorted in relation to other threads (at the top/root level). +This can be set to any value that $sort can, except \(lqthreads\(rq. +You can also specify the \(lqlast\-\(rq prefix in addition to the +\(lqreverse\-\(rq prefix, but \(lqlast\-\(rq must come after \(lqreverse\-\(rq. +The \(lqlast\-\(rq prefix causes messages to be sorted against its +siblings by which has the last descendant, using the rest of +$sort_thread_groups as an ordering. +.IP +For backward compatibility, the default value is \(lqaux\(rq, which +means to use $sort_aux for top\-level thread sorting too. The +value \(lqaux\(rq does not respect \(lqlast\-\(rq or \(lqreverse\-\(rq +prefixes, it simply delegates sorting directly to $sort_aux. +.IP +Note: For reversed\-threads $sort order, $sort_thread_groups is +reversed again (which is not the right thing to do, but kept to +not break any existing configuration setting). + + +.TP +.B spam_separator +.nf +Type: string +Default: \(lq,\(rq +.fi +.IP +This variable controls what happens when multiple spam headers +are matched: if \fIunset\fP, each successive header will overwrite any +previous matches value for the spam label. If \fIset\fP, each successive +match will append to the previous, using this variable's value as a +separator. + + +.TP +.B spoolfile +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +If your spool mailbox is in a non\-default place where Mutt cannot find +it, you can specify its location with this variable. Mutt will +initially set this variable to the value of the environment +variable \fB$MAIL\fP or \fB$MAILDIR\fP if either is defined. + + +.TP +.B ssl_ca_certificates_file +.nf +Type: path +Default: \(lq/etc/ssl/certs/ca\-bundle.crt\(rq +.fi +.IP +This variable specifies a file containing trusted CA certificates. +Any server certificate that is signed with one of these CA +certificates is also automatically accepted. (GnuTLS only) +.IP +Example: + +.IP +.EX +set ssl_ca_certificates_file=/etc/ssl/certs/ca\-certificates.crt + +.EE + + +.TP +.B ssl_client_cert +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +The file containing a client certificate and its associated private +key. + + +.TP +.B ssl_force_tls +.nf +Type: boolean +Default: yes +.fi +.IP +If this variable is \fIset\fP, Mutt will require that all connections +to remote servers be encrypted. Furthermore it will attempt to +negotiate TLS even if the server does not advertise the capability, +since it would otherwise have to abort the connection anyway. This +option supersedes $ssl_starttls. + + +.TP +.B ssl_min_dh_prime_bits +.nf +Type: number +Default: 0 +.fi +.IP +This variable specifies the minimum acceptable prime size (in bits) +for use in any Diffie\-Hellman key exchange. A value of 0 will use +the default from the GNUTLS library. (GnuTLS only) + + +.TP +.B ssl_starttls +.nf +Type: quadoption +Default: yes +.fi +.IP +If \fIset\fP (the default), mutt will attempt to use \fBSTARTTLS\fP on servers +advertising the capability. When \fIunset\fP, mutt will not attempt to +use \fBSTARTTLS\fP regardless of the server's capabilities. +.IP +\fBNote\fP that \fBSTARTTLS\fP is subject to many kinds of +attacks, including the ability of a machine\-in\-the\-middle to +suppress the advertising of support. Setting $ssl_force_tls is +recommended if you rely on \fBSTARTTLS\fP. + + +.TP +.B ssl_use_sslv2 +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP , Mutt will use SSLv2 when communicating with servers that +request it. \fBN.B. As of 2011, SSLv2 is considered insecure, and using +is inadvisable. See https://tools.ietf.org/html/rfc6176 .\fP +(OpenSSL only) + + +.TP +.B ssl_use_sslv3 +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP , Mutt will use SSLv3 when communicating with servers that +request it. \fBN.B. As of 2015, SSLv3 is considered insecure, and using +it is inadvisable. See https://tools.ietf.org/html/rfc7525 .\fP + + +.TP +.B ssl_use_tlsv1 +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP , Mutt will use TLSv1.0 when communicating with servers that +request it. \fBN.B. As of 2015, TLSv1.0 is considered insecure, and using +it is inadvisable. See https://tools.ietf.org/html/rfc7525 .\fP + + +.TP +.B ssl_use_tlsv1_1 +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP , Mutt will use TLSv1.1 when communicating with servers that +request it. \fBN.B. As of 2015, TLSv1.1 is considered insecure, and using +it is inadvisable. See https://tools.ietf.org/html/rfc7525 .\fP + + +.TP +.B ssl_use_tlsv1_2 +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP , Mutt will use TLSv1.2 when communicating with servers that +request it. + + +.TP +.B ssl_use_tlsv1_3 +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP , Mutt will use TLSv1.3 when communicating with servers that +request it. + + +.TP +.B ssl_usesystemcerts +.nf +Type: boolean +Default: yes +.fi +.IP +If set to \fIyes\fP, mutt will use CA certificates in the +system\-wide certificate store when checking if a server certificate +is signed by a trusted CA. (OpenSSL only) + + +.TP +.B ssl_verify_dates +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP (the default), mutt will not automatically accept a server +certificate that is either not yet valid or already expired. You should +only unset this for particular known hosts, using the +\fB\fP function. + + +.TP +.B ssl_verify_host +.nf +Type: boolean +Default: yes +.fi +.IP +If \fIset\fP (the default), mutt will not automatically accept a server +certificate whose host name does not match the host used in your folder +URL. You should only unset this for particular known hosts, using +the \fB\fP function. + + +.TP +.B ssl_verify_host_override +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Defines an alternate host name to verify the server certificate against. +This should not be set unless you are sure what you are doing, but it +might be useful for connection to a .onion host without a properly +configured host name in the certificate. See $ssl_verify_host. + + +.TP +.B ssl_verify_partial_chains +.nf +Type: boolean +Default: no +.fi +.IP +This option should not be changed from the default unless you understand +what you are doing. +.IP +Setting this variable to \fIyes\fP will permit verifying partial +certification chains, i. e. a certificate chain where not the root, +but an intermediate certificate CA, or the host certificate, are +marked trusted (in $certificate_file), without marking the root +signing CA as trusted. +.IP +(OpenSSL 1.0.2b and newer only). + + +.TP +.B ssl_ciphers +.nf +Type: string +Default: \(lq@SYSTEM\(rq +.fi +.IP +Contains a colon\-separated list of ciphers to use when using SSL. +For OpenSSL, see ciphers(1) for the syntax of the string. +.IP +For GnuTLS, this option will be used in place of \(rqNORMAL\(rq at the +start of the priority string. See gnutls_priority_init(3) for the +syntax and more details. (Note: GnuTLS version 2.1.7 or higher is +required.) + + +.TP +.B status_chars +.nf +Type: string +Default: \(lq\-*%A\(rq +.fi +.IP +Controls the characters used by the \(lq%r\(rq indicator in +$status_format. The first character is used when the mailbox is +unchanged. The second is used when the mailbox has been changed, and +it needs to be resynchronized. The third is used if the mailbox is in +read\-only mode, or if the mailbox will not be written when exiting +that mailbox (You can toggle whether to write changes to a mailbox +with the \fB\fP operation, bound by default to \(lq%\(rq). The fourth +is used to indicate that the current folder has been opened in attach\- +message mode (Certain operations like composing a new mail, replying, +forwarding, etc. are not permitted in this mode). + + +.TP +.B status_format +.nf +Type: string (localized) +Default: \(lq\-%r\-Mutt: %f [Msgs:%?M?%M/?%m%?n? New:%n?%?o? Old:%o?%?d? Del:%d?%?F? Flag:%F?%?t? Tag:%t?%?p? Post:%p?%?b? Inc:%b?%?B? Back:%B?%?l? %l?]\-\-\-(%s/%?T?%T/?%S)\-%>\-(%P)\-\-\-\(rq +.fi +.IP +Controls the format of the status line displayed in the \(lqindex\(rq +menu. This string is similar to $index_format, but has its own +set of \fBprintf(3)\fP\-like sequences: +.RS +.PD 0 +.TP +%b +number of mailboxes with new mail * +.TP +%B +number of backgrounded editing sessions * +.TP +%d +number of deleted messages * +.TP +%f +the full pathname of the current mailbox +.TP +%F +number of flagged messages * +.TP +%h +local hostname +.TP +%l +size (in bytes) of the current mailbox (see formatstrings-size) * +.TP +%L +size (in bytes) of the messages shown +(i.e., which match the current limit) (see formatstrings-size) * +.TP +%m +the number of messages in the mailbox * +.TP +%M +the number of messages shown (i.e., which match the current limit) * +.TP +%n +number of new messages in the mailbox * +.TP +%o +number of old unread messages * +.TP +%p +number of postponed messages * +.TP +%P +percentage of the way through the index +.TP +%r +modified/read\-only/won't\-write/attach\-message indicator, +according to $status_chars +.TP +%R +number of read messages * +.TP +%s +current sorting mode ($sort) +.TP +%S +current aux sorting method ($sort_aux) +.TP +%t +number of tagged messages * +.TP +%T +current thread group sorting method ($sort_thread_groups) * +.TP +%u +number of unread messages * +.TP +%v +Mutt version string +.TP +%V +currently active limit pattern, if any * +.TP +%>X +right justify the rest of the string and pad with \(lqX\(rq +.TP +%|X +pad to the end of the line with \(lqX\(rq +.TP +%*X +soft\-fill with character \(lqX\(rq as pad +.RE +.PD 1 +.IP +For an explanation of \(lqsoft\-fill\(rq, see the $index_format documentation. +.IP +* = can be optionally printed if nonzero +.IP +Some of the above sequences can be used to optionally print a string +if their value is nonzero. For example, you may only want to see the +number of flagged messages if such messages exist, since zero is not +particularly meaningful. To optionally print a string based upon one +of the above sequences, the following construct is used: +.IP +\fB%???\fP +.IP +where \fIsequence_char\fP is a character from the table above, and +\fIoptional_string\fP is the string you would like printed if +\fIsequence_char\fP is nonzero. \fIoptional_string\fP \fBmay\fP contain +other sequences as well as normal text, but you may \fBnot\fP nest +optional strings. +.IP +Here is an example illustrating how to optionally print the number of +new messages in a mailbox: +.IP +\fB%?n?%n new messages.?\fP +.IP +You can also switch between two strings using the following construct: +.IP +\fB%??&?\fP +.IP +If the value of \fIsequence_char\fP is non\-zero, \fIif_string\fP will +be expanded, otherwise \fIelse_string\fP will be expanded. +.IP +You can force the result of any \fBprintf(3)\fP\-like sequence to be lowercase +by prefixing the sequence character with an underscore (\(lq_\(rq) sign. +For example, if you want to display the local hostname in lowercase, +you would use: \(lq\fB%_h\fP\(rq. +.IP +If you prefix the sequence character with a colon (\(lq:\(rq) character, mutt +will replace any dots in the expansion by underscores. This might be helpful +with IMAP folders that don't like dots in folder names. + + +.TP +.B status_on_top +.nf +Type: boolean +Default: no +.fi +.IP +Setting this variable causes the \(lqstatus bar\(rq to be displayed on +the first line of the screen rather than near the bottom. If $help +is \fIset\fP, too it'll be placed at the bottom. + + +.TP +.B strict_threads +.nf +Type: boolean +Default: no +.fi +.IP +If \fIset\fP, threading will only make use of the \(lqIn\-Reply\-To\(rq and +\(lqReferences:\(rq fields when you $sort by message threads. By +default, messages with the same subject are grouped together in +\(lqpseudo threads.\(rq. This may not always be desirable, such as in a +personal mailbox where you might have several unrelated messages with +the subjects like \(lqhi\(rq which will get grouped together. See also +$sort_re for a less drastic way of controlling this +behavior. + + +.TP +.B suspend +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIunset\fP, mutt won't stop when the user presses the terminal's +\fIsusp\fP key, usually \(lq^Z\(rq. This is useful if you run mutt +inside an xterm using a command like \(lq\fBxterm \-e mutt\fP\(rq. + + +.TP +.B text_flowed +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will generate \(lqformat=flowed\(rq bodies with a content type +of \(lq\fBtext/plain; format=flowed\fP\(rq. +This format is easier to handle for some mailing software, and generally +just looks like ordinary text. To actually make use of this format's +features, you'll need support in your editor. +.IP +The option only controls newly composed messages. Postponed messages, +resent messages, and draft messages (via \-H on the command line) will +use the content\-type of the source message. +.IP +Note that $indent_string is ignored when this option is \fIset\fP. + + +.TP +.B thorough_search +.nf +Type: boolean +Default: yes +.fi +.IP +Affects the \fB~b\fP, \fB~B\fP, and \fB~h\fP search operations described in +section \(lqpatterns\(rq. If \fIset\fP, the headers and body/attachments of +messages to be searched are decoded before searching. If \fIunset\fP, +messages are searched as they appear in the folder. +.IP +Users searching attachments or for non\-ASCII characters should \fIset\fP +this value because decoding also includes MIME parsing/decoding and possible +character set conversions. Otherwise mutt will attempt to match against the +raw message received (for example quoted\-printable encoded or with encoded +headers) which may lead to incorrect search results. + + +.TP +.B thread_received +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt uses the date received rather than the date sent +to thread messages by subject. + + +.TP +.B tilde +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, the internal\-pager will pad blank lines to the bottom of the +screen with a tilde (\(lq~\(rq). + + +.TP +.B time_inc +.nf +Type: number +Default: 0 +.fi +.IP +Along with $read_inc, $write_inc, and $net_inc, this +variable controls the frequency with which progress updates are +displayed. It suppresses updates less than $time_inc milliseconds +apart. This can improve throughput on systems with slow terminals, +or when running mutt on a remote system. +.IP +Also see the \(lqtuning\(rq section of the manual for performance considerations. + + +.TP +.B timeout +.nf +Type: number +Default: 600 +.fi +.IP +When Mutt is waiting for user input either idling in menus or +in an interactive prompt, Mutt would block until input is +present. Depending on the context, this would prevent certain +operations from working, like checking for new mail or keeping +an IMAP connection alive. +.IP +This variable controls how many seconds Mutt will at most wait +until it aborts waiting for input, performs these operations and +continues to wait for input. +.IP +A value of zero or less will cause Mutt to never time out. + + +.TP +.B tmpdir +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +This variable allows you to specify where Mutt will place its +temporary files needed for displaying and composing messages. If +this variable is not set, the environment variable \fB$TMPDIR\fP is +used. If \fB$TMPDIR\fP is not set then \(lq\fB/tmp\fP\(rq is used. + + +.TP +.B to_chars +.nf +Type: string +Default: \(lq +TCFL\(rq +.fi +.IP +Controls the character used to indicate mail addressed to you. The +first character is the one used when the mail is \fInot\fP addressed to your +address. The second is used when you are the only +recipient of the message. The third is when your address +appears in the \(lqTo:\(rq header field, but you are not the only recipient of +the message. The fourth character is used when your +address is specified in the \(lqCc:\(rq header field, but you are not the only +recipient. The fifth character is used to indicate mail that was sent +by \fIyou\fP. The sixth character is used to indicate when a mail +was sent to a mailing\-list you subscribe to. + + +.TP +.B trash +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +If set, this variable specifies the path of the trash folder where the +mails marked for deletion will be moved, instead of being irremediably +purged. +.IP +NOTE: When you delete a message in the trash folder, it is really +deleted, so that you have a way to clean the trash. + + +.TP +.B ts_icon_format +.nf +Type: string (localized) +Default: \(lqM%?n?AIL&ail?\(rq +.fi +.IP +Controls the format of the icon title, as long as \(lq$ts_enabled\(rq is set. +This string is identical in formatting to the one used by +\(lq$status_format\(rq. + + +.TP +.B ts_enabled +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether mutt tries to set the terminal status line and icon name. +Most terminal emulators emulate the status line in the window title. + + +.TP +.B ts_status_format +.nf +Type: string (localized) +Default: \(lqMutt with %?m?%m messages&no messages?%?n? [%n NEW]?\(rq +.fi +.IP +Controls the format of the terminal status line (or window title), +provided that \(lq$ts_enabled\(rq has been set. This string is identical in +formatting to the one used by \(lq$status_format\(rq. + + +.TP +.B tunnel +.nf +Type: string +Default: \(lq\(rq +.fi +.IP +Setting this variable will cause mutt to open a pipe to a command +instead of a raw socket. You may be able to use this to set up +preauthenticated connections to your IMAP/POP3/SMTP server. Example: + +.IP +.EX +set tunnel=\(rqssh \-q mailhost.net /usr/local/libexec/imapd\(rq + +.EE +.IP +Note: For this example to work you must be able to log in to the remote +machine without having to enter a password. +.IP +When set, Mutt uses the tunnel for all remote connections. +Please see \(lqaccount-hook\(rq in the manual for how to use different +tunnel commands per connection. + + +.TP +.B tunnel_is_secure +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will assume the $tunnel connection does not need +STARTTLS to be enabled. It will also allow IMAP PREAUTH server +responses inside a tunnel to proceed. This is appropriate if $tunnel +uses ssh or directly invokes the server locally. +.IP +When \fIunset\fP, Mutt will negotiate STARTTLS according to the +ssl_starttls and ssl_force_tls variables. If ssl_force_tls is +set, Mutt will abort connecting if an IMAP server responds with PREAUTH. +This setting is appropriate if $tunnel does not provide security and +could be tampered with by attackers. + + +.TP +.B uncollapse_jump +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, Mutt will jump to the next unread message, if any, +when the current thread is \fIun\fPcollapsed. + + +.TP +.B uncollapse_new +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will automatically uncollapse any collapsed +thread that receives a newly delivered message. When +\fIunset\fP, collapsed threads will remain collapsed. The +presence of the newly delivered message will still affect index +sorting, though. + + +.TP +.B use_8bitmime +.nf +Type: boolean +Default: no +.fi +.IP +\fBWarning:\fP do not set this variable unless you are using a version +of sendmail which supports the \fB\-B8BITMIME\fP flag (such as sendmail +8.8.x) or you may not be able to send mail. +.IP +When \fIset\fP, Mutt will invoke $sendmail with the \fB\-B8BITMIME\fP +flag when sending 8\-bit messages to enable ESMTP negotiation. + + +.TP +.B use_domain +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will qualify all local addresses (ones without the +\(lq@host\(rq portion) with the value of $hostname. If \fIunset\fP, no +addresses will be qualified. + + +.TP +.B use_envelope_from +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will set the \fIenvelope\fP sender of the message. +If $envelope_from_address is \fIset\fP, it will be used as the sender +address. If \fIunset\fP, mutt will attempt to derive the sender from the +\(lqFrom:\(rq header. +.IP +Note that this information is passed to sendmail command using the +\fB\-f\fP command line switch. Therefore setting this option is not useful +if the $sendmail variable already contains \fB\-f\fP or if the +executable pointed to by $sendmail doesn't support the \fB\-f\fP switch. + + +.TP +.B use_from +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will generate the \(lqFrom:\(rq header field when +sending messages. If \fIunset\fP, no \(lqFrom:\(rq header field will be +generated unless the user explicitly sets one using the \(lqmy_hdr\(rq +command. + + +.TP +.B use_ipv6 +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, Mutt will look for IPv6 addresses of hosts it tries to +contact. If this option is \fIunset\fP, Mutt will restrict itself to IPv4 addresses. +Normally, the default should work. + + +.TP +.B user_agent +.nf +Type: boolean +Default: no +.fi +.IP +When \fIset\fP, mutt will add a \(lqUser\-Agent:\(rq header to outgoing +messages, indicating which version of mutt was used for composing +them. + + +.TP +.B visual +.nf +Type: path +Default: \(lq\(rq +.fi +.IP +Specifies the visual editor to invoke when the \(lq\fB~v\fP\(rq command is +given in the built\-in editor. + + +.TP +.B wait_key +.nf +Type: boolean +Default: yes +.fi +.IP +Controls whether Mutt will ask you to press a key after an external command +has been invoked by these functions: \fB\fP, +\fB\fP, \fB\fP, \fB\fP, +and \fB\fP commands. +.IP +It is also used when viewing attachments with \(lqauto_view\(rq, provided +that the corresponding mailcap entry has a \fIneedsterminal\fP flag, +and the external program is interactive. +.IP +When \fIset\fP, Mutt will always ask for a key. When \fIunset\fP, Mutt will wait +for a key only if the external command returned a non\-zero status. + + +.TP +.B weed +.nf +Type: boolean +Default: yes +.fi +.IP +When \fIset\fP, mutt will weed headers when displaying, forwarding, +or replying to messages. +.IP +Also see $copy_decode_weed, $pipe_decode_weed, $print_decode_weed. + + +.TP +.B wrap +.nf +Type: number +Default: 0 +.fi +.IP +When set to a positive value, mutt will wrap text at $wrap characters. +When set to a negative value, mutt will wrap text so that there are $wrap +characters of empty space on the right side of the terminal. Setting it +to zero makes mutt wrap at the terminal width. +.IP +Also see $reflow_wrap. + + +.TP +.B wrap_headers +.nf +Type: number +Default: 78 +.fi +.IP +This option specifies the number of characters to use for wrapping +an outgoing message's headers. Allowed values are between 78 and 998 +inclusive. +.IP +\fBNote:\fP This option usually shouldn't be changed. RFC5233 +recommends a line length of 78 (the default), so \fBplease only change +this setting when you know what you're doing\fP. + + +.TP +.B wrap_search +.nf +Type: boolean +Default: yes +.fi +.IP +Controls whether searches wrap around the end. +.IP +When \fIset\fP, searches will wrap around the first (or last) item. When +\fIunset\fP, incremental searches will not wrap. + + +.TP +.B wrapmargin +.nf +Type: number +Default: 0 +.fi +.IP +(DEPRECATED) Equivalent to setting $wrap with a negative value. + + +.TP +.B write_bcc +.nf +Type: boolean +Default: no +.fi +.IP +Controls whether mutt writes out the \(lqBcc:\(rq header when +preparing messages to be sent. Some MTAs, such as Exim and +Courier, do not strip the \(lqBcc:\(rq header; so it is advisable to +leave this unset unless you have a particular need for the header +to be in the sent message. +.IP +If mutt is set to deliver directly via SMTP (see $smtp_url), +this option does nothing: mutt will never write out the \(lqBcc:\(rq +header in this case. +.IP +Note this option only affects the sending of messages. Fcc'ed +copies of a message will always contain the \(lqBcc:\(rq header if +one exists. + + +.TP +.B write_inc +.nf +Type: number +Default: 10 +.fi +.IP +When writing a mailbox, a message will be printed every +$write_inc messages to indicate progress. If set to 0, only a +single message will be displayed before writing a mailbox. +.IP +Also see the $read_inc, $net_inc and $time_inc variables and the +\(lqtuning\(rq section of the manual for performance considerations. + + +.\" -*-nroff-*- +.SH SEE ALSO +.PP +.BR iconv (1), +.BR iconv (3), +.BR mailcap (5), +.BR maildir (5), +.BR mbox (5), +.BR mutt (1), +.BR printf (3), +.BR regex (7), +.BR strftime (3) +.PP +The Mutt Manual +.PP +The Mutt home page: http://www.mutt.org/ +.SH AUTHOR +.PP +Michael Elkins, and others. Use to contact +the developers. diff --git a/upstream/fedora-40/man5/nanorc.5 b/upstream/fedora-40/man5/nanorc.5 new file mode 100644 index 00000000..4416b7dd --- /dev/null +++ b/upstream/fedora-40/man5/nanorc.5 @@ -0,0 +1,1057 @@ +.\" Copyright (C) 2003-2011, 2013-2023 Free Software Foundation, Inc. +.\" +.\" This document is dual-licensed. You may distribute and/or modify it +.\" under the terms of either of the following licenses: +.\" +.\" * The GNU General Public License, as published by the Free Software +.\" Foundation, version 3 or (at your option) any later version. You +.\" should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" . +.\" +.\" * The GNU Free Documentation License, as published by the Free +.\" Software Foundation, version 1.2 or (at your option) any later +.\" version, with no Invariant Sections, no Front-Cover Texts, and no +.\" Back-Cover Texts. You should have received a copy of the GNU Free +.\" Documentation License along with this program. If not, see +.\" . +.\" +.TH NANORC 5 "version 7.2" "January 2023" + +.SH NAME +nanorc \- GNU nano's configuration file + +.SH DESCRIPTION +The \fInanorc\fP files contain the default settings for \fBnano\fP, +a small and friendly editor. During startup, if \fB\-\-rcfile\fR +is not given, \fBnano\fR will read two files: first the +system-wide settings, from \fI/etc/nanorc\fP (the exact path might be +different on your system), and then the user-specific settings, either +from \fI~/.nanorc\fR or from \fI$XDG_CONFIG_HOME/nano/nanorc\fR +or from \fI~/.config/nano/nanorc\fR, whichever is encountered first. +If \fB\-\-rcfile\fR is given, \fBnano\fR will read just the specified +settings file. + +.SH OPTIONS +The configuration file accepts a series of \fBset\fP and \fBunset\fP +commands, which can be used to configure nano on startup without using +command-line options. Additionally, there are some commands to define +syntax highlighting and to rebind keys -- see the two separate sections +on those. \fBnano\fP reads one command per line. +All commands and keywords should be written in lowercase. +.sp +Options in \fInanorc\fP files take precedence over nano's defaults, and +command-line options override \fInanorc\fP settings. Also, options that +do not take an argument are unset by default. So using the \fBunset\fR +command is only needed when wanting to override a setting of the system's +\fInanorc\fR file in your own \fInanorc\fR. Options that take an +argument cannot be unset. +.sp +Quotes inside the \fIcharacters\fR parameters below should not be escaped. +The last double quote on the line will be seen as the closing quote. +.sp +The supported commands and arguments are: +.TP 3 +.B set afterends +Make Ctrl+Right and Ctrl+Delete stop at word ends instead of beginnings. +.TP +.B set allow_insecure_backup +When backing up files, allow the backup to succeed even if its permissions +can't be (re)set due to special OS considerations. You should +NOT enable this option unless you are sure you need it. +.TP +.B set atblanks +When soft line wrapping is enabled, make it wrap lines at blank characters +(tabs and spaces) instead of always at the edge of the screen. +.TP +.B set autoindent +Automatically indent a newly created line to the same number of tabs +and/or spaces as the previous line (or as the next line if the previous +line is the beginning of a paragraph). +.TP +.B set backup +When saving a file, create a backup file by adding a tilde (\fB~\fP) to +the file's name. +.TP +.B set backupdir "\fIdirectory\fP" +Make and keep not just one backup file, but make and keep a uniquely +numbered one every time a file is saved -- when backups are enabled +with \fBset backup\fR or \fB\-\-backup\fR or \fB\-B\fR. +The uniquely numbered files are stored in the specified \fIdirectory\fR. +.TP +.B set boldtext +Use bold instead of reverse video for the title bar, status bar, key combos, +function tags, line numbers, and selected text. This can be overridden by +setting the options \fBtitlecolor\fP, \fBstatuscolor\fP, \fBkeycolor\fP, +\fBfunctioncolor\fP, \fBnumbercolor\fP, and \fBselectedcolor\fP. +.TP +.B set bookstyle +When justifying, treat any line that starts with whitespace as the +beginning of a paragraph (unless auto-indenting is on). +.TP +.BI "set brackets """ characters """ +Set the characters treated as closing brackets when justifying +paragraphs. This may not include blank characters. Only closing +punctuation (see \fBset punct\fP), optionally followed by the specified +closing brackets, can end sentences. The default value is "\fB\(dq')>]}\fR". +.TP +.B set breaklonglines +Automatically hard-wrap the current line when it becomes overlong. +.TP +.B set casesensitive +Do case-sensitive searches by default. +.TP +.B set constantshow +Constantly display the cursor position in the status bar. +This overrides the option \fBquickblank\fR. +.TP +.B set cutfromcursor +Use cut-from-cursor-to-end-of-line by default, instead of cutting the whole line. +.TP +.B set emptyline +Do not use the line below the title bar, leaving it entirely blank. +.TP +.B set errorcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the status bar when an error message is displayed. +The default value is \fBbold,white,red\fR. +See \fBset titlecolor\fR for valid color names. +.TP +.B set fill \fInumber\fR +Set the target width for justifying and automatic hard-wrapping at this +\fInumber\fR of columns. If the value is 0 or less, wrapping will occur +at the width of the screen minus \fInumber\fR columns, allowing the wrap +point to vary along with the width of the screen if the screen is resized. +The default value is \fB\-8\fR. +.TP +.B set functioncolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the concise function descriptions +in the two help lines at the bottom of the screen. +See \fBset titlecolor\fR for more details. +.TP +.B set guidestripe \fInumber +Draw a vertical stripe at the given column, to help judge the width of the +text. (The color of the stripe can be changed with \fBset stripecolor\fR.) +.TP +.B set historylog +Save the last hundred search strings and replacement strings and +executed commands, so they can be easily reused in later sessions. +.TP +.B set indicator +Display a "scrollbar" on the righthand side of the edit window. +It shows the position of the viewport in the buffer +and how much of the buffer is covered by the viewport. +.TP +.B set jumpyscrolling +Scroll the buffer contents per half-screen instead of per line. +.TP +.B set keycolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the shortcut key combos +in the two help lines at the bottom of the screen. +See \fBset titlecolor\fR for more details. +.TP +.B set linenumbers +Display line numbers to the left of the text area. +(Any line with an anchor additionally gets a mark in the margin.) +.TP +.B set locking +Enable vim-style lock-files for when editing files. +.TP +.B set magic +When neither the file's name nor its first line give a clue, +try using libmagic to determine the applicable syntax. +(Calling libmagic can be relatively time consuming. +It is therefore not done by default.) +.TP +.BI "set matchbrackets """ characters """ +Specify the opening and closing brackets that can be found by bracket +searches. This may not include blank characters. The opening set must +come before the closing set, and the two sets must be in the same order. +The default value is "\fB(<[{)>]}\fP". +.TP +.B set minibar +Suppress the title bar and instead show information about +the current buffer at the bottom of the screen, in the space +for the status bar. In this "minibar" the filename is shown +on the left, followed by an asterisk if the buffer has been modified. +On the right are displayed the current line and column number, the +code of the character under the cursor (in Unicode format: U+xxxx), +the same flags as are shown by \fBset stateflags\fR, and a percentage +that expresses how far the cursor is into the file (linewise). +When a file is loaded or saved, and also when switching between buffers, +the number of lines in the buffer is displayed after the filename. +This number is cleared upon the next keystroke, or replaced with an +[i/n] counter when multiple buffers are open. +The line plus column numbers and the character code are displayed only when +\fBset constantshow\fR is used, and can be toggled on and off with \fBM\-C\fR. +The state flags are displayed only when \fBset stateflags\fR is used. +.TP +.B set minicolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the minibar. +(When this option is not specified, the colors of the title bar are used.) +See \fBset titlecolor\fR for more details. +.TP +.B set mouse +Enable mouse support, if available for your system. When enabled, mouse +clicks can be used to place the cursor, set the mark (with a double +click), and execute shortcuts. The mouse will work in the X Window +System, and on the console when gpm is running. Text can still be +selected through dragging by holding down the Shift key. +.TP +.B set multibuffer +When reading in a file with \fB^R\fR, insert it into a new buffer by default. +.TP +.B set noconvert +Don't convert files from DOS/Mac format. +.TP +.B set nohelp +Don't display the two help lines at the bottom of the screen. +.TP +.B set nonewlines +Don't automatically add a newline when a text does not end with one. +(This can cause you to save non-POSIX text files.) +.TP +.B set nowrap +Deprecated option since it has become the default setting. +When needed, use \fBunset breaklonglines\fR instead. +.TP +.B set numbercolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for line numbers. +See \fBset titlecolor\fR for more details. +.TP +.B set operatingdir "\fIdirectory\fP" +\fBnano\fP will only read and write files inside \fIdirectory\fP and its +subdirectories. Also, the current directory is changed to here, so +files are inserted from this directory. By default, the operating +directory feature is turned off. +.TP +.B set positionlog +Save the cursor position of files between editing sessions. +The cursor position is remembered for the 200 most-recently edited files. +.TP +.B set preserve +Preserve the XON and XOFF keys (\fB^Q\fR and \fB^S\fR). +.TP +.B set promptcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the prompt bar. +(When this option is not specified, the colors of the title bar are used.) +See \fBset titlecolor\fR for more details. +.TP +.BI "set punct """ characters """ +Set the characters treated as closing punctuation when justifying +paragraphs. This may not include blank characters. Only the +specfified closing punctuation, optionally followed by closing brackets +(see \fBbrackets\fP), can end sentences. The default value is "\fB!.?\fP". +.TP +.B set quickblank +Make status-bar messages disappear after 1 keystroke instead of after 20. +Note that option \fBconstantshow\fR overrides this. +When option \fBminibar\fR or \fBzero\fR is in effect, +\fBquickblank\fR makes a message disappear after +0.8 seconds instead of after the default 1.5 seconds. +.TP +.BI "set quotestr """ regex """ +Set the regular expression for matching the quoting part of a line. +The default value is "\fB^([\ \\t]*([!#%:;>|}]|//))+\fP". +(Note that \fB\\t\fR stands for an actual Tab character.) +This makes it possible to rejustify blocks of quoted text when composing +email, and to rewrap blocks of line comments when writing source code. +.TP +.B set rawsequences +Interpret escape sequences directly, instead of asking \fBncurses\fR +to translate them. (If you need this option to get some keys to work +properly, it means that the terminfo terminal description that is used +does not fully match the actual behavior of your terminal. This can +happen when you ssh into a BSD machine, for example.) +Using this option disables \fBnano\fR's mouse support. +.TP +.B set rebinddelete +Interpret the Delete and Backspace keys differently so that both Backspace +and Delete work properly. You should only use this option when on your +system either Backspace acts like Delete or Delete acts like Backspace. +.TP +.B set regexp +Do regular-expression searches by default. +Regular expressions in \fBnano\fR are of the extended type (ERE). +.TP +.B set saveonexit +Save a changed buffer automatically on exit (\fB^X\fR); don't prompt. +.TP +.B set scrollercolor \fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the indicator alias "scrollbar". +(On terminal emulators that link to a libvte older than version 0.55, +using a background color here does not work correctly.) +See \fBset titlecolor\fR for more details. +.TP +.B set selectedcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for selected text. +See \fBset titlecolor\fR for more details. +.TP +.B set showcursor +Put the cursor on the highlighted item in the file browser, and show +the cursor in the help viewer, to aid braille users and people with +poor vision. +.TP +.B set smarthome +Make the Home key smarter. When Home is pressed anywhere but at the +very beginning of non-whitespace characters on a line, the cursor will +jump to that beginning (either forwards or backwards). If the cursor is +already at that position, it will jump to the true beginning of the +line. +.TP +.B set softwrap +Display lines that exceed the screen's width over multiple screen lines. +(You can make this soft-wrapping occur at whitespace instead of rudely at +the screen's edge, by using also \fBset atblanks\fR.) +.TP +.B set speller """\fIprogram\fR [\fIargument \fR...]\fB""" +Use the given \fIprogram\fR to do spell checking and correcting, instead of +using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1). +.TP +.B set spotlightcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for highlighting a search match. +The default value is \fBblack,lightyellow\fR. +See \fBset titlecolor\fR for valid color names. +.TP +.B set stateflags +Use the top-right corner of the screen for showing some state flags: +\fBI\fR when auto-indenting, \fBM\fR when the mark is on, \fBL\fR when +hard-wrapping (breaking long lines), \fBR\fR when recording a macro, +and \fBS\fR when soft-wrapping. +When the buffer is modified, a star (\fB*\fR) is shown after the +filename in the center of the title bar. +.TP +.B set statuscolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the status bar. +See \fBset titlecolor\fR for more details. +.TP +.B set stripecolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the vertical guiding stripe. +See \fBset titlecolor\fR for more details. +.TP +.B set tabsize \fInumber\fR +Use a tab size of \fInumber\fR columns. The value of \fInumber\fP must be +greater than 0. The default value is \fB8\fR. +.TP +.B set tabstospaces +Convert each typed tab to spaces -- to the number of spaces +that a tab at that position would take up. +.TP +.B set titlecolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the title bar. +Valid names for the foreground and background colors are: +.BR red ", " green ", " blue ", " magenta ", " yellow ", " cyan ", " +.BR white ", and " black . +Each of these eight names may be prefixed with the word \fBlight\fR +to get a brighter version of that color. +The word \fBgrey\fR or \fBgray\fR may be used +as a synonym for \fBlightblack\fR. +On terminal emulators that can do at least 256 colors, +other valid (but unprefixable) color names are: +.BR pink ", " purple ", " mauve ", " lagoon ", " mint ", " +.BR lime ", " peach ", " orange ", " latte ", " +.BR rosy ", " beet ", " plum ", " sea ", " sky ", " slate ", " +.BR teal ", " sage ", " brown ", " ocher ", " sand ", " tawny ", " +.BR brick ", " crimson ", and " normal +-- where \fBnormal\fR means the default foreground or background color. +On such emulators, the color may also be specified as a three-digit hexadecimal +number prefixed with \fB#\fR, with the digits representing the amounts of red, +green, and blue, respectively. This tells \fBnano\fR to select from the +available palette the color that approximates the given values. + +Either "\fIfgcolor\fR" or "\fB,\fIbgcolor\fR" may be left out, +and the pair may be preceded by \fBbold\fR and/or \fBitalic\fR +(separated by commas) to get a bold and/or slanting typeface, +if your terminal can do those. +.TP +.B set trimblanks +Remove trailing whitespace from wrapped lines when automatic +hard-wrapping occurs or when text is justified. +.TP +.B set unix +Save a file by default in Unix format. This overrides nano's +default behavior of saving a file in the format that it had. +(This option has no effect when you also use \fBset noconvert\fR.) +.TP +.BI "set whitespace """ characters """ +Set the two characters used to indicate the presence of tabs and +spaces. They must be single-column characters. The default pair +for a UTF-8 locale is "\fB\[Fc]\[md]\fR", and for other locales "\fB>.\fR". +.TP +.B set wordbounds +Detect word boundaries differently by treating punctuation +characters as parts of words. +.TP +.BI "set wordchars """ characters """ +Specify which other characters (besides the normal alphanumeric ones) +should be considered as parts of words. When using this option, you +probably want to unset \fBwordbounds\fR. +.TP +.B set zap +Let an unmodified Backspace or Delete erase the marked region +(instead of a single character, and without affecting the cutbuffer). +.TP +.B set zero +Hide all elements of the interface (title bar, status bar, and help lines) +and use all rows of the terminal for showing the contents of the buffer. +The status bar appears only when there is a significant message, +and disappears after 1.5 seconds or upon the next keystroke. +With \fBM\-Z\fR the title bar plus status bar can be toggled. +With \fBM\-X\fR the help lines. + +.SH NOTES +Option \fBset suspendable\fR has been removed. +Suspension is enabled by default, reachable via \fB^T^Z\fR. +(If you want a plain \fB^Z\fR to suspend nano, +add \fBbind ^Z suspend main\fR to your nanorc.) + +.SH SYNTAX HIGHLIGHTING +Coloring the different syntactic elements of a file +is done via regular expressions (see the \fBcolor\fR command below). +This is inherently imperfect, because regular expressions are not +powerful enough to fully parse a file. Nevertheless, regular +expressions can do a lot and are easy to make, so they are a +good fit for a small editor like \fBnano\fR. +.sp +All regular expressions in \fBnano\fR are POSIX extended regular expressions. +This means that \fB.\fR, \fB?\fR, \fB*\fR, \fB+\fR, \fB^\fR, \fB$\fR, and +several other characters are special. +The period \fB.\fR matches any single character, +\fB?\fR means the preceding item is optional, +\fB*\fR means the preceding item may be matched zero or more times, +\fB+\fR means the preceding item must be matched one or more times, +\fB^\fR matches the beginning of a line, and \fB$\fR the end, +\fB\\<\fR matches the start of a word, and \fB\\>\fR the end, +and \fB\\s\fR matches a blank. +It also means that lookahead and lookbehind are not possible. +A complete explanation can be found in the manual page of GNU grep: +\fBman grep\fR. +.sp +Each regular expression in a \fBnanorc\fR file should be wrapped in +double quotes (\fB""\fR). Multiple regular expressions can follow +each other on a line by separating them with blanks. This means that +a regular expression cannot contain a double quote followed by a blank. +When you need this combination inside a regular expression, +then either the double quote or the blank should be put +between square brackets (\fB[]\fR). +.sp +For each kind of file a separate syntax can be defined +via the following commands: +.TP +.BI syntax " name \fR[" """" fileregex """ " \fR...] +Start the definition of a syntax with this \fIname\fR. +All subsequent \fBcolor\fR and other such commands +will be added to this syntax, until a new \fBsyntax\fR +command is encountered. +.sp +When \fBnano\fR is run, this syntax will be automatically +activated if the current filename matches the extended regular +expression \fIfileregex\fR. Or the syntax can be explicitly +activated by using the \fB\-Y\fR or \fB\-\-syntax\fR +command-line option followed by the \fIname\fR. +.sp +The syntax \fBdefault\fP is special: it takes no \fIfileregex\fR, +and applies to files that don't match any syntax's regexes. +The syntax \fBnone\fP is reserved; specifying it on the command line +is the same as not having a syntax at all. +.TP +.BI "header """ regex """ \fR... +If from all defined syntaxes no \fIfileregex\fR matched, then compare +this \fIregex\fR (or regexes) against the first line of the current file, +to determine whether this syntax should be used for it. +.TP +.BI "magic """ regex """ \fR... +If no \fIfileregex\fR matched and no \fBheader\fR regex matched +either, then compare this \fIregex\fR (or regexes) against the +result of querying the \fBmagic\fP database about the current +file, to determine whether this syntax should be used for it. +(This functionality only works when \fBlibmagic\fP is installed on the +system and will be silently ignored otherwise.) +.TP +.BI formatter " program " \fR[ "argument " \fR...] +Run the given \fIprogram\fR on the full contents of the current buffer. +.TP +.BI linter " program " \fR[ "argument " \fR...] +Use the given \fIprogram\fR to run a syntax check on the current buffer. +.TP +.BI "comment """ string """ +Use the given \fIstring\fR for commenting and uncommenting lines. +If the string contains a vertical bar or pipe character (\fB|\fR), +this designates bracket-style comments; for example, "\fB/*|*/\fR" for +CSS files. The characters before the pipe are prepended to the line and the +characters after the pipe are appended at the end of the line. If no pipe +character is present, the full string is prepended; for example, "\fB#\fR" +for Python files. If empty double quotes are specified, the comment/uncomment +function is disabled; for example, "" for JSON. +The default value is "\fB#\fP". +.TP +.BI "tabgives """ string """ +Make the key produce the given \fIstring\fR. Useful for languages like +Python that want to see only spaces for indentation. +This overrides the setting of the \fBtabstospaces\fR option. +.TP +.BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR... +Paint all pieces of text that match the extended regular expression +\fIregex\fP with the given foreground and background colors, at least +one of which must be specified. Valid color names are: +.BR red ", " green ", " blue ", " magenta ", " yellow ", " cyan ", " +.BR white ", and " black . +Each of these eight names may be prefixed with the word \fBlight\fR +to get a brighter version of that color. +The word \fBgrey\fR or \fBgray\fR may be used +as a synonym for \fBlightblack\fR. +On terminal emulators that can do at least 256 colors, +other valid (but unprefixable) color names are: +.BR pink ", " purple ", " mauve ", " lagoon ", " mint ", " +.BR lime ", " peach ", " orange ", " latte ", " +.BR rosy ", " beet ", " plum ", " sea ", " sky ", " slate ", " +.BR teal ", " sage ", " brown ", " ocher ", " sand ", " tawny ", " +.BR brick ", " crimson ", and " normal +-- where \fBnormal\fR means the default foreground or background color. +On such emulators, the color may also be specified as a three-digit hexadecimal +number prefixed with \fB#\fR, with the digits representing the amounts of red, +green, and blue, respectively. This tells \fBnano\fR to select from the +available palette the color that approximates the given values. + +The color pair may be preceded by \fBbold\fR and/or \fBitalic\fR +(separated by commas) to get a bold and/or slanting typeface, +if your terminal can do those. +.sp +All coloring commands are applied in the order in which they are specified, +which means that later commands can recolor stuff that was colored earlier. +.TP +.BI "icolor \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR... +Same as above, except that the matching is case insensitive. +.TP +.BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " start=""" fromrx """ end=""" torx """ +Paint all pieces of text whose start matches extended regular expression +\fIfromrx\fP and whose end matches extended regular expression \fItorx\fP +with the given foreground and background colors, +at least one of which must be specified. This means that, after an +initial instance of \fIfromrx\fP, all text until the first instance of +\fItorx\fP will be colored. This allows syntax highlighting to span +multiple lines. +.TP +.BI "icolor \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " start=""" fromrx """ end=""" torx """ +Same as above, except that the matching is case insensitive. +.TP +.BI "include """ syntaxfile """ +Read in self-contained color syntaxes from \fIsyntaxfile\fP. Note that +\fIsyntaxfile\fP may contain only the above commands, from \fBsyntax\fP +to \fBicolor\fP. +.TP +.BI extendsyntax " name command argument " \fR... +Extend the syntax previously defined as \fIname\fR with another +\fIcommand\fR. This allows adding a new \fBcolor\fP, \fBicolor\fP, +\fBheader\fR, \fBmagic\fR, \fBformatter\fR, \fBlinter\fR, \fBcomment\fR, +or \fBtabgives\fR +command to an already defined syntax -- useful when you want to +slightly improve a syntax defined in one of the system-installed +files (which normally are not writable). + +.SH REBINDING KEYS +Key bindings can be changed via the following three commands: +.RS 3 +.TP +.BI bind " key function menu" +Rebinds the given \fIkey\fP to the given \fIfunction\fP in the given \fImenu\fP +(or in all menus where the function exists when \fBall\fP is used). +.TP +.BI bind " key " """" string """" " menu" +Makes the given \fIkey\fR produce the given \fIstring\fR in the given +\fImenu\fR (or in all menus where the key exists when \fBall\fR is used). +Besides literal text and/or control codes, the \fIstring\fR may contain +function names between braces. These functions will be invoked when +the key is typed. To include a literal opening brace, use \fB{{}\fR. +.TP +.BI unbind " key menu" +Unbinds the given \fIkey\fP from the given \fImenu\fP (or from all +menus where the key exists when \fBall\fP is used). +.RE +.sp +Note that \fBbind \fIkey\fR \fB"{\fIfunction\fB}"\fR \fImenu\fR is equivalent +to \fBbind \fIkey\fR \fIfunction\fR \fImenu\fR, except that for the latter form +\fBnano\fR will check the availabilty of the \fIfunction\fR in the given \fImenu\fR +at startup time (and report an error if it does not exist there), whereas for the +first form \fBnano\fR will check at execution time that the \fIfunction\fR exists +but not whether it makes any sense in the current menu. The user has to take care +that a function name between braces (or any sequence of them) is appropriate. +Strange behavior can result when it is not. + +.TP +The format of \fIkey\fP should be one of: +.RS 3 +.TP 7 +.BI ^ X +where \fIX\fR is a Latin letter, or one of several ASCII characters +(@, ], \\, ^, _), or the word "Space". +Example: ^C. +.TP +.BI M\- X +where \fIX\fR is any ASCII character except [, or the word "Space". +Example: M\-8. +.TP +.BI Sh\-M\- X +where \fIX\fR is a Latin letter. +Example: Sh\-M\-U. +By default, each Meta+letter keystroke does the same as the corresponding +Shift+Meta+letter. But when any Shift+Meta bind is made, that will +no longer be the case, for all letters. +.TP +.BI F N +where \fIN\fR is a numeric value from 1 to 24. +Example: F10. +(Often, \fBF13\fR to \fBF24\fR can be typed as \fBF1\fR to \fBF12\fR with Shift.) +.TP +.BR Ins " or " Del . +.RE +.sp +Rebinding \fB^M\fR (Enter) or \fB^I\fR (Tab) is probably not a good idea. +Rebinding \fB^[\fR (Esc) is not possible, because its keycode +is the starter byte of Meta keystrokes and escape sequences. +Rebinding any of the dedicated cursor-moving keys (the arrows, Home, End, +PageUp and PageDown) is not possible. +On some terminals it's not possible to rebind \fB^H\fR (unless \fB\-\-raw\fR +is used) because its keycode is identical to that of the Backspace key. + +.TP +Valid \fIfunction\fP names to be bound are: +.RS 3 +.TP 2 +.B help +Invokes the help viewer. +.TP +.B cancel +Cancels the current command. +.TP +.B exit +Exits from the program (or from the help viewer or file browser). +.TP +.B writeout +Writes the current buffer to disk, asking for a name. +.TP +.B savefile +Writes the current file to disk without prompting. +.TP +.B insert +Inserts a file into the current buffer (at the current cursor position), +or into a new buffer when option \fBmultibuffer\fR is set. +.TP +.B whereis +Starts a forward search for text in the current buffer -- or for filenames +matching a string in the current list in the file browser. +.TP +.B wherewas +Starts a backward search for text in the current buffer -- or for filenames +matching a string in the current list in the file browser. +.TP +.B findprevious +Searches the next occurrence in the backward direction. +.TP +.B findnext +Searches the next occurrence in the forward direction. +.TP +.B replace +Interactively replaces text within the current buffer. +.TP +.B cut +Cuts and stores the current line (or the marked region). +.TP +.B copy +Copies the current line (or the marked region) without deleting it. +.TP +.B paste +Pastes the currently stored text into the current buffer at the +current cursor position. +.TP +.B zap +Throws away the current line (or the marked region). +(This function is bound by default to .) +.TP +.B chopwordleft +Deletes from the cursor position to the beginning of the preceding word. +(This function is bound by default to . If your terminal +produces \fB^H\fR for , you can make delete +the word to the left of the cursor by rebinding \fB^H\fR to this function.) +.TP +.B chopwordright +Deletes from the cursor position to the beginning of the next word. +(This function is bound by default to .) +.TP +.B cutrestoffile +Cuts all text from the cursor position till the end of the buffer. +.TP +.B mark +Sets the mark at the current position, to start selecting text. +Or, when it is set, unsets the mark. +.TP +.B location +Reports the current position of the cursor in the buffer: +the line, column, and character positions. +.TP +.B wordcount +Counts and reports on the status bar the number of lines, words, +and characters in the current buffer (or in the marked region). +.TP +.B execute +Prompts for a program to execute. The program's output will be inserted +into the current buffer (or into a new buffer when \fBM\-F\fR is toggled). +.TP +.B speller +Invokes a spell-checking program, either the default \fBhunspell\fR(1) or GNU +\fBspell\fR(1), or the one defined by \fB\-\-speller\fR or \fBset speller\fR. +.TP +.B formatter +Invokes a full-buffer-processing program (if the active syntax defines one). +(The current buffer is written out to a temporary file, the program +is run on it, and then the temporary file is read back in, replacing +the contents of the buffer.) +.TP +.B linter +Invokes a syntax-checking program (if the active syntax defines one). +If this program produces lines of the form "filename:linenum:charnum: +some message", then the cursor will be put at the indicated position +in the mentioned file while showing "some message" on the status bar. +You can move from message to message with and , +and leave linting mode with \fB^C\fR or . +.TP +.B justify +Justifies the current paragraph (or the marked region). +A paragraph is a group of contiguous lines that, apart from possibly +the first line, all have the same indentation. The beginning of a +paragraph is detected by either this lone line with a differing +indentation or by a preceding blank line. +.TP +.B fulljustify +Justifies the entire current buffer (or the marked region). +.TP +.B indent +Indents (shifts to the right) the current line or the marked lines. +.TP +.B unindent +Unindents (shifts to the left) the current line or the marked lines. +.TP +.B comment +Comments or uncomments the current line or the marked lines, +using the comment style specified in the active syntax. +.TP +.B complete +Completes (when possible) the fragment before the cursor +to a full word found elsewhere in the current buffer. +.TP +.B left +Goes left one position (in the editor or browser). +.TP +.B right +Goes right one position (in the editor or browser). +.TP +.B up +Goes one line up (in the editor or browser). +.TP +.B down +Goes one line down (in the editor or browser). +.TP +.B scrollup +Scrolls the viewport up one row (meaning that the text slides down) +while keeping the cursor in the same text position, if possible. +(This function is bound by default to . +If does nothing on your Linux console, see the FAQ: +.UR https://nano\-editor.org/dist/latest/faq.html#4.1 +.UE .) +.TP +.B scrolldown +Scrolls the viewport down one row (meaning that the text slides up) +while keeping the cursor in the same text position, if possible. +(This function is bound by default to .) +.TP +.B center +Scrolls the line with the cursor to the middle of the screen. +.TP +.B prevword +Moves the cursor to the beginning of the previous word. +.TP +.B nextword +Moves the cursor to the beginning of the next word. +.TP +.B home +Moves the cursor to the beginning of the current line. +.TP +.B end +Moves the cursor to the end of the current line. +.TP +.B beginpara +Moves the cursor to the beginning of the current paragraph. +.TP +.B endpara +Moves the cursor to the end of the current paragraph. +.TP +.B prevblock +Moves the cursor to the beginning of the current or preceding block of text. +(Blocks are separated by one or more blank lines.) +.TP +.B nextblock +Moves the cursor to the beginning of the next block of text. +.TP +.B pageup +Goes up one screenful. +.TP +.B pagedown +Goes down one screenful. +.TP +.B firstline +Goes to the first line of the file. +.TP +.B lastline +Goes to the last line of the file. +.TP +.B gotoline +Goes to a specific line (and column if specified). Negative numbers count +from the end of the file (and end of the line). +.TP +.B findbracket +Moves the cursor to the bracket (or brace or parenthesis, etc.) that matches +(pairs) with the one under the cursor. See \fBset matchbrackets\fR. +.TP +.B anchor +Places an anchor at the current line, or removes it when already present. +(An anchor is visible when line numbers are activated.) +.TP +.B prevanchor +Goes to the first anchor before the current line. +.TP +.B nextanchor +Goes to the first anchor after the current line. +.TP +.B prevbuf +Switches to editing/viewing the previous buffer when multiple buffers are open. +.TP +.B nextbuf +Switches to editing/viewing the next buffer when multiple buffers are open. +.TP +.B verbatim +Inserts the next keystroke verbatim into the file, or begins Unicode input +when a hexadecimal digit is typed. +.TP +.B tab +Inserts a tab at the current cursor location. +.TP +.B enter +Inserts a new line below the current one. +.TP +.B delete +Deletes the character under the cursor. +.TP +.B backspace +Deletes the character before the cursor. +.TP +.B recordmacro +Starts the recording of keystrokes -- the keystrokes are stored +as a macro. When already recording, the recording is stopped. +.TP +.B runmacro +Replays the keystrokes of the last recorded macro. +.TP +.B undo +Undoes the last performed text action (add text, delete text, etc). +.TP +.B redo +Redoes the last undone action (i.e., it undoes an undo). +.TP +.B refresh +Refreshes the screen. +.TP +.B suspend +Suspends the editor and returns control to the shell +(until you tell the process to resume execution with \fBfg\fR). +.TP +.B casesens +Toggles whether searching/replacing ignores or respects the case of +the given characters. +.TP +.B regexp +Toggles whether searching/replacing uses literal strings or regular expressions. +.TP +.B backwards +Toggles whether searching/replacing goes forward or backward. +.TP +.B older +Retrieves the previous (earlier) entry at a prompt. +.TP +.B newer +Retrieves the next (later) entry at a prompt. +.TP +.B flipreplace +Toggles between searching for something and replacing something. +.TP +.B flipgoto +Toggles between searching for text and targeting a line number. +.TP +.B flipexecute +Toggles between inserting a file and executing a command. +.TP +.B flippipe +When executing a command, toggles whether the current buffer (or marked +region) is piped to the command. +.TP +.B flipnewbuffer +Toggles between inserting into the current buffer and into a new +empty buffer. +.TP +.B flipconvert +When reading in a file, toggles between converting and not converting +it from DOS/Mac format. Converting is the default. +.TP +.B dosformat +When writing a file, switches to writing a DOS format (CR/LF). +.TP +.B macformat +When writing a file, switches to writing a Mac format. +.TP +.B append +When writing a file, appends to the end instead of overwriting. +.TP +.B prepend +When writing a file, 'prepends' (writes at the beginning) instead of overwriting. +.TP +.B backup +When writing a file, creates a backup of the current file. +.TP +.B discardbuffer +When about to write a file, discard the current buffer without saving. +(This function is bound by default only when option \fB\-\-saveonexit\fR +is in effect.) +.TP +.B browser +Starts the file browser (in the Read File and Write Out menus), +allowing to select a file from a list. +.TP +.B gotodir +Goes to a directory to be specified, allowing to browse anywhere +in the filesystem. +.TP +.B firstfile +Goes to the first file in the list when using the file browser. +.TP +.B lastfile +Goes to the last file in the list when using the file browser. +.TP +.B nohelp +Toggles the presence of the two-line list of key bindings at the bottom of the screen. +(This toggle is special: it is available in all menus except the help viewer +and the linter. All further toggles are available in the main menu only.) +.TP +.B zero +Toggles the presence of title bar and status bar. +.TP +.B constantshow +Toggles the constant display of the current line, column, and character positions. +.TP +.B softwrap +Toggles the displaying of overlong lines on multiple screen lines. +.TP +.B linenumbers +Toggles the display of line numbers in front of the text. +.TP +.B whitespacedisplay +Toggles the showing of whitespace. +.TP +.B nosyntax +Toggles syntax highlighting. +.TP +.B smarthome +Toggles the smartness of the Home key. +.TP +.B autoindent +Toggles whether a newly created line will contain the same amount of leading +whitespace as the preceding line -- or as the next line if the preceding line +is the beginning of a paragraph. +.TP +.B cutfromcursor +Toggles whether cutting text will cut the whole line or just from the current cursor +position to the end of the line. +.TP +.B breaklonglines +Toggles whether long lines will be hard-wrapped to the next line. +(The old name of this function, 'nowrap', is deprecated.) +.TP +.B tabstospaces +Toggles whether typed tabs will be converted to spaces. +.TP +.B mouse +Toggles mouse support. +.RE + +.TP +Valid \fImenu\fP sections are: +.RS 3 +.TP 2 +.B main +The main editor window where text is entered and edited. +.TP +.B help +The help-viewer menu. +.TP +.B search +The search menu (AKA whereis). +.TP +.B replace +The 'search to replace' menu. +.TP +.B replacewith +The 'replace with' menu, which comes up after 'search to replace'. +.TP +.B yesno +The 'yesno' menu, where the Yes/No/All/Cancel question is asked. +.TP +.B gotoline +The 'goto line (and column)' menu. +.TP +.B writeout +The 'write file' menu. +.TP +.B insert +The 'insert file' menu. +.TP +.B browser +The 'file browser' menu, for selecting a file to be opened or +inserted or written to. +.TP +.B whereisfile +The 'search for a file' menu in the file browser. +.TP +.B gotodir +The 'go to directory' menu in the file browser. +.TP +.B execute +The menu for inserting the output from an external command, +or for filtering the buffer (or the marked region) through +an external command, or for executing one of several tools. +.TP +.B spell +The menu of the integrated spell checker where the user can edit a misspelled word. +.TP +.B linter +The linter menu, which allows jumping through the linting messages. +.TP +.B all +A special name that encompasses all menus. +For \fBbind\fR it means all menus where the specified \fIfunction\fR exists; +for \fBunbind\fR it means all menus where the specified \fIkey\fR exists. +.RE + +.SH FILES +.TP +.I /etc/nanorc +System-wide configuration file. +.TP +.IR ~/.nanorc " or " $XDG_CONFIG_HOME/nano/nanorc " or " ~/.config/nano/nanorc +Per-user configuration file. +.TP +.I /usr/share/nano/* +Syntax definitions for the syntax coloring of common file types +(and for less common file types in the \fIextra/\fR subdirectory). + +.SH SEE ALSO +.BR nano (1) +.TP +.I https://nano-editor.org/cheatsheet.html +An overview of the default key bindings. diff --git a/upstream/fedora-40/man5/networkd.conf.5 b/upstream/fedora-40/man5/networkd.conf.5 new file mode 100644 index 00000000..caead9da --- /dev/null +++ b/upstream/fedora-40/man5/networkd.conf.5 @@ -0,0 +1,269 @@ +'\" t +.TH "NETWORKD\&.CONF" "5" "" "systemd 255" "networkd.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +networkd.conf, networkd.conf.d \- Global Network configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/networkd\&.conf +.PP +/etc/systemd/networkd\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/networkd\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These configuration files control global network parameters\&. Currently the DHCP Unique Identifier (DUID)\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "[NETWORK] SECTION OPTIONS" +.PP +The following options are available in the [Network] section: +.PP +\fISpeedMeter=\fR +.RS 4 +Takes a boolean\&. If set to yes, then +\fBsystemd\-networkd\fR +measures the traffic of each interface, and +\fBnetworkctl status \fR\fB\fIINTERFACE\fR\fR +shows the measured speed\&. Defaults to no\&. +.sp +Added in version 244\&. +.RE +.PP +\fISpeedMeterIntervalSec=\fR +.RS 4 +Specifies the time interval to calculate the traffic speed of each interface\&. If +\fISpeedMeter=no\fR, the value is ignored\&. Defaults to 10sec\&. +.sp +Added in version 244\&. +.RE +.PP +\fIManageForeignRoutingPolicyRules=\fR +.RS 4 +A boolean\&. When true, +\fBsystemd\-networkd\fR +will remove rules that are not configured in \&.network files (except for rules with protocol +"kernel")\&. When false, it will not remove any foreign rules, keeping them even if they are not configured in a \&.network file\&. Defaults to yes\&. +.sp +Added in version 249\&. +.RE +.PP +\fIManageForeignRoutes=\fR +.RS 4 +A boolean\&. When true, +\fBsystemd\-networkd\fR +will remove routes that are not configured in \&.network files (except for routes with protocol +"kernel", +"dhcp" +when +\fIKeepConfiguration=\fR +is true or +"dhcp", and +"static" +when +\fIKeepConfiguration=\fR +is true or +"static")\&. When false, it will not remove any foreign routes, keeping them even if they are not configured in a \&.network file\&. Defaults to yes\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRouteTable=\fR +.RS 4 +Defines the route table name\&. Takes a whitespace\-separated list of the pairs of route table name and number\&. The route table name and number in each pair are separated with a colon, i\&.e\&., +"\fIname\fR:\fInumber\fR"\&. The route table name must not be +"default", +"main", or +"local", as these route table names are predefined with route table number 253, 254, and 255, respectively\&. The route table number must be an integer in the range 1\&...4294967295, except for predefined numbers 253, 254, and 255\&. This setting can be specified multiple times\&. If an empty string is specified, then the list specified earlier are cleared\&. Defaults to unset\&. +.sp +Added in version 248\&. +.RE +.PP +\fIIPv6PrivacyExtensions=\fR +.RS 4 +Specifies the default value for per\-network +\fIIPv6PrivacyExtensions=\fR\&. Takes a boolean or the special values +"prefer\-public" +and +"kernel"\&. See for details in +\fBsystemd.network\fR(5)\&. Defaults to +"no"\&. +.sp +Added in version 254\&. +.RE +.SH "[DHCPV4] SECTION OPTIONS" +.PP +This section configures the DHCP Unique Identifier (DUID) value used by DHCP protocol\&. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring a dynamic IPv4 address if +\fBClientIdentifier=duid\fR\&. IAID and DUID allows a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP address\&. To configure IAID and ClientIdentifier, see +\fBsystemd.network\fR(5)\&. +.PP +The following options are understood: +.PP +\fIDUIDType=\fR +.RS 4 +Specifies how the DUID should be generated\&. See +\m[blue]\fBRFC 3315\fR\m[]\&\s-2\u[1]\d\s+2 +for a description of all the options\&. +.sp +This takes an integer in the range 0\&...65535, or one of the following string values: +.PP +\fBvendor\fR +.RS 4 +If +"DUIDType=vendor", then the DUID value will be generated using +"43793" +as the vendor identifier (systemd) and hashed contents of +\fBmachine-id\fR(5)\&. This is the default if +\fIDUIDType=\fR +is not specified\&. +.sp +Added in version 230\&. +.RE +.PP +\fBuuid\fR +.RS 4 +If +"DUIDType=uuid", and +\fIDUIDRawData=\fR +is not set, then the product UUID is used as a DUID value\&. If a system does not have valid product UUID, then an application\-specific +\fBmachine-id\fR(5) +is used as a DUID value\&. About the application\-specific machine ID, see +\fBsd_id128_get_machine_app_specific\fR(3)\&. +.sp +Added in version 230\&. +.RE +.PP +\fBlink\-layer\-time[:\fR\fB\fITIME\fR\fR\fB]\fR, \fBlink\-layer\fR +.RS 4 +If +"link\-layer\-time" +or +"link\-layer" +is specified, then the MAC address of the interface is used as a DUID value\&. The value +"link\-layer\-time" +can take additional time value after a colon, e\&.g\&. +"link\-layer\-time:2018\-01\-23 12:34:56 UTC"\&. The default time value is +"2000\-01\-01 00:00:00 UTC"\&. +.sp +Added in version 240\&. +.RE +.sp +In all cases, +\fIDUIDRawData=\fR +can be used to override the actual DUID value that is used\&. +.sp +Added in version 230\&. +.RE +.PP +\fIDUIDRawData=\fR +.RS 4 +Specifies the DHCP DUID value as a single newline\-terminated, hexadecimal string, with each byte separated by +":"\&. The DUID that is sent is composed of the DUID type specified by +\fIDUIDType=\fR +and the value configured here\&. +.sp +The DUID value specified here overrides the DUID that +\fBsystemd-networkd.service\fR(8) +generates from the machine ID\&. To configure DUID per\-network, see +\fBsystemd.network\fR(5)\&. The configured DHCP DUID should conform to the specification in +\m[blue]\fBRFC 3315\fR\m[]\&\s-2\u[2]\d\s+2, +\m[blue]\fBRFC 6355\fR\m[]\&\s-2\u[3]\d\s+2\&. To configure IAID, see +\fBsystemd.network\fR(5)\&. +.PP +\fBExample\ \&1.\ \&A DUIDType=vendor with a custom value\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +DUIDType=vendor +DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00 +.fi +.if n \{\ +.RE +.\} +.sp +This specifies a 14 byte DUID, with the type DUID\-EN ("00:02"), enterprise number 43793 ("00:00:ab:11"), and identifier value +"f9:2a:c2:77:29:f9:5c:00"\&. + +Added in version 230\&. +.RE +.SH "[DHCPV6] SECTION OPTIONS" +.PP +This section configures the DHCP Unique Identifier (DUID) value used by DHCPv6 protocol\&. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface Identity Association Identifier (IAID) to a DHCPv6 server when acquiring a dynamic IPv6 address\&. IAID and DUID allows a DHCPv6 server to uniquely identify the machine and the interface requesting a DHCP IP address\&. To configure IAID, see +\fBsystemd.network\fR(5)\&. +.PP +The following options are understood: +.PP +\fIDUIDType=\fR, \fIDUIDRawData=\fR +.RS 4 +As in the [DHCPv4] section\&. +.sp +Added in version 249\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd.network\fR(5), +\fBsystemd-networkd.service\fR(8), +\fBmachine-id\fR(5), +\fBsd_id128_get_machine_app_specific\fR(3) +.SH "NOTES" +.IP " 1." 4 +RFC 3315 +.RS 4 +\%https://tools.ietf.org/html/rfc3315#section-9 +.RE +.IP " 2." 4 +RFC 3315 +.RS 4 +\%http://tools.ietf.org/html/rfc3315#section-9 +.RE +.IP " 3." 4 +RFC 6355 +.RS 4 +\%http://tools.ietf.org/html/rfc6355 +.RE diff --git a/upstream/fedora-40/man5/networks.5 b/upstream/fedora-40/man5/networks.5 new file mode 100644 index 00000000..f30ceef9 --- /dev/null +++ b/upstream/fedora-40/man5/networks.5 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001 Martin Schulze +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-09-04, mtk, taken from Debian downstream, with a few light edits +.\" +.TH networks 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +networks \- network name information +.SH DESCRIPTION +The file +.I /etc/networks +is a plain ASCII file that describes known DARPA networks and symbolic +names for these networks. +Each line represents a network and has the following structure: +.P +.RS +.I name number aliases ... +.RE +.P +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +The hash character (\fB#\fP) indicates the start of a comment: +this character, and the remaining characters up to +the end of the current line, +are ignored by library functions that process the file. +.P +The field descriptions are: +.TP +.I name +The symbolic name for the network. +Network names can contain any printable characters except +white-space characters or the comment character. +.TP +.I number +The official number for this network in numbers-and-dots notation (see +.BR inet (3)). +The trailing ".0" (for the host component of the network address) +may be omitted. +.TP +.I aliases +Optional aliases for the network. +.P +This file is read by the +.BR route (8) +and +.BR netstat (8) +utilities. +Only Class A, B, or C networks are supported, partitioned networks +(i.e., network/26 or network/28) are not supported by this file. +.SH FILES +.TP +.I /etc/networks +The networks definition file. +.SH SEE ALSO +.BR getnetbyaddr (3), +.BR getnetbyname (3), +.BR getnetent (3), +.BR netstat (8), +.BR route (8) diff --git a/upstream/fedora-40/man5/nfs.5 b/upstream/fedora-40/man5/nfs.5 new file mode 100644 index 00000000..7103d28e --- /dev/null +++ b/upstream/fedora-40/man5/nfs.5 @@ -0,0 +1,1968 @@ +.\"@(#)nfs.5" +.TH NFS 5 "9 October 2012" +.SH NAME +nfs \- fstab format and options for the +.B nfs +file systems +.SH SYNOPSIS +.I /etc/fstab +.SH DESCRIPTION +NFS is an Internet Standard protocol +created by Sun Microsystems in 1984. NFS was developed +to allow file sharing between systems residing +on a local area network. +Depending on kernel configuration, the Linux NFS client may +support NFS versions 3, 4.0, 4.1, or 4.2. +.P +The +.BR mount (8) +command attaches a file system to the system's +name space hierarchy at a given mount point. +The +.I /etc/fstab +file describes how +.BR mount (8) +should assemble a system's file name hierarchy +from various independent file systems +(including file systems exported by NFS servers). +Each line in the +.I /etc/fstab +file describes a single file system, its mount point, +and a set of default mount options for that mount point. +.P +For NFS file system mounts, a line in the +.I /etc/fstab +file specifies the server name, +the path name of the exported server directory to mount, +the local directory that is the mount point, +the type of file system that is being mounted, +and a list of mount options that control +the way the filesystem is mounted and +how the NFS client behaves when accessing +files on this mount point. +The fifth and sixth fields on each line are not used +by NFS, thus conventionally each contain the digit zero. For example: +.P +.nf +.ta 8n +14n +14n +9n +20n + server:path /mountpoint fstype option,option,... 0 0 +.fi +.P +The server's hostname and export pathname +are separated by a colon, while +the mount options are separated by commas. The remaining fields +are separated by blanks or tabs. +.P +The server's hostname can be an unqualified hostname, +a fully qualified domain name, +a dotted quad IPv4 address, or +an IPv6 address enclosed in square brackets. +Link-local and site-local IPv6 addresses must be accompanied by an +interface identifier. +See +.BR ipv6 (7) +for details on specifying raw IPv6 addresses. +.P +The +.I fstype +field contains "nfs". Use of the "nfs4" fstype in +.I /etc/fstab +is deprecated. +.SH "MOUNT OPTIONS" +Refer to +.BR mount (8) +for a description of generic mount options +available for all file systems. If you do not need to +specify any mount options, use the generic option +.B defaults +in +.IR /etc/fstab . +.DT +.SS "Options supported by all versions" +These options are valid to use with any NFS version. +.TP 1.5i +.BI nfsvers= n +The NFS protocol version number used to contact the server's NFS service. +If the server does not support the requested version, the mount request +fails. +If this option is not specified, the client tries version 4.2 first, +then negotiates down until it finds a version supported by the server. +.TP 1.5i +.BI vers= n +This option is an alternative to the +.B nfsvers +option. +It is included for compatibility with other operating systems +.TP 1.5i +.BR soft " / " softerr " / " hard +Determines the recovery behavior of the NFS client +after an NFS request times out. +If no option is specified (or if the +.B hard +option is specified), NFS requests are retried indefinitely. +If either the +.BR soft " or " softerr +option is specified, then the NFS client fails an NFS request +after +.B retrans +retransmissions have been sent, +causing the NFS client to return either the error +.B EIO +(for the +.B soft +option) or +.B ETIMEDOUT +(for the +.B softerr +option) to the calling application. +.IP +.I NB: +A so-called "soft" timeout can cause +silent data corruption in certain cases. As such, use the +.BR soft " or " softerr +option only when client responsiveness +is more important than data integrity. +Using NFS over TCP or increasing the value of the +.B retrans +option may mitigate some of the risks of using the +.BR soft " or " softerr +option. +.TP 1.5i +.BR softreval " / " nosoftreval +In cases where the NFS server is down, it may be useful to +allow the NFS client to continue to serve up paths and +attributes from cache after +.B retrans +attempts to revalidate that cache have timed out. +This may, for instance, be helpful when trying to unmount a +filesystem tree from a server that is permanently down. +.IP +It is possible to combine +.BR softreval +with the +.B soft +mount option, in which case operations that cannot be served up +from cache will time out and return an error after +.B retrans +attempts. The combination with the default +.B hard +mount option implies those uncached operations will continue to +retry until a response is received from the server. +.IP +Note: the default mount option is +.BR nosoftreval +which disallows fallback to cache when revalidation fails, and +instead follows the behavior dictated by the +.B hard +or +.B soft +mount option. +.TP 1.5i +.BR intr " / " nointr +This option is provided for backward compatibility. +It is ignored after kernel 2.6.25. +.TP 1.5i +.BI timeo= n +The time in deciseconds (tenths of a second) the NFS client waits for a +response before it retries an NFS request. +.IP +For NFS over TCP the default +.B timeo +value is 600 (60 seconds). +The NFS client performs linear backoff: After each retransmission the +timeout is increased by +.BR timeo +up to the maximum of 600 seconds. +.IP +However, for NFS over UDP, the client uses an adaptive +algorithm to estimate an appropriate timeout value for frequently used +request types (such as READ and WRITE requests), but uses the +.B timeo +setting for infrequently used request types (such as FSINFO requests). +If the +.B timeo +option is not specified, +infrequently used request types are retried after 1.1 seconds. +After each retransmission, the NFS client doubles the timeout for +that request, +up to a maximum timeout length of 60 seconds. +.TP 1.5i +.BI retrans= n +The number of times the NFS client retries a request before +it attempts further recovery action. If the +.B retrans +option is not specified, the NFS client tries each UDP request +three times and each TCP request twice. +.IP +The NFS client generates a "server not responding" message +after +.B retrans +retries, then attempts further recovery (depending on whether the +.B hard +mount option is in effect). +.TP 1.5i +.BI rsize= n +The maximum number of bytes in each network READ request +that the NFS client can receive when reading data from a file +on an NFS server. +The actual data payload size of each NFS READ request is equal to +or smaller than the +.B rsize +setting. The largest read payload supported by the Linux NFS client +is 1,048,576 bytes (one megabyte). +.IP +The +.B rsize +value is a positive integral multiple of 1024. +Specified +.B rsize +values lower than 1024 are replaced with 4096; values larger than +1048576 are replaced with 1048576. If a specified value is within the supported +range but not a multiple of 1024, it is rounded down to the nearest +multiple of 1024. +.IP +If an +.B rsize +value is not specified, or if the specified +.B rsize +value is larger than the maximum that either client or server can support, +the client and server negotiate the largest +.B rsize +value that they can both support. +.IP +The +.B rsize +mount option as specified on the +.BR mount (8) +command line appears in the +.I /etc/mtab +file. However, the effective +.B rsize +value negotiated by the client and server is reported in the +.I /proc/mounts +file. +.TP 1.5i +.BI wsize= n +The maximum number of bytes per network WRITE request +that the NFS client can send when writing data to a file +on an NFS server. The actual data payload size of each +NFS WRITE request is equal to +or smaller than the +.B wsize +setting. The largest write payload supported by the Linux NFS client +is 1,048,576 bytes (one megabyte). +.IP +Similar to +.B rsize +, the +.B wsize +value is a positive integral multiple of 1024. +Specified +.B wsize +values lower than 1024 are replaced with 4096; values larger than +1048576 are replaced with 1048576. If a specified value is within the supported +range but not a multiple of 1024, it is rounded down to the nearest +multiple of 1024. +.IP +If a +.B wsize +value is not specified, or if the specified +.B wsize +value is larger than the maximum that either client or server can support, +the client and server negotiate the largest +.B wsize +value that they can both support. +.IP +The +.B wsize +mount option as specified on the +.BR mount (8) +command line appears in the +.I /etc/mtab +file. However, the effective +.B wsize +value negotiated by the client and server is reported in the +.I /proc/mounts +file. +.TP 1.5i +.BR ac " / " noac +Selects whether the client may cache file attributes. If neither +option is specified (or if +.B ac +is specified), the client caches file +attributes. +.IP +To improve performance, NFS clients cache file +attributes. Every few seconds, an NFS client checks the server's version of each +file's attributes for updates. Changes that occur on the server in +those small intervals remain undetected until the client checks the +server again. The +.B noac +option prevents clients from caching file +attributes so that applications can more quickly detect file changes +on the server. +.IP +In addition to preventing the client from caching file attributes, +the +.B noac +option forces application writes to become synchronous so +that local changes to a file become visible on the server +immediately. That way, other clients can quickly detect recent +writes when they check the file's attributes. +.IP +Using the +.B noac +option provides greater cache coherence among NFS clients +accessing the same files, +but it extracts a significant performance penalty. +As such, judicious use of file locking is encouraged instead. +The DATA AND METADATA COHERENCE section contains a detailed discussion +of these trade-offs. +.TP 1.5i +.BI acregmin= n +The minimum time (in seconds) that the NFS client caches +attributes of a regular file before it requests +fresh attribute information from a server. +If this option is not specified, the NFS client uses +a 3-second minimum. +See the DATA AND METADATA COHERENCE section +for a full discussion of attribute caching. +.TP 1.5i +.BI acregmax= n +The maximum time (in seconds) that the NFS client caches +attributes of a regular file before it requests +fresh attribute information from a server. +If this option is not specified, the NFS client uses +a 60-second maximum. +See the DATA AND METADATA COHERENCE section +for a full discussion of attribute caching. +.TP 1.5i +.BI acdirmin= n +The minimum time (in seconds) that the NFS client caches +attributes of a directory before it requests +fresh attribute information from a server. +If this option is not specified, the NFS client uses +a 30-second minimum. +See the DATA AND METADATA COHERENCE section +for a full discussion of attribute caching. +.TP 1.5i +.BI acdirmax= n +The maximum time (in seconds) that the NFS client caches +attributes of a directory before it requests +fresh attribute information from a server. +If this option is not specified, the NFS client uses +a 60-second maximum. +See the DATA AND METADATA COHERENCE section +for a full discussion of attribute caching. +.TP 1.5i +.BI actimeo= n +Using +.B actimeo +sets all of +.BR acregmin , +.BR acregmax , +.BR acdirmin , +and +.B acdirmax +to the same value. +If this option is not specified, the NFS client uses +the defaults for each of these options listed above. +.TP 1.5i +.BR bg " / " fg +Determines how the +.BR mount (8) +command behaves if an attempt to mount an export fails. +The +.B fg +option causes +.BR mount (8) +to exit with an error status if any part of the mount request +times out or fails outright. +This is called a "foreground" mount, +and is the default behavior if neither the +.B fg +nor +.B bg +mount option is specified. +.IP +If the +.B bg +option is specified, a timeout or failure causes the +.BR mount (8) +command to fork a child which continues to attempt +to mount the export. +The parent immediately returns with a zero exit code. +This is known as a "background" mount. +.IP +If the local mount point directory is missing, the +.BR mount (8) +command acts as if the mount request timed out. +This permits nested NFS mounts specified in +.I /etc/fstab +to proceed in any order during system initialization, +even if some NFS servers are not yet available. +Alternatively these issues can be addressed +using an automounter (refer to +.BR automount (8) +for details). +.TP 1.5i +.BR nconnect= n +When using a connection oriented protocol such as TCP, it may +sometimes be advantageous to set up multiple connections between +the client and server. For instance, if your clients and/or servers +are equipped with multiple network interface cards (NICs), using multiple +connections to spread the load may improve overall performance. +In such cases, the +.BR nconnect +option allows the user to specify the number of connections +that should be established between the client and server up to +a limit of 16. +.IP +Note that the +.BR nconnect +option may also be used by some pNFS drivers to decide how many +connections to set up to the data servers. +.TP 1.5i +.BR rdirplus " / " nordirplus +Selects whether to use NFS v3 or v4 READDIRPLUS requests. +If this option is not specified, the NFS client uses READDIRPLUS requests +on NFS v3 or v4 mounts to read small directories. +Some applications perform better if the client uses only READDIR requests +for all directories. +.TP 1.5i +.BI retry= n +The number of minutes that the +.BR mount (8) +command retries an NFS mount operation +in the foreground or background before giving up. +If this option is not specified, the default value for foreground mounts +is 2 minutes, and the default value for background mounts is 10000 minutes +(80 minutes shy of one week). +If a value of zero is specified, the +.BR mount (8) +command exits immediately after the first failure. +.IP +Note that this only affects how many retries are made and doesn't +affect the delay caused by each retry. For UDP each retry takes the +time determined by the +.BR timeo +and +.BR retrans +options, which by default will be about 7 seconds. For TCP the +default is 3 minutes, but system TCP connection timeouts will +sometimes limit the timeout of each retransmission to around 2 minutes. +.TP 1.5i +.BI sec= flavors +A colon-separated list of one or more security flavors to use for accessing +files on the mounted export. If the server does not support any of these +flavors, the mount operation fails. +If +.B sec= +is not specified, the client attempts to find +a security flavor that both the client and the server supports. +Valid +.I flavors +are +.BR none , +.BR sys , +.BR krb5 , +.BR krb5i , +and +.BR krb5p . +Refer to the SECURITY CONSIDERATIONS section for details. +.TP 1.5i +.BR sharecache " / " nosharecache +Determines how the client's data cache and attribute cache are shared +when mounting the same export more than once concurrently. Using the +same cache reduces memory requirements on the client and presents +identical file contents to applications when the same remote file is +accessed via different mount points. +.IP +If neither option is specified, or if the +.B sharecache +option is +specified, then a single cache is used for all mount points that +access the same export. If the +.B nosharecache +option is specified, +then that mount point gets a unique cache. Note that when data and +attribute caches are shared, the mount options from the first mount +point take effect for subsequent concurrent mounts of the same export. +.IP +As of kernel 2.6.18, the behavior specified by +.B nosharecache +is legacy caching behavior. This +is considered a data risk since multiple cached copies +of the same file on the same client can become out of sync +following a local update of one of the copies. +.TP 1.5i +.BR resvport " / " noresvport +Specifies whether the NFS client should use a privileged source port +when communicating with an NFS server for this mount point. +If this option is not specified, or the +.B resvport +option is specified, the NFS client uses a privileged source port. +If the +.B noresvport +option is specified, the NFS client uses a non-privileged source port. +This option is supported in kernels 2.6.28 and later. +.IP +Using non-privileged source ports helps increase the maximum number of +NFS mount points allowed on a client, but NFS servers must be configured +to allow clients to connect via non-privileged source ports. +.IP +Refer to the SECURITY CONSIDERATIONS section for important details. +.TP 1.5i +.BI lookupcache= mode +Specifies how the kernel manages its cache of directory entries +for a given mount point. +.I mode +can be one of +.BR all , +.BR none , +.BR pos , +or +.BR positive . +This option is supported in kernels 2.6.28 and later. +.IP +The Linux NFS client caches the result of all NFS LOOKUP requests. +If the requested directory entry exists on the server, +the result is referred to as +.IR positive . +If the requested directory entry does not exist on the server, +the result is referred to as +.IR negative . +.IP +If this option is not specified, or if +.B all +is specified, the client assumes both types of directory cache entries +are valid until their parent directory's cached attributes expire. +.IP +If +.BR pos " or " positive +is specified, the client assumes positive entries are valid +until their parent directory's cached attributes expire, but +always revalidates negative entires before an application +can use them. +.IP +If +.B none +is specified, +the client revalidates both types of directory cache entries +before an application can use them. +This permits quick detection of files that were created or removed +by other clients, but can impact application and server performance. +.IP +The DATA AND METADATA COHERENCE section contains a +detailed discussion of these trade-offs. +.TP 1.5i +.BR fsc " / " nofsc +Enable/Disables the cache of (read-only) data pages to the local disk +using the FS-Cache facility. See cachefilesd(8) +and /Documentation/filesystems/caching +for detail on how to configure the FS-Cache facility. +Default value is nofsc. +.TP 1.5i +.B sloppy +The +.B sloppy +option is an alternative to specifying +.BR mount.nfs " -s " option. +.TP 1.5i +.BI xprtsec= policy +Specifies the use of transport layer security to protect NFS network +traffic on behalf of this mount point. +.I policy +can be one of +.BR none , +.BR tls , +or +.BR mtls . +.IP +If +.B none +is specified, +transport layer security is forced off, even if the NFS server supports +transport layer security. +.IP +If +.B tls +is specified, the client uses RPC-with-TLS to provide in-transit +confidentiality. +.IP +If +.B mtls +is specified, the client uses RPC-with-TLS to authenticate itself and +to provide in-transit confidentiality. +.IP +If either +.B tls +or +.B mtls +is specified and the server does not support RPC-with-TLS or peer +authentication fails, the mount attempt fails. +.IP +If the +.B xprtsec= +option is not specified, +the default behavior depends on the kernel version, +but is usually equivalent to +.BR "xprtsec=none" . +.SS "Options for NFS versions 2 and 3 only" +Use these options, along with the options in the above subsection, +for NFS versions 2 and 3 only. +.TP 1.5i +.BI proto= netid +The +.I netid +determines the transport that is used to communicate with the NFS +server. Available options are +.BR udp ", " udp6 ", "tcp ", " tcp6 ", " rdma ", and " rdma6 . +Those which end in +.B 6 +use IPv6 addresses and are only available if support for TI-RPC is +built in. Others use IPv4 addresses. +.IP +Each transport protocol uses different default +.B retrans +and +.B timeo +settings. +Refer to the description of these two mount options for details. +.IP +In addition to controlling how the NFS client transmits requests to +the server, this mount option also controls how the +.BR mount (8) +command communicates with the server's rpcbind and mountd services. +Specifying a netid that uses TCP forces all traffic from the +.BR mount (8) +command and the NFS client to use TCP. +Specifying a netid that uses UDP forces all traffic types to use UDP. +.IP +.B Before using NFS over UDP, refer to the TRANSPORT METHODS section. +.IP +If the +.B proto +mount option is not specified, the +.BR mount (8) +command discovers which protocols the server supports +and chooses an appropriate transport for each service. +Refer to the TRANSPORT METHODS section for more details. +.TP 1.5i +.B udp +The +.B udp +option is an alternative to specifying +.BR proto=udp. +It is included for compatibility with other operating systems. +.IP +.B Before using NFS over UDP, refer to the TRANSPORT METHODS section. +.TP 1.5i +.B tcp +The +.B tcp +option is an alternative to specifying +.BR proto=tcp. +It is included for compatibility with other operating systems. +.TP 1.5i +.B rdma +The +.B rdma +option is an alternative to specifying +.BR proto=rdma. +.TP 1.5i +.BI port= n +The numeric value of the server's NFS service port. +If the server's NFS service is not available on the specified port, +the mount request fails. +.IP +If this option is not specified, or if the specified port value is 0, +then the NFS client uses the NFS service port number +advertised by the server's rpcbind service. +The mount request fails if the server's rpcbind service is not available, +the server's NFS service is not registered with its rpcbind service, +or the server's NFS service is not available on the advertised port. +.TP 1.5i +.BI mountport= n +The numeric value of the server's mountd port. +If the server's mountd service is not available on the specified port, +the mount request fails. +.IP +If this option is not specified, +or if the specified port value is 0, then the +.BR mount (8) +command uses the mountd service port number +advertised by the server's rpcbind service. +The mount request fails if the server's rpcbind service is not available, +the server's mountd service is not registered with its rpcbind service, +or the server's mountd service is not available on the advertised port. +.IP +This option can be used when mounting an NFS server +through a firewall that blocks the rpcbind protocol. +.TP 1.5i +.BI mountproto= netid +The transport the NFS client uses +to transmit requests to the NFS server's mountd service when performing +this mount request, and when later unmounting this mount point. +.IP +.I netid +may be one of +.BR udp ", and " tcp +which use IPv4 address or, if TI-RPC is built into the +.B mount.nfs +command, +.BR udp6 ", and " tcp6 +which use IPv6 addresses. +.IP +This option can be used when mounting an NFS server +through a firewall that blocks a particular transport. +When used in combination with the +.B proto +option, different transports for mountd requests and NFS requests +can be specified. +If the server's mountd service is not available via the specified +transport, the mount request fails. +.IP +Refer to the TRANSPORT METHODS section for more on how the +.B mountproto +mount option interacts with the +.B proto +mount option. +.TP 1.5i +.BI mounthost= name +The hostname of the host running mountd. +If this option is not specified, the +.BR mount (8) +command assumes that the mountd service runs +on the same host as the NFS service. +.TP 1.5i +.BI mountvers= n +The RPC version number used to contact the server's mountd. +If this option is not specified, the client uses a version number +appropriate to the requested NFS version. +This option is useful when multiple NFS services +are running on the same remote server host. +.TP 1.5i +.BI namlen= n +The maximum length of a pathname component on this mount. +If this option is not specified, the maximum length is negotiated +with the server. In most cases, this maximum length is 255 characters. +.IP +Some early versions of NFS did not support this negotiation. +Using this option ensures that +.BR pathconf (3) +reports the proper maximum component length to applications +in such cases. +.TP 1.5i +.BR lock " / " nolock +Selects whether to use the NLM sideband protocol to lock files on the server. +If neither option is specified (or if +.B lock +is specified), NLM locking is used for this mount point. +When using the +.B nolock +option, applications can lock files, +but such locks provide exclusion only against other applications +running on the same client. +Remote applications are not affected by these locks. +.IP +NLM locking must be disabled with the +.B nolock +option when using NFS to mount +.I /var +because +.I /var +contains files used by the NLM implementation on Linux. +Using the +.B nolock +option is also required when mounting exports on NFS servers +that do not support the NLM protocol. +.TP 1.5i +.BR cto " / " nocto +Selects whether to use close-to-open cache coherence semantics. +If neither option is specified (or if +.B cto +is specified), the client uses close-to-open +cache coherence semantics. If the +.B nocto +option is specified, the client uses a non-standard heuristic to determine when +files on the server have changed. +.IP +Using the +.B nocto +option may improve performance for read-only mounts, +but should be used only if the data on the server changes only occasionally. +The DATA AND METADATA COHERENCE section discusses the behavior +of this option in more detail. +.TP 1.5i +.BR acl " / " noacl +Selects whether to use the NFSACL sideband protocol on this mount point. +The NFSACL sideband protocol is a proprietary protocol +implemented in Solaris that manages Access Control Lists. NFSACL was never +made a standard part of the NFS protocol specification. +.IP +If neither +.B acl +nor +.B noacl +option is specified, +the NFS client negotiates with the server +to see if the NFSACL protocol is supported, +and uses it if the server supports it. +Disabling the NFSACL sideband protocol may be necessary +if the negotiation causes problems on the client or server. +Refer to the SECURITY CONSIDERATIONS section for more details. +.TP 1.5i +.BR local_lock= mechanism +Specifies whether to use local locking for any or both of the flock and the +POSIX locking mechanisms. +.I mechanism +can be one of +.BR all , +.BR flock , +.BR posix , +or +.BR none . +This option is supported in kernels 2.6.37 and later. +.IP +The Linux NFS client provides a way to make locks local. This means, the +applications can lock files, but such locks provide exclusion only against +other applications running on the same client. Remote applications are not +affected by these locks. +.IP +If this option is not specified, or if +.B none +is specified, the client assumes that the locks are not local. +.IP +If +.BR all +is specified, the client assumes that both flock and POSIX locks are local. +.IP +If +.BR flock +is specified, the client assumes that only flock locks are local and uses +NLM sideband protocol to lock files when POSIX locks are used. +.IP +If +.BR posix +is specified, the client assumes that POSIX locks are local and uses NLM +sideband protocol to lock files when flock locks are used. +.IP +To support legacy flock behavior similar to that of NFS clients < 2.6.12, +use 'local_lock=flock'. This option is required when exporting NFS mounts via +Samba as Samba maps Windows share mode locks as flock. Since NFS clients > +2.6.12 implement flock by emulating POSIX locks, this will result in +conflicting locks. +.IP +NOTE: When used together, the 'local_lock' mount option will be overridden +by 'nolock'/'lock' mount option. +.SS "Options for NFS version 4 only" +Use these options, along with the options in the first subsection above, +for NFS version 4.0 and newer. +.TP 1.5i +.BI proto= netid +The +.I netid +determines the transport that is used to communicate with the NFS +server. Supported options are +.BR tcp ", " tcp6 ", " rdma ", and " rdma6 . +.B tcp6 +use IPv6 addresses and is only available if support for TI-RPC is +built in. Both others use IPv4 addresses. +.IP +All NFS version 4 servers are required to support TCP, +so if this mount option is not specified, the NFS version 4 client +uses the TCP protocol. +Refer to the TRANSPORT METHODS section for more details. +.TP 1.5i +.BI minorversion= n +Specifies the protocol minor version number. +NFSv4 introduces "minor versioning," where NFS protocol enhancements can +be introduced without bumping the NFS protocol version number. +Before kernel 2.6.38, the minor version is always zero, and this +option is not recognized. +After this kernel, specifying "minorversion=1" enables a number of +advanced features, such as NFSv4 sessions. +.IP +Recent kernels allow the minor version to be specified using the +.B vers= +option. +For example, specifying +.B vers=4.1 +is the same as specifying +.BR vers=4,minorversion=1 . +.TP 1.5i +.BI port= n +The numeric value of the server's NFS service port. +If the server's NFS service is not available on the specified port, +the mount request fails. +.IP +If this mount option is not specified, +the NFS client uses the standard NFS port number of 2049 +without first checking the server's rpcbind service. +This allows an NFS version 4 client to contact an NFS version 4 +server through a firewall that may block rpcbind requests. +.IP +If the specified port value is 0, +then the NFS client uses the NFS service port number +advertised by the server's rpcbind service. +The mount request fails if the server's rpcbind service is not available, +the server's NFS service is not registered with its rpcbind service, +or the server's NFS service is not available on the advertised port. +.TP 1.5i +.BR cto " / " nocto +Selects whether to use close-to-open cache coherence semantics +for NFS directories on this mount point. +If neither +.B cto +nor +.B nocto +is specified, +the default is to use close-to-open cache coherence +semantics for directories. +.IP +File data caching behavior is not affected by this option. +The DATA AND METADATA COHERENCE section discusses +the behavior of this option in more detail. +.TP 1.5i +.BI clientaddr= n.n.n.n +.TP 1.5i +.BI clientaddr= n:n: ... :n +Specifies a single IPv4 address (in dotted-quad form), +or a non-link-local IPv6 address, +that the NFS client advertises to allow servers +to perform NFS version 4.0 callback requests against +files on this mount point. If the server is unable to +establish callback connections to clients, performance +may degrade, or accesses to files may temporarily hang. +Can specify a value of IPv4_ANY (0.0.0.0) or equivalent +IPv6 any address which will signal to the NFS server that +this NFS client does not want delegations. +.IP +If this option is not specified, the +.BR mount (8) +command attempts to discover an appropriate callback address automatically. +The automatic discovery process is not perfect, however. +In the presence of multiple client network interfaces, +special routing policies, +or atypical network topologies, +the exact address to use for callbacks may be nontrivial to determine. +.IP +NFS protocol versions 4.1 and 4.2 use the client-established +TCP connection for callback requests, so do not require the server to +connect to the client. This option is therefore only affect NFS version +4.0 mounts. +.TP 1.5i +.BR migration " / " nomigration +Selects whether the client uses an identification string that is compatible +with NFSv4 Transparent State Migration (TSM). +If the mounted server supports NFSv4 migration with TSM, specify the +.B migration +option. +.IP +Some server features misbehave in the face of a migration-compatible +identification string. +The +.B nomigration +option retains the use of a traditional client identification string +which is compatible with legacy NFS servers. +This is also the behavior if neither option is specified. +A client's open and lock state cannot be migrated transparently +when it identifies itself via a traditional identification string. +.IP +This mount option has no effect with NFSv4 minor versions newer than zero, +which always use TSM-compatible client identification strings. +.TP 1.5i +.BR max_connect= n +While +.BR nconnect +option sets a limit on the number of connections that can be established +to a given server IP, +.BR max_connect +option allows the user to specify maximum number of connections to different +server IPs that belong to the same NFSv4.1+ server (session trunkable +connections) up to a limit of 16. When client discovers that it established +a client ID to an already existing server, instead of dropping the newly +created network transport, the client will add this new connection to the +list of available transports for that RPC client. +.TP 1.5i +.BR trunkdiscovery " / " notrunkdiscovery +When the client discovers a new filesystem on a NFSv4.1+ server, the +.BR trunkdiscovery +mount option will cause it to send a GETATTR for the fs_locations attribute. +If is receives a non-zero length reply, it will iterate through the response, +and for each server location it will establish a connection, send an +EXCHANGE_ID, and test for session trunking. If the trunking test succeeds, +the connection will be added to the existing set of transports for the server, +subject to the limit specified by the +.BR max_connect +option. The default is +.BR notrunkdiscovery . +.SH nfs4 FILE SYSTEM TYPE +The +.BR nfs4 +file system type is an old syntax for specifying NFSv4 usage. It can still +be used with all NFSv4-specific and common options, excepted the +.B nfsvers +mount option. +.SH MOUNT CONFIGURATION FILE +If the mount command is configured to do so, all of the mount options +described in the previous section can also be configured in the +.I /etc/nfsmount.conf +file. See +.BR nfsmount.conf(5) +for details. +.SH EXAMPLES +To mount using NFS version 3, +use the +.B nfs +file system type and specify the +.B nfsvers=3 +mount option. +To mount using NFS version 4, +use either the +.B nfs +file system type, with the +.B nfsvers=4 +mount option, or the +.B nfs4 +file system type. +.P +The following example from an +.I /etc/fstab +file causes the mount command to negotiate +reasonable defaults for NFS behavior. +.P +.nf +.ta 8n +16n +6n +6n +30n + server:/export /mnt nfs defaults 0 0 +.fi +.P +This example shows how to mount using NFS version 4 over TCP +with Kerberos 5 mutual authentication. +.P +.nf +.ta 8n +16n +6n +6n +30n + server:/export /mnt nfs4 sec=krb5 0 0 +.fi +.P +This example shows how to mount using NFS version 4 over TCP +with Kerberos 5 privacy or data integrity mode. +.P +.nf +.ta 8n +16n +6n +6n +30n + server:/export /mnt nfs4 sec=krb5p:krb5i 0 0 +.fi +.P +This example can be used to mount /usr over NFS. +.P +.nf +.ta 8n +16n +6n +6n +30n + server:/export /usr nfs ro,nolock,nocto,actimeo=3600 0 0 +.fi +.P +This example shows how to mount an NFS server +using a raw IPv6 link-local address. +.P +.nf +.ta 8n +40n +5n +4n +9n + [fe80::215:c5ff:fb3e:e2b1%eth0]:/export /mnt nfs defaults 0 0 +.fi +.SH "TRANSPORT METHODS" +NFS clients send requests to NFS servers via +Remote Procedure Calls, or +.IR RPCs . +The RPC client discovers remote service endpoints automatically, +handles per-request authentication, +adjusts request parameters for different byte endianness on client and server, +and retransmits requests that may have been lost by the network or server. +RPC requests and replies flow over a network transport. +.P +In most cases, the +.BR mount (8) +command, NFS client, and NFS server +can automatically negotiate proper transport +and data transfer size settings for a mount point. +In some cases, however, it pays to specify +these settings explicitly using mount options. +.P +Traditionally, NFS clients used the UDP transport exclusively for +transmitting requests to servers. Though its implementation is +simple, NFS over UDP has many limitations that prevent smooth +operation and good performance in some common deployment +environments. Even an insignificant packet loss rate results in the +loss of whole NFS requests; as such, retransmit timeouts are usually +in the subsecond range to allow clients to recover quickly from +dropped requests, but this can result in extraneous network traffic +and server load. +.P +However, UDP can be quite effective in specialized settings where +the networks MTU is large relative to NFSs data transfer size (such +as network environments that enable jumbo Ethernet frames). In such +environments, trimming the +.B rsize +and +.B wsize +settings so that each +NFS read or write request fits in just a few network frames (or even +in a single frame) is advised. This reduces the probability that +the loss of a single MTU-sized network frame results in the loss of +an entire large read or write request. +.P +TCP is the default transport protocol used for all modern NFS +implementations. It performs well in almost every conceivable +network environment and provides excellent guarantees against data +corruption caused by network unreliability. TCP is often a +requirement for mounting a server through a network firewall. +.P +Under normal circumstances, networks drop packets much more +frequently than NFS servers drop requests. As such, an aggressive +retransmit timeout setting for NFS over TCP is unnecessary. Typical +timeout settings for NFS over TCP are between one and ten minutes. +After the client exhausts its retransmits (the value of the +.B retrans +mount option), it assumes a network partition has occurred, +and attempts to reconnect to the server on a fresh socket. Since +TCP itself makes network data transfer reliable, +.B rsize +and +.B wsize +can safely be allowed to default to the largest values supported by +both client and server, independent of the network's MTU size. +.SS "Using the mountproto mount option" +This section applies only to NFS version 3 mounts +since NFS version 4 does not use a separate protocol for mount +requests. +.P +The Linux NFS client can use a different transport for +contacting an NFS server's rpcbind service, its mountd service, +its Network Lock Manager (NLM) service, and its NFS service. +The exact transports employed by the Linux NFS client for +each mount point depends on the settings of the transport +mount options, which include +.BR proto , +.BR mountproto , +.BR udp ", and " tcp . +.P +The client sends Network Status Manager (NSM) notifications +via UDP no matter what transport options are specified, but +listens for server NSM notifications on both UDP and TCP. +The NFS Access Control List (NFSACL) protocol shares the same +transport as the main NFS service. +.P +If no transport options are specified, the Linux NFS client +uses UDP to contact the server's mountd service, and TCP to +contact its NLM and NFS services by default. +.P +If the server does not support these transports for these services, the +.BR mount (8) +command attempts to discover what the server supports, and then retries +the mount request once using the discovered transports. +If the server does not advertise any transport supported by the client +or is misconfigured, the mount request fails. +If the +.B bg +option is in effect, the mount command backgrounds itself and continues +to attempt the specified mount request. +.P +When the +.B proto +option, the +.B udp +option, or the +.B tcp +option is specified but the +.B mountproto +option is not, the specified transport is used to contact +both the server's mountd service and for the NLM and NFS services. +.P +If the +.B mountproto +option is specified but none of the +.BR proto ", " udp " or " tcp +options are specified, then the specified transport is used for the +initial mountd request, but the mount command attempts to discover +what the server supports for the NFS protocol, preferring TCP if +both transports are supported. +.P +If both the +.BR mountproto " and " proto +(or +.BR udp " or " tcp ) +options are specified, then the transport specified by the +.B mountproto +option is used for the initial mountd request, and the transport +specified by the +.B proto +option (or the +.BR udp " or " tcp " options)" +is used for NFS, no matter what order these options appear. +No automatic service discovery is performed if these options are +specified. +.P +If any of the +.BR proto ", " udp ", " tcp ", " +or +.B mountproto +options are specified more than once on the same mount command line, +then the value of the rightmost instance of each of these options +takes effect. +.SS "Using NFS over UDP on high-speed links" +Using NFS over UDP on high-speed links such as Gigabit +.BR "can cause silent data corruption" . +.P +The problem can be triggered at high loads, and is caused by problems in +IP fragment reassembly. NFS read and writes typically transmit UDP packets +of 4 Kilobytes or more, which have to be broken up into several fragments +in order to be sent over the Ethernet link, which limits packets to 1500 +bytes by default. This process happens at the IP network layer and is +called fragmentation. +.P +In order to identify fragments that belong together, IP assigns a 16bit +.I IP ID +value to each packet; fragments generated from the same UDP packet +will have the same IP ID. The receiving system will collect these +fragments and combine them to form the original UDP packet. This process +is called reassembly. The default timeout for packet reassembly is +30 seconds; if the network stack does not receive all fragments of +a given packet within this interval, it assumes the missing fragment(s) +got lost and discards those it already received. +.P +The problem this creates over high-speed links is that it is possible +to send more than 65536 packets within 30 seconds. In fact, with +heavy NFS traffic one can observe that the IP IDs repeat after about +5 seconds. +.P +This has serious effects on reassembly: if one fragment gets lost, +another fragment +.I from a different packet +but with the +.I same IP ID +will arrive within the 30 second timeout, and the network stack will +combine these fragments to form a new packet. Most of the time, network +layers above IP will detect this mismatched reassembly - in the case +of UDP, the UDP checksum, which is a 16 bit checksum over the entire +packet payload, will usually not match, and UDP will discard the +bad packet. +.P +However, the UDP checksum is 16 bit only, so there is a chance of 1 in +65536 that it will match even if the packet payload is completely +random (which very often isn't the case). If that is the case, +silent data corruption will occur. +.P +This potential should be taken seriously, at least on Gigabit +Ethernet. +Network speeds of 100Mbit/s should be considered less +problematic, because with most traffic patterns IP ID wrap around +will take much longer than 30 seconds. +.P +It is therefore strongly recommended to use +.BR "NFS over TCP where possible" , +since TCP does not perform fragmentation. +.P +If you absolutely have to use NFS over UDP over Gigabit Ethernet, +some steps can be taken to mitigate the problem and reduce the +probability of corruption: +.TP +1.5i +.I Jumbo frames: +Many Gigabit network cards are capable of transmitting +frames bigger than the 1500 byte limit of traditional Ethernet, typically +9000 bytes. Using jumbo frames of 9000 bytes will allow you to run NFS over +UDP at a page size of 8K without fragmentation. Of course, this is +only feasible if all involved stations support jumbo frames. +.IP +To enable a machine to send jumbo frames on cards that support it, +it is sufficient to configure the interface for a MTU value of 9000. +.TP +1.5i +.I Lower reassembly timeout: +By lowering this timeout below the time it takes the IP ID counter +to wrap around, incorrect reassembly of fragments can be prevented +as well. To do so, simply write the new timeout value (in seconds) +to the file +.BR /proc/sys/net/ipv4/ipfrag_time . +.IP +A value of 2 seconds will greatly reduce the probability of IPID clashes on +a single Gigabit link, while still allowing for a reasonable timeout +when receiving fragmented traffic from distant peers. +.SH "DATA AND METADATA COHERENCE" +Some modern cluster file systems provide +perfect cache coherence among their clients. +Perfect cache coherence among disparate NFS clients +is expensive to achieve, especially on wide area networks. +As such, NFS settles for weaker cache coherence that +satisfies the requirements of most file sharing types. +.SS "Close-to-open cache consistency" +Typically file sharing is completely sequential. +First client A opens a file, writes something to it, then closes it. +Then client B opens the same file, and reads the changes. +.P +When an application opens a file stored on an NFS version 3 server, +the NFS client checks that the file exists on the server +and is permitted to the opener by sending a GETATTR or ACCESS request. +The NFS client sends these requests +regardless of the freshness of the file's cached attributes. +.P +When the application closes the file, +the NFS client writes back any pending changes +to the file so that the next opener can view the changes. +This also gives the NFS client an opportunity to report +write errors to the application via the return code from +.BR close (2). +.P +The behavior of checking at open time and flushing at close time +is referred to as +.IR "close-to-open cache consistency" , +or +.IR CTO . +It can be disabled for an entire mount point using the +.B nocto +mount option. +.SS "Weak cache consistency" +There are still opportunities for a client's data cache +to contain stale data. +The NFS version 3 protocol introduced "weak cache consistency" +(also known as WCC) which provides a way of efficiently checking +a file's attributes before and after a single request. +This allows a client to help identify changes +that could have been made by other clients. +.P +When a client is using many concurrent operations +that update the same file at the same time +(for example, during asynchronous write behind), +it is still difficult to tell whether it was +that client's updates or some other client's updates +that altered the file. +.SS "Attribute caching" +Use the +.B noac +mount option to achieve attribute cache coherence +among multiple clients. +Almost every file system operation checks +file attribute information. +The client keeps this information cached +for a period of time to reduce network and server load. +When +.B noac +is in effect, a client's file attribute cache is disabled, +so each operation that needs to check a file's attributes +is forced to go back to the server. +This permits a client to see changes to a file very quickly, +at the cost of many extra network operations. +.P +Be careful not to confuse the +.B noac +option with "no data caching." +The +.B noac +mount option prevents the client from caching file metadata, +but there are still races that may result in data cache incoherence +between client and server. +.P +The NFS protocol is not designed to support +true cluster file system cache coherence +without some type of application serialization. +If absolute cache coherence among clients is required, +applications should use file locking. Alternatively, applications +can also open their files with the O_DIRECT flag +to disable data caching entirely. +.SS "File timestamp maintenance" +NFS servers are responsible for managing file and directory timestamps +.RB ( atime , +.BR ctime ", and" +.BR mtime ). +When a file is accessed or updated on an NFS server, +the file's timestamps are updated just like they would be on a filesystem +local to an application. +.P +NFS clients cache file attributes, including timestamps. +A file's timestamps are updated on NFS clients when its attributes +are retrieved from the NFS server. +Thus there may be some delay before timestamp updates +on an NFS server appear to applications on NFS clients. +.P +To comply with the POSIX filesystem standard, the Linux NFS client +relies on NFS servers to keep a file's +.B mtime +and +.B ctime +timestamps properly up to date. +It does this by flushing local data changes to the server +before reporting +.B mtime +to applications via system calls such as +.BR stat (2). +.P +The Linux client handles +.B atime +updates more loosely, however. +NFS clients maintain good performance by caching data, +but that means that application reads, which normally update +.BR atime , +are not reflected to the server where a file's +.B atime +is actually maintained. +.P +Because of this caching behavior, +the Linux NFS client does not support generic atime-related mount options. +See +.BR mount (8) +for details on these options. +.P +In particular, the +.BR atime / noatime , +.BR diratime / nodiratime , +.BR relatime / norelatime , +and +.BR strictatime / nostrictatime +mount options have no effect on NFS mounts. +.P +.I /proc/mounts +may report that the +.B relatime +mount option is set on NFS mounts, but in fact the +.B atime +semantics are always as described here, and are not like +.B relatime +semantics. +.SS "Directory entry caching" +The Linux NFS client caches the result of all NFS LOOKUP requests. +If the requested directory entry exists on the server, +the result is referred to as a +.IR positive " lookup result. +If the requested directory entry does not exist on the server +(that is, the server returned ENOENT), +the result is referred to as +.IR negative " lookup result. +.P +To detect when directory entries have been added or removed +on the server, +the Linux NFS client watches a directory's mtime. +If the client detects a change in a directory's mtime, +the client drops all cached LOOKUP results for that directory. +Since the directory's mtime is a cached attribute, it may +take some time before a client notices it has changed. +See the descriptions of the +.BR acdirmin ", " acdirmax ", and " noac +mount options for more information about +how long a directory's mtime is cached. +.P +Caching directory entries improves the performance of applications that +do not share files with applications on other clients. +Using cached information about directories can interfere +with applications that run concurrently on multiple clients and +need to detect the creation or removal of files quickly, however. +The +.B lookupcache +mount option allows some tuning of directory entry caching behavior. +.P +Before kernel release 2.6.28, +the Linux NFS client tracked only positive lookup results. +This permitted applications to detect new directory entries +created by other clients quickly while still providing some of the +performance benefits of caching. +If an application depends on the previous lookup caching behavior +of the Linux NFS client, you can use +.BR lookupcache=positive . +.P +If the client ignores its cache and validates every application +lookup request with the server, +that client can immediately detect when a new directory +entry has been either created or removed by another client. +You can specify this behavior using +.BR lookupcache=none . +The extra NFS requests needed if the client does not +cache directory entries can exact a performance penalty. +Disabling lookup caching +should result in less of a performance penalty than using +.BR noac , +and has no effect on how the NFS client caches the attributes of files. +.P +.SS "The sync mount option" +The NFS client treats the +.B sync +mount option differently than some other file systems +(refer to +.BR mount (8) +for a description of the generic +.B sync +and +.B async +mount options). +If neither +.B sync +nor +.B async +is specified (or if the +.B async +option is specified), +the NFS client delays sending application +writes to the server +until any of these events occur: +.IP +Memory pressure forces reclamation of system memory resources. +.IP +An application flushes file data explicitly with +.BR sync (2), +.BR msync (2), +or +.BR fsync (3). +.IP +An application closes a file with +.BR close (2). +.IP +The file is locked/unlocked via +.BR fcntl (2). +.P +In other words, under normal circumstances, +data written by an application may not immediately appear +on the server that hosts the file. +.P +If the +.B sync +option is specified on a mount point, +any system call that writes data to files on that mount point +causes that data to be flushed to the server +before the system call returns control to user space. +This provides greater data cache coherence among clients, +but at a significant performance cost. +.P +Applications can use the O_SYNC open flag to force application +writes to individual files to go to the server immediately without +the use of the +.B sync +mount option. +.SS "Using file locks with NFS" +The Network Lock Manager protocol is a separate sideband protocol +used to manage file locks in NFS version 3. +To support lock recovery after a client or server reboot, +a second sideband protocol -- +known as the Network Status Manager protocol -- +is also required. +In NFS version 4, +file locking is supported directly in the main NFS protocol, +and the NLM and NSM sideband protocols are not used. +.P +In most cases, NLM and NSM services are started automatically, +and no extra configuration is required. +Configure all NFS clients with fully-qualified domain names +to ensure that NFS servers can find clients to notify them of server reboots. +.P +NLM supports advisory file locks only. +To lock NFS files, use +.BR fcntl (2) +with the F_GETLK and F_SETLK commands. +The NFS client converts file locks obtained via +.BR flock (2) +to advisory locks. +.P +When mounting servers that do not support the NLM protocol, +or when mounting an NFS server through a firewall +that blocks the NLM service port, +specify the +.B nolock +mount option. NLM locking must be disabled with the +.B nolock +option when using NFS to mount +.I /var +because +.I /var +contains files used by the NLM implementation on Linux. +.P +Specifying the +.B nolock +option may also be advised to improve the performance +of a proprietary application which runs on a single client +and uses file locks extensively. +.SS "NFS version 4 caching features" +The data and metadata caching behavior of NFS version 4 +clients is similar to that of earlier versions. +However, NFS version 4 adds two features that improve +cache behavior: +.I change attributes +and +.IR "file delegation" . +.P +The +.I change attribute +is a new part of NFS file and directory metadata +which tracks data changes. +It replaces the use of a file's modification +and change time stamps +as a way for clients to validate the content +of their caches. +Change attributes are independent of the time stamp +resolution on either the server or client, however. +.P +A +.I file delegation +is a contract between an NFS version 4 client +and server that allows the client to treat a file temporarily +as if no other client is accessing it. +The server promises to notify the client (via a callback request) if another client +attempts to access that file. +Once a file has been delegated to a client, the client can +cache that file's data and metadata aggressively without +contacting the server. +.P +File delegations come in two flavors: +.I read +and +.IR write . +A +.I read +delegation means that the server notifies the client +about any other clients that want to write to the file. +A +.I write +delegation means that the client gets notified about +either read or write accessors. +.P +Servers grant file delegations when a file is opened, +and can recall delegations at any time when another +client wants access to the file that conflicts with +any delegations already granted. +Delegations on directories are not supported. +.P +In order to support delegation callback, the server +checks the network return path to the client during +the client's initial contact with the server. +If contact with the client cannot be established, +the server simply does not grant any delegations to +that client. +.SH "SECURITY CONSIDERATIONS" +NFS servers control access to file data, +but they depend on their RPC implementation +to provide authentication of NFS requests. +Traditional NFS access control mimics +the standard mode bit access control provided in local file systems. +Traditional RPC authentication uses a number +to represent each user +(usually the user's own uid), +a number to represent the user's group (the user's gid), +and a set of up to 16 auxiliary group numbers +to represent other groups of which the user may be a member. +.P +Typically, file data and user ID values appear unencrypted +(i.e. "in the clear") on the network. +Moreover, NFS versions 2 and 3 use +separate sideband protocols for mounting, +locking and unlocking files, +and reporting system status of clients and servers. +These auxiliary protocols use no authentication. +.P +In addition to combining these sideband protocols with the main NFS protocol, +NFS version 4 introduces more advanced forms of access control, +authentication, and in-transit data protection. +The NFS version 4 specification mandates support for +strong authentication and security flavors +that provide per-RPC integrity checking and encryption. +Because NFS version 4 combines the +function of the sideband protocols into the main NFS protocol, +the new security features apply to all NFS version 4 operations +including mounting, file locking, and so on. +RPCGSS authentication can also be used with NFS versions 2 and 3, +but it does not protect their sideband protocols. +.P +The +.B sec +mount option specifies the security flavor used for operations +on behalf of users on that NFS mount point. +Specifying +.B sec=krb5 +provides cryptographic proof of a user's identity in each RPC request. +This provides strong verification of the identity of users +accessing data on the server. +Note that additional configuration besides adding this mount option +is required in order to enable Kerberos security. +Refer to the +.BR rpc.gssd (8) +man page for details. +.P +Two additional flavors of Kerberos security are supported: +.B krb5i +and +.BR krb5p . +The +.B krb5i +security flavor provides a cryptographically strong guarantee +that the data in each RPC request has not been tampered with. +The +.B krb5p +security flavor encrypts every RPC request +to prevent data exposure during network transit; however, +expect some performance impact +when using integrity checking or encryption. +Similar support for other forms of cryptographic security +is also available. +.SS "NFS version 4 filesystem crossing" +The NFS version 4 protocol allows +a client to renegotiate the security flavor +when the client crosses into a new filesystem on the server. +The newly negotiated flavor effects only accesses of the new filesystem. +.P +Such negotiation typically occurs when a client crosses +from a server's pseudo-fs +into one of the server's exported physical filesystems, +which often have more restrictive security settings than the pseudo-fs. +.SS "NFS version 4 Leases" +In NFS version 4, a lease is a period during which a server +irrevocably grants a client file locks. +Once the lease expires, the server may revoke those locks. +Clients periodically renew their leases to prevent lock revocation. +.P +After an NFS version 4 server reboots, each client tells the +server about existing file open and lock state under its lease +before operation can continue. +If a client reboots, the server frees all open and lock state +associated with that client's lease. +.P +When establishing a lease, therefore, +a client must identify itself to a server. +Each client presents an arbitrary string +to distinguish itself from other clients. +The client administrator can +supplement the default identity string using the +.I nfs4.nfs4_unique_id +module parameter to avoid collisions +with other client identity strings. +.P +A client also uses a unique security flavor and principal +when it establishes its lease. +If two clients present the same identity string, +a server can use client principals to distinguish between them, +thus securely preventing one client from interfering with the other's lease. +.P +The Linux NFS client establishes one lease on each NFS version 4 server. +Lease management operations, such as lease renewal, are not +done on behalf of a particular file, lock, user, or mount +point, but on behalf of the client that owns that lease. +A client uses a consistent identity string, security flavor, +and principal across client reboots to ensure that the server +can promptly reap expired lease state. +.P +When Kerberos is configured on a Linux NFS client +(i.e., there is a +.I /etc/krb5.keytab +on that client), the client attempts to use a Kerberos +security flavor for its lease management operations. +Kerberos provides secure authentication of each client. +By default, the client uses the +.I host/ +or +.I nfs/ +service principal in its +.I /etc/krb5.keytab +for this purpose, as described in +.BR rpc.gssd (8). +.P +If the client has Kerberos configured, but the server +does not, or if the client does not have a keytab or +the requisite service principals, the client uses +.I AUTH_SYS +and UID 0 for lease management. +.SS "Using non-privileged source ports" +NFS clients usually communicate with NFS servers via network sockets. +Each end of a socket is assigned a port value, which is simply a number +between 1 and 65535 that distinguishes socket endpoints at the same +IP address. +A socket is uniquely defined by a tuple that includes the transport +protocol (TCP or UDP) and the port values and IP addresses of both +endpoints. +.P +The NFS client can choose any source port value for its sockets, +but usually chooses a +.I privileged +port. +A privileged port is a port value less than 1024. +Only a process with root privileges may create a socket +with a privileged source port. +.P +The exact range of privileged source ports that can be chosen is +set by a pair of sysctls to avoid choosing a well-known port, such as +the port used by ssh. +This means the number of source ports available for the NFS client, +and therefore the number of socket connections that can be used +at the same time, +is practically limited to only a few hundred. +.P +As described above, the traditional default NFS authentication scheme, +known as AUTH_SYS, relies on sending local UID and GID numbers to identify +users making NFS requests. +An NFS server assumes that if a connection comes from a privileged port, +the UID and GID numbers in the NFS requests on this connection have been +verified by the client's kernel or some other local authority. +This is an easy system to spoof, but on a trusted physical network between +trusted hosts, it is entirely adequate. +.P +Roughly speaking, one socket is used for each NFS mount point. +If a client could use non-privileged source ports as well, +the number of sockets allowed, +and thus the maximum number of concurrent mount points, +would be much larger. +.P +Using non-privileged source ports may compromise server security somewhat, +since any user on AUTH_SYS mount points can now pretend to be any other +when making NFS requests. +Thus NFS servers do not support this by default. +They explicitly allow it usually via an export option. +.P +To retain good security while allowing as many mount points as possible, +it is best to allow non-privileged client connections only if the server +and client both require strong authentication, such as Kerberos. +.SS "Mounting through a firewall" +A firewall may reside between an NFS client and server, +or the client or server may block some of its own ports via IP +filter rules. +It is still possible to mount an NFS server through a firewall, +though some of the +.BR mount (8) +command's automatic service endpoint discovery mechanisms may not work; this +requires you to provide specific endpoint details via NFS mount options. +.P +NFS servers normally run a portmapper or rpcbind daemon to advertise +their service endpoints to clients. Clients use the rpcbind daemon to determine: +.IP +What network port each RPC-based service is using +.IP +What transport protocols each RPC-based service supports +.P +The rpcbind daemon uses a well-known port number (111) to help clients find a service endpoint. +Although NFS often uses a standard port number (2049), +auxiliary services such as the NLM service can choose +any unused port number at random. +.P +Common firewall configurations block the well-known rpcbind port. +In the absence of an rpcbind service, +the server administrator fixes the port number +of NFS-related services so that the firewall +can allow access to specific NFS service ports. +Client administrators then specify the port number +for the mountd service via the +.BR mount (8) +command's +.B mountport +option. +It may also be necessary to enforce the use of TCP or UDP +if the firewall blocks one of those transports. +.SS "NFS Access Control Lists" +Solaris allows NFS version 3 clients direct access +to POSIX Access Control Lists stored in its local file systems. +This proprietary sideband protocol, known as NFSACL, +provides richer access control than mode bits. +Linux implements this protocol +for compatibility with the Solaris NFS implementation. +The NFSACL protocol never became a standard part +of the NFS version 3 specification, however. +.P +The NFS version 4 specification mandates a new version +of Access Control Lists that are semantically richer than POSIX ACLs. +NFS version 4 ACLs are not fully compatible with POSIX ACLs; as such, +some translation between the two is required +in an environment that mixes POSIX ACLs and NFS version 4. +.SH "THE REMOUNT OPTION" +Generic mount options such as +.BR rw " and " sync +can be modified on NFS mount points using the +.BR remount +option. +See +.BR mount (8) +for more information on generic mount options. +.P +With few exceptions, NFS-specific options +are not able to be modified during a remount. +The underlying transport or NFS version +cannot be changed by a remount, for example. +.P +Performing a remount on an NFS file system mounted with the +.B noac +option may have unintended consequences. +The +.B noac +option is a combination of the generic option +.BR sync , +and the NFS-specific option +.BR actimeo=0 . +.SS "Unmounting after a remount" +For mount points that use NFS versions 2 or 3, the NFS umount subcommand +depends on knowing the original set of mount options used to perform the +MNT operation. +These options are stored on disk by the NFS mount subcommand, +and can be erased by a remount. +.P +To ensure that the saved mount options are not erased during a remount, +specify either the local mount directory, or the server hostname and +export pathname, but not both, during a remount. For example, +.P +.nf +.ta 8n + mount -o remount,ro /mnt +.fi +.P +merges the mount option +.B ro +with the mount options already saved on disk for the NFS server mounted at /mnt. +.SH FILES +.TP 1.5i +.I /etc/fstab +file system table +.TP 1.5i +.I /etc/nfsmount.conf +Configuration file for NFS mounts +.SH NOTES +Before 2.4.7, the Linux NFS client did not support NFS over TCP. +.P +Before 2.4.20, the Linux NFS client used a heuristic +to determine whether cached file data was still valid +rather than using the standard close-to-open cache coherency method +described above. +.P +Starting with 2.4.22, the Linux NFS client employs +a Van Jacobsen-based RTT estimator to determine retransmit +timeout values when using NFS over UDP. +.P +Before 2.6.0, the Linux NFS client did not support NFS version 4. +.P +Before 2.6.8, the Linux NFS client used only synchronous reads and writes +when the +.BR rsize " and " wsize +settings were smaller than the system's page size. +.P +The Linux client's support for protocol versions depend on whether the +kernel was built with options CONFIG_NFS_V2, CONFIG_NFS_V3, +CONFIG_NFS_V4, CONFIG_NFS_V4_1, and CONFIG_NFS_V4_2. +.SH "SEE ALSO" +.BR fstab (5), +.BR mount (8), +.BR umount (8), +.BR mount.nfs (5), +.BR umount.nfs (5), +.BR exports (5), +.BR nfsmount.conf (5), +.BR netconfig (5), +.BR ipv6 (7), +.BR nfsd (8), +.BR sm-notify (8), +.BR rpc.statd (8), +.BR rpc.idmapd (8), +.BR rpc.gssd (8), +.BR rpc.svcgssd (8), +.BR kerberos (1) +.sp +RFC 768 for the UDP specification. +.br +RFC 793 for the TCP specification. +.br +RFC 1813 for the NFS version 3 specification. +.br +RFC 1832 for the XDR specification. +.br +RFC 1833 for the RPC bind specification. +.br +RFC 2203 for the RPCSEC GSS API protocol specification. +.br +RFC 7530 for the NFS version 4.0 specification. +.br +RFC 5661 for the NFS version 4.1 specification. +.br +RFC 7862 for the NFS version 4.2 specification. diff --git a/upstream/fedora-40/man5/nfs.conf.5 b/upstream/fedora-40/man5/nfs.conf.5 new file mode 100644 index 00000000..d03fc887 --- /dev/null +++ b/upstream/fedora-40/man5/nfs.conf.5 @@ -0,0 +1,335 @@ +.TH NFS.CONF 5 +.SH NAME +nfs.conf \- general configuration for NFS daemons and tools +.SH SYNOPSIS +.I /usr/etc/nfs.conf +.I /usr/etc/nfs.conf.d/ +.I /etc/nfs.conf +.I /etc/nfs.conf.d/ +.SH DESCRIPTION +.PP +These files contain site-specific configuration for various NFS daemons +and other processes. Most configuration can also be passed to +processes via command line arguments, but it can be more convenient to +have a central file. In particular, this encourages consistent +configuration across different processes. +.PP +When command line options are provided, they override values set in +this file. When this file does not specify a particular parameter, +and no command line option is provided, each tool provides its own +default values. +.PP +The file format supports multiple sections, each of which can contain +multiple value assignments. A section is introduced by a line +containing the section name enclosed in square brackets, so +.RS +.B [global] +.RE +would introduce a section called +.BR global . +A value assignment is a single line that has the name of the value, an +equals sign, and a setting for the value, so +.RS +.B threads = 4 +.RE +would set the value named +.B threads +in the current section to +.BR 4 . +Leading and trailing spaces and tab +are ignored, as are spaces and tabs surrounding the equals sign. +Single and double quotes surrounding the assigned value are also +removed. If the resulting string is empty, the whole assignment +is ignored. +.PP +Any line starting with +.RB \*(lq # \*(rq +or +.RB \*(lq ; \*(rq +is ignored, as is any blank line. +.PP +If the assigned value started with a +.RB \*(lq $ \*(rq +then the remainder is treated as a name and looked for in the section +.B [environment] +or in the processes environment (see +.BR environ (7)). +The value found is used for this value. +.PP +The value name +.B include +is special. If a section contains +.RS +.B include = /some/file/name +.RE +then the named file will be read, and any value assignments found +there-in will be added to the current section. If the file contains +section headers, then new sections will be created just as if the +included file appeared in place of the +.B include +line. +If the file name starts with a hyphen then that is stripped off +before the file is opened, and if file doesn't exist no warning is +given. Normally a non-existent include file generates a warning. +.PP +Lookup of section and value names is case-insensitive. + +Where a Boolean value is expected, any of +.BR true , +.BR t , +.BR yes , +.BR y , +.BR on ", or" +.B 1 +can be used for "true", while +.BR false , +.BR f , +.BR no , +.BR n , +.BR off ", or" +.B 0 +can be used for "false". Comparisons are case-insensitive. + +.SH SECTIONS +The following sections are known to various programs, and can contain +the given named values. Most sections can also contain a +.B debug +value, which can be one or more from the list +.BR general , +.BR call , +.BR auth , +.BR parse , +.BR all . +When a list is given, the members should be comma-separated. +The values +.BR 0 +and +.BR 1 +are also accepted, with '0' making no changes to the debug level, and '1' equivalent to specifying 'all'. + +.TP +.B general +Recognized values: +.BR pipefs-directory . + +See +.BR blkmapd (8), +.BR rpc.idmapd (8), +and +.BR rpc.gssd (8) +for details. + +.TP +.B exports +Recognized values: +.BR rootdir . + +Setting +.B rootdir +to a valid path causes the nfs server to act as if the +supplied path is being prefixed to all the exported entries. For +instance, if +.BR rootdir=/my/root , +and there is an entry in /etc/exports for +.BR /filesystem , +then the client will be able to mount the path as +.BR /filesystem , +but on the server, this will resolve to the path +.BR /my/root/filesystem . + +.TP +.B exportd +Recognized values: +.BR manage-gids , +.BR threads , +.BR cache-use-ipaddr , +.BR ttl , +.BR state-directory-path + +See +.BR exportd (8) +for details. + +Note that setting +.B "\[dq]debug = auth\[dq]" +for +.B exportd +is equivalent to providing the +.B \-\-log\-auth +option. + +.TP +.B nfsdcltrack +Recognized values: +.BR storagedir . + +The +.B nfsdcltrack +program is run directly by the Linux kernel and there is no +opportunity to provide command line arguments, so the configuration +file is the only way to configure this program. See +.BR nfsdcltrack (8) +for details. + +.TP +.B nfsd +Recognized values: +.BR threads , +.BR host , +.BR scope , +.BR port , +.BR grace-time , +.BR lease-time , +.BR udp , +.BR tcp , +.BR vers3 , +.BR vers4 , +.BR vers4.0 , +.BR vers4.1 , +.BR vers4.2 , +.BR rdma , + +Version and protocol values are Boolean values as described above, +and are also used by +.BR rpc.mountd . +Threads and the two times are integers. +.B port +and +.B rdma +are service names or numbers. See +.BR rpc.nfsd (8) +for details. + +.TP +.B mountd +Recognized values: +.BR manage-gids , +.BR descriptors , +.BR port , +.BR threads , +.BR reverse-lookup , +.BR cache-use-ipaddr , +.BR ttl , +.BR state-directory-path , +.BR ha-callout . + +These, together with the protocol and version values in the +.B [nfsd] +section, are used to configure mountd. See +.BR rpc.mountd (8) +for details. + +Note that setting +.B "\[dq]debug = auth\[dq]" +for +.B mountd +is equivalent to providing the +.B \-\-log\-auth +option. + +The +.B state-directory-path +value in the +.B [mountd] +section is also used by +.BR exportfs (8). + +.TP +.B statd +Recognized values: +.BR port , +.BR outgoing-port , +.BR name , +.BR state-directory-path , +.BR ha-callout . + +See +.BR rpc.statd (8) +for details. + +.TP +.B lockd +Recognized values: +.B port +and +.BR udp-port . + +See +.BR rpc.statd (8) +for details. + +.TP +.B sm-notify +Recognized values: +.BR retry-time , +.BR outgoing-port ", and" +.BR outgoing-addr . + +See +.BR sm-notify (8) +for details. + +.TP +.B gssd +Recognized values: +.BR verbosity , +.BR rpc-verbosity , +.BR use-memcache , +.BR use-machine-creds , +.BR use-gss-proxy , +.BR avoid-dns , +.BR limit-to-legacy-enctypes , +.BR context-timeout , +.BR rpc-timeout , +.BR keytab-file , +.BR cred-cache-directory , +.BR preferred-realm , +.BR set-home . + +See +.BR rpc.gssd (8) +for details. + +.TP +.B svcgssd +Recognized values: +.BR principal . + +See +.BR rpc.svcgssd (8) +for details. + +.TP +.B exportfs +Only +.B debug= +is recognized. + +.TP +.B nfsrahead +Recognized values: +.BR nfs , +.BR nfsv4 , +.BR default . + +See +.BR nfsrahead (5) +for deatils. + +.SH FILES +.I /usr/etc/nfs.conf +.br +.I /usr/etc/nfs.conf.d/*.conf +.br +.I /etc/nfs.conf +.br +.I /etc/nfs.conf.d/*.conf +.br +.IP +Various configuration files read in order. Later settings override +earlier settings. +.SH SEE ALSO +.BR nfsdcltrack (8), +.BR rpc.nfsd (8), +.BR rpc.mountd (8), +.BR nfsmount.conf (5). diff --git a/upstream/fedora-40/man5/nfsmount.conf.5 b/upstream/fedora-40/man5/nfsmount.conf.5 new file mode 100644 index 00000000..6419190c --- /dev/null +++ b/upstream/fedora-40/man5/nfsmount.conf.5 @@ -0,0 +1,132 @@ +.\" @(#)nfsmount.conf.5" +.TH NFSMOUNT.CONF 5 "16 December 2020" +.SH NAME +nfsmount.conf - Configuration file for NFS mounts +.SH SYNOPSIS +Configuration file for NFS mounts that allows options +to be set globally, per server or per mount point. +.SH DESCRIPTION +The configuration file is made up of multiple section headers +followed by variable assignments associated with that section. +A section header is defined by a string enclosed by +.BR [ +and +.BR ] +brackets. +Variable assignments are assignment statements that assign values +to particular variables using the +.BR = +operator, as in +.BR Proto=Tcp . +The variables that can be assigned are the set of NFS specific +mount options listed in +.BR nfs (5) +together with the filesystem-independant mount options listed in +.BR mount (8) +and three additions: +.B Sloppy=True +has the same effect as the +.B -s +option to +.IR mount , +and +.B Foreground=True +and +.B Background=True +have the same effect as +.B bg +and +.BR fg . +.PP +Options in the config file may be given in upper, lower, or mixed case +and will be shifted to lower case before being passed to the filesystem. +.PP +Boolean mount options which do not need an equals sign must be given as +.RI \[dq] option =True". +Instead of preceding such an option with +.RB \[dq] no \[dq] +its negation must be given as +.RI \[dq] option =False". +.PP +Sections are broken up into three basic categories: +Global options, Server options and Mount Point options. +.HP +.B [ NFSMount_Global_Options ] +- This statically named section +defines all of the global mount options that can be +applied to every NFS mount. +.HP +.B [ Server \[dq]Server_Name\[dq] ] +- This section defines all the mount options that should +be used on mounts to a particular NFS server. The +.I \[dq]Server_Name\[dq] +strings needs to be surrounded by '\[dq]' and be an exact match +(ignoring case) of the server name used in the +.B mount +command. +.HP +.B [ MountPoint \[dq]Mount_Point\[dq] ] +- This section defines all the mount options that +should be used on a particular mount point. +The +.I \[dq]Mount_Point\[dq] +string needs to be surrounded by '\[dq]' and be an +exact match of the mount point used in the +.BR mount +command. Though path names are usually case-sensitive, the Mount_Point +name is matched insensitive to case. +.PP +The sections are processed in the reverse of the order listed above, and +any options already seen, either in a previous section or on the +command line, will be ignored when seen again. +.SH EXAMPLES +.PP +These are some example lines of how sections and variables +are defined in the configuration file. +.PP +[ NFSMount_Global_Options ] +.br + Proto=Tcp +.RS +.PP +The TCP/IPv4 protocol will be used on every NFS mount. +.RE +.PP +[ Server \[dq]nfsserver.foo.com\[dq] ] +.br + rsize=32k +.br + wsize=32k +.br + proto=udp6 +.RS +.PP +A 32k (32768 bytes) block size will be used as the read and write +size on all mounts to the 'nfsserver.foo.com' server. UDP/IPv6 +is the protocol to be used. +.RE +.PP +[ MountPoint \[dq]/export/home\[dq] ] +.br + Background=True +.RS +.PP +All mounts to the '/export/home' export will be performed in +the background (i.e. done asynchronously). +.RE +.SH FILES +.I /usr/etc/nfsmount.conf +.br +.I /usr/etc/nfsmount.conf.d/*.conf +.br +.I /etc/nfsmount.conf +.br +.I /etc/nfsmount.conf.d/*.conf +.br +.IP +Default NFS mount configuration files, variables set in the later file +over-ride those in the earlier file. +.PD +.SH SEE ALSO +.BR nfs (5), +.BR mount (8), diff --git a/upstream/fedora-40/man5/nfsrahead.5 b/upstream/fedora-40/man5/nfsrahead.5 new file mode 100644 index 00000000..5488f633 --- /dev/null +++ b/upstream/fedora-40/man5/nfsrahead.5 @@ -0,0 +1,72 @@ +.\" Manpage for nfsrahead. +.nh +.ad l +.TH man 5 "08 Mar 2022" "1.0" "nfsrahead man page" +.SH NAME + +nfsrahead \- Configure the readahead for NFS mounts + +.SH SYNOPSIS + +nfsrahead [-F] [-d] + +.SH DESCRIPTION + +\fInfsrahead\fR is a tool intended to be used with udev to set the \fIread_ahead_kb\fR parameter of NFS mounts, according to the configuration file (see \fICONFIGURATION\fR). \fIdevice\fR is the device number for the NFS backing device as provided by the kernel. + +.SH OPTIONS +.TP +.B -F +Send messages to +.I stderr +instead of +.I syslog + +.TP +.B -d +Increase the debugging level. + +.SH CONFIGURATION +.I nfsrahead +is configured in +.IR /etc/nfs.conf , +in the section titled +.IR nfsrahead . +It accepts the following configurations. + +.TP +.B nfs= +The readahead value applied to NFSv3 mounts. + +.TP +.B nfs4= +The readahead value applied to NFSv4 mounts. + +.TP +.B default= +The default configuration when none of the configurations above is set. + +.SH EXAMPLE CONFIGURATION +[nfsrahead] +.br +nfs=15000 # readahead of 15000 for NFSv3 mounts +.br +nfs4=16000 # readahead of 16000 for NFSv4 mounts +.br +default=128 # default is 128 + +.SH SEE ALSO + +.BR mount.nfs (8), +.BR nfs (5), +.BR nfs.conf (5), +.BR udev (7), +.BR bcc-readahead (8) + +.SH BUGS + +No known bugs. + +.SH AUTHOR + +Thiago Rafael Becker diff --git a/upstream/fedora-40/man5/nologin.5 b/upstream/fedora-40/man5/nologin.5 new file mode 100644 index 00000000..e5875188 --- /dev/null +++ b/upstream/fedora-40/man5/nologin.5 @@ -0,0 +1,22 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:06:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Corrected Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH nologin 5 2022-10-30 "Linux man-pages 6.06" +.SH NAME +nologin \- prevent unprivileged users from logging into the system +.SH DESCRIPTION +If the file \fI/etc/nologin\fP exists and is readable, +.BR login (1) +will allow access only to root. +Other users will +be shown the contents of this file and their logins will be refused. +This provides a simple way of temporarily disabling all unprivileged logins. +.SH FILES +.I /etc/nologin +.SH SEE ALSO +.BR login (1), +.BR shutdown (8) diff --git a/upstream/fedora-40/man5/nscd.conf.5 b/upstream/fedora-40/man5/nscd.conf.5 new file mode 100644 index 00000000..6f9695cd --- /dev/null +++ b/upstream/fedora-40/man5/nscd.conf.5 @@ -0,0 +1,342 @@ +.\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" Updates: Greg Banks Copyright (c) 2021 Microsoft Corp. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH nscd.conf 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +nscd.conf \- name service cache daemon configuration file +.SH DESCRIPTION +The file +.I /etc/nscd.conf +is read from +.BR nscd (8) +at startup. +Each line specifies either an attribute and a value, or an +attribute, service, and a value. +Fields are separated either by SPACE +or TAB characters. +A \[aq]#\[aq] (number sign) indicates the beginning of a +comment; following characters, up to the end of the line, +are not interpreted by nscd. +.P +Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP, +or \fInetgroup\fP. +.P +.B logfile +.I debug-file-name +.RS +Specifies name of the file to which debug info should be written. +.RE +.P +.B debug\-level +.I value +.RS +Sets the desired debug level. +0 hides debug info. +1 shows general debug info. +2 additionally shows data in cache dumps. +3 (and above) shows all debug info. +The default is 0. +.RE +.P +.B threads +.I number +.RS +This is the initial number of threads that are started to wait for +requests. +At least five threads will always be created. +The number of threads may increase dynamically up to +.B max\-threads +in response to demand from clients, +but never decreases. +.RE +.P +.B max\-threads +.I number +.RS +Specifies the maximum number of threads. +The default is 32. +.RE +.P +.B server\-user +.I user +.RS +If this option is set, nscd will run as this user and not as root. +If a separate cache for every user is used (\-S parameter), this +option is ignored. +.RE +.P +.B stat\-user +.I user +.RS +Specifies the user who is allowed to request statistics. +.RE +.P +.B reload\-count +unlimited | +.I number +.RS +Sets a limit on the number of times a cached entry +gets reloaded without being used +before it gets removed. +The limit can take values ranging from 0 to 254; +values 255 or higher behave the same as +.BR unlimited . +Limit values can be specified in either decimal +or hexadecimal with a "0x" prefix. +The special value +.B unlimited +is case-insensitive. +The default limit is 5. +A limit of 0 turns off the reloading feature. +See NOTES below for further discussion of reloading. +.RE +.P +.B paranoia +.I +.RS +Enabling paranoia mode causes nscd to restart itself periodically. +The default is no. +.RE +.P +.B restart\-interval +.I time +.RS +Sets the restart interval to +.I time +seconds +if periodic restart is enabled by enabling +.B paranoia +mode. +The default is 3600. +.RE +.P +.B enable\-cache +.I service +.I +.RS +Enables or disables the specified +.I service +cache. +The default is no. +.RE +.P +.B positive\-time\-to\-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for positive entries (successful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. +Larger values increase cache hit rates and reduce mean +response times, but increase problems with cache coherence. +Note that for some name services (including specifically DNS) +the TTL returned from the name service is used and +this attribute is ignored. +.RE +.P +.B negative\-time\-to\-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for negative entries (unsuccessful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. +Can result in significant performance improvements if there +are several files owned by UIDs (user IDs) not in system databases (for +example untarring the Linux kernel sources as root); should be kept small +to reduce cache coherency problems. +.RE +.P +.B suggested\-size +.I service +.I value +.RS +This is the internal hash table size, +.I value +should remain a prime number for optimum efficiency. +The default is 211. +.RE +.P +.B check\-files +.I service +.I +.RS +Enables or disables checking the file belonging to the specified +.I service +for changes. +The files are +.IR /etc/passwd , +.IR /etc/group , +.IR /etc/hosts , +.IR /etc/resolv.conf , +.IR /etc/services , +and +.IR /etc/netgroup . +The default is yes. +.RE +.P +.B persistent +.I service +.I +.RS +Keep the content of the cache for +.I service +over server restarts; useful when +.B paranoia +mode is set. +The default is no. +.RE +.P +.B shared +.I service +.I +.RS +The memory mapping of the nscd databases for +.I service +is shared with the clients so +that they can directly search in them instead of having to ask the +daemon over the socket each time a lookup is performed. +The default is no. +Note that a cache miss will still result in +asking the daemon over the socket. +.RE +.P +.B max\-db\-size +.I service +.I bytes +.RS +The maximum allowable size, in bytes, of the database files for the +.IR service . +The default is 33554432. +.RE +.P +.B auto\-propagate +.I service +.I +.RS +When set to +.I no +for +.I passwd +or +.I group +service, then the +.I .byname +requests are not added to +.I passwd.byuid +or +.I group.bygid +cache. +This can help with tables containing multiple records for the same ID. +The default is yes. +This option is valid only for services +.I passwd +and +.IR group . +.RE +.SH NOTES +The default values stated in this manual page originate +from the source code of +.BR nscd (8) +and are used if not overridden in the configuration file. +The default values used in the configuration file of +your distribution might differ. +.SS Reloading +.BR nscd (8) +has a feature called reloading, +whose behavior can be surprising. +.P +Reloading is enabled when the +.B reload-count +attribute has a non-zero value. +The default value in the source code enables reloading, +although your distribution may differ. +.P +When reloading is enabled, +positive cached entries (the results of successful queries) +do not simply expire when their TTL is up. +Instead, at the expiry time, +.B nscd +will "reload", +i.e., +re-issue to the name service the same query that created the cached entry, +to get a new value to cache. +Depending on +.I /etc/nsswitch.conf +this may mean that a DNS, LDAP, or NIS request is made. +If the new query is successful, +reloading will repeat when the new value would expire, +until +.B reload-count +reloads have happened for the entry, +and only then will it actually be removed from the cache. +A request from a client which hits the entry will +reset the reload counter on the entry. +Purging the cache using +.I nscd\~-i +overrides the reload logic and removes the entry. +.P +Reloading has the effect of extending cache entry TTLs +without compromising on cache coherency, +at the cost of additional load on the backing name service. +Whether this is a good idea on your system depends on +details of your applications' behavior, +your name service, +and the effective TTL values of your cache entries. +Note that for some name services +(for example, DNS), +the effective TTL is the value returned from the name service and +.I not +the value of the +.B positive\-time\-to\-live +attribute. +.P +Please consider the following advice carefully: +.IP \[bu] 3 +If your application will make a second request for the same name, +after more than 1 TTL but before +.B reload\-count +TTLs, +and is sensitive to the latency of a cache miss, +then reloading may be a good idea for you. +.IP \[bu] +If your name service is configured to return very short TTLs, +and your applications only make requests rarely under normal circumstances, +then reloading may result in additional load on your backing name service +without any benefit to applications, +which is probably a bad idea for you. +.IP \[bu] +If your name service capacity is limited, +reloading may have the surprising effect of +increasing load on your name service instead of reducing it, +and may be a bad idea for you. +.IP \[bu] +Setting +.B reload\-count +to +.B unlimited +is almost never a good idea, +as it will result in a cache that never expires entries +and puts never-ending additional load on the backing name service. +.P +Some distributions have an init script for +.BR nscd (8) +with a +.I reload +command which uses +.I nscd\~-i +to purge the cache. +That use of the word "reload" is entirely different +from the "reloading" described here. +.SH SEE ALSO +.BR nscd (8) +.\" .SH AUTHOR +.\" .B nscd +.\" was written by Thorsten Kukuk and Ulrich Drepper. diff --git a/upstream/fedora-40/man5/nss.5 b/upstream/fedora-40/man5/nss.5 new file mode 100644 index 00000000..cf301fc3 --- /dev/null +++ b/upstream/fedora-40/man5/nss.5 @@ -0,0 +1,101 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved. +.\" Author: Ulrich Drepper +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.TH nss 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +nss \- Name Service Switch configuration file +.SH DESCRIPTION +Each call to a function which retrieves data from a system database +like the password or group database is handled by the Name Service +Switch implementation in the GNU C library. +The various services +provided are implemented by independent modules, each of which +naturally varies widely from the other. +.P +The default implementations coming with the GNU C library are by +default conservative and do not use unsafe data. +This might be very costly in some situations, especially when the databases +are large. +Some modules allow the system administrator to request +taking shortcuts if these are known to be safe. +It is then the system administrator's responsibility to ensure the assumption +is correct. +.P +There are other modules where the implementation changed over time. +If an implementation used to sacrifice speed for memory consumption, +it might create problems if the preference is switched. +.P +The +.I /etc/default/nss +file contains a number of variable assignments. +Each variable controls the behavior of one or more +NSS modules. +White spaces are ignored. +Lines beginning with \[aq]#\[aq] +are treated as comments. +.P +The variables currently recognized are: +.TP +\fBNETID_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR initgroups (3) +function will accept the information +from the +.I netid.byname +NIS map as authoritative. +This can speed up the function significantly if the +.I group.byname +map is large. +The content of the +.I netid.byname +map is used \fBas is\fR. +The system administrator has to make sure it is correctly generated. +.TP +\fBSERVICES_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR getservbyname (3) +and +.BR getservbyname_r (3) +functions will assume that the +.I services.byservicename +NIS map exists and is authoritative, particularly +that it contains both keys with /proto and without /proto for both +primary service names and service aliases. +The system administrator has to make sure it is correctly generated. +.TP +\fBSETENT_BATCH_READ =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR setpwent (3) +and +.BR setgrent (3) +functions will read the entire database at once and then +hand out the requests one by one from memory with every corresponding +.BR getpwent (3) +or +.BR getgrent (3) +call respectively. +Otherwise, each +.BR getpwent (3) +or +.BR getgrent (3) +call might result in a network communication with the server to get +the next entry. +.SH FILES +\fI/etc/default/nss\fR +.SH EXAMPLES +The default configuration corresponds to the following configuration file: +.P +.in +4n +.EX +NETID_AUTHORITATIVE=FALSE +SERVICES_AUTHORITATIVE=FALSE +SETENT_BATCH_READ=FALSE +.EE +.in +.\" .SH AUTHOR +.\" Ulrich Drepper +.\" +.SH SEE ALSO +\fInsswitch.conf\fR diff --git a/upstream/fedora-40/man5/nsswitch.conf.5 b/upstream/fedora-40/man5/nsswitch.conf.5 new file mode 100644 index 00000000..2d2bd64c --- /dev/null +++ b/upstream/fedora-40/man5/nsswitch.conf.5 @@ -0,0 +1,427 @@ +.\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de) +.\" Copyright (c) 2011, Mark R. Bannister +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH nsswitch.conf 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +nsswitch.conf \- Name Service Switch configuration file +.SH DESCRIPTION +The Name Service Switch (NSS) configuration file, +.IR /etc/nsswitch.conf , +is used by the GNU C Library and certain other applications to determine +the sources from which to obtain name-service information in +a range of categories, +and in what order. +Each category of information is identified by a database name. +.P +The file is plain ASCII text, with columns separated by spaces or tab +characters. +The first column specifies the database name. +The remaining columns describe the order of sources to query and a +limited set of actions that can be performed by lookup result. +.P +The following databases are understood by the GNU C Library: +.TP 12 +.B aliases +Mail aliases, used by +.BR getaliasent (3) +and related functions. +.TP +.B ethers +Ethernet numbers. +.TP +.B group +Groups of users, used by +.BR getgrent (3) +and related functions. +.TP +.B hosts +Host names and numbers, used by +.BR gethostbyname (3) +and related functions. +.TP +.B initgroups +Supplementary group access list, used by +.BR getgrouplist (3) +function. +.TP +.B netgroup +Network-wide list of hosts and users, used for access rules. +C libraries before glibc 2.1 supported netgroups only over NIS. +.TP +.B networks +Network names and numbers, used by +.BR getnetent (3) +and related functions. +.TP +.B passwd +User passwords, used by +.BR getpwent (3) +and related functions. +.TP +.B protocols +Network protocols, used by +.BR getprotoent (3) +and related functions. +.TP +.B publickey +Public and secret keys for Secure_RPC used by NFS and NIS+. +.TP +.B rpc +Remote procedure call names and numbers, used by +.BR getrpcbyname (3) +and related functions. +.TP +.B services +Network services, used by +.BR getservent (3) +and related functions. +.TP +.B shadow +Shadow user passwords, used by +.BR getspnam (3) +and related functions. +.P +The GNU C Library ignores databases with unknown names. +Some applications use this to implement special handling for their own +databases. +For example, +.BR sudo (8) +consults the +.B sudoers +database. +Delegation of subordinate user/group IDs +can be configured using the +.B subid +database. +Refer to +.BR subuid (5) +and +.BR subgid (5) +for more details. +.P +Here is an example +.I /etc/nsswitch.conf +file: +.P +.in +4n +.EX +passwd: compat +group: compat +shadow: compat +\& +hosts: dns [!UNAVAIL=return] files +networks: nis [NOTFOUND=return] files +ethers: nis [NOTFOUND=return] files +protocols: nis [NOTFOUND=return] files +rpc: nis [NOTFOUND=return] files +services: nis [NOTFOUND=return] files +.EE +.in +.P +The first column is the database name. +The remaining columns specify: +.IP \[bu] 3 +One or more service specifications, for example, "files", "db", or "nis". +The order of the services on the line determines the order in which +those services will be queried, in turn, until a result is found. +.IP \[bu] +Optional actions to perform if a particular result is obtained +from the preceding service, for example, "[NOTFOUND=return]". +.P +The service specifications supported on your system depend on the +presence of shared libraries, and are therefore extensible. +Libraries called +.IB /lib/libnss_SERVICE.so. X +will provide the named +.IR SERVICE . +On a standard installation, you can use +"files", "db", "nis", and "nisplus". +For the +.B hosts +database, you can additionally specify "dns". +For the +.BR passwd , +.BR group , +and +.B shadow +databases, you can additionally specify +"compat" (see +.B "Compatibility mode" +below). +The version number +.B X +may be 1 for glibc 2.0, or 2 for glibc 2.1 and later. +On systems with additional libraries installed, you may have access to +further services such as "hesiod", "ldap", "winbind", and "wins". +.P +An action may also be specified following a service specification. +The action modifies the behavior following a result obtained +from the preceding data source. +Action items take the general form: +.P +.RS 4 +.RI [ STATUS = ACTION ] +.br +.RI [! STATUS = ACTION ] +.RE +.P +where +.P +.RS 4 +.I STATUS +=> +.B success +| +.B notfound +| +.B unavail +| +.B tryagain +.br +.I ACTION +=> +.B return +| +.B continue +| +.B merge +.RE +.P +The ! negates the test, matching all possible results except the +one specified. +The case of the keywords is not significant. +.P +The +.I STATUS +value is matched against the result of the lookup function called by +the preceding service specification, and can be one of: +.RS 4 +.TP 12 +.B success +No error occurred and the requested entry is returned. +The default action for this condition is "return". +.TP +.B notfound +The lookup succeeded, but the requested entry was not found. +The default action for this condition is "continue". +.TP +.B unavail +The service is permanently unavailable. +This can mean either that the +required file cannot be read, or, for network services, that the server +is not available or does not allow queries. +The default action for this condition is "continue". +.TP +.B tryagain +The service is temporarily unavailable. +This could mean a file is +locked or a server currently cannot accept more connections. +The default action for this condition is "continue". +.RE +.P +The +.I ACTION +value can be one of: +.RS 4 +.TP 12 +.B return +Return a result now. +Do not call any further lookup functions. +However, for compatibility reasons, if this is the selected action for the +.B group +database and the +.B notfound +status, and the configuration file does not contain the +.B initgroups +line, the next lookup function is always called, +without affecting the search result. +.TP +.B continue +Call the next lookup function. +.TP +.B merge +.I [SUCCESS=merge] +is used between two database entries. +When a group is located in the first of the two group entries, +processing will continue on to the next one. +If the group is also found in the next entry (and the group name and GID +are an exact match), the member list of the second entry will be added +to the group object to be returned. +Available since glibc 2.24. +Note that merging will not be done for +.BR getgrent (3) +nor will duplicate members be pruned when they occur in both entries +being merged. +.RE +.SS Compatibility mode (compat) +The NSS "compat" service is similar to "files" except that it +additionally permits special entries in corresponding files +for granting users or members of netgroups access to the system. +The following entries are valid in this mode: +.RS 4 +.P +For +.B passwd +and +.B shadow +databases: +.RS 4 +.TP 12 +.BI + user +Include the specified +.I user +from the NIS passwd/shadow map. +.TP +.BI +@ netgroup +Include all users in the given +.IR netgroup . +.TP +.BI \- user +Exclude the specified +.I user +from the NIS passwd/shadow map. +.TP +.BI \-@ netgroup +Exclude all users in the given +.IR netgroup . +.TP +.B + +Include every user, except previously excluded ones, from the +NIS passwd/shadow map. +.RE +.P +For +.B group +database: +.RS 4 +.TP 12 +.BI + group +Include the specified +.I group +from the NIS group map. +.TP +.BI \- group +Exclude the specified +.I group +from the NIS group map. +.TP +.B + +Include every group, except previously excluded ones, from the +NIS group map. +.RE +.RE +.P +By default, the source is "nis", but this may be +overridden by specifying any NSS service except "compat" itself +as the source for the pseudo-databases +.BR passwd_compat , +.BR group_compat , +and +.BR shadow_compat . +.SH FILES +A service named +.I SERVICE +is implemented by a shared object library named +.IB libnss_SERVICE.so. X +that resides in +.IR /lib . +.RS 4 +.TP 25 +.PD 0 +.I /etc/nsswitch.conf +NSS configuration file. +.TP +.IB /lib/libnss_compat.so. X +implements "compat" source. +.TP +.IB /lib/libnss_db.so. X +implements "db" source. +.TP +.IB /lib/libnss_dns.so. X +implements "dns" source. +.TP +.IB /lib/libnss_files.so. X +implements "files" source. +.TP +.IB /lib/libnss_hesiod.so. X +implements "hesiod" source. +.TP +.IB /lib/libnss_nis.so. X +implements "nis" source. +.TP +.IB /lib/libnss_nisplus.so. X +implements "nisplus" source. +.PD +.RE +.P +The following files are read when "files" source is specified +for respective databases: +.RS 4 +.TP 12 +.PD 0 +.B aliases +.I /etc/aliases +.TP +.B ethers +.I /etc/ethers +.TP +.B group +.I /etc/group +.TP +.B hosts +.I /etc/hosts +.TP +.B initgroups +.I /etc/group +.TP +.B netgroup +.I /etc/netgroup +.TP +.B networks +.I /etc/networks +.TP +.B passwd +.I /etc/passwd +.TP +.B protocols +.I /etc/protocols +.TP +.B publickey +.I /etc/publickey +.TP +.B rpc +.I /etc/rpc +.TP +.B services +.I /etc/services +.TP +.B shadow +.I /etc/shadow +.PD +.RE +.SH NOTES +Starting with glibc 2.33, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=12459 +.B nsswitch.conf +is automatically reloaded if the file is changed. +In earlier versions, the entire file was read only once within each process. +If the file was later changed, +the process would continue using the old configuration. +.P +Traditionally, there was only a single source for service information, +often in the form of a single configuration +file (e.g., \fI/etc/passwd\fP). +However, as other name services, such as the Network Information +Service (NIS) and the Domain Name Service (DNS), became popular, +a method was needed +that would be more flexible than fixed search orders coded into +the C library. +The Name Service Switch mechanism, +which was based on the mechanism used by +Sun Microsystems in the Solaris 2 C library, +introduced a cleaner solution to the problem. +.SH SEE ALSO +.BR getent (1), +.BR nss (5) diff --git a/upstream/fedora-40/man5/oomd.conf.5 b/upstream/fedora-40/man5/oomd.conf.5 new file mode 100644 index 00000000..b6b0b1a8 --- /dev/null +++ b/upstream/fedora-40/man5/oomd.conf.5 @@ -0,0 +1,114 @@ +'\" t +.TH "OOMD\&.CONF" "5" "" "systemd 255" "oomd.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +oomd.conf, oomd.conf.d \- Global \fBsystemd\-oomd\fR configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/oomd\&.conf +.PP +/etc/systemd/oomd\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/oomd\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These files configure the various parameters of the +\fBsystemd\fR(1) +userspace out\-of\-memory (OOM) killer, +\fBsystemd-oomd.service\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "[OOM] SECTION OPTIONS" +.PP +The following options are available in the [OOM] section: +.PP +\fISwapUsedLimit=\fR +.RS 4 +Sets the limit for memory and swap usage on the system before +\fBsystemd\-oomd\fR +will take action\&. If the fraction of memory used and the fraction of swap used on the system are both more than what is defined here, +\fBsystemd\-oomd\fR +will act on eligible descendant control groups with swap usage greater than 5% of total swap, starting from the ones with the highest swap usage\&. Which control groups are monitored and what action gets taken depends on what the unit has configured for +\fIManagedOOMSwap=\fR\&. Takes a value specified in percent (when suffixed with "%"), permille ("‰") or permyriad ("‱"), between 0% and 100%, inclusive\&. Defaults to 90%\&. +.sp +Added in version 247\&. +.RE +.PP +\fIDefaultMemoryPressureLimit=\fR +.RS 4 +Sets the limit for memory pressure on the unit\*(Aqs control group before +\fBsystemd\-oomd\fR +will take action\&. A unit can override this value with +\fIManagedOOMMemoryPressureLimit=\fR\&. The memory pressure for this property represents the fraction of time in a 10 second window in which all tasks in the control group were delayed\&. For each monitored control group, if the memory pressure on that control group exceeds the limit set for longer than the duration set by +\fIDefaultMemoryPressureDurationSec=\fR, +\fBsystemd\-oomd\fR +will act on eligible descendant control groups, starting from the ones with the most reclaim activity to the least reclaim activity\&. Which control groups are monitored and what action gets taken depends on what the unit has configured for +\fIManagedOOMMemoryPressure=\fR\&. Takes a fraction specified in the same way as +\fISwapUsedLimit=\fR +above\&. Defaults to 60%\&. +.sp +Added in version 247\&. +.RE +.PP +\fIDefaultMemoryPressureDurationSec=\fR +.RS 4 +Sets the amount of time a unit\*(Aqs control group needs to have exceeded memory pressure limits before +\fBsystemd\-oomd\fR +will take action\&. Memory pressure limits are defined by +\fIDefaultMemoryPressureLimit=\fR +and +\fIManagedOOMMemoryPressureLimit=\fR\&. Must be set to 0, or at least 1 second\&. Defaults to 30 seconds when unset or 0\&. +.sp +Added in version 248\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd.resource-control\fR(5), +\fBsystemd-oomd.service\fR(8), +\fBoomctl\fR(1) diff --git a/upstream/fedora-40/man5/org.freedesktop.LogControl1.5 b/upstream/fedora-40/man5/org.freedesktop.LogControl1.5 new file mode 100644 index 00000000..70733a8e --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.LogControl1.5 @@ -0,0 +1,391 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.LOGCONTROL1" "5" "" "systemd 255" "org.freedesktop.LogControl1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.LogControl1 \- D\-Bus interface to query and set logging configuration +.SH "INTRODUCTION" +.PP +org\&.freedesktop\&.LogControl1 +is a generic interface that is intended to be used by any daemon which allows the log level and target to be set over D\-Bus\&. It is implemented by various daemons that are part of the +\fBsystemd\fR(1) +suite\&. +.PP +It is assumed that those settings are global for the whole program, so a fixed object path is used\&. The interface should always be available under the path +/org/freedesktop/LogControl1\&. +.SH "DESCRIPTION" +.PP +The following interface is exposed: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/LogControl1 { + interface org\&.freedesktop\&.LogControl1 { + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite s LogLevel = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite s LogTarget = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s SyslogIdentifier = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + +.SS "Properties" +.PP +\fILogLevel\fR +describes the +\fBsyslog\fR(3)\-style log\-level, and should be one of +"emerg", +"alert", +"crit", +"err", +"warning", +"notice", +"info", +"debug", in order of increasing verbosity\&. +.PP +\fILogTarget\fR +describes the log target (mechanism)\&. It should be one of +"console" +(log to the console or standard output), +"kmsg" +(log to the kernel ring buffer), +"journal" +(log to the journal natively, see +\fBsystemd-journald.service\fR(8)), +"syslog" +(log using the +\fBsyslog\fR(3) +call)\&. +.PP +Those two properties are writable, so they may be set by sufficiently privileged users\&. +.PP +\fISyslogIdentifier\fR +is a read\-only property that shows the "syslog identifier"\&. It is a short string that identifies the program that is the source of log messages that is passed to the +\fBsyslog\fR(3) +call\&. +.SH "TOOLS" +.PP +\fBjournalctl\fR +option +\fB\-p\fR/\fB\-\-priority=\fR +may be used to filter log messages by log level, option +\fB\-t\fR/\fB\-\-identifier=\fR +may be used to by the syslog identifier, and filters like +"_TRANSPORT=syslog", +"_TRANSPORT=journal", and +"_TRANSPORT=kernel" +may be used to filter messages by the mechanism through which they reached +\fBsystemd\-journald\fR\&. +.PP +\fBsystemctl log\-level\fR +and +\fBsystemctl log\-target\fR +verbs may be used to query and set the +\fILogLevel\fR +and +\fILogTarget\fR +properties of the service manager\&. +\fBsystemctl service\-log\-level\fR +and +\fBsystemctl service\-log\-target\fR +may similarly be used for individual services\&. (Services must have the +\fIBusName=\fR +property set and must implement the interface described here\&. See +\fBsystemd.service\fR(5) +for details about +\fIBusName=\fR\&.) +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&Create a simple listener on the bus that implements LogControl1\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* SPDX\-License\-Identifier: MIT\-0 */ + +/* Implements the LogControl1 interface as per specification: + * https://www\&.freedesktop\&.org/software/systemd/man/org\&.freedesktop\&.LogControl1\&.html + * + * Compile with \*(Aqcc logcontrol\-example\&.c $(pkg\-config \-\-libs \-\-cflags libsystemd)\*(Aq + * + * To get and set properties via busctl: + * + * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e + * /org/freedesktop/LogControl1 \e + * org\&.freedesktop\&.LogControl1 \e + * SyslogIdentifier + * s "example" + * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e + * /org/freedesktop/LogControl1 \e + * org\&.freedesktop\&.LogControl1 \e + * LogTarget + * s "journal" + * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e + * /org/freedesktop/LogControl1 \e + * org\&.freedesktop\&.LogControl1 \e + * LogLevel + * s "info" + * $ busctl \-\-user set\-property org\&.freedesktop\&.Example \e + * /org/freedesktop/LogControl1 \e + * org\&.freedesktop\&.LogControl1 \e + * LogLevel \e + * "s" debug + * $ busctl \-\-user get\-property org\&.freedesktop\&.Example \e + * /org/freedesktop/LogControl1 \e + * org\&.freedesktop\&.LogControl1 \e + * LogLevel + * s "debug" + */ + +#include +#include +#include +#include +#include +#include + +#define _cleanup_(f) __attribute__((cleanup(f))) + +#define check(log_level, x) ({ \e + int _r = (x); \e + errno = _r < 0 ? \-_r : 0; \e + sd_journal_print((log_level), #x ": %m"); \e + if (_r < 0) \e + return EXIT_FAILURE; \e + }) + +typedef enum LogTarget { + LOG_TARGET_JOURNAL, + LOG_TARGET_KMSG, + LOG_TARGET_SYSLOG, + LOG_TARGET_CONSOLE, + _LOG_TARGET_MAX, +} LogTarget; + +static const char* const log_target_table[_LOG_TARGET_MAX] = { + [LOG_TARGET_JOURNAL] = "journal", + [LOG_TARGET_KMSG] = "kmsg", + [LOG_TARGET_SYSLOG] = "syslog", + [LOG_TARGET_CONSOLE] = "console", +}; + +static const char* const log_level_table[LOG_DEBUG + 1] = { + [LOG_EMERG] = "emerg", + [LOG_ALERT] = "alert", + [LOG_CRIT] = "crit", + [LOG_ERR] = "err", + [LOG_WARNING] = "warning", + [LOG_NOTICE] = "notice", + [LOG_INFO] = "info", + [LOG_DEBUG] = "debug", +}; + +typedef struct object { + const char *syslog_identifier; + LogTarget log_target; + int log_level; +} object; + +static int property_get( + sd_bus *bus, + const char *path, + const char *interface, + const char *property, + sd_bus_message *reply, + void *userdata, + sd_bus_error *error) { + + object *o = userdata; + + if (strcmp(property, "LogLevel") == 0) + return sd_bus_message_append(reply, "s", log_level_table[o\->log_level]); + + if (strcmp(property, "LogTarget") == 0) + return sd_bus_message_append(reply, "s", log_target_table[o\->log_target]); + + if (strcmp(property, "SyslogIdentifier") == 0) + return sd_bus_message_append(reply, "s", o\->syslog_identifier); + + return sd_bus_error_setf(error, + SD_BUS_ERROR_UNKNOWN_PROPERTY, + "Unknown property \*(Aq%s\*(Aq", + property); +} + +static int property_set( + sd_bus *bus, + const char *path, + const char *interface, + const char *property, + sd_bus_message *message, + void *userdata, + sd_bus_error *error) { + + object *o = userdata; + const char *value; + int r; + + r = sd_bus_message_read(message, "s", &value); + if (r < 0) + return r; + + if (strcmp(property, "LogLevel") == 0) { + for (int i = 0; i < LOG_DEBUG + 1; i++) + if (strcmp(value, log_level_table[i]) == 0) { + o\->log_level = i; + setlogmask(LOG_UPTO(i)); + return 0; + } + + return sd_bus_error_setf(error, + SD_BUS_ERROR_INVALID_ARGS, + "Invalid value for LogLevel: \*(Aq%s\*(Aq", + value); + } + + if (strcmp(property, "LogTarget") == 0) { + for (LogTarget i = 0; i < _LOG_TARGET_MAX; i++) + if (strcmp(value, log_target_table[i]) == 0) { + o\->log_target = i; + return 0; + } + + return sd_bus_error_setf(error, + SD_BUS_ERROR_INVALID_ARGS, + "Invalid value for LogTarget: \*(Aq%s\*(Aq", + value); + } + + return sd_bus_error_setf(error, + SD_BUS_ERROR_UNKNOWN_PROPERTY, + "Unknown property \*(Aq%s\*(Aq", + property); +} + +/* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html + */ +static const sd_bus_vtable vtable[] = { + SD_BUS_VTABLE_START(0), + SD_BUS_WRITABLE_PROPERTY( + "LogLevel", "s", + property_get, property_set, + 0, + 0), + SD_BUS_WRITABLE_PROPERTY( + "LogTarget", "s", + property_get, property_set, + 0, + 0), + SD_BUS_PROPERTY( + "SyslogIdentifier", "s", + property_get, + 0, + SD_BUS_VTABLE_PROPERTY_CONST), + SD_BUS_VTABLE_END +}; + +int main(int argc, char **argv) { + /* The bus should be relinquished before the program terminates\&. The cleanup + * attribute allows us to do it nicely and cleanly whenever we exit the + * block\&. + */ + _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL; + + object o = { + \&.log_level = LOG_INFO, + \&.log_target = LOG_TARGET_JOURNAL, + \&.syslog_identifier = "example", + }; + + /* https://man7\&.org/linux/man\-pages/man3/setlogmask\&.3\&.html + * Programs using syslog() instead of sd_journal can use this API to cut logs + * emission at the source\&. + */ + setlogmask(LOG_UPTO(o\&.log_level)); + + /* Acquire a connection to the bus, letting the library work out the details\&. + * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_default\&.html + */ + check(o\&.log_level, sd_bus_default(&bus)); + + /* Publish an interface on the bus, specifying our well\-known object access + * path and public interface name\&. + * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_add_object\&.html + * https://dbus\&.freedesktop\&.org/doc/dbus\-tutorial\&.html + */ + check(o\&.log_level, sd_bus_add_object_vtable(bus, NULL, + "/org/freedesktop/LogControl1", + "org\&.freedesktop\&.LogControl1", + vtable, + &o)); + + /* By default the service is assigned an ephemeral name\&. Also add a fixed + * one, so that clients know whom to call\&. + * https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_request_name\&.html + */ + check(o\&.log_level, sd_bus_request_name(bus, "org\&.freedesktop\&.Example", 0)); + + for (;;) { + /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_wait\&.html + */ + check(o\&.log_level, sd_bus_wait(bus, UINT64_MAX)); + /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_process\&.html + */ + check(o\&.log_level, sd_bus_process(bus, NULL)); + } + + /* https://www\&.freedesktop\&.org/software/systemd/man/sd_bus_release_name\&.html + */ + check(o\&.log_level, sd_bus_release_name(bus, "org\&.freedesktop\&.Example")); + + return 0; +} +.fi +.if n \{\ +.RE +.\} +.PP +This creates a simple server on the bus\&. It implements the LogControl1 interface by providing the required properties and allowing to set the writable ones\&. It logs at the configured log level using +\fBsd_journal_print\fR(3)\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBjournalctl\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.service\fR(5), +\fBsyslog\fR(3) diff --git a/upstream/fedora-40/man5/org.freedesktop.home1.5 b/upstream/fedora-40/man5/org.freedesktop.home1.5 new file mode 100644 index 00000000..b91e1d7e --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.home1.5 @@ -0,0 +1,508 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.HOME1" "5" "" "systemd 255" "org.freedesktop.home1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.home1 \- The D\-Bus interface of systemd\-homed +.SH "INTRODUCTION" +.PP +\fBsystemd-homed.service\fR(8) +is a system service which may be used to create, remove, change or inspect home areas\&. This page describes the D\-Bus interface\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/home1 { + interface org\&.freedesktop\&.home1\&.Manager { + methods: + GetHomeByName(in s user_name, + out u uid, + out s home_state, + out u gid, + out s real_name, + out s home_directory, + out s shell, + out o bus_path); + GetHomeByUID(in u uid, + out s user_name, + out s home_state, + out u gid, + out s real_name, + out s home_directory, + out s shell, + out o bus_path); + GetUserRecordByName(in s user_name, + out s user_record, + out b incomplete, + out o bus_path); + GetUserRecordByUID(in u uid, + out s user_record, + out b incomplete, + out o bus_path); + ListHomes(out a(susussso) home_areas); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + ActivateHome(in s user_name, + in s secret); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + DeactivateHome(in s user_name); + RegisterHome(in s user_record); + UnregisterHome(in s user_name); + CreateHome(in s user_record); + RealizeHome(in s user_name, + in s secret); + RemoveHome(in s user_name); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + FixateHome(in s user_name, + in s secret); + AuthenticateHome(in s user_name, + in s secret); + UpdateHome(in s user_record); + ResizeHome(in s user_name, + in t size, + in s secret); + ChangePasswordHome(in s user_name, + in s new_secret, + in s old_secret); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + LockHome(in s user_name); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + UnlockHome(in s user_name, + in s secret); + AcquireHome(in s user_name, + in s secret, + in b please_suspend, + out h send_fd); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + RefHome(in s user_name, + in b please_suspend, + out h send_fd); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + ReleaseHome(in s user_name); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + LockAllHomes(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + DeactivateAllHomes(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Rebalance(); + properties: + readonly a(sso) AutoLogin = [\&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBGetHomeByName()\fR +returns basic user information (a minimal subset of the full user record), provided a user name\&. The information supplied more or less matches what +\fBgetpwnam\fR(3) +returns: the numeric UID and GID, the real name, home directory and shell\&. In addition it returns a state identifier describing the state the user\*(Aqs home directory is in, as well as a bus path referring to the bus object encapsulating the user record and home directory\&. This object implements the +org\&.freedesktop\&.home1\&.Home +interface documented below\&. +.PP +\fBGetHomeByUID()\fR +is similar to +\fBGetHomeByName()\fR +but acquires the information based on the numeric UID of the user\&. +.PP +\fBGetUserRecordByName()\fR +is also similar to +\fBGetHomeByName()\fR +but returns the full JSON user record data instead of the broken down records\&. An additional returned boolean indicates whether the record is complete or not\&. A record is considered complete when its +"privileged" +section is included, and incomplete if it was removed (see +\m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2 +for details about the various sections of a user record)\&. Generally, only privileged clients and clients running under the identity of the user itself get access to the +"privileged" +section and will thus see complete records\&. +.PP +\fBGetUserRecordByUID()\fR +is similar to +\fBGetUserRecordByName()\fR +but returns the user record matching the specified numeric UID\&. +.PP +\fBListHomes()\fR +returns an array of all locally managed users\&. The array contains the same fields +\fBGetHomeByName()\fR +returns: user name, numeric UID, state, numeric GID, real name, home directory, shell and bus path of the matching bus object\&. +.PP +\fBActivateHome()\fR +activates (i\&.e\&. mounts) the home directory of the specified user\&. The second argument shall contain a user record consisting only of a +"secret" +section (all other sections should be stripped, see +\m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2 +for details), and should contain only the secret credentials necessary for unlocking the home directory\&. Typically a client would invoke this function first with an entirely empty record (which is possibly sufficient if single\-factor authentication with a plugged\-in security token is configured), and would then retry with a record populated with more information, depending on the returned error code, in case more credentials are necessary\&. This function is synchronous and returns only after the home directory was fully activated (or the operation failed), which might take some time\&. Clients must be prepared for that, and typically should extend the D\-Bus method call timeout accordingly\&. This method is equivalent to the +\fBActivate()\fR +method on the +org\&.freedesktop\&.home1\&.Home +interface documented below, but may be called on the manager object and takes a user name as additional argument, instead\&. +.PP +\fBDeactivateHome()\fR +deactivates (i\&.e\&. unmounts) the home directory of the specified user\&. It is equivalent to the +\fBDeactivate()\fR +method on the +org\&.freedesktop\&.home1\&.Home +interface documented below\&. +.PP +\fBRegisterHome()\fR +registers a new home directory locally\&. It receives the JSON user record as only argument (which typically excludes the +"secret" +section)\&. Registering a home directory just makes the user record known to the system, it does not create a home directory or such (which is expected to exist already, or created later)\&. This operation is useful to register home directories locally that are not located where +systemd\-homed\&.service +would find them automatically\&. +.PP +\fBUnregisterHome()\fR +unregisters an existing home directory\&. It takes a user name as argument and undoes what +\fBRegisterHome()\fR +does\&. It does not attempt to remove the home directory itself, it just unregisters it with the local system\&. Note that if the home directory is placed where +systemd\-homed\&.service +looks for home directories anyway this call will only undo fixation (see below), but the record will remain known to +systemd\-homed\&.service +and be listed among known records\&. Since the user record is embedded into the home directory this operation generally does not discard data belonging to the user or their record\&. This method is equivalent to +\fBUnregister()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBCreateHome()\fR +registers and creates a new home directory\&. This takes a fully specified JSON user record as argument (including the +"secret" +section)\&. This registers the user record locally and creates a home directory matching it, depending on the settings specified in the record in combination with local configuration\&. +.PP +\fBRealizeHome()\fR +creates a home directory whose user record is already registered locally\&. This takes a user name plus a user record consisting only of the +"secret" +section\&. Invoking +\fBRegisterHome()\fR +followed by +\fBRealizeHome()\fR +is mostly equivalent to calling +\fBCreateHome()\fR, except that the latter combines the two in atomic fashion\&. This method is equivalent to +\fBRealize()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBRemoveHome()\fR +unregisters a user record locally, and removes the home directory belonging to it, if it is accessible\&. It takes a user name as argument\&. This method is equivalent to +\fBRemove()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBFixateHome()\fR +"fixates" +an automatically discovered home directory\&. +systemd\-homed\&.service +automatically discovers home directories dropped in our plugged in and adds them to the runtime list of user records it manages\&. A user record discovered that way may be +"fixated", in which case it is copied out of the home directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract additional (typically previously encrypted) user record data from the home directory\&. A home directory mus be fixated before it can be logged into\&. This method call takes a user name and a JSON user record consisting only of the +"secret" +section as argument\&. This method is equivalent to +\fBFixate()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBAuthenticateHome()\fR +checks passwords or other authentication credentials associated with the home directory\&. It takes a user name and a JSON user record consisting only of the +"secret" +section as argument\&. Note that many of the other method calls authenticate the user first, in order to execute some other operation\&. This method call only authenticates and executes no further operation\&. Like +\fBActivateHome()\fR +it is usually first invoked with an empty JSON user record, which is then populated for subsequent tries with additional authentication data supplied\&. This method is equivalent to +\fBAuthenticate()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBUpdateHome()\fR +updates a locally registered user record\&. Takes a fully specified JSON user record as argument (including the +"secret" +section)\&. A user with a matching name and realm must be registered locally already, and the last change timestamp of the newly supplied record must be newer than the previously existing user record\&. Note this operation updates the user record only, it does not propagate passwords/authentication tokens from the user record to the storage back\-end, or resizes the storage back\-end\&. Typically a home directory is first updated, and then the password of the underlying storage updated using +\fBChangePasswordHome()\fR +as well as the storage resized using +\fBResizeHome()\fR\&. This method is equivalent to +\fBUpdate()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBResizeHome()\fR +resizes the storage associated with a user record\&. Takes a user name, a disk size in bytes and a user record consisting only of the +"secret" +section as argument\&. If the size is specified as +\fBUINT64_MAX\fR +the storage is resized to the size already specified in the user record\&. Typically, if the user record is updated using +\fBUpdateHome()\fR +above this is used to propagate the size configured there\-in down to the underlying storage back\-end\&. This method is equivalent to +\fBResize()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBChangePasswordHome()\fR +changes the passwords/authentication tokens of a home directory\&. Takes a user name, and two JSON user record objects, each consisting only of the +"secret" +section, for the old and for the new passwords/authentication tokens\&. If the user record with the new passwords/authentication token data is specified as empty the existing user record\*(Aqs settings are propagated down to the home directory storage\&. This is typically used after a user record is updated using +\fBUpdateHome()\fR +in order to propagate the secrets/authentication tokens down to the storage\&. Background: depending on the backend the user\*(Aqs authentication credentials are stored at multiple places: the user record kept on the host, the user record kept in the home directory and the encrypted LUKS volume slot\&. If the home directory is used on a different machined temporarily, and the password is changed there, and then is moved back to the original host, the passwords of the three might get out of sync\&. By issuing +\fBChangePasswordHome()\fR +the three locations are updated to match the newest information\&. This method is equivalent to +\fBChangePassword()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBLockHome()\fR +temporarily suspends access to a home directory, flushing out any cryptographic keys from memory\&. This is only supported on some back\-ends, and usually done during system suspend, in order to effectively secure home directories while the system is sleeping\&. Takes a user name as single argument\&. If an application attempts to access a home directory while it is locked it will typically freeze until the home directory is unlocked again\&. This method is equivalent to +\fBLock()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBUnlockHome()\fR +undoes the effect of +\fBLockHome()\fR\&. Takes a user name and a user record consisting only of the +"secret" +section as arguments\&. This method is equivalent to +\fBUnlock()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBAcquireHome()\fR +activates or unlocks a home directory in a reference counted mode of operation\&. Takes a user name and user record consisting only of +"secret" +section as argument\&. If the home directory is not active yet, it is activated\&. If it is currently locked it is unlocked\&. After completion a reference to the activation/unlocking of the home directory is returned via a file descriptor\&. When the last client which acquired such a file descriptor closes it the home directory is automatically deactivated again\&. This method is typically invoked when a user logs in, and the file descriptor is held until the user logs out again, thus ensuring the user\*(Aqs home directory can be unmounted automatically again in a robust fashion, when the user logs out\&. The third argument is a boolean which indicates whether the client invoking the call is able to automatically re\-authenticate when the system comes back from suspending\&. It should be set by all clients that implement a secure lock screen running outside of the user\*(Aqs context, that is brought up when the system comes back from suspend and can be used to re\-acquire the credentials to unlock the user\*(Aqs home directory\&. If a home directory has at least one client with an open reference to the home directory that does not support this it is not suspended automatically at system suspend, otherwise it is\&. This method is equivalent to +\fBAcquire()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBRefHome()\fR +is similar to +\fBAcquireHome()\fR +but takes no user record with +"secret" +section, i\&.e\&. will take an additional reference to an already activated/unlocked home directory without attempting to activate/unlock it itself\&. It will fail if the home directory is not already activated\&. This method is equivalent to +\fBRef()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBReleaseHome()\fR +releases a home directory again, if all file descriptors referencing it are already closed, that where acquired through +\fBAcquireHome()\fR +or +\fBRefHome()\fR\&. Note that this call does not actually cause the deactivation of the home directory (which happens automatically when the last referencing file descriptor is closed), but is simply a synchronization mechanism that allows delaying of the user session\*(Aqs termination until any triggered deactivation is completed\&. This method is equivalent to +\fBRelease()\fR +on the +org\&.freedesktop\&.home1\&.Home +interface\&. +.PP +\fBLockAllHomes()\fR +locks all active home directories that only have references that opted into automatic suspending during system suspend\&. This is usually invoked automatically shortly before system suspend\&. +.PP +\fBDeactivateAllHomes()\fR +deactivates all home areas that are currently active\&. This is usually invoked automatically shortly before system shutdown\&. +.PP +\fBRebalance()\fR +synchronously rebalances free disk space between home areas\&. This only executes an operation if at least one home area using the LUKS2 backend is active and has rebalancing enabled, and is otherwise a NOP\&. +.SS "Properties" +.PP +\fIAutoLogin\fR +exposes an array of structures consisting of user name, seat name and object path of an home directory object\&. All locally managed users that have the +"autoLogin" +field set are listed here, with the seat name they are associated with\&. A display manager may watch this property and pre\-fill the login screen with the users exposed this way\&. +.SH "THE HOME OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/home1/home { + interface org\&.freedesktop\&.home1\&.Home { + methods: + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Activate(in s secret); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Deactivate(); + Unregister(); + Realize(in s secret); + Remove(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Fixate(in s secret); + Authenticate(in s secret); + Update(in s user_record); + Resize(in t size, + in s secret); + ChangePassword(in s new_secret, + in s old_secret); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Lock(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Unlock(in s secret); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Acquire(in s secret, + in b please_suspend, + out h send_fd); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Ref(in b please_suspend, + out h send_fd); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Release(); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UserName = \*(Aq\&.\&.\&.\*(Aq; + readonly u UID = \&.\&.\&.; + readonly (suusss) UnixRecord = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly (sb) UserRecord = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.ObjectManager { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBActivate()\fR, +\fBDeactivate()\fR, +\fBUnregister()\fR, +\fBRealize()\fR, +\fBRemove()\fR, +\fBFixate()\fR, +\fBAuthenticate()\fR, +\fBUpdate()\fR, +\fBResize()\fR, +\fBChangePassword()\fR, +\fBLock()\fR, +\fBUnlock()\fR, +\fBAcquire()\fR, +\fBRef()\fR, +\fBRelease()\fR +operate like their matching counterparts on the +org\&.freedesktop\&.home1\&.Manager +interface (see above)\&. The main difference is that they are methods of the home directory objects, and hence carry no additional user name parameter\&. Which of the two flavors of methods to call depends on the handles to the user known on the client side: if only the user name is known, it\*(Aqs preferable to use the methods on the manager object since they operate with user names only\&. If however the home object path was already acquired some way it is preferable to operate on the +org\&.freedesktop\&.home1\&.Home +objects instead\&. +.SS "Properties" +.PP +\fIUserName\fR +contains the user name of the user account/home directory\&. +.PP +\fIUID\fR +contains the numeric UNIX UID of the user account\&. +.PP +\fIUnixRecord\fR +contains a structure encapsulating the six fields a +struct passwd +typically contains (the password field is suppressed)\&. +.PP +\fIState\fR +exposes the current state home the home directory\&. +.PP +\fIUserRecord\fR +contains the full JSON user record string of the user account\&. +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-homed.service\fR(8), +\fBhomectl\fR(1) +.SH "NOTES" +.IP " 1." 4 +JSON User Records +.RS 4 +\%https://systemd.io/USER_RECORD +.RE +.IP " 2." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.hostname1.5 b/upstream/fedora-40/man5/org.freedesktop.hostname1.5 new file mode 100644 index 00000000..b0d8da1f --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.hostname1.5 @@ -0,0 +1,618 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.HOSTNAME1" "5" "" "systemd 255" "org.freedesktop.hostname1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.hostname1 \- The D\-Bus interface of systemd\-hostnamed +.SH "INTRODUCTION" +.PP +\fBsystemd-hostnamed.service\fR(8) +is a system service that can be used to control the hostname and related machine metadata from user programs\&. This page describes the hostname semantics and the D\-Bus interface\&. +.SH "THE D\-BUS API" +.PP +The service exposes the following interfaces on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/hostname1 { + interface org\&.freedesktop\&.hostname1 { + methods: + SetHostname(in s hostname, + in b interactive); + SetStaticHostname(in s hostname, + in b interactive); + SetPrettyHostname(in s hostname, + in b interactive); + SetIconName(in s icon, + in b interactive); + SetChassis(in s chassis, + in b interactive); + SetDeployment(in s deployment, + in b interactive); + SetLocation(in s location, + in b interactive); + GetProductUUID(in b interactive, + out ay uuid); + GetHardwareSerial(out s serial); + Describe(out s json); + properties: + readonly s Hostname = \*(Aq\&.\&.\&.\*(Aq; + readonly s StaticHostname = \*(Aq\&.\&.\&.\*(Aq; + readonly s PrettyHostname = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s DefaultHostname = \*(Aq\&.\&.\&.\*(Aq; + readonly s HostnameSource = \*(Aq\&.\&.\&.\*(Aq; + readonly s IconName = \*(Aq\&.\&.\&.\*(Aq; + readonly s Chassis = \*(Aq\&.\&.\&.\*(Aq; + readonly s Deployment = \*(Aq\&.\&.\&.\*(Aq; + readonly s Location = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KernelName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KernelRelease = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KernelVersion = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s OperatingSystemPrettyName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s OperatingSystemCPEName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t OperatingSystemSupportEnd = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HomeURL = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HardwareVendor = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HardwareModel = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s FirmwareVersion = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s FirmwareVendor = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t FirmwareDate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay MachineID = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay BootID = [\&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.PP +Whenever the hostname or other metadata is changed via the daemon, +\fBPropertyChanged\fR +signals are sent out to subscribed clients\&. Changing a hostname using this interface is authenticated via +\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "SEMANTICS" +.PP +The +\fIStaticHostname\fR +property exposes the "static" hostname configured in +/etc/hostname\&. It is not always in sync with the current hostname as returned by the +\fBgethostname\fR(3) +system call\&. If no static hostname is configured this property will be the empty string\&. +.PP +When +\fBsystemd\fR(1) +or +\fBsystemd-hostnamed.service\fR(8) +set the hostname, this static hostname +\fIhas the highest priority\fR\&. +.PP +The +\fIHostname\fR +property exposes the actual hostname configured in the kernel via +\fBsethostname\fR(2)\&. It can be different from the static hostname\&. This property is never empty\&. +.PP +The +\fIPrettyHostname\fR +property exposes the +\fIpretty hostname\fR +which is a free\-form UTF\-8 hostname for presentation to the user\&. User interfaces should ensure that the pretty hostname and the static hostname stay in sync\&. E\&.g\&. when the former is +"Lennart\(cqs Computer" +the latter should be +"lennarts\-computer"\&. If no pretty hostname is set this setting will be the empty string\&. Applications should then find a suitable fallback, such as the dynamic hostname\&. +.PP +The +\fIDefaultHostname\fR +property exposes the default hostname (configured through +\fBos-release\fR(5), or a fallback set at compilation time)\&. +.PP +The +\fIHostnameSource\fR +property exposes the origin of the currently configured hostname\&. One of +"static" +(set from +/etc/hostname), +"transient" +(a non\-permanent hostname from an external source), +"default" +(the value from +os\-release +or the compiled\-in fallback)\&. +.PP +The +\fIIconName\fR +property exposes the +\fIicon name\fR +following the XDG icon naming spec\&. If not set, information such as the chassis type (see below) is used to find a suitable fallback icon name (i\&.e\&. +"computer\-laptop" +vs\&. +"computer\-desktop" +is picked based on the chassis information)\&. If no such data is available, the empty string is returned\&. In that case an application should fall back to a replacement icon, for example +"computer"\&. If this property is set to the empty string, the automatic fallback name selection is enabled again\&. +.PP +The +\fIChassis\fR +property exposes a +\fIchassis type\fR, one of the currently defined chassis types: +"desktop", +"laptop", +"server", +"tablet", +"handset", as well as the special chassis types +"vm" +and +"container" +for virtualized systems\&. Note that in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information\&. Writing to this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if it could not be auto\-detected\&. Set this property to the empty string to reenable the automatic detection of the chassis type from firmware information\&. +.PP +Note that +systemd\-hostnamed +starts only on request and terminates after a short idle period\&. This effectively means that +\fBPropertyChanged\fR +messages are not sent out for changes made directly on the files (as in: administrator edits the files with vi)\&. This is the intended behavior: manual configuration changes should require manual reloading\&. +.PP +The transient (dynamic) hostname exposed by the +\fIHostname\fR +property maps directly to the kernel hostname\&. This hostname should be assumed to be highly dynamic, and hence should be watched directly, without depending on +\fBPropertyChanged\fR +messages from +systemd\-hostnamed\&. To accomplish this, open +/proc/sys/kernel/hostname +and +\fBpoll\fR(3) +for +\fBSIGHUP\fR +which is triggered by the kernel every time the hostname changes\&. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname\&. +.PP +Applications may read the hostname data directly if hostname change notifications are not necessary\&. Use +\fBgethostname\fR(2), +/etc/hostname +(possibly with per\-distribution fallbacks), and +\fBmachine-info\fR(3) +for that\&. For more information on these files and syscalls see the respective man pages\&. +.PP +\fIKernelName\fR, +\fIKernelRelease\fR, and +\fIKernelVersion\fR +expose the kernel name (e\&.g\&. +"Linux"), release (e\&.g\&. +"5\&.0\&.0\-11"), and version (i\&.e\&. the build number, e\&.g\&. +"#11") as reported by +\fBuname\fR(2)\&. +\fIOperatingSystemPrettyName\fR, +\fIOperatingSystemCPEName\fR, and +\fIHomeURL\fR +expose the +\fIPRETTY_NAME=\fR, +\fICPE_NAME=\fR +and +\fIHOME_URL=\fR +fields from +\fBos-release\fR(5)\&. The purpose of those properties is to allow remote clients to access this information over D\-Bus\&. Local clients can access the information directly\&. +.SS "Methods" +.PP +\fBSetHostname()\fR +sets the transient (dynamic) hostname, which is used if no static hostname is set\&. This value must be an internet\-style hostname, 7\-bit lowercase ASCII, no special chars/spaces\&. An empty string will unset the transient hostname\&. +.PP +\fBSetStaticHostname()\fR +sets the static hostname which is exposed by the +\fIStaticHostname\fR +property\&. When called with an empty argument, the static configuration in +/etc/hostname +is removed\&. Since the static hostname has the highest priority, calling this function usually affects also the +\fIHostname\fR +property and the effective hostname configured in the kernel\&. +.PP +\fBSetPrettyHostname()\fR +sets the pretty hostname which is exposed by the +\fIPrettyHostname\fR +property\&. +.PP +\fBSetIconName()\fR, +\fBSetChassis()\fR, +\fBSetDeployment()\fR, and +\fBSetLocation()\fR +set the properties +\fIIconName\fR +(the name of the icon representing for the machine), +\fIChassis\fR +(the machine form factor), +\fIDeployment\fR +(the system deployment environment), and +\fILocation\fR +(physical system location), respectively\&. +.PP +\fIPrettyHostname\fR, +\fIIconName\fR, +\fIChassis\fR, +\fIDeployment\fR, and +\fILocation\fR +are stored in +/etc/machine\-info\&. See +\fBmachine-info\fR(5) +for the semantics of those settings\&. +.PP +\fBGetProductUUID()\fR +returns the "product UUID" as exposed by the kernel based on DMI information in +/sys/class/dmi/id/product_uuid\&. Reading the file directly requires root privileges, and this method allows access to unprivileged clients through the polkit framework\&. +.PP +\fBDescribe()\fR +returns a JSON representation of all properties in one\&. +.SS "Security" +.PP +The +\fIinteractive\fR +boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required\&. +.PP +The polkit action for +\fBSetHostname()\fR +is +org\&.freedesktop\&.hostname1\&.set\-hostname\&. For +\fBSetStaticHostname()\fR +and +\fBSetPrettyHostname()\fR +it is +org\&.freedesktop\&.hostname1\&.set\-static\-hostname\&. For +\fBSetIconName()\fR, +\fBSetChassis()\fR, +\fBSetDeployment()\fR +and +\fBSetLocation()\fR +it is +org\&.freedesktop\&.hostname1\&.set\-machine\-info\&. +.SH "RECOMMENDATIONS" +.PP +Here are three examples that show how the pretty hostname and the icon name should be used: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +When registering DNS\-SD services: use the pretty hostname in the service name, and pass the icon name in the TXT data, if there is an icon name\&. Browsing clients can then show the server icon on each service\&. This is especially useful for WebDAV applications or UPnP media sharing\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Set the bluetooth name to the pretty hostname\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set\&. +.RE +.PP +To properly handle name lookups with changing local hostnames without having to edit +/etc/hosts, we recommend using +systemd\-hostnamed +in combination with +\fBnss-myhostname\fR(3)\&. +.PP +Here are some recommendations to follow when generating a static (internet) hostname from a pretty name: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Generate a single DNS label only, not an FQDN\&. That means no dots allowed\&. Strip them, or replace them with +"\-"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +It\*(Aqs probably safer to not use any non\-ASCII chars, even if DNS allows this in some way these days\&. In fact, restrict your charset to +"a\-zA\-Z0\-9" +and +"\-"\&. Strip other chars, or try to replace them in some smart way with chars from this set, for example +"ä" +→ +"ae", and use +"\-" +as the replacement for all punctuation characters and whitespace\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Try to avoid creating repeated +"\-", as well as +"\-" +as the first or last char\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Limit the hostname to 63 chars, which is the length of a DNS label\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If after stripping special chars the empty string is the result, you can pass this as\-is to +systemd\-hostnamed +in which case it will automatically use a suitable fallback\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Uppercase characters should be replaced with their lowercase equivalents\&. +.RE +.PP +Note that while +systemd\-hostnamed +applies some checks to the hostname you pass they are much looser than the recommendations above\&. For example, +systemd\-hostnamed +will also accept +"_" +in the hostname, but we recommend not using this to avoid clashes with DNS\-SD service types\&. Also +systemd\-hostnamed +allows longer hostnames, but because of the DNS label limitations, we recommend not making use of this\&. +.PP +Here are a couple of example conversions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"Lennart\*(Aqs PC" +→ +"lennarts\-pc" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"Müllers Computer" +→ +"muellers\-computer" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"Voran!" +→ +"voran" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"Es war einmal ein Männlein" +→ +"es\-war\-einmal\-ein\-maennlein" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"Jawoll\&. Ist doch wahr!" +→ +"jawoll\-ist\-doch\-wahr" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"レナート" +→ +"localhost" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"\&.\&.\&.zack!!! zack!\&.\&.\&." +→ +"zack\-zack" +.RE +.PP +Of course, an already valid internet hostname label you enter and pass through this conversion should stay unmodified, so that users have direct control of it, if they want \(em by simply ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet name\&. +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.hostname1 on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.hostname1 \e + \-\-object\-path /org/freedesktop/hostname1 + +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +David Zeuthen\*(Aqs original Fedora +\m[blue]\fBFeature page about xdg\-hostname\fR\m[]\&\s-2\u[3]\d\s+2 +.SH "HISTORY" +.SS "The D\-Bus API" +.PP +\fIFirmwareVersion\fR +and +\fBGetHardwareSerial()\fR +were added in version 251\&. +.PP +\fIOperatingSystemSupportEnd\fR, +\fIFirmwareVendor\fR, and +\fIFirmwareDate\fR +were added in version 253\&. +.PP +\fIMachineID\fR, and +\fIBootID\fR +were added in version 256\&. +.SH "NOTES" +.IP " 1." 4 +polkit +.RS 4 +\%https://www.freedesktop.org/software/polkit/docs/latest/ +.RE +.IP " 2." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE +.IP " 3." 4 +Feature page about xdg-hostname +.RS 4 +\%https://fedoraproject.org/wiki/Features/BetterHostname +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.import1.5 b/upstream/fedora-40/man5/org.freedesktop.import1.5 new file mode 100644 index 00000000..cbea124e --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.import1.5 @@ -0,0 +1,347 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.IMPORT1" "5" "" "systemd 255" "org.freedesktop.import1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.import1 \- The D\-Bus interface of systemd\-importd +.SH "INTRODUCTION" +.PP +\fBsystemd-importd.service\fR(8) +is a system service which may be used to import, export and download additional system images\&. These images can be used by tools such as +\fBsystemd-nspawn\fR(1) +to run local containers\&. The service is used as the backend for +\fBmachinectl pull\-raw\fR, +\fBmachinectl pull\-tar\fR +and related commands\&. This page describes the D\-Bus interface\&. +.PP +Note that +\fBsystemd-importd.service\fR(8) +is mostly a small companion service for +\fBsystemd-machined.service\fR(8)\&. Many operations to manipulate local container and VM images are hence available via the +\fBsystemd\-machined\fR +D\-Bus API, c\&.f\&. +\fBorg.freedesktop.machine1\fR(5)\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/import1 { + interface org\&.freedesktop\&.import1\&.Manager { + methods: + ImportTar(in h fd, + in s local_name, + in b force, + in b read_only, + out u transfer_id, + out o transfer_path); + ImportRaw(in h fd, + in s local_name, + in b force, + in b read_only, + out u transfer_id, + out o transfer_path); + ImportFileSystem(in h fd, + in s local_name, + in b force, + in b read_only, + out u transfer_id, + out o transfer_path); + ExportTar(in s local_name, + in h fd, + in s format, + out u transfer_id, + out o transfer_path); + ExportRaw(in s local_name, + in h fd, + in s format, + out u transfer_id, + out o transfer_path); + PullTar(in s url, + in s local_name, + in s verify_mode, + in b force, + out u transfer_id, + out o transfer_path); + PullRaw(in s url, + in s local_name, + in s verify_mode, + in b force, + out u transfer_id, + out o transfer_path); + ListTransfers(out a(usssdo) transfers); + CancelTransfer(in u transfer_id); + signals: + TransferNew(u transfer_id, + o transfer_path); + TransferRemoved(u transfer_id, + o transfer_path, + s result); + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + +.SS "Methods" +.PP +\fBImportTar()\fR +and +\fBImportRaw()\fR +import a system image and place it into +/var/lib/machines/\&. The first argument should be a file descriptor (opened for reading) referring to the tar or raw file to import\&. It should reference a file on disk, a pipe or a socket\&. When +\fBImportTar()\fR +is used the file descriptor should refer to a tar file, optionally compressed with +\fBgzip\fR(1), +\fBbzip2\fR(1), or +\fBxz\fR(1)\&. +\fBsystemd\-importd\fR +will detect the used compression scheme (if any) automatically\&. When +\fBImportRaw()\fR +is used the file descriptor should refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz\&. In either case, if the file is specified as a file descriptor on disk, progress information is generated for the import operation (as in that case we know the total size on disk)\&. If a socket or pipe is specified, progress information is not available\&. The file descriptor argument is followed by a local name for the image\&. This should be a name suitable as a hostname and will be used to name the imported image below +/var/lib/machines/\&. A tar import is placed as a directory tree or a +\fBbtrfs\fR(8) +subvolume below +/var/lib/machines/ +under the specified name with no suffix appended\&. A raw import is placed as a file in +/var/lib/machines/ +with the +\&.raw +suffix appended\&. If the +\fBforce\fR +argument is true, any pre\-existing image with the same name is removed before starting the operation\&. Otherwise, the operation fails if an image with the same name already exists\&. Finally, the +\fBread_only\fR +argument controls whether to create a writable or read\-only image\&. Both methods return immediately after starting the import, with the import transfer ongoing\&. They return a pair of transfer identifier and object path, which may be used to retrieve progress information about the transfer or to cancel it\&. The transfer identifier is a simple numeric identifier, the object path references an +org\&.freedesktop\&.import1\&.Transfer +object, see below\&. Listen for a +\fBTransferRemoved\fR +signal for the transfer ID in order to detect when a transfer is complete\&. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation\&. +.PP +\fBExportTar()\fR +and +\fBExportRaw()\fR +implement the reverse operation, and may be used to export a system image in order to place it in a tar or raw image\&. They take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) where the tar or raw file will be written\&. It may either reference a file on disk or a pipe/socket\&. The third argument specifies in which compression format to write the image\&. It takes one of +"uncompressed", +"xz", +"bzip2" +or +"gzip", depending on which compression scheme is required\&. The image written to the specified file descriptor will be a tar file in case of +\fBExportTar()\fR +or a raw disk image in case of +\fBExportRaw()\fR\&. Note that currently raw disk images may not be exported as tar files, and vice versa\&. This restriction might be lifted eventually\&. The method returns a transfer identifier and object path for cancelling or tracking the export operation, similarly to +\fBImportTar()\fR +or +\fBImportRaw()\fR +as described above\&. +.PP +\fBPullTar()\fR +and +\fBPullRaw()\fR +may be used to download, verify and import a system image from a URL\&. They take a URL argument which should point to a tar or raw file on the +"http://" +or +"https://" +protocols, possibly compressed with xz, bzip2 or gzip\&. The second argument is a local name for the image\&. It should be suitable as a hostname, similarly to the matching argument of the +\fBImportTar()\fR +and +\fBImportRaw()\fR +methods above\&. The third argument indicates the verification mode for the image\&. It may be one of +"no", +"checksum", +"signature"\&. +"no" +turns off any kind of verification of the image; +"checksum" +looks for a +SHA256SUM +file next to the downloaded image and verifies any SHA256 hash value in that file against the image; +"signature" +does the same but also tries to authenticate the +SHA256SUM +file via +\fBgpg\fR(8) +first\&. The last argument indicates whether to replace a possibly pre\-existing image with the same local name (if +"true"), or whether to fail (if +"false")\&. Like the import and export calls above, these calls return a pair of transfer identifier and object path for the ongoing download\&. +.PP +\fBListTransfers()\fR +returns a list of ongoing import, export or download operations as created with the six calls described above\&. It returns an array of structures which consist of the numeric transfer identifier, a string indicating the operation (one of +"import\-tar", +"import\-raw", +"export\-tar", +"export\-raw", +"pull\-tar" +or +"pull\-raw"), a string describing the remote file (in case of download operations this is the source URL, in case of import/export operations this is a short string describing the file descriptor passed in), a string with the local machine image name, a progress value between 0\&.0 (for 0%) and 1\&.0 (for 100%), as well as the transfer object path\&. +.PP +\fBCancelTransfer()\fR +may be used to cancel an ongoing import, export or download operation\&. Simply specify the transfer identifier to cancel the ongoing operation\&. +.SS "Signals" +.PP +The +\fBTransferNew\fR +signal is generated each time a new transfer is started with the import, export or download calls described above\&. It carries the transfer ID and object path that have just been created\&. +.PP +The +\fBTransferRemoved\fR +signal is sent each time a transfer finishes, is canceled or fails\&. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of +"done" +(on success), +"canceled" +or +"failed"\&. +.SH "THE TRANSFER OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/import1/transfer/_1 { + interface org\&.freedesktop\&.import1\&.Transfer { + methods: + Cancel(); + signals: + LogMessage(u priority, + s line); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u Id = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Local = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Remote = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Type = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Verify = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly d Progress = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + +.SS "Methods" +.PP +The +\fBCancel()\fR +method may be used to cancel the transfer\&. It takes no parameters\&. This method is pretty much equivalent to the +\fBCancelTransfer()\fR +method on the +Manager +interface (see above), but is exposed on the +Transfer +object itself instead of taking a transfer ID\&. +.SS "Properties" +.PP +The +\fIId\fR +property exposes the numeric transfer ID of the transfer object\&. +.PP +The +\fILocal\fR, +\fIRemote\fR +and +\fIType\fR +properties expose the local container name of this transfer, the remote source (in case of download: the URL, in case of import/export: a string describing the file descriptor passed in), and the type of operation (see the Manager\*(Aqs +\fBListTransfer()\fR +method above for an explanation of the possible values)\&. +.PP +The +\fIVerify\fR +property exposes the selected verification setting and is only defined for download operations (see above)\&. +.PP +The +\fIProgress\fR +property exposes the current progress of the transfer as a value between 0\&.0 and 1\&.0\&. To show a progress bar on screen we recommend to query this value in regular intervals, for example every 500\ \&ms or so\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.import1\&.Manager on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.import1 \e + \-\-object\-path /org/freedesktop/import1 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.import1\&.Transfer on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.import1 \e + \-\-object\-path /org/freedesktop/import1/transfer/_1 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "NOTES" +.IP " 1." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.locale1.5 b/upstream/fedora-40/man5/org.freedesktop.locale1.5 new file mode 100644 index 00000000..4644366b --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.locale1.5 @@ -0,0 +1,202 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.LOCALE1" "5" "" "systemd 255" "org.freedesktop.locale1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.locale1 \- The D\-Bus interface of systemd\-localed +.SH "INTRODUCTION" +.PP +\fBsystemd-localed.service\fR(8) +is a system service that can be used to control the system locale and keyboard mapping from user programs\&. This page describes the D\-Bus interface\&. +.SH "THE D\-BUS API" +.PP +The service exposes the following interfaces on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/locale1 { + interface org\&.freedesktop\&.locale1 { + methods: + SetLocale(in as locale, + in b interactive); + SetVConsoleKeyboard(in s keymap, + in s keymap_toggle, + in b convert, + in b interactive); + SetX11Keyboard(in s layout, + in s model, + in s variant, + in s options, + in b convert, + in b interactive); + properties: + readonly as Locale = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + readonly s X11Layout = \*(Aq\&.\&.\&.\*(Aq; + readonly s X11Model = \*(Aq\&.\&.\&.\*(Aq; + readonly s X11Variant = \*(Aq\&.\&.\&.\*(Aq; + readonly s X11Options = \*(Aq\&.\&.\&.\*(Aq; + readonly s VConsoleKeymap = \*(Aq\&.\&.\&.\*(Aq; + readonly s VConsoleKeymapToggle = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + +.SS "Methods" +.PP +If you set a new system locale all old system locale settings will be dropped and the new settings will be saved to disk\&. The locale will also be passed to the system manager, and subsequently started daemons will inherit the new system locale\&. Note that already running daemons will not learn about the new value\&. +.PP +The +\fBSetVConsoleKeyboard()\fR +method may be used to set the key mapping for the virtual console\&. Similarly, +\fBSetX11Keyboard()\fR +may be used to set the default key mapping of any X11 servers\&. +.PP +Note that +\fBSetVConsoleKeyboard()\fR +instantly applies the new key mapping to the console, while +\fBSetX11Keyboard()\fR +simply sets a default that may be used by later sessions\&. +.PP +The boolean argument +\fIconvert\fR +may be set to optionally convert the console keyboard configuration to X11 keyboard mappings and vice versa\&. If true and +\fBSetVConsoleKeyboard()\fR +is used, the nearest X11 keyboard setting for the chosen console setting is set\&. If true and +\fBSetX11Keyboard()\fR +is used, the nearest console keyboard setting for the chosen X11 setting is set\&. Hence, it is usually sufficient to call only one of the two functions\&. +.PP +For graphical UIs that need to set the system keyboard mapping simply invoke +\fBSetX11Keyboard()\fR, set +\fIconvert=true\fR +and ignore +\fBSetVConsoleKeyboard()\fR\&. +.PP +Use the empty string for the keymap parameters you wish not to set\&. +.PP +The +\fIinteractive\fR +boolean parameters can be used to control whether +\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2 +should interactively ask the user for authentication credentials if required\&. +.SS "Signals" +.PP +Whenever the system locale or keymap is changed via the daemon, +\fBPropertyChanged\fR +signals are sent out to which clients can subscribe\&. +.SS "Properties" +.PP +The system locale is shown in the +\fILocale\fR +property\&. It is an array containing environment\-variable\-assignment\-like strings\&. The following strings are known: +\fILANG=\fR, +\fILC_CTYPE=\fR, +\fILC_NUMERIC=\fR, +\fILC_TIME=\fR, +\fILC_COLLATE=\fR, +\fILC_MONETARY=\fR, +\fILC_MESSAGES=\fR, +\fILC_PAPER=\fR, +\fILC_NAME=\fR, +\fILC_ADDRESS=\fR, +\fILC_TELEPHONE=\fR, +\fILC_MEASUREMENT=\fR, +\fILC_IDENTIFICATION=\fR\&. +.PP +The +\fIX11Layout\fR, +\fIX11Model\fR, +\fIX11Variant\fR, and +\fIX11Options\fR +properties show values configurable with +\fBSetX11Keyboard()\fR +described above (or +\fBSetVConsoleKeyboard()\fR +with +\fIconvert=true\fR)\&. The +\fIVConsoleKeymap\fR +and +\fIVConsoleKeymapToggle\fR +properties show values configurable with +\fBSetVConsoleKeyboard()\fR +(or +\fBSetX11Keyboard()\fR +with +\fIconvert=true\fR)\&. +.SS "Security" +.PP +Changing the system locale or keymap using this interface is authenticated via polkit\&. The polkit action for +\fBSetLocale()\fR +is +\fBorg\&.freedesktop\&.locale1\&.set\-locale\fR\&. The polkit action for +\fBSetX11Keyboard()\fR +and +\fBSetVConsoleKeyboard()\fR +is +\fBorg\&.freedesktop\&.locale1\&.set\-keyboard\fR\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.locale1 on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.locale1 \e + \-\-object\-path /org/freedesktop/locale1 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "NOTES" +.IP " 1." 4 +polkit +.RS 4 +\%https://www.freedesktop.org/software/polkit/docs/latest/ +.RE +.IP " 2." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.login1.5 b/upstream/fedora-40/man5/org.freedesktop.login1.5 new file mode 100644 index 00000000..135cb69b --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.login1.5 @@ -0,0 +1,1649 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.LOGIN1" "5" "" "systemd 255" "org.freedesktop.login1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.login1 \- The D\-Bus interface of systemd\-logind +.SH "INTRODUCTION" +.PP +\fBsystemd-logind.service\fR(8) +is a system service that keeps track of user logins and seats\&. +.PP +The daemon provides both a C library interface as well as a D\-Bus interface\&. The library interface may be used to introspect and watch the state of user logins and seats\&. The bus interface provides the same functionality but in addition may also be used to make changes to the system state\&. For more information please consult +\fBsd-login\fR(3)\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/login1 { + interface org\&.freedesktop\&.login1\&.Manager { + methods: + GetSession(in s session_id, + out o object_path); + GetSessionByPID(in u pid, + out o object_path); + GetUser(in u uid, + out o object_path); + GetUserByPID(in u pid, + out o object_path); + GetSeat(in s seat_id, + out o object_path); + ListSessions(out a(susso) sessions); + ListUsers(out a(uso) users); + ListSeats(out a(so) seats); + ListInhibitors(out a(ssssuu) inhibitors); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + CreateSession(in u uid, + in u pid, + in s service, + in s type, + in s class, + in s desktop, + in s seat_id, + in u vtnr, + in s tty, + in s display, + in b remote, + in s remote_user, + in s remote_host, + in a(sv) properties, + out s session_id, + out o object_path, + out s runtime_path, + out h fifo_fd, + out u uid, + out s seat_id, + out u vtnr, + out b existing); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + CreateSessionWithPIDFD(in u uid, + in h pidfd, + in s service, + in s type, + in s class, + in s desktop, + in s seat_id, + in u vtnr, + in s tty, + in s display, + in b remote, + in s remote_user, + in s remote_host, + in t flags, + in a(sv) properties, + out s session_id, + out o object_path, + out s runtime_path, + out h fifo_fd, + out u uid, + out s seat_id, + out u vtnr, + out b existing); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + ReleaseSession(in s session_id); + ActivateSession(in s session_id); + ActivateSessionOnSeat(in s session_id, + in s seat_id); + LockSession(in s session_id); + UnlockSession(in s session_id); + LockSessions(); + UnlockSessions(); + KillSession(in s session_id, + in s who, + in i signal_number); + KillUser(in u uid, + in i signal_number); + TerminateSession(in s session_id); + TerminateUser(in u uid); + TerminateSeat(in s seat_id); + SetUserLinger(in u uid, + in b enable, + in b interactive); + AttachDevice(in s seat_id, + in s sysfs_path, + in b interactive); + FlushDevices(in b interactive); + PowerOff(in b interactive); + PowerOffWithFlags(in t flags); + Reboot(in b interactive); + RebootWithFlags(in t flags); + Halt(in b interactive); + HaltWithFlags(in t flags); + Suspend(in b interactive); + SuspendWithFlags(in t flags); + Hibernate(in b interactive); + HibernateWithFlags(in t flags); + HybridSleep(in b interactive); + HybridSleepWithFlags(in t flags); + SuspendThenHibernate(in b interactive); + SuspendThenHibernateWithFlags(in t flags); + CanPowerOff(out s result); + CanReboot(out s result); + CanHalt(out s result); + CanSuspend(out s result); + CanHibernate(out s result); + CanHybridSleep(out s result); + CanSuspendThenHibernate(out s result); + ScheduleShutdown(in s type, + in t usec); + CancelScheduledShutdown(out b cancelled); + Inhibit(in s what, + in s who, + in s why, + in s mode, + out h pipe_fd); + CanRebootParameter(out s result); + SetRebootParameter(in s parameter); + CanRebootToFirmwareSetup(out s result); + SetRebootToFirmwareSetup(in b enable); + CanRebootToBootLoaderMenu(out s result); + SetRebootToBootLoaderMenu(in t timeout); + CanRebootToBootLoaderEntry(out s result); + SetRebootToBootLoaderEntry(in s boot_loader_entry); + SetWallMessage(in s wall_message, + in b enable); + signals: + SessionNew(s session_id, + o object_path); + SessionRemoved(s session_id, + o object_path); + UserNew(u uid, + o object_path); + UserRemoved(u uid, + o object_path); + SeatNew(s seat_id, + o object_path); + SeatRemoved(s seat_id, + o object_path); + PrepareForShutdown(b start); + PrepareForShutdownWithMetadata(b start, + a{sv} metadata); + PrepareForSleep(b start); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite b EnableWallMessages = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite s WallMessage = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u NAutoVTs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as KillOnlyUsers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as KillExcludeUsers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b KillUserProcesses = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s RebootParameter = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b RebootToFirmwareSetup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t RebootToBootLoaderMenu = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s RebootToBootLoaderEntry = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as BootLoaderEntries = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + readonly b IdleHint = \&.\&.\&.; + readonly t IdleSinceHint = \&.\&.\&.; + readonly t IdleSinceHintMonotonic = \&.\&.\&.; + readonly s BlockInhibited = \*(Aq\&.\&.\&.\*(Aq; + readonly s DelayInhibited = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InhibitDelayMaxUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UserStopDelayUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandlePowerKey = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandlePowerKeyLongPress = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleRebootKey = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleRebootKeyLongPress = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleSuspendKey = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleSuspendKeyLongPress = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleHibernateKey = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleHibernateKeyLongPress = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleLidSwitch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleLidSwitchExternalPower = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s HandleLidSwitchDocked = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t HoldoffTimeoutUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s IdleAction = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t IdleActionUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b PreparingForShutdown = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b PreparingForSleep = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (st) ScheduledShutdown = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Docked = \&.\&.\&.; + readonly b LidClosed = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b OnExternalPower = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemoveIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RuntimeDirectorySize = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RuntimeDirectoryInodesMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InhibitorsMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t NCurrentInhibitors = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t SessionsMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t NCurrentSessions = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t StopIdleSessionUSec = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBGetSession()\fR +may be used to get the session object path for the session with the specified ID\&. Similarly, +\fBGetUser()\fR +and +\fBGetSeat()\fR +get the user and seat objects, respectively\&. +\fBGetSessionByPID()\fR +and +\fBGetUserByPID()\fR +get the session/user object the specified PID belongs to if there is any\&. +.PP +\fBListSessions()\fR +returns an array of all current sessions\&. The structures in the array consist of the following fields: session id, user id, user name, seat id, session object path\&. If a session does not have a seat attached, the seat id field will be an empty string\&. +.PP +\fBListUsers()\fR +returns an array of all currently logged in users\&. The structures in the array consist of the following fields: user id, user name, user object path\&. +.PP +\fBListSeats()\fR +returns an array of all currently available seats\&. The structure in the array consists of the following fields: seat id, seat object path\&. +.PP +\fBListInhibitors()\fR +lists all currently active inhibitors\&. It returns an array of structures consisting of +\fIwhat\fR, +\fIwho\fR, +\fIwhy\fR, +\fImode\fR, +\fIuid\fR +(user ID), and +\fIpid\fR +(process ID)\&. +.PP +\fBCreateSession()\fR, +\fBCreateSessionWithPIDFD()\fR, and +\fBReleaseSession()\fR +may be used to open or close login sessions\&. These calls should +\fInever\fR +be invoked directly by clients\&. Creating/closing sessions is exclusively the job of PAM and its +\fBpam_systemd\fR(8) +module\&. +.PP +\fBActivateSession()\fR +brings the session with the specified ID into the foreground\&. +\fBActivateSessionOnSeat()\fR +does the same, but only if the seat id matches\&. +.PP +\fBLockSession()\fR +asks the session with the specified ID to activate the screen lock\&. +\fBUnlockSession()\fR +asks the session with the specified ID to remove an active screen lock, if there is any\&. This is implemented by sending out the Lock() and Unlock() signals from the respective session object which session managers are supposed to listen on\&. +.PP +\fBLockSessions()\fR +asks all sessions to activate their screen locks\&. This may be used to lock access to the entire machine in one action\&. Similarly, +\fBUnlockSessions()\fR +asks all sessions to deactivate their screen locks\&. +.PP +\fBKillSession()\fR +may be used to send a Unix signal to one or all processes of a session\&. As arguments it takes the session id, either the string +"leader" +or +"all" +and a signal number\&. If +"leader" +is passed only the session +"leader" +is killed\&. If +"all" +is passed all processes of the session are killed\&. +.PP +\fBKillUser()\fR +may be used to send a Unix signal to all processes of a user\&. As arguments it takes the user id and a signal number\&. +.PP +\fBTerminateSession()\fR, +\fBTerminateUser()\fR, +\fBTerminateSeat()\fR +may be used to forcibly terminate one specific session, all processes of a user, and all sessions attached to a specific seat, respectively\&. The session, user, and seat are identified by their respective IDs\&. +.PP +\fBSetUserLinger()\fR +enables or disables user lingering\&. If enabled, the runtime directory of a user is kept around and they may continue to run processes while logged out\&. If disabled, the runtime directory goes away as soon as they log out\&. +\fBSetUserLinger()\fR +expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the +\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2 +authorization interactivity (see below)\&. Note that the user linger state is persistently stored on disk\&. +.PP +\fBAttachDevice()\fR +may be used to assign a specific device to a specific seat\&. The device is identified by its +/sys/ +path and must be eligible for seat assignments\&. +\fBAttachDevice()\fR +takes three arguments: the seat id, the sysfs path, and a boolean for controlling polkit interactivity (see below)\&. Device assignments are persistently stored on disk\&. To create a new seat, simply specify a previously unused seat id\&. For more information about the seat assignment logic see +\fBsd-login\fR(3)\&. +.PP +\fBFlushDevices()\fR +removes all explicit seat assignments for devices, resetting all assignments to the automatic defaults\&. The only argument it takes is the polkit interactivity boolean (see below)\&. +.PP +\fBPowerOff()\fR, +\fBReboot()\fR, +\fBHalt()\fR, +\fBSuspend()\fR, and +\fBHibernate()\fR +result in the system being powered off, rebooted, halted (shut down without turning off power), suspended (the system state is saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and the machine is powered down)\&. +\fBHybridSleep()\fR +results in the system entering a hybrid\-sleep mode, i\&.e\&. the system is both hibernated and suspended\&. +\fBSuspendThenHibernate()\fR +results in the system being suspended, then later woken using an RTC timer and hibernated\&. The only argument is the polkit interactivity boolean +\fIinteractive\fR +(see below)\&. The main purpose of these calls is that they enforce polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users\&. They also enforce inhibition locks for non\-privileged users\&. UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine\&. Methods +\fBPowerOffWithFlags()\fR, +\fBRebootWithFlags()\fR, +\fBHaltWithFlags()\fR, +\fBSuspendWithFlags()\fR, +\fBHibernateWithFlags()\fR, +\fBHybridSleepWithFlags()\fR +and +\fBSuspendThenHibernateWithFlags()\fR +add +\fIflags\fR +to allow for extendability, defined as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0) +#define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1) +#define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) << 2) +#define SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP (UINT64_C(1) << 3) + +.fi +.if n \{\ +.RE +.\} +.PP +When the +\fIflags\fR +is 0 then these methods behave just like the versions without flags\&. When +\fBSD_LOGIND_ROOT_CHECK_INHIBITORS\fR +(0x01) is set, active inhibitors are honoured for privileged users too\&. When +\fBSD_LOGIND_KEXEC_REBOOT\fR +(0x02) is set, then +\fBRebootWithFlags()\fR +performs a kexec reboot if kexec kernel is loaded\&. When +\fBSD_LOGIND_SOFT_REBOOT\fR +(0x04) is set, or +\fBSD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP\fR +(0x08) is set and a new root file system has been set up on +"/run/nextroot/", then +\fBRebootWithFlags()\fR +performs a userspace reboot only\&. +\fBSD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP\fR +and +\fBSD_LOGIND_KEXEC_REBOOT\fR +can be combined, with soft\-reboot having precedence\&. +.PP +\fBSetRebootParameter()\fR +sets a parameter for a subsequent reboot operation\&. See the description of +\fBreboot\fR +in +\fBsystemctl\fR(1) +and +\fBreboot\fR(2) +for more information\&. +.PP +\fBSetRebootToFirmwareSetup()\fR, +\fBSetRebootToBootLoaderMenu()\fR, and +\fBSetRebootToBootLoaderEntry()\fR +configure the action to be taken from the boot loader after a reboot: respectively entering firmware setup mode, the boot loader menu, or a specific boot loader entry\&. See +\fBsystemctl\fR(1) +for the corresponding command line interface\&. +.PP +\fBCanPowerOff()\fR, +\fBCanReboot()\fR, +\fBCanHalt()\fR, +\fBCanSuspend()\fR, +\fBCanHibernate()\fR, +\fBCanHybridSleep()\fR, +\fBCanSuspendThenHibernate()\fR, +\fBCanRebootParameter()\fR, +\fBCanRebootToFirmwareSetup()\fR, +\fBCanRebootToBootLoaderMenu()\fR, and +\fBCanRebootToBootLoaderEntry()\fR +test whether the system supports the respective operation and whether the calling user is allowed to execute it\&. Returns one of +"na", +"yes", +"no", and +"challenge"\&. If +"na" +is returned, the operation is not available because hardware, kernel, or drivers do not support it\&. If +"yes" +is returned, the operation is supported and the user may execute the operation without further authentication\&. If +"no" +is returned, the operation is available but the user is not allowed to execute the operation\&. If +"challenge" +is returned, the operation is available but only after authorization\&. +.PP +\fBScheduleShutdown()\fR +schedules a shutdown operation +\fItype\fR +at time +\fIusec\fR +in microseconds since the UNIX epoch\&. +\fItype\fR +can be one of +"poweroff", +"dry\-poweroff", +"reboot", +"dry\-reboot", +"halt", and +"dry\-halt"\&. (The +"dry\-" +variants do not actually execute the shutdown action\&.) +\fBCancelScheduledShutdown()\fR +cancels a scheduled shutdown\&. The output parameter +\fIcancelled\fR +is true if a shutdown operation was scheduled\&. +.PP +\fBSetWallMessage()\fR +sets the wall message (the message that will be sent out to all terminals and stored in a +\fButmp\fR(5) +record) for a subsequent scheduled shutdown operation\&. The parameter +\fIwall_message\fR +specifies the shutdown reason (and may be empty) which will be included in the shutdown message\&. The parameter +\fIenable\fR +specifies whether to print a wall message on shutdown\&. +.PP +\fBInhibit()\fR +creates an inhibition lock\&. It takes four parameters: +\fIwhat\fR, +\fIwho\fR, +\fIwhy\fR, and +\fImode\fR\&. +\fIwhat\fR +is one or more of +"shutdown", +"sleep", +"idle", +"handle\-power\-key", +"handle\-suspend\-key", +"handle\-hibernate\-key", +"handle\-lid\-switch", separated by colons, for inhibiting poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware key handling\&. +\fIwho\fR +should be a short human readable string identifying the application taking the lock\&. +\fIwhy\fR +should be a short human readable string identifying the reason why the lock is taken\&. Finally, +\fImode\fR +is either +"block" +or +"delay" +which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time\&. The method returns a file descriptor\&. The lock is released the moment this file descriptor and all its duplicates are closed\&. For more information on the inhibition logic see +\m[blue]\fBInhibitor Locks\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SS "Signals" +.PP +Whenever the inhibition state or idle hint changes, +\fBPropertyChanged\fR +signals are sent out to which clients can subscribe\&. +.PP +The +\fBSessionNew\fR, +\fBSessionRemoved\fR, +\fBUserNew\fR, +\fBUserRemoved\fR, +\fBSeatNew\fR, and +\fBSeatRemoved\fR +signals are sent each time a session is created or removed, a user logs in or out, or a seat is added or removed\&. They each contain the ID of the object plus the object path\&. +.PP +The +\fBPrepareForShutdown\fR, +\fBPrepareForShutdownWithMetadata\fR, and +\fBPrepareForSleep\fR +signals are sent right before (with the argument +"true") or after (with the argument +"false") the system goes down for reboot/poweroff and suspend/hibernate, respectively\&. This may be used by applications to save data on disk, release memory, or do other jobs that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks\&. After completion of this work they should release their inhibition locks in order to not delay the operation any further\&. For more information see +\m[blue]\fBInhibitor Locks\fR\m[]\&\s-2\u[2]\d\s+2\&. The +\fBPrepareForShutdownWithMetadata()\fR +signal additionally sends a list of key/value pair metadata fields\&. Currently it sends a +\fItype\fR +string which defines the type of shutdown\&. The type can be one of +"power\-off", +"reboot", +"halt", +"kexec" +or +"soft\-reboot"\&. This signal is sent first, followed by +\fBPrepareForShutdown\fR +(for backward compatibility)\&. +.SS "Properties" +.PP +Most properties simply reflect the configuration, see +\fBlogind.conf\fR(5)\&. This includes: +\fINAutoVTs\fR, +\fIKillOnlyUsers\fR, +\fIKillExcludeUsers\fR, +\fIKillUserProcesses\fR, +\fIIdleAction\fR, +\fIInhibitDelayMaxUSec\fR, +\fIInhibitorsMax\fR, +\fIUserStopDelayUSec\fR, +\fIHandlePowerKey\fR, +\fIHandleSuspendKey\fR, +\fIHandleHibernateKey\fR, +\fIHandleLidSwitch\fR, +\fIHandleLidSwitchExternalPower\fR, +\fIHandleLidSwitchDocked\fR, +\fIIdleActionUSec\fR, +\fIHoldoffTimeoutUSec\fR, +\fIRemoveIPC\fR, +\fIRuntimeDirectorySize\fR, +\fIRuntimeDirectoryInodesMax\fR, +\fIInhibitorsMax\fR, and +\fISessionsMax\fR\&. +.PP +The +\fIIdleHint\fR +property reflects the idle hint state of the system\&. If the system is idle it might get into automatic suspend or shutdown depending on the configuration\&. +.PP +\fIIdleSinceHint\fR +and +\fIIdleSinceHintMonotonic\fR +encode the timestamps of the last change of the idle hint boolean, in +\fBCLOCK_REALTIME\fR +and +\fBCLOCK_MONOTONIC\fR +timestamps, respectively, in microseconds since the epoch\&. +.PP +The +\fIBlockInhibited\fR +and +\fIDelayInhibited\fR +properties encode the currently active locks of the respective modes\&. They are colon separated lists of +"shutdown", +"sleep", and +"idle" +(see above)\&. +.PP +\fINCurrentSessions\fR +and +\fINCurrentInhibitors\fR +contain the number of currently registered sessions and inhibitors\&. +.PP +The +\fIBootLoaderEntries\fR +property contains a list of boot loader entries\&. This includes boot loader entries defined in configuration and any additional loader entries reported by the boot loader\&. See +\fBsystemd-boot\fR(7) +for more information\&. +.PP +The +\fIPreparingForShutdown\fR +and +\fIPreparingForSleep\fR +boolean properties are true during the interval between the two +\fBPrepareForShutdown\fR +and +\fBPrepareForSleep\fR +signals respectively\&. Note that these properties do not send out +\fBPropertyChanged\fR +signals\&. +.PP +The +\fIRebootParameter\fR +property shows the value set with the +\fBSetRebootParameter()\fR +method described above\&. +.PP +\fIScheduledShutdown\fR +shows the value pair set with the +\fBScheduleShutdown()\fR +method described above\&. +.PP +\fIRebootToFirmwareSetup\fR, +\fIRebootToBootLoaderMenu\fR, and +\fIRebootToBootLoaderEntry\fR +are true when the resprective post\-reboot operation was selected with +\fBSetRebootToFirmwareSetup\fR, +\fBSetRebootToBootLoaderMenu\fR, or +\fBSetRebootToBootLoaderEntry\fR\&. +.PP +The +\fIWallMessage\fR +and +\fIEnableWallMessages\fR +properties reflect the shutdown reason and wall message enablement switch which can be set with the +\fBSetWallMessage()\fR +method described above\&. +.PP +\fIDocked\fR +is true if the machine is connected to a dock\&. +\fILidClosed\fR +is true when the lid (of a laptop) is closed\&. +\fIOnExternalPower\fR +is true when the machine is connected to an external power supply\&. +.SS "Security" +.PP +A number of operations are protected via the polkit privilege system\&. +\fBSetUserLinger()\fR +requires the +org\&.freedesktop\&.login1\&.set\-user\-linger +privilege\&. +\fBAttachDevice()\fR +requires +org\&.freedesktop\&.login1\&.attach\-device +and +\fBFlushDevices()\fR +requires +org\&.freedesktop\&.login1\&.flush\-devices\&. +\fBPowerOff()\fR, +\fBReboot()\fR, +\fBHalt()\fR, +\fBSuspend()\fR, +\fBHibernate()\fR +require +org\&.freedesktop\&.login1\&.power\-off, +org\&.freedesktop\&.login1\&.power\-off\-multiple\-sessions, +org\&.freedesktop\&.login1\&.power\-off\-ignore\-inhibit, +org\&.freedesktop\&.login1\&.reboot, +org\&.freedesktop\&.login1\&.reboot\-multiple\-sessions, +org\&.freedesktop\&.login1\&.reboot\-ignore\-inhibit, +org\&.freedesktop\&.login1\&.halt, +org\&.freedesktop\&.login1\&.halt\-multiple\-sessions, +org\&.freedesktop\&.login1\&.halt\-ignore\-inhibit, +org\&.freedesktop\&.login1\&.suspend, +org\&.freedesktop\&.login1\&.suspend\-multiple\-sessions, +org\&.freedesktop\&.login1\&.suspend\-ignore\-inhibit, +org\&.freedesktop\&.login1\&.hibernate, +org\&.freedesktop\&.login1\&.hibernate\-multiple\-sessions, +org\&.freedesktop\&.login1\&.hibernate\-ignore\-inhibit, respectively depending on whether there are other sessions around or active inhibits are present\&. +\fBHybridSleep()\fR +and +\fBSuspendThenHibernate()\fR +use the same privileges as +\fBHibernate()\fR\&. +\fBSetRebootParameter()\fR +requires +org\&.freedesktop\&.login1\&.set\-reboot\-parameter\&. +.PP +\fBSetRebootToFirmwareSetup\fR +requires +org\&.freedesktop\&.login1\&.set\-reboot\-to\-firmware\-setup\&. +\fBSetRebootToBootLoaderMenu\fR +requires +org\&.freedesktop\&.login1\&.set\-reboot\-to\-boot\-loader\-menu\&. +\fBSetRebootToBootLoaderEntry\fR +requires +org\&.freedesktop\&.login1\&.set\-reboot\-to\-boot\-loader\-entry\&. +.PP +\fBScheduleShutdown\fR +and +\fBCancelScheduledShutdown\fR +require the same privileges (listed above) as the immediate poweroff/reboot/halt operations\&. +.PP +\fBInhibit()\fR +is protected via one of +org\&.freedesktop\&.login1\&.inhibit\-block\-shutdown, +org\&.freedesktop\&.login1\&.inhibit\-delay\-shutdown, +org\&.freedesktop\&.login1\&.inhibit\-block\-sleep, +org\&.freedesktop\&.login1\&.inhibit\-delay\-sleep, +org\&.freedesktop\&.login1\&.inhibit\-block\-idle, +org\&.freedesktop\&.login1\&.inhibit\-handle\-power\-key, +org\&.freedesktop\&.login1\&.inhibit\-handle\-suspend\-key, +org\&.freedesktop\&.login1\&.inhibit\-handle\-hibernate\-key, +org\&.freedesktop\&.login1\&.inhibit\-handle\-lid\-switch +depending on the lock type and mode taken\&. +.PP +The +\fIinteractive\fR +boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required\&. +.SH "SEAT OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/login1/seat/seat0 { + interface org\&.freedesktop\&.login1\&.Seat { + methods: + Terminate(); + ActivateSession(in s session_id); + SwitchTo(in u vtnr); + SwitchToNext(); + SwitchToPrevious(); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Id = \*(Aq\&.\&.\&.\*(Aq; + readonly (so) ActiveSession = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CanTTY = \&.\&.\&.; + readonly b CanGraphical = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(so) Sessions = [\&.\&.\&.]; + readonly b IdleHint = \&.\&.\&.; + readonly t IdleSinceHint = \&.\&.\&.; + readonly t IdleSinceHintMonotonic = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBTerminate()\fR +and +\fBActivateSession()\fR +work similarly to +\fBTerminateSeat()\fR +and +\fBActivationSessionOnSeat()\fR +on the Manager object\&. +.PP +\fBSwitchTo()\fR +switches to the session on the virtual terminal +\fIvtnr\fR\&. +\fBSwitchToNext()\fR +and +\fBSwitchToPrevious()\fR +switch to, respectively, the next and previous sessions on the seat in the order of virtual terminals\&. If there is no active session, they switch to, respectively, the first and last session on the seat\&. +.SS "Signals" +.PP +Whenever +\fBActiveSession\fR, +\fBSessions\fR, +\fBCanGraphical\fR, +\fBCanTTY\fR, or the idle state changes, +\fBPropertyChanged\fR +signals are sent out to which clients can subscribe\&. +.SS "Properties" +.PP +The +\fIId\fR +property encodes the ID of the seat\&. +.PP +\fIActiveSession\fR +encodes the currently active session if there is one\&. It is a structure consisting of the session id and the object path\&. +.PP +\fICanTTY\fR +encodes whether the session is suitable for text logins, and +\fICanGraphical\fR +whether it is suitable for graphical sessions\&. +.PP +The +\fISessions\fR +property is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path\&. +.PP +The +\fIIdleHint\fR, +\fIIdleSinceHint\fR, and +\fIIdleSinceHintMonotonic\fR +properties encode the idle state, similarly to the ones exposed on the +Manager +object, but specific for this seat\&. +.SH "USER OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/login1/user/_1000 { + interface org\&.freedesktop\&.login1\&.User { + methods: + Terminate(); + Kill(in i signal_number); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u UID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u GID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Name = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t Timestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RuntimePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Service = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + readonly (so) Display = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(so) Sessions = [\&.\&.\&.]; + readonly b IdleHint = \&.\&.\&.; + readonly t IdleSinceHint = \&.\&.\&.; + readonly t IdleSinceHintMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Linger = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBTerminate()\fR +and +\fBKill()\fR +work similarly to the +\fBTerminateUser()\fR +and +\fBKillUser()\fR +methods on the manager object\&. +.SS "Signals" +.PP +Whenever +\fISessions\fR +or the idle state changes, +\fBPropertyChanged\fR +signals are sent out to which clients can subscribe\&. +.SS "Properties" +.PP +The +\fIUID\fR +and +\fIGID\fR +properties encode the Unix UID and primary GID of the user\&. +.PP +The +\fIName\fR +property encodes the user name\&. +.PP +\fITimestamp\fR +and +\fITimestampMonotonic\fR +encode the login time of the user in microseconds since the epoch, in the +\fBCLOCK_REALTIME\fR +and +\fBCLOCK_MONOTONIC\fR +clocks, respectively\&. +.PP +\fIRuntimePath\fR +encodes the runtime path of the user, i\&.e\&. +\fI$XDG_RUNTIME_DIR\fR\&. For details see the +\m[blue]\fBXDG Basedir Specification\fR\m[]\&\s-2\u[3]\d\s+2\&. +.PP +\fIService\fR +contains the unit name of the user systemd service of this user\&. Each logged in user is assigned a user service that runs a user systemd instance\&. This is usually an instance of +user@\&.service\&. +.PP +\fISlice\fR +contains the unit name of the user systemd slice of this user\&. Each logged in user gets a private slice\&. +.PP +\fIDisplay\fR +encodes which graphical session should be used as the primary UI display for the user\&. It is a structure encoding the session ID and the object path of the session to use\&. +.PP +\fIState\fR +encodes the user state and is one of +"offline", +"lingering", +"online", +"active", or +"closing"\&. See +\fBsd_uid_get_state\fR(3) +for more information about the states\&. +.PP +\fISessions\fR +is an array of structures encoding all current sessions of the user\&. Each structure consists of the ID and object path\&. +.PP +The +\fIIdleHint\fR, +\fIIdleSinceHint\fR, and +\fIIdleSinceHintMonotonic\fR +properties encode the idle hint state of the user, similarly to the +Manager\*(Aqs properties, but specific for this user\&. +.PP +The +\fILinger\fR +property shows whether lingering is enabled for this user\&. +.SH "SESSION OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/login1/session/1 { + interface org\&.freedesktop\&.login1\&.Session { + methods: + Terminate(); + Activate(); + Lock(); + Unlock(); + SetIdleHint(in b idle); + SetLockedHint(in b locked); + Kill(in s who, + in i signal_number); + TakeControl(in b force); + ReleaseControl(); + SetType(in s type); + SetDisplay(in s display); + SetTTY(in h tty_fd); + TakeDevice(in u major, + in u minor, + out h fd, + out b inactive); + ReleaseDevice(in u major, + in u minor); + PauseDeviceComplete(in u major, + in u minor); + SetBrightness(in s subsystem, + in s name, + in u brightness); + signals: + PauseDevice(u major, + u minor, + s type); + ResumeDevice(u major, + u minor, + h fd); + Lock(); + Unlock(); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Id = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (uo) User = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Name = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t Timestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u VTNr = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (so) Seat = \&.\&.\&.; + readonly s TTY = \*(Aq\&.\&.\&.\*(Aq; + readonly s Display = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Remote = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RemoteHost = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RemoteUser = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Service = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Desktop = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Scope = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u Leader = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u Audit = \&.\&.\&.; + readonly s Type = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Class = \*(Aq\&.\&.\&.\*(Aq; + readonly b Active = \&.\&.\&.; + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + readonly b IdleHint = \&.\&.\&.; + readonly t IdleSinceHint = \&.\&.\&.; + readonly t IdleSinceHintMonotonic = \&.\&.\&.; + readonly b LockedHint = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBTerminate()\fR, +\fBActivate()\fR, +\fBLock()\fR, +\fBUnlock()\fR, and +\fBKill()\fR +work similarly to the respective calls on the +Manager +object\&. +.PP +\fBSetIdleHint()\fR +is called by the session object to update the idle state of the session whenever it changes\&. +.PP +\fBTakeControl()\fR +allows a process to take exclusive managed device access\-control for that session\&. Only one D\-Bus connection can be a controller for a given session at any time\&. If the +\fIforce\fR +argument is set (root only), an existing controller is kicked out and replaced\&. Otherwise, this method fails if there is already a controller\&. Note that this method is limited to D\-Bus users with the effective UID set to the user of the session or root\&. +.PP +\fBReleaseControl()\fR +drops control of a given session\&. Closing the D\-Bus connection implicitly releases control as well\&. See +\fBTakeControl()\fR +for more information\&. This method also releases all devices for which the controller requested ownership via +\fBTakeDevice()\fR\&. +.PP +\fBSetType()\fR +allows the type of the session to be changed dynamically\&. It can only be called by session\*(Aqs current controller\&. If +\fBTakeControl()\fR +has not been called, this method will fail\&. In addition, the session type will be reset to its original value once control is released, either by calling +\fBReleaseControl()\fR +or closing the D\-Bus connection\&. This should help prevent a session from entering an inconsistent state, for example if the controller crashes\&. The only argument +\fItype\fR +is the new session type\&. +.PP +\fBSetDisplay()\fR +allows the display name of the graphical session to be changed\&. This is useful if the display server is started as part of the session\&. It can only be called by session\*(Aqs current controller\&. If +\fBTakeControl()\fR +has not been called, this method will fail\&. The only argument +\fIdisplay\fR +is the new display name\&. +.PP +\fBSetTTY()\fR +allows the device name of the session to be changed\&. This is useful if the tty device is only known after authentication\&. It can only be called by session\*(Aqs current controller\&. If +\fBTakeControl()\fR +has not been called, this method will fail\&. The only argument +\fItty_fd\fR +is a file handle to the new tty device\&. +.PP +\fBTakeDevice()\fR +allows a session controller to get a file descriptor for a specific device\&. Pass in the major and minor numbers of the character device and +systemd\-logind +will return a file descriptor for the device\&. Only a limited set of device\-types is currently supported (but may be extended)\&. +systemd\-logind +automatically mutes the file descriptor if the session is inactive and resumes it once the session is activated again\&. This guarantees that a session can only access session devices if the session is active\&. Note that this revoke/resume mechanism is asynchronous and may happen at any given time\&. This only works on devices that are attached to the seat of the given session\&. A process is not required to have direct access to the device node\&. +systemd\-logind +only requires you to be the active session controller (see +\fBTakeControl()\fR)\&. Also note that any device can only be requested once\&. As long as you don\*(Aqt release it, further +\fBTakeDevice()\fR +calls will fail\&. +.PP +\fBReleaseDevice()\fR +releases a device again (see +\fBTakeDevice()\fR)\&. This is also implicitly done by +\fBReleaseControl()\fR +or when closing the D\-Bus connection\&. +.PP +\fBPauseDeviceComplete()\fR +allows a session controller to synchronously pause a device after receiving a +\fBPauseDevice(\fR\fB"pause"\fR\fB)\fR +signal\&. Forced signals (or after an internal timeout) are automatically completed by +systemd\-logind +asynchronously\&. +.PP +\fBSetLockedHint()\fR +may be used to set the "locked hint" to +\fIlocked\fR, i\&.e\&. information whether the session is locked\&. This is intended to be used by the desktop environment to tell +\fBsystemd\-logind\fR +when the session is locked and unlocked\&. +.PP +\fBSetBrightness()\fR +may be used to set the display brightness\&. This is intended to be used by the desktop environment and allows unprivileged programs to access hardware settings in a controlled way\&. The +\fIsubsystem\fR +parameter specifies a kernel subsystem, either +"backlight" +or +"leds"\&. The +\fIname\fR +parameter specifies a device name under the specified subsystem\&. The +\fIbrightness\fR +parameter specifies the brightness\&. The range is defined by individual drivers, see +/sys/class/\fIsubsystem\fR/\fIname\fR/max_brightness\&. +.SS "Signals" +.PP +The active session controller exclusively gets +\fBPauseDevice\fR +and +\fBResumeDevice\fR +events for any device it requested via +\fBTakeDevice()\fR\&. They notify the controller whenever a device is paused or resumed\&. A device is never resumed if its session is inactive\&. Also note that +\fBPauseDevice\fR +signals are sent before the +\fBPropertyChanged\fR +signal for the +\fBActive\fR +state\&. The inverse is true for +\fBResumeDevice\fR\&. A device may remain paused for unknown reasons even though the +Session +is active\&. +.PP +A +\fBPauseDevice\fR +signal carries the major and minor numbers and a string describing the type as arguments\&. +\fBforce\fR +means the device was already paused by +systemd\-logind +and the signal is only an asynchronous notification\&. +\fBpause\fR +means +systemd\-logind +grants you a limited amount of time to pause the device\&. You must respond to this via +\fBPauseDeviceComplete()\fR\&. This synchronous pausing mechanism is used for backwards\-compatibility to VTs and +systemd\-logind +is free to not make use of it\&. It is also free to send a forced +\fBPauseDevice\fR +if you don\*(Aqt respond in a timely manner (or for any other reason)\&. +\fBgone\fR +means the device was unplugged from the system and you will no longer get any notifications about it\&. There is no need to call +\fBReleaseDevice()\fR\&. You may call +\fBTakeDevice()\fR +again if a new device is assigned the major+minor combination\&. +.PP +\fBResumeDevice\fR +is sent whenever a session is active and a device is resumed\&. It carries the major/minor numbers as arguments and provides a new open file descriptor\&. You should switch to the new descriptor and close the old one\&. They are not guaranteed to have the same underlying open file descriptor in the kernel (except for a limited set of device types)\&. +.PP +Whenever +\fBActive\fR +or the idle state changes, +\fBPropertyChanged\fR +signals are sent out to which clients can subscribe\&. +.PP +\fBLock\fR/\fBUnlock\fR +is sent when the session is asked to be screen\-locked/unlocked\&. A session manager of the session should listen to this signal and act accordingly\&. This signal is sent out as a result of the +\fBLock()\fR +and +\fBUnlock()\fR +methods, respectively\&. +.SS "Properties" +.PP +\fIId\fR +encodes the session ID\&. +.PP +\fIUser\fR +encodes the user ID of the user this session belongs to\&. This is a structure consisting of the Unix UID and the object path\&. +.PP +\fIName\fR +encodes the user name\&. +.PP +\fITimestamp\fR +and +\fITimestampMonotonic\fR +encode the microseconds since the epoch when the session was created, in +\fBCLOCK_REALTIME\fR +or +\fBCLOCK_MONOTONIC\fR, respectively\&. +.PP +\fIVTNr\fR +encodes the virtual terminal number of the session if there is any, 0 otherwise\&. +.PP +\fISeat\fR +encodes the seat this session belongs to if there is any\&. This is a structure consisting of the ID and the seat object path\&. +.PP +\fITTY\fR +encodes the kernel TTY path of the session if this is a text login\&. If not this is an empty string\&. +.PP +\fIDisplay\fR +encodes the X11 display name if this is a graphical login\&. If not, this is an empty string\&. +.PP +\fIRemote\fR +encodes whether the session is local or remote\&. +.PP +\fIRemoteHost\fR +and +\fIRemoteUser\fR +encode the remote host and user if this is a remote session, or an empty string otherwise\&. +.PP +\fIService\fR +encodes the PAM service name that registered the session\&. +.PP +\fIDesktop\fR +describes the desktop environment running in the session (if known)\&. +.PP +\fIScope\fR +contains the systemd scope unit name of this session\&. +.PP +\fILeader\fR +encodes the PID of the process that registered the session\&. +.PP +\fIAudit\fR +encodes the Kernel Audit session ID of the session if auditing is available\&. +.PP +\fIType\fR +encodes the session type\&. It\*(Aqs one of +"unspecified" +(for cron PAM sessions and suchlike), +"tty" +(for text logins) or +"x11"/"mir"/"wayland" +(for graphical logins)\&. +.PP +\fIClass\fR +encodes the session class\&. It\*(Aqs one of +"user" +(for normal user sessions), +"greeter" +(for display manager pseudo\-sessions), or +"lock\-screen" +(for display lock screens)\&. +.PP +\fIActive\fR +is a boolean that is true if the session is active, i\&.e\&. currently in the foreground\&. This field is semi\-redundant due to +\fIState\fR\&. +.PP +\fIState\fR +encodes the session state and one of +"online", +"active", or +"closing"\&. See +\fBsd_session_get_state\fR(3) +for more information about the states\&. +.PP +\fIIdleHint\fR, +\fIIdleSinceHint\fR, and +\fIIdleSinceHintMonotonic\fR +encapsulate the idle hint state of this session, similarly to how the respective properties on the manager object do it for the whole system\&. +.PP +\fILockedHint\fR +shows the locked hint state of this session, as set by the +\fBSetLockedHint()\fR +method described above\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect the logind manager on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e + \-\-object\-path /org/freedesktop/login1 + +.fi +.if n \{\ +.RE +.\} +.PP +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Introspect the default seat on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e + \-\-object\-path /org/freedesktop/login1/seat/seat0 + +.fi +.if n \{\ +.RE +.\} +.PP +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/seat/seat0 + +.fi +.if n \{\ +.RE +.\} +.PP +Seat +"seat0" +is the default seat, so it\*(Aqll be present unless local configuration is made to reassign all devices to a different seat\&. The list of seats and users can be acquired with +\fBloginctl list\-sessions\fR\&. +.PP +\fBExample\ \&3.\ \&Introspect a single user on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e + \-\-object\-path /org/freedesktop/login1/user/_1000 + +.fi +.if n \{\ +.RE +.\} +.PP +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/user/_1000 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&Introspect org\&.freedesktop\&.login1\&.Session on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e + \-\-object\-path /org/freedesktop/login1/session/45 + +.fi +.if n \{\ +.RE +.\} +.PP +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/session/45 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[4]\d\s+2\&. +.SH "HISTORY" +.SS "The Manager Object" +.PP +\fIHandlePowerKeyLongPress\fR, +\fIHandleRebootKey\fR, +\fIHandleRebootKeyLongPress\fR, +\fIHandleSuspendKeyLongPress\fR, and +\fIHandleHibernateKeyLongPress\fR +were added in version 251\&. +.PP +\fIStopIdleSessionUSec\fR +was added in version 252\&. +.PP +\fBPrepareForShutdownWithMetadata\fR +and +\fBCreateSessionWithPIDFD()\fR +were added in version 255\&. +.SS "Session Objects" +.PP +\fBSetDisplay()\fR +was added in version 252\&. +.PP +\fBSetTTY()\fR +was added in version 254\&. +.SH "NOTES" +.IP " 1." 4 +polkit +.RS 4 +\%https://www.freedesktop.org/software/polkit/docs/latest/ +.RE +.IP " 2." 4 +Inhibitor Locks +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/inhibit +.RE +.IP " 3." 4 +XDG Basedir Specification +.RS 4 +\%https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +.RE +.IP " 4." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.machine1.5 b/upstream/fedora-40/man5/org.freedesktop.machine1.5 new file mode 100644 index 00000000..a63a4960 --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.machine1.5 @@ -0,0 +1,587 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.MACHINE1" "5" "" "systemd 255" "org.freedesktop.machine1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.machine1 \- The D\-Bus interface of systemd\-machined +.SH "INTRODUCTION" +.PP +\fBsystemd-machined.service\fR(8) +is a system service that keeps track of locally running virtual machines and containers\&. This page describes the D\-Bus interface\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/machine1 { + interface org\&.freedesktop\&.machine1\&.Manager { + methods: + GetMachine(in s name, + out o machine); + GetImage(in s name, + out o image); + GetMachineByPID(in u pid, + out o machine); + ListMachines(out a(ssso) machines); + ListImages(out a(ssbttto) images); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + CreateMachine(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + in a(sv) scope_properties, + out o path); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + CreateMachineWithNetwork(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + in ai ifindices, + in a(sv) scope_properties, + out o path); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + RegisterMachine(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + out o path); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + RegisterMachineWithNetwork(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + in ai ifindices, + out o path); + UnregisterMachine(in s name); + TerminateMachine(in s id); + KillMachine(in s name, + in s who, + in i signal); + GetMachineAddresses(in s name, + out a(iay) addresses); + GetMachineOSRelease(in s name, + out a{ss} fields); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + OpenMachinePTY(in s name, + out h pty, + out s pty_path); + OpenMachineLogin(in s name, + out h pty, + out s pty_path); + OpenMachineShell(in s name, + in s user, + in s path, + in as args, + in as environment, + out h pty, + out s pty_path); + BindMountMachine(in s name, + in s source, + in s destination, + in b read_only, + in b mkdir); + CopyFromMachine(in s name, + in s source, + in s destination); + CopyToMachine(in s name, + in s source, + in s destination); + CopyFromMachineWithFlags(in s name, + in s source, + in s destination, + in t flags); + CopyToMachineWithFlags(in s name, + in s source, + in s destination, + in t flags); + OpenMachineRootDirectory(in s name, + out h fd); + GetMachineUIDShift(in s name, + out u shift); + RemoveImage(in s name); + RenameImage(in s name, + in s new_name); + CloneImage(in s name, + in s new_name, + in b read_only); + MarkImageReadOnly(in s name, + in b read_only); + GetImageHostname(in s name, + out s hostname); + GetImageMachineID(in s name, + out ay id); + GetImageMachineInfo(in s name, + out a{ss} machine_info); + GetImageOSRelease(in s name, + out a{ss} os_release); + SetPoolLimit(in t size); + SetImageLimit(in s name, + in t size); + CleanPool(in s mode, + out a(st) images); + MapFromMachineUser(in s name, + in u uid_inner, + out u uid_outer); + MapToMachineUser(in u uid_outer, + out s machine_name, + out o machine_path, + out u uid_inner); + MapFromMachineGroup(in s name, + in u gid_inner, + out u gid_outer); + MapToMachineGroup(in u gid_outer, + out s machine_name, + out o machine_path, + out u gid_inner); + signals: + MachineNew(s machine, + o path); + MachineRemoved(s machine, + o path); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s PoolPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t PoolUsage = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t PoolLimit = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBGetMachine()\fR +may be used to get the machine object path for the machine with the specified name\&. Similarly, +\fBGetMachineByPID()\fR +gets the machine object the specified PID belongs to if there is any\&. +.PP +\fBGetImage()\fR +may be used to get the image object path of the image with the specified name\&. +.PP +\fBListMachines()\fR +returns an array of all currently registered machines\&. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path\&. +.PP +\fBListImages()\fR +returns an array of all currently known images\&. The structures in the array consist of the following fields: image name, type, read\-only flag, creation time, modification time, current disk space, and image object path\&. +.PP +\fBCreateMachine()\fR +may be used to register a new virtual machine or container with +\fBsystemd\-machined\fR, creating a scope unit for it\&. It accepts the following arguments: a machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope registration\&. The virtual machine name must be suitable as a hostname, and hence should follow the usual DNS hostname rules, as well as the Linux hostname restrictions\&. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set +"a\-zA\-Z0\-9\-_\&." +are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other\&. Container and VM managers should ideally use the hostname used internally in the machine for this parameter\&. This recommendation is made in order to make the machine name naturally resolvable using +\fBnss-mymachines\fR(8)\&. If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using +"_" +as the escape character\&. Another (somewhat natural) option would be to utilize Internet IDNA encoding\&. The UUID is passed as a 32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed out array shall be passed\&. The UUID should identify the virtual machine/container uniquely and should ideally be the same UUID that +/etc/machine\-id +in the VM/container is initialized from\&. The service string can be free\-form, but it is recommended to pass a short lowercase identifier like +"systemd\-nspawn", +"libvirt\-lxc" +or similar\&. The class string should be either +"container" +or +"vm" +indicating whether the machine to register is of the respective class\&. The leader PID should be the host PID of the init process of the container or the encapsulating process of the VM\&. If the root directory of the container is known and available in the host\*(Aqs hierarchy, it should be passed\&. Otherwise, pass the empty string instead\&. Finally, the scope properties are passed as array in the same way as to PID1\*(Aqs +\fBStartTransientUnit()\fR +method\&. Calling this method will internally register a transient scope unit for the calling client (utilizing the passed scope_properties) and move the leader PID into it\&. The method returns an object path for the registered machine object that implements the +org\&.freedesktop\&.machine1\&.Machine +interface (see below)\&. Also see the +\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2 +for details about scope units and how to alter resource control settings on the created machine at runtime\&. +.PP +\fBRegisterMachine()\fR +is similar to +\fBCreateMachine()\fR\&. However, it only registers a machine and does not create a scope unit for it\&. Instead, the caller\*(Aqs unit is registered\&. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services\&. +.PP +\fBCreateMachineWithNetwork()\fR +and +\fBRegisterMachineWithNetwork()\fR +are similar to +\fBCreateMachine()\fR +and +\fBRegisterMachine()\fR +but take an extra argument: an array of network interface indices that point towards the virtual machine or container\&. The interface indices should reference one or more network interfaces on the host that can be used to communicate with the guest\&. Commonly, the passed interface index refers to the host side of a "veth" link (in case of containers), a "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces\&. Specifying this information is useful to enable support for link\-local IPv6 communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex\&. +\fBnss-mymachines\fR(8) +makes use of this information\&. +.PP +\fBKillMachine()\fR +sends a UNIX signal to the machine\*(Aqs processes\&. As its arguments, it takes a machine name (as originally passed to +\fBCreateMachine()\fR +or returned by +\fBListMachines()\fR), an identifier that specifies what precisely to send the signal to (either +"leader" +or +"all"), and a numeric UNIX signal integer\&. +.PP +\fBTerminateMachine()\fR +terminates a virtual machine, killing its processes\&. It takes a machine name as its only argument\&. +.PP +\fBGetMachineAddresses()\fR +retrieves the IP addresses of a container\&. This method returns an array of pairs consisting of an address family specifier (\fBAF_INET\fR +or +\fBAF_INET6\fR) and a byte array containing the addresses\&. This is only supported for containers that make use of network namespacing\&. +.PP +\fBGetMachineOSRelease()\fR +retrieves the OS release information of a container\&. This method returns an array of key value pairs read from the +\fBos-release\fR(5) +file in the container and is useful to identify the operating system used in a container\&. +.PP +\fBOpenMachinePTY()\fR +allocates a pseudo TTY in the container and returns a file descriptor and its path\&. This is equivalent to transitioning into the container and invoking +\fBposix_openpt\fR(3)\&. +.PP +\fBOpenMachineLogin()\fR +allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end\&. It returns the file descriptor of the PTY and the PTY path\&. This is useful for acquiring a pty with a login prompt from the container\&. +.PP +\fBOpenMachineShell()\fR +allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv[0]) and an environment block\&. It then returns the file descriptor of the PTY and the PTY path\&. +.PP +\fBBindMountMachine()\fR +bind mounts a file or directory from the host into the container\&. Its arguments consist of a machine name, the source directory on the host, the destination directory in the container, and two booleans, one indicating whether the bind mount shall be read\-only, the other indicating whether the destination mount point shall be created first, if it is missing\&. +.PP +\fBCopyFromMachine()\fR +copies files or directories from a container into the host\&. It takes a container name, a source directory in the container and a destination directory on the host as arguments\&. +\fBCopyToMachine()\fR +does the opposite and copies files from a source directory on the host into a destination directory in the container\&. +\fBCopyFromMachineWithFlags()\fR +and +\fBCopyToMachineWithFlags\fR +do the same but take an additional flags argument\&. +.PP +\fBRemoveImage()\fR +removes the image with the specified name\&. +.PP +\fBRenameImage()\fR +renames the specified image\&. +.PP +\fBCloneImage()\fR +clones the specified image under a new name\&. It also takes a boolean argument indicating whether the resulting image shall be read\-only or not\&. +.PP +\fBMarkImageReadOnly()\fR +toggles the read\-only flag of an image\&. +.PP +\fBSetPoolLimit()\fR +sets an overall quota limit on the pool of images\&. +.PP +\fBSetImageLimit()\fR +sets a per\-image quota limit\&. +.PP +\fBMapFromMachineUser()\fR, +\fBMapToMachineUser()\fR, +\fBMapFromMachineGroup()\fR, and +\fBMapToMachineGroup()\fR +may be used to map UIDs/GIDs from the host user namespace to a container user namespace or vice versa\&. +.SS "Signals" +.PP +\fBMachineNew\fR +and +\fBMachineRemoved\fR +are sent whenever a new machine is registered or removed\&. These signals carry the machine name and the object path to the corresponding +org\&.freedesktop\&.machine1\&.Machine +interface (see below)\&. +.SS "Properties" +.PP +\fIPoolPath\fR +specifies the file system path where images are written to\&. +.PP +\fIPoolUsage\fR +specifies the current usage size of the image pool in bytes\&. +.PP +\fIPoolLimit\fR +specifies the size limit of the image pool in bytes\&. +.SH "MACHINE OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/machine1/machine/rawhide { + interface org\&.freedesktop\&.machine1\&.Machine { + methods: + Terminate(); + Kill(in s who, + in i signal); + GetAddresses(out a(iay) addresses); + GetOSRelease(out a{ss} fields); + GetUIDShift(out u shift); + OpenPTY(out h pty, + out s pty_path); + OpenLogin(out h pty, + out s pty_path); + OpenShell(in s user, + in s path, + in as args, + in as environment, + out h pty, + out s pty_path); + BindMount(in s source, + in s destination, + in b read_only, + in b mkdir); + CopyFrom(in s source, + in s destination); + CopyTo(in s source, + in s destination); + CopyFromWithFlags(in s source, + in s destination, + in t flags); + CopyToWithFlags(in s source, + in s destination, + in t flags); + OpenRootDirectory(out h fd); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Name = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay Id = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t Timestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Service = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Unit = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u Leader = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Class = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ai NetworkInterfaces = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBTerminate()\fR +and +\fBKill()\fR +terminate/kill the machine\&. These methods take the same arguments as +\fBTerminateMachine()\fR +and +\fBKillMachine()\fR +on the Manager interface, respectively\&. +.PP +\fBGetAddresses()\fR +and +\fBGetOSRelease()\fR +get the IP address and OS release information from the machine\&. These methods take the same arguments as +\fBGetMachineAddresses()\fR +and +\fBGetMachineOSRelease()\fR +of the Manager interface, respectively\&. +.SS "Properties" +.PP +\fIName\fR +is the machine name as it was passed in during registration with +\fBCreateMachine()\fR +on the manager object\&. +.PP +\fIId\fR +is the machine UUID\&. +.PP +\fITimestamp\fR +and +\fITimestampMonotonic\fR +are the realtime and monotonic timestamps when the virtual machines where created in microseconds since the epoch\&. +.PP +\fIService\fR +contains a short string identifying the registering service as passed in during registration of the machine\&. +.PP +\fIUnit\fR +is the systemd scope or service unit name for the machine\&. +.PP +\fILeader\fR +is the PID of the leader process of the machine\&. +.PP +\fIClass\fR +is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for light\-weight userspace virtualization sharing the same kernel as the host)\&. +.PP +\fIRootDirectory\fR +is the root directory of the container if it is known and applicable or the empty string\&. +.PP +\fINetworkInterfaces\fR +contains an array of network interface indices that point towards the container, the VM or the host\&. For details about this information see the description of +\fBCreateMachineWithNetwork()\fR +above\&. +.PP +\fIState\fR +is the state of the machine and is one of +"opening", +"running", or +"closing"\&. Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.machine1\&.Manager on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.machine1 \e + \-\-object\-path /org/freedesktop/machine1 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.machine1\&.Machine on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.machine1 \e + \-\-object\-path /org/freedesktop/machine1/machine/rawhide + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "HISTORY" +.SS "The Manager Object" +.PP +\fBCopyFromMachineWithFlags()\fR +and +\fBCopyToMachineWithFlags()\fR +were added in version 252\&. +.SS "Machine Objects" +.PP +\fBCopyFromWithFlags()\fR +and +\fBCopyToWithFlags()\fR +were added in version 252\&. +.SH "NOTES" +.IP " 1." 4 +New Control Group Interfaces +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface +.RE +.IP " 2." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.network1.5 b/upstream/fedora-40/man5/org.freedesktop.network1.5 new file mode 100644 index 00000000..46092e21 --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.network1.5 @@ -0,0 +1,376 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.NETWORK1" "5" "" "systemd 255" "org.freedesktop.network1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.network1 \- The D\-Bus interface of systemd\-networkd +.SH "INTRODUCTION" +.PP +\fBsystemd-networkd.service\fR(8) +is a system service that manages and configures network interfaces\&. This page describes the D\-Bus interface\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/network1 { + interface org\&.freedesktop\&.network1\&.Manager { + methods: + ListLinks(out a(iso) links); + GetLinkByName(in s name, + out i ifindex, + out o path); + GetLinkByIndex(in i ifindex, + out s name, + out o path); + SetLinkNTP(in i ifindex, + in as servers); + SetLinkDNS(in i ifindex, + in a(iay) addresses); + SetLinkDNSEx(in i ifindex, + in a(iayqs) addresses); + SetLinkDomains(in i ifindex, + in a(sb) domains); + SetLinkDefaultRoute(in i ifindex, + in b enable); + SetLinkLLMNR(in i ifindex, + in s mode); + SetLinkMulticastDNS(in i ifindex, + in s mode); + SetLinkDNSOverTLS(in i ifindex, + in s mode); + SetLinkDNSSEC(in i ifindex, + in s mode); + SetLinkDNSSECNegativeTrustAnchors(in i ifindex, + in as names); + RevertLinkNTP(in i ifindex); + RevertLinkDNS(in i ifindex); + RenewLink(in i ifindex); + ForceRenewLink(in i ifindex); + ReconfigureLink(in i ifindex); + Reload(); + DescribeLink(in i ifindex, + out s json); + Describe(out s json); + properties: + readonly s OperationalState = \*(Aq\&.\&.\&.\*(Aq; + readonly s CarrierState = \*(Aq\&.\&.\&.\*(Aq; + readonly s AddressState = \*(Aq\&.\&.\&.\*(Aq; + readonly s IPv4AddressState = \*(Aq\&.\&.\&.\*(Aq; + readonly s IPv6AddressState = \*(Aq\&.\&.\&.\*(Aq; + readonly s OnlineState = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t NamespaceId = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.PP +Provides information about the manager\&. +.SH "LINK OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/network1/link/_1 { + interface org\&.freedesktop\&.network1\&.Link { + methods: + SetNTP(in as servers); + SetDNS(in a(iay) addresses); + SetDNSEx(in a(iayqs) addresses); + SetDomains(in a(sb) domains); + SetDefaultRoute(in b enable); + SetLLMNR(in s mode); + SetMulticastDNS(in s mode); + SetDNSOverTLS(in s mode); + SetDNSSEC(in s mode); + SetDNSSECNegativeTrustAnchors(in as names); + RevertNTP(); + RevertDNS(); + Renew(); + ForceRenew(); + Reconfigure(); + Describe(out s json); + properties: + readonly s OperationalState = \*(Aq\&.\&.\&.\*(Aq; + readonly s CarrierState = \*(Aq\&.\&.\&.\*(Aq; + readonly s AddressState = \*(Aq\&.\&.\&.\*(Aq; + readonly s IPv4AddressState = \*(Aq\&.\&.\&.\*(Aq; + readonly s IPv6AddressState = \*(Aq\&.\&.\&.\*(Aq; + readonly s OnlineState = \*(Aq\&.\&.\&.\*(Aq; + readonly s AdministrativeState = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (tt) BitRates = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + + + + + + + + + + + + + + + + + + + + + + +.PP +Provides information about interfaces\&. +.SH "NETWORK OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/network1/network/_1 { + interface org\&.freedesktop\&.network1\&.Network { + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Description = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SourcePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as MatchMAC = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as MatchPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as MatchDriver = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as MatchType = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as MatchName = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + + + + + +.PP +Provides information about \&.network files\&. +.SH "DHCP SERVER OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/network1/link/_1 { + interface org\&.freedesktop\&.network1\&.DHCPServer { + properties: + readonly a(uayayayayt) Leases = [\&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.network1\&.Link { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + +.PP +Provides information about leases\&. +.SH "DHCPV4 CLIENT OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/network1/link/_1 { + interface org\&.freedesktop\&.network1\&.DHCPv4Client { + properties: + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.network1\&.Link { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + +.PP +Provides information about DHCPv4 client status\&. +.SH "DHCPV6 CLIENT OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/network1/link/_1 { + interface org\&.freedesktop\&.network1\&.DHCPv6Client { + properties: + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.network1\&.Link { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + +.PP +Provides information about DHCPv6 client status\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.network1\&.Manager on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.network1 \e + \-\-object\-path /org/freedesktop/network1 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.network1\&.Link on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.network1 \e + \-\-object\-path /org/freedesktop/network1/link/_11 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "HISTORY" +.SS "DHCPv4 Client Object" +.PP +\fIState\fR +was added in version 255\&. +.SS "DHCPv6 Client Object" +.PP +\fIState\fR +was added in version 255\&. +.SH "NOTES" +.IP " 1." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.oom1.5 b/upstream/fedora-40/man5/org.freedesktop.oom1.5 new file mode 100644 index 00000000..85840abb --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.oom1.5 @@ -0,0 +1,105 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.OOM1" "5" "" "systemd 255" "org.freedesktop.oom1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.oom1 \- The D\-Bus interface of systemd\-oomd +.SH "INTRODUCTION" +.PP +\fBsystemd-oomd.service\fR(8) +is a system service which implements a userspace out\-of\-memory (OOM) killer\&. This page describes the D\-Bus interface\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/oom1 { + interface org\&.freedesktop\&.oom1\&.Manager { + methods: + DumpByFileDescriptor(out h fd); + signals: + Killed(s cgroup, + s reason); + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + +.SS "Methods" +.PP +\fBKilled\fR +signal is sent when any cgroup is killed by oomd\&. +.PP +Note that more reasons will be added in the future, and the table below will be expanded accordingly\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Killing reasons +.TS +allbox tab(:); +lB lB. +T{ +Reason +T}:T{ +Description +T} +.T& +l l +l l. +T{ +memory\-used +T}:T{ +Application took too much memory and swap\&. +T} +T{ +memory\-pressure +T}:T{ +Application took enough memory and swap to cause sufficient slowdown of other applications\&. +T} +.TE +.sp 1 +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "HISTORY" +.SS "The Manager Object" +.PP +\fBKilled\fR +was added in version 252\&. +.SH "NOTES" +.IP " 1." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.portable1.5 b/upstream/fedora-40/man5/org.freedesktop.portable1.5 new file mode 100644 index 00000000..5fa495f0 --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.portable1.5 @@ -0,0 +1,769 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.PORTABLE1" "5" "" "systemd 255" "org.freedesktop.portable1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.portable1 \- The D\-Bus interface of systemd\-portabled +.SH "INTRODUCTION" +.PP +\fBsystemd-portabled.service\fR(8) +is a system service that may be used to attach, detach and inspect portable services\&. This page describes the D\-Bus interface\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/portable1 { + interface org\&.freedesktop\&.portable1\&.Manager { + methods: + GetImage(in s image, + out o object); + ListImages(out a(ssbtttso) images); + GetImageOSRelease(in s image, + out a{ss} os_release); + GetImageMetadata(in s image, + in as matches, + out s image, + out ay os_release, + out a{say} units); + GetImageMetadataWithExtensions(in s image, + in as extensions, + in as matches, + in t flags, + out s image, + out ay os_release, + out a{say} extensions, + out a{say} units); + GetImageState(in s image, + out s state); + GetImageStateWithExtensions(in s image, + in as extensions, + in t flags, + out s state); + AttachImage(in s image, + in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes); + AttachImageWithExtensions(in s image, + in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + out a(sss) changes); + DetachImage(in s image, + in b runtime, + out a(sss) changes); + DetachImageWithExtensions(in s image, + in as extensions, + in t flags, + out a(sss) changes); + ReattachImage(in s image, + in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes_removed, + out a(sss) changes_updated); + ReattachImageWithExtensions(in s image, + in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + out a(sss) changes_removed, + out a(sss) changes_updated); + RemoveImage(in s image); + MarkImageReadOnly(in s image, + in b read_only); + SetImageLimit(in s image, + in t limit); + SetPoolLimit(in t limit); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s PoolPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t PoolUsage = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t PoolLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as Profiles = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBGetImage()\fR +may be used to get the image object path of the image with the specified name\&. +.PP +\fBListImages()\fR +returns an array of all currently known images\&. The structures in the array consist of the following fields: image name, type, read\-only flag, creation time, modification time, current disk space, usage and image object path\&. +.PP +\fBGetImageOSRelease()\fR +retrieves the OS release information of an image\&. This method returns an array of key value pairs read from the +\fBos-release\fR(5) +file in the image and is useful to identify the operating system used in a portable service\&. +.PP +\fBGetImageMetadata()\fR +retrieves metadata associated with an image\&. This method returns the image name, the image\*(Aqs +\fBos-release\fR(5) +content in the form of a (streamable) array of bytes, and a list of portable units contained in the image, in the form of a string (unit name) and an array of bytes with the content\&. +.PP +\fBGetImageMetadataWithExtensions()\fR +retrieves metadata associated with an image\&. This method is a superset of +\fBGetImageMetadata()\fR +with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via +\fBAttachImageWithExtensions()\fR\&. The path of each extension and an array of bytes with the content of the respective extension\-release file are returned, one such structure for each extension named in the input arguments\&. +.PP +\fBGetImageState()\fR +retrieves the image state as one of the following strings: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +detached +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +attached +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +attached\-runtime +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +enabled +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +enabled\-runtime +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +running +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +running\-runtime +.RE +.PP +\fBGetImageStateWithExtensions()\fR +is a superset of +\fBGetImageState()\fR, with additional support for a list of extensions as input parameters, which is necessary to query the state in case the image was attached in that particular way\&. The +\fIflag\fR +parameter is currently unused and reserved for future purposes\&. +.PP +\fBAttachImage()\fR +attaches a portable image to the system\&. This method takes an image path or name, a list of strings that will be used to search for unit files inside the image (partial or complete matches), a string indicating which portable profile to use for the image (see +\fIProfiles\fR +property for a list of available profiles), a boolean indicating whether to attach the image only for the current boot session, and a string representing the preferred copy mode (whether to copy the image or to just symlink it) with the following possible values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +(null) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +copy +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +symlink +.RE +.sp +This method returns the list of changes applied to the system (for example, which unit was added and is now available as a system service)\&. Each change is represented as a triplet of strings: the type of change applied, the path on which it was applied, and the source (if any)\&. The type of change applied will be one of the following possible values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +copy +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +symlink +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +write +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mkdir +.RE +.sp +Note that an image cannot be attached if a unit that it contains is already present on the system\&. +.PP +\fBAttachImageWithExtensions()\fR +attaches a portable image to the system\&. This method is a superset of +\fBAttachImage()\fR +with the addition of a list of extensions as input parameter, which will be overlaid on top of the main image\&. When this method is used, detaching must be done by passing the same arguments via the +\fBDetachImageWithExtensions()\fR +method\&. For more details on this functionality, see the +\fIMountImages=\fR +entry on +\fBsystemd.exec\fR(5) +and +\fBsystemd-sysext\fR(8)\&. +.PP +\fBDetachImage()\fR +detaches a portable image from the system\&. This method takes an image path or name, and a boolean indicating whether the image to detach was attached only for the current boot session or persistently\&. This method returns the list of changes applied to the system (for example, which unit was removed and is no longer available as a system service)\&. Each change is represented as a triplet of strings: the type of change applied, the path on which it was applied, and the source (if any)\&. The type of change applied will be one of the following possible values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +unlink +.RE +.sp +Note that an image cannot be detached if a unit that it contains is running\&. +.PP +\fBDetachImageWithExtensions()\fR +detaches a portable image from the system\&. This method is a superset of +\fBDetachImage()\fR +with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via +\fBAttachImageWithExtensions()\fR\&. The +\fIflag\fR +parameter is currently unused and reserved for future purposes\&. +.PP +\fBReattachImage()\fR +combines the effects of the +\fBAttachImage()\fR +method and the +\fBDetachImage()\fR +method\&. The difference is that it is allowed to reattach an image while one or more of its units are running\&. The reattach operation will fail if no matching image is attached\&. The input parameters match the +\fBAttachImage()\fR +method, and the return parameters are the combination of the return parameters of the +\fBDetachImage()\fR +method (first array, units that were removed) and the +\fBAttachImage()\fR +method (second array, units that were updated or added)\&. +.PP +\fBReattachImageWithExtensions()\fR +reattaches a portable image to the system\&. This method is a superset of +\fBReattachImage()\fR +with the addition of a list of extensions as input parameter, which will be overlaid on top of the main image\&. For more details on this functionality, see the +\fIMountImages=\fR +entry on +\fBsystemd.exec\fR(5) +and +\fBsystemd-sysext\fR(8)\&. The +\fIflag\fR +parameter is currently unused and reserved for future purposes +.PP +\fBRemoveImage()\fR +removes the image with the specified name\&. +.PP +\fBMarkImageReadOnly()\fR +toggles the read\-only flag of an image\&. +.PP +\fBSetPoolLimit()\fR +sets an overall quota limit on the pool of images\&. +.PP +\fBSetImageLimit()\fR +sets a per\-image quota limit\&. +.PP +The +\fBAttachImageWithExtensions()\fR, +\fBDetachImageWithExtensions()\fR +and +\fBReattachImageWithExtensions()\fR +methods take in options as flags instead of booleans to allow for extendability\&. +\fISD_SYSTEMD_PORTABLE_FORCE_ATTACH\fR +will cause safety checks that ensure the units are not running while the new image is attached or detached to be skipped\&. +\fISD_SYSTEMD_PORTABLE_FORCE_EXTENSION\fR +will cause the check that the +extension\-release\&.\fINAME\fR +file in the extension image matches the image name to be skipped\&. They are defined as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#define SD_SYSTEMD_PORTABLE_RUNTIME (UINT64_C(1) << 0) +#define SD_SYSTEMD_PORTABLE_FORCE_ATTACH (UINT64_C(1) << 1) +#define SD_SYSTEMD_PORTABLE_FORCE_EXTENSION (UINT64_C(1) << 2) + +.fi +.if n \{\ +.RE +.\} +.SS "Properties" +.PP +\fIPoolPath\fR +specifies the file system path where images are written to\&. +.PP +\fIPoolUsage\fR +specifies the current usage size of the image pool in bytes\&. +.PP +\fIPoolLimit\fR +specifies the size limit of the image pool in bytes\&. +.PP +\fIProfiles\fR +specifies the available runtime profiles for portable services\&. +.SH "THE IMAGE OBJECT" +.PP +The service exposes the following interfaces on the Image object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/portable1 { + interface org\&.freedesktop\&.portable1\&.Image { + methods: + GetOSRelease(out a{ss} os_release); + GetMetadata(in as matches, + out s image, + out ay os_release, + out a{say} units); + GetMetadataWithExtensions(in as extensions, + in as matches, + in t flags, + out s image, + out ay os_release, + out a{say} extensions, + out a{say} units); + GetState(out s state); + GetStateWithExtensions(in as extensions, + in t flags, + out s state); + Attach(in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes); + AttachWithExtensions(in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + out a(sss) changes); + Detach(in b runtime, + out a(sss) changes); + DetachWithExtensions(in as extensions, + in t flags, + out a(sss) changes); + Reattach(in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes_removed, + out a(sss) changes_updated); + ReattachWithExtensions(in as extensions, + in as matches, + in s profile, + in s copy_mode, + in t flags, + out a(sss) changes_removed, + out a(sss) changes_updated); + Remove(); + MarkReadOnly(in b read_only); + SetLimit(in t limit); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Name = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Path = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Type = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b ReadOnly = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CreationTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ModificationTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t Usage = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t Limit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t UsageExclusive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t LimitExclusive = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +The following methods implement the same operation as the respective methods on the +Manager +object (see above)\&. However, these methods operate on the image object and hence does not take an image name parameter\&. Invoking the methods directly on the Manager object has the advantage of not requiring a +\fBGetImage()\fR +call to get the image object for a specific image name\&. Calling the methods on the Manager object is hence a round trip optimization\&. List of methods: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +GetOSRelease() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +GetMetadata() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +GetMetadataWithExtensions() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +GetState() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Attach() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +AttachWithExtensions() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Detach() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +DetachWithExtensions() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Reattach() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ReattachWithExtensions() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Remove() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +MarkReadOnly() +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SetLimit() +.RE +.SS "Properties" +.PP +\fIName\fR +specifies the image name\&. +.PP +\fIPath\fR +specifies the file system path where image is stored\&. +.PP +\fIType\fR +specifies the image type\&. +.PP +\fIReadOnly\fR +specifies whether the image is read\-only\&. +.PP +\fICreationTimestamp\fR +specifies the image creation timestamp\&. +.PP +\fIModificationTimestamp\fR +specifies the image modification timestamp\&. +.PP +\fIUsage\fR +specifies the image disk usage\&. +.PP +\fILimit\fR +specifies the image disk usage limit\&. +.PP +\fIUsageExclusive\fR +specifies the image disk usage (exclusive)\&. +.PP +\fILimitExclusive\fR +specifies the image disk usage limit (exclusive)\&. +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "HISTORY" +.SS "The Manager Object" +.PP +\fBGetImageStateWithExtensions()\fR +was added in version 251\&. +.SS "The Image Object" +.PP +\fBGetStateWithExtensions()\fR +was added in version 251\&. +.PP +\fBReattachWithExtensions()\fR +was added in version 254\&. +.SH "NOTES" +.IP " 1." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.resolve1.5 b/upstream/fedora-40/man5/org.freedesktop.resolve1.5 new file mode 100644 index 00000000..4f3b397f --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.resolve1.5 @@ -0,0 +1,935 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.RESOLVE1" "5" "" "systemd 255" "org.freedesktop.resolve1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.resolve1 \- The D\-Bus interface of systemd\-resolved +.SH "INTRODUCTION" +.PP +\fBsystemd-resolved.service\fR(8) +is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS\&. It also does DNSSEC validation\&. This page describes the resolve semantics and the D\-Bus interface\&. +.PP +This page contains an API reference only\&. If you are looking for a longer explanation how to use this API, please consult +\m[blue]\fBWriting Network Configuration Managers\fR\m[]\&\s-2\u[1]\d\s+2 +and +\m[blue]\fBWriting Resolver Clients\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "THE MANAGER OBJECT" +.PP +The service exposes the following interfaces on the Manager object on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/resolve1 { + interface org\&.freedesktop\&.resolve1\&.Manager { + methods: + ResolveHostname(in i ifindex, + in s name, + in i family, + in t flags, + out a(iiay) addresses, + out s canonical, + out t flags); + ResolveAddress(in i ifindex, + in i family, + in ay address, + in t flags, + out a(is) names, + out t flags); + ResolveRecord(in i ifindex, + in s name, + in q class, + in q type, + in t flags, + out a(iqqay) records, + out t flags); + ResolveService(in i ifindex, + in s name, + in s type, + in s domain, + in i family, + in t flags, + out a(qqqsa(iiay)s) srv_data, + out aay txt_data, + out s canonical_name, + out s canonical_type, + out s canonical_domain, + out t flags); + GetLink(in i ifindex, + out o path); + SetLinkDNS(in i ifindex, + in a(iay) addresses); + SetLinkDNSEx(in i ifindex, + in a(iayqs) addresses); + SetLinkDomains(in i ifindex, + in a(sb) domains); + SetLinkDefaultRoute(in i ifindex, + in b enable); + SetLinkLLMNR(in i ifindex, + in s mode); + SetLinkMulticastDNS(in i ifindex, + in s mode); + SetLinkDNSOverTLS(in i ifindex, + in s mode); + SetLinkDNSSEC(in i ifindex, + in s mode); + SetLinkDNSSECNegativeTrustAnchors(in i ifindex, + in as names); + RevertLink(in i ifindex); + RegisterService(in s name, + in s name_template, + in s type, + in q service_port, + in q service_priority, + in q service_weight, + in aa{say} txt_datas, + out o service_path); + UnregisterService(in o service_path); + ResetStatistics(); + FlushCaches(); + ResetServerFeatures(); + properties: + readonly s LLMNRHostname = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s LLMNR = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MulticastDNS = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DNSOverTLS = \*(Aq\&.\&.\&.\*(Aq; + readonly a(iiay) DNS = [\&.\&.\&.]; + readonly a(iiayqs) DNSEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(iiay) FallbackDNS = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(iiayqs) FallbackDNSEx = [\&.\&.\&.]; + readonly (iiay) CurrentDNSServer = \&.\&.\&.; + readonly (iiayqs) CurrentDNSServerEx = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(isb) Domains = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (tt) TransactionStatistics = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (ttt) CacheStatistics = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DNSSEC = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (tttt) DNSSECStatistics = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b DNSSECSupported = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DNSSECNegativeTrustAnchors = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DNSStubListener = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ResolvConfMode = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBResolveHostname()\fR +takes a hostname and resolves it to one or more IP addresses\&. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be done on any suitable interface\&. The +\fIname\fR +parameter specifies the hostname to resolve\&. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS\&. The +\fIfamily\fR +parameter limits the results to a specific address family\&. It may be +\fBAF_INET\fR, +\fBAF_INET6\fR +or +\fBAF_UNSPEC\fR\&. If +\fBAF_UNSPEC\fR +is specified (recommended), both kinds are retrieved, subject to local network configuration (i\&.e\&. if no local, routable IPv6 address is found, no IPv6 address is retrieved; and similarly for IPv4)\&. A 64\-bit +\fIflags\fR +field may be used to alter the behaviour of the resolver operation (see below)\&. The method returns an array of address records\&. Each address record consists of the interface index the address belongs to, an address family as well as a byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address family)\&. The returned address family will be one of +\fBAF_INET\fR +or +\fBAF_INET6\fR\&. For IPv6, the returned address interface index should be used to initialize the \&.sin6_scope_id field of a +struct\ \&sockaddr_in6 +instance to permit support for resolution to link\-local IP addresses\&. The address array is followed by the canonical name of the host, which may or may not be identical to the resolved hostname\&. Finally, a 64\-bit +\fIflags\fR +field is returned that is defined similarly to the +\fIflags\fR +field that was passed in, but contains information about the resolved data (see below)\&. If the hostname passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned\&. In this case, no network communication is done\&. +.PP +\fBResolveAddress()\fR +executes the reverse operation: it takes an IP address and acquires one or more hostnames for it\&. As parameters it takes the interface index to execute the query on, or +\fB0\fR +if all suitable interfaces are OK\&. The +\fIfamily\fR +parameter indicates the address family of the IP address to resolve\&. It may be either +\fBAF_INET\fR +or +\fBAF_INET6\fR\&. The +\fIaddress\fR +parameter takes the raw IP address data (as either a 4 or 16 byte array)\&. The +\fIflags\fR +input parameter may be used to alter the resolver operation (see below)\&. The method returns an array of name records, each consisting of an interface index and a hostname\&. The +\fIflags\fR +output field contains additional information about the resolver operation (see below)\&. +.PP +\fBResolveRecord()\fR +takes a DNS resource record (RR) type, class and name, and retrieves the full resource record set (RRset), including the RDATA, for it\&. As parameter it takes the Linux network interface index to execute the query on, or +\fB0\fR +if it may be done on any suitable interface\&. The +\fIname\fR +parameter specifies the RR domain name to look up (no IDNA conversion is applied), followed by the 16\-bit class and type fields (which may be ANY)\&. Finally, a +\fIflags\fR +field may be passed in to alter behaviour of the look\-up (see below)\&. On completion, an array of RR items is returned\&. Each array entry consists of the network interface index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw RR discovered\&. The raw RR data starts with the RR\*(Aqs domain name, in the original casing, followed by the RR type, class, TTL and RDATA, in the binary format documented in +\m[blue]\fBRFC\ \&1035\fR\m[]\&\s-2\u[3]\d\s+2\&. For RRs that support name compression in the payload (such as MX or PTR), the compression is expanded in the returned data\&. +.PP +Note that currently, the class field has to be specified as IN or ANY\&. Specifying a different class will return an error indicating that look\-ups of this kind are unsupported\&. Similarly, some special types are not supported either (AXFR, OPT, \&...)\&. While +systemd\-resolved +parses and validates resource records of many types, it is crucial that clients using this API understand that the RR data originates from the network and should be thoroughly validated before use\&. +.PP +\fBResolveService()\fR +may be used to resolve a DNS +\fBSRV\fR +service record, as well as the hostnames referenced in it, and possibly an accompanying DNS\-SD +\fBTXT\fR +record containing additional service metadata\&. The primary benefit of using this method over +\fBResolveRecord()\fR +specifying the +\fBSRV\fR +type is that it will resolve the +\fBSRV\fR +and +\fBTXT\fR +RRs as well as the hostnames referenced in the SRV in a single operation\&. As parameters it takes a Linux network interface index, a service name, a service type and a service domain\&. This method may be invoked in three different modes: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +To resolve a DNS\-SD service, specify the service name (e\&.g\&. +"Lennart\*(Aqs Files"), the service type (e\&.g\&. +"_webdav\&._tcp") and the domain to search in (e\&.g\&. +"local") as the three service parameters\&. The service name must be in UTF\-8 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS\-SD specifications)\&. However, if necessary, IDNA conversion is applied to the domain parameter\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +To resolve a plain +\fBSRV\fR +record, set the service name parameter to the empty string and set the service type and domain properly\&. (IDNA conversion is applied to the domain, if necessary\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Alternatively, leave both the service name and type empty and specify the full domain name of the +\fBSRV\fR +record (i\&.e\&. prefixed with the service type) in the domain parameter\&. (No IDNA conversion is applied in this mode\&.) +.RE +.PP +The +\fIfamily\fR +parameter of the +\fBResolveService()\fR +method encodes the desired family of the addresses to resolve (use +\fBAF_INET\fR, +\fBAF_INET6\fR, or +\fBAF_UNSPEC\fR)\&. If this is enabled (Use the +\fBNO_ADDRESS\fR +flag to turn address resolution off, see below)\&. The +\fIflags\fR +parameter takes a couple of flags that may be used to alter the resolver operation\&. +.PP +On completion, +\fBResolveService()\fR +returns an array of +\fBSRV\fR +record structures\&. Each items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the +\fBSRV\fR +record\&. Immediately following is an array of the addresses of this hostname, with each item consisting of the interface index, the address family and the address data in a byte array\&. This address array is followed by the canonicalized hostname\&. After this array of +\fBSRV\fR +record structures an array of byte arrays follows that encodes the TXT RR strings, in case DNS\-SD look\-ups are enabled\&. The next parameters are the canonical service name, type and domain\&. This may or may not be identical to the parameters passed in\&. Finally, a +\fIflags\fR +field is returned that contains information about the resolver operation performed\&. +.PP +The +\fBResetStatistics()\fR +method resets the various statistics counters that +systemd\-resolved +maintains to zero\&. (For details, see the statistics properties below\&.) +.PP +The +\fBGetLink()\fR +method takes a network interface index and returns the object path to the +org\&.freedesktop\&.resolve1\&.Link +object corresponding to it\&. +.PP +The +\fBSetLinkDNS()\fR +method sets the DNS servers to use on a specific interface\&. This method (and the following ones) may be used by network management software to configure per\-interface DNS settings\&. It takes a network interface index as well as an array of DNS server IP address records\&. Each array item consists of an address family (either +\fBAF_INET\fR +or +\fBAF_INET6\fR), followed by a 4\-byte or 16\-byte array with the raw address data\&. This method is a one\-step shortcut for retrieving the Link object for a network interface using +\fBGetLink()\fR +(see above) and then invoking the +\fBSetDNS()\fR +method (see below) on it\&. +.PP +\fBSetLinkDNSEx()\fR +is similar to +\fBSetLinkDNS()\fR, but allows an IP port (instead of the default 53) and DNS name to be specified for each DNS server\&. The server name is used for Server Name Indication (SNI), which is useful when DNS\-over\-TLS is used\&. C\&.f\&. +\fIDNS=\fR +in +\fBresolved.conf\fR(5)\&. +.PP +\fBSetLinkDefaultRoute()\fR +specifies whether the link shall be used as the default route for name queries\&. See the description of name routing in +\fBsystemd-resolved.service\fR(8) +for details\&. +.PP +The +\fBSetLinkDomains()\fR +method sets the search and routing domains to use on a specific network interface for DNS look\-ups\&. It takes a network interface index and an array of domains, each with a boolean parameter indicating whether the specified domain shall be used as a search domain (false), or just as a routing domain (true)\&. Search domains are used for qualifying single\-label names into FQDN when looking up hostnames, as well as for making routing decisions on which interface to send queries ending in the domain to\&. Routing domains are only used for routing decisions and not used for single\-label name qualification\&. Pass the search domains in the order they should be used\&. +.PP +The +\fBSetLinkLLMNR()\fR +method enables or disables LLMNR support on a specific network interface\&. It takes a network interface index as well as a string that may either be empty or one of +"yes", +"no" +or +"resolve"\&. If empty, the systemd\-wide default LLMNR setting is used\&. If +"yes", LLMNR is used for resolution of single\-label names and the local hostname is registered on all local LANs for LLMNR resolution by peers\&. If +"no", LLMNR is turned off fully on this interface\&. If +"resolve", LLMNR is only enabled for resolving names, but the local hostname is not registered for other peers to use\&. +.PP +Similarly, the +\fBSetLinkMulticastDNS()\fR +method enables or disables MulticastDNS support on a specific interface\&. It takes the same parameters as +\fBSetLinkLLMNR()\fR +described above\&. +.PP +The +\fBSetLinkDNSSEC()\fR +method enables or disables DNSSEC validation on a specific network interface\&. It takes a network interface index as well as a string that may either be empty or one of +"yes", +"no", or +"allow\-downgrade"\&. When empty, the system\-wide default DNSSEC setting is used\&. If +"yes", full DNSSEC validation is done for all look\-ups\&. If the selected DNS server does not support DNSSEC, look\-ups will fail if this mode is used\&. If +"no", DNSSEC validation is fully disabled\&. If +"allow\-downgrade", DNSSEC validation is enabled, but is turned off automatically if the selected server does not support it (thus opening up behaviour to downgrade attacks)\&. Note that DNSSEC only applies to traditional DNS, not to LLMNR or MulticastDNS\&. +.PP +The +\fBSetLinkDNSSECNegativeTrustAnchors()\fR +method may be used to configure DNSSEC Negative Trust Anchors (NTAs) for a specific network interface\&. It takes a network interface index and a list of domains as arguments\&. +.PP +The +\fBSetLinkDNSOverTLS()\fR +method enables or disables DNS\-over\-TLS\&. C\&.f\&. +\fIDNSOverTLS=\fR +in +\fBsystemd-resolved.service\fR(8) +for details\&. +.PP +Network management software integrating with +systemd\-resolved +should call +\fBSetLinkDNS()\fR +or +\fBSetLinkDNSEx()\fR, +\fBSetLinkDefaultRoute()\fR, +\fBSetLinkDomains()\fR +and others after the interface appeared in the kernel (and thus after a network interface index has been assigned), but before the network interfaces is activated (\fBIFF_UP\fR +set) so that all settings take effect during the full time the network interface is up\&. It is safe to alter settings while the interface is up, however\&. Use +\fBRevertLink()\fR +(described below) to reset all per\-interface settings\&. +.PP +The +\fBRevertLink()\fR +method may be used to revert all per\-link settings described above to the defaults\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBThe Flags Parameter\fR +.RS 4 +.PP +The four methods above accept and return a 64\-bit flags value\&. In most cases passing 0 is sufficient and recommended\&. However, the following flags are defined to alter the look\-up: +.sp +.if n \{\ +.RS 4 +.\} +.nf +/* Input+Output: Protocol/scope */ +#define SD_RESOLVED_DNS (UINT64_C(1) << 0) +#define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1) +#define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2) +#define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3) +#define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4) + +/* Input: Restrictions */ +#define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5) +#define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6) +#define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7) +#define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8) +#define SD_RESOLVED_NO_VALIDATE (UINT64_C(1) << 10) +#define SD_RESOLVED_NO_SYNTHESIZE (UINT64_C(1) << 11) +#define SD_RESOLVED_NO_CACHE (UINT64_C(1) << 12) +#define SD_RESOLVED_NO_ZONE (UINT64_C(1) << 13) +#define SD_RESOLVED_NO_TRUST_ANCHOR (UINT64_C(1) << 14) +#define SD_RESOLVED_NO_NETWORK (UINT64_C(1) << 15) +#define SD_RESOLVED_NO_STALE (UINT64_C(1) << 24) + +/* Output: Security */ +#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9) +#define SD_RESOLVED_CONFIDENTIAL (UINT64_C(1) << 18) + +/* Output: Origin */ +#define SD_RESOLVED_SYNTHETIC (UINT64_C(1) << 19) +#define SD_RESOLVED_FROM_CACHE (UINT64_C(1) << 20) +#define SD_RESOLVED_FROM_ZONE (UINT64_C(1) << 21) +#define SD_RESOLVED_FROM_TRUST_ANCHOR (UINT64_C(1) << 22) +#define SD_RESOLVED_FROM_NETWORK (UINT64_C(1) << 23) +.fi +.if n \{\ +.RE +.\} +.PP +On input, the first five flags control the protocols to use for the look\-up\&. They refer to classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via IPv4/UDP and IPv6/UDP\&. If all of these five bits are off on input (which is strongly recommended) the look\-up will be done via all suitable protocols for the specific look\-up\&. Note that these flags operate as filter only, but cannot force a look\-up to be done via a protocol\&. Specifically, +systemd\-resolved +will only route look\-ups within the \&.local TLD to MulticastDNS (plus some reverse look\-up address domains), and single\-label names to LLMNR (plus some reverse address lookup domains)\&. It will route neither of these to Unicast DNS servers\&. Also, it will do LLMNR and Multicast DNS only on interfaces suitable for multicast\&. +.PP +On output, these five flags indicate which protocol was used to execute the operation, and hence where the data was found\&. +.PP +The primary use cases for these five flags are follow\-up look\-ups based on DNS data retrieved earlier\&. In this case it is often a good idea to limit the follow\-up look\-up to the protocol that was used to discover the first DNS result\&. +.PP +The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the look\-up\&. This flag is only available at input, none of the functions will return it on output\&. If a CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead\&. By default, when the flag is off, CNAME/DNAME RRs are followed\&. +.PP +The NO_TXT and NO_ADDRESS flags only influence operation of the +\fBResolveService()\fR +method\&. They are only defined for input, not output\&. If NO_TXT is set, the DNS\-SD TXT RR look\-up is not done in the same operation\&. If NO_ADDRESS is set, the discovered hostnames are not implicitly translated to their addresses\&. +.PP +The NO_SEARCH flag turns off the search domain logic\&. It is only defined for input in +\fBResolveHostname()\fR\&. When specified, single\-label hostnames are not qualified using defined search domains, if any are configured\&. Note that +\fBResolveRecord()\fR +will never qualify single\-label domain names using search domains\&. Also note that multi\-label hostnames are never subject to search list expansion\&. +.PP +NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be used\&. +.PP +The next six flags allow disabling certain sources during resolution\&. NO_SYNTHESIZE disables synthetic records, e\&.g\&. the local host name, see section SYNTHETIC RECORDS in +\fBsystemd-resolved.service\fR(8) +for more information\&. NO_CACHE disables the use of the cache of previously resolved records\&. NO_ZONE disables answers using locally registered public LLMNR/mDNS resource records\&. NO_TRUST_ANCHOR disables answers using locally configured trust anchors\&. NO_NETWORK requires all answers to be provided without using the network, i\&.e\&. either from local sources or the cache\&. NO_STALE flag can be set to disable answering request with stale records\&. +.PP +The AUTHENTICATED bit is defined only in the output flags of the four functions\&. If set, the returned data has been fully authenticated\&. Specifically, this bit is set for all DNSSEC\-protected data for which a full trust chain may be established to a trusted domain anchor\&. It is also set for locally synthesized data, such as +"localhost" +or data from +/etc/hosts\&. Moreover, it is set for all LLMNR or mDNS RRs which originate from the local host\&. Applications that require authenticated RR data for operation should check this flag before trusting the data\&. Note that +systemd\-resolved +will never return invalidated data, hence this flag simply allows one to discern the cases where data is known to be trusted, or where there is proof that the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server does not support authenticating data)\&. +.PP +CONFIDENTIAL means the query was resolved via encrypted channels or never left this system\&. +.PP +The next five bits flags are used in output and provide information about the origin of the answer\&. FROM_SYNTHETIC means the query was (at least partially) synthesized locally\&. FROM_CACHE means the query was answered (at least partially) using the cache\&. FROM_ZONE means the query was answered (at least partially) based on public, locally registered records\&. FROM_TRUST_ANCHOR means the query was answered (at least partially) using local trust anchors\&. FROM_NETWORK means the query was answered (at least partially) using the network\&. +.RE +.SS "Properties" +.PP +The +\fILLMNR\fR +and +\fIMulticastDNS\fR +properties report whether LLMNR and MulticastDNS are (globally) enabled\&. Each may be one of +"yes", +"no", and +"resolve"\&. See +\fBSetLinkLLMNR()\fR +and +\fBSetLinkMulticastDNS()\fR +above\&. +.PP +\fILLMNRHostname\fR +contains the hostname currently exposed on the network via LLMNR\&. It usually follows the system hostname as may be queried via +\fBgethostname\fR(3), but may differ if a conflict is detected on the network\&. +.PP +\fIDNS\fR +and +\fIDNSEx\fR +contain arrays of all DNS servers currently used by +systemd\-resolved\&. +\fIDNS\fR +contains information similar to the DNS server data in +/run/systemd/resolve/resolv\&.conf\&. Each structure in the array consists of a numeric network interface index, an address family, and a byte array containing the DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6)\&. +\fIDNSEx\fR +is similar, but additionally contains the IP port and server name (used for Server Name Indication, SNI)\&. Both arrays contain DNS servers configured system\-wide, including those possibly read from a foreign +/etc/resolv\&.conf +or the +\fIDNS=\fR +setting in +/etc/systemd/resolved\&.conf, as well as per\-interface DNS server information either retrieved from +\fBsystemd-networkd\fR(8), or configured by external software via +\fBSetLinkDNS()\fR +or +\fBSetLinkDNSEx()\fR +(see above)\&. The network interface index will be 0 for the system\-wide configured services and non\-zero for the per\-link servers\&. +.PP +\fIFallbackDNS\fR +and +\fIFallbackDNSEx\fR +contain arrays of all DNS servers configured as fallback servers, if any, using the same format as +\fIDNS\fR +and +\fIDNSEx\fR +described above\&. See the description of +\fIFallbackDNS=\fR +in +\fBresolved.conf\fR(5) +for the description of when those servers are used\&. +.PP +\fICurrentDNSServer\fR +and +\fICurrentDNSServerEx\fR +specify the server that is currently used for query resolution, in the same format as a single entry in the +\fIDNS\fR +and +\fIDNSEx\fR +arrays described above\&. +.PP +Similarly, the +\fIDomains\fR +property contains an array of all search and routing domains currently used by +systemd\-resolved\&. Each entry consists of a network interface index (again, 0 encodes system\-wide entries), the actual domain name, and whether the entry is used only for routing (true) or for both routing and searching (false)\&. +.PP +The +\fITransactionStatistics\fR +property contains information about the number of transactions +systemd\-resolved +has processed\&. It contains a pair of unsigned 64\-bit counters, the first containing the number of currently ongoing transactions, the second the number of total transactions +systemd\-resolved +is processing or has processed\&. The latter value may be reset using the +\fBResetStatistics()\fR +method described above\&. Note that the number of transactions does not directly map to the number of issued resolver bus method calls\&. While simple look\-ups usually require a single transaction only, more complex look\-ups might result in more, for example when CNAMEs or DNSSEC are in use\&. +.PP +The +\fICacheStatistics\fR +property contains information about the executed cache operations so far\&. It exposes three 64\-bit counters: the first being the total number of current cache entries (both positive and negative), the second the number of cache hits, and the third the number of cache misses\&. The latter counters may be reset using +\fBResetStatistics()\fR +(see above)\&. +.PP +The +\fIDNSSEC\fR +property specifies current status of DNSSEC validation\&. It is one of +"yes" +(validation is enforced), +"no" +(no validation is done), +"allow\-downgrade" +(validation is done if the current DNS server supports it)\&. See the description of +\fIDNSSEC=\fR +in +\fBresolved.conf\fR(5)\&. +.PP +The +\fIDNSSECStatistics\fR +property contains information about the DNSSEC validations executed so far\&. It contains four 64\-bit counters: the number of secure, insecure, bogus, and indeterminate DNSSEC validations so far\&. The counters are increased for each validated RRset, and each non\-existence proof\&. The secure counter is increased for each operation that successfully verified a signed reply, the insecure counter is increased for each operation that successfully verified that an unsigned reply is rightfully unsigned\&. The bogus counter is increased for each operation where the validation did not check out and the data is likely to have been tempered with\&. Finally the indeterminate counter is increased for each operation which did not complete because the necessary keys could not be acquired or the cryptographic algorithms were unknown\&. +.PP +The +\fIDNSSECSupported\fR +boolean property reports whether DNSSEC is enabled and the selected DNS servers support it\&. It combines information about system\-wide and per\-link DNS settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for which DNS is configured and for the system\-wide settings if there are any\&. Note that +systemd\-resolved +assumes DNSSEC is supported by DNS servers until it verifies that this is not the case\&. Thus, the reported value may initially be true, until the first transactions are executed\&. +.PP +The +\fIDNSOverTLS\fR +boolean property reports whether DNS\-over\-TLS is enabled\&. +.PP +The +\fIResolvConfMode\fR +property exposes how +/etc/resolv\&.conf +is managed on the host\&. Currently, the values +"uplink", +"stub", +"static" +(these three correspond to the three different files +systemd\-resolved\&.service +provides), +"foreign" +(the file is managed by admin or another service, +systemd\-resolved\&.service +just consumes it), +"missing" +(/etc/resolv\&.conf +is missing)\&. +.PP +The +\fIDNSStubListener\fR +property reports whether the stub listener on port 53 is enabled\&. Possible values are +"yes" +(enabled), +"no" +(disabled), +"udp" +(only the UDP listener is enabled), and +"tcp" +(only the TCP listener is enabled)\&. +.SH "LINK OBJECT" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/resolve1/link/_1 { + interface org\&.freedesktop\&.resolve1\&.Link { + methods: + SetDNS(in a(iay) addresses); + SetDNSEx(in a(iayqs) addresses); + SetDomains(in a(sb) domains); + SetDefaultRoute(in b enable); + SetLLMNR(in s mode); + SetMulticastDNS(in s mode); + SetDNSOverTLS(in s mode); + SetDNSSEC(in s mode); + SetDNSSECNegativeTrustAnchors(in as names); + Revert(); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ScopesMask = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iay) DNS = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayqs) DNSEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (iay) CurrentDNSServer = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (iayqs) CurrentDNSServerEx = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(sb) Domains = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b DefaultRoute = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s LLMNR = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MulticastDNS = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DNSOverTLS = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DNSSEC = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DNSSECNegativeTrustAnchors = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b DNSSECSupported = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + + + + + + + + + + + + + + + + + + + + + +.PP +For each Linux network interface a "Link" object is created which exposes per\-link DNS configuration and state\&. Use +\fBGetLink()\fR +on the Manager interface to retrieve the object path for a link object given the network interface index (see above)\&. +.SS "Methods" +.PP +The various methods exposed by the Link interface are equivalent to their similarly named counterparts on the Manager interface\&. e\&.g\&. +\fBSetDNS()\fR +on the Link object maps to +\fBSetLinkDNS()\fR +on the Manager object, the main difference being that the later expects an interface index to be specified\&. Invoking the methods on the Manager interface has the benefit of reducing roundtrips, as it is not necessary to first request the Link object path via +\fBGetLink()\fR +before invoking the methods\&. The same relationship holds for +\fBSetDNSEx()\fR, +\fBSetDomains()\fR, +\fBSetDefaultRoute()\fR, +\fBSetLLMNR()\fR, +\fBSetMulticastDNS()\fR, +\fBSetDNSOverTLS()\fR, +\fBSetDNSSEC()\fR, +\fBSetDNSSECNegativeTrustAnchors()\fR, and +\fBRevert()\fR\&. For further details on these methods see the +Manager +documentation above\&. +.SS "Properties" +.PP +\fIScopesMask\fR +defines which resolver scopes are currently active on this interface\&. This 64\-bit unsigned integer field is a bit mask consisting of a subset of the bits of the flags parameter describe above\&. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in IPv4 and IPv6 flavours) set\&. Each individual bit is set when the protocol applies to a specific interface and is enabled for it\&. It is unset otherwise\&. Specifically, a multicast\-capable interface in the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and has an IP address is suitable for DNS\&. Note the relationship of the bits exposed here with the LLMNR and MulticastDNS properties also exposed on the Link interface\&. The latter expose what is *configured* to be used on the interface, the former expose what is actually used on the interface, taking into account the abilities of the interface\&. +.PP +\fIDNSSECSupported\fR +exposes a boolean field that indicates whether DNSSEC is currently configured and in use on the interface\&. Note that if DNSSEC is enabled on an interface, it is assumed available until it is detected that the configured server does not actually support it\&. Thus, this property may initially report that DNSSEC is supported on an interface\&. +.PP +\fIDefaultRoute\fR +exposes a boolean field that indicates whether the interface will be used as default route for name queries\&. See +\fBSetLinkDefaultRoute()\fR +above\&. +.PP +The other properties reflect the state of the various configuration settings for the link which may be set with the various methods calls such as +\fBSetDNS()\fR +or +\fBSetLLMNR()\fR\&. +.SH "COMMON ERRORS" +.PP +Many bus methods +systemd\-resolved +exposes (in particular the resolver methods such as +\fBResolveHostname()\fR +on the +Manager +interface) may return some of the following errors: +.PP +\fBorg\&.freedesktop\&.resolve1\&.NoNameServers\fR +.RS 4 +No suitable DNS servers were found to resolve a request\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.InvalidReply\fR +.RS 4 +A response from the selected DNS server was not understood\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.NoSuchRR\fR +.RS 4 +The requested name exists, but there is no resource record of the requested type for it\&. (This is the DNS NODATA case)\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.CNameLoop\fR +.RS 4 +The look\-up failed because a CNAME or DNAME loop was detected\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.Aborted\fR +.RS 4 +The look\-up was aborted because the selected protocol became unavailable while the operation was ongoing\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.NoSuchService\fR +.RS 4 +A service look\-up was successful, but the +\fBSRV\fR +record reported that the service is not available\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.DnssecFailed\fR +.RS 4 +The acquired response did not pass DNSSEC validation\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.NoTrustAnchor\fR +.RS 4 +No chain of trust could be established for the response to a configured DNSSEC trust anchor\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.ResourceRecordTypeUnsupported\fR +.RS 4 +The requested resource record type is not supported on the selected DNS servers\&. This error is generated for example when an RRSIG record is requested from a DNS server that does not support DNSSEC\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.NoSuchLink\fR +.RS 4 +No network interface with the specified network interface index exists\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.LinkBusy\fR +.RS 4 +The requested configuration change could not be made because +\fBsystemd-networkd\fR(8), already took possession of the interface and supplied configuration data for it\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.NetworkDown\fR +.RS 4 +The requested look\-up failed because the system is currently not connected to any suitable network\&. +.sp +Added in version 246\&. +.RE +.PP +\fBorg\&.freedesktop\&.resolve1\&.DnsError\&.NXDOMAIN\fR, \fBorg\&.freedesktop\&.resolve1\&.DnsError\&.REFUSED\fR, \&.\&.\&. +.RS 4 +The look\-up failed with a DNS return code reporting a failure\&. The error names used as suffixes here are defined in by IANA in +\m[blue]\fBDNS\ \&RCODEs\fR\m[]\&\s-2\u[4]\d\s+2\&. +.sp +Added in version 246\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.resolve1\&.Manager on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.resolve1 \e + \-\-object\-path /org/freedesktop/resolve1 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.resolve1\&.Link on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.resolve1 \e + \-\-object\-path /org/freedesktop/resolve1/link/_11 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[5]\d\s+2\&. +.SH "NOTES" +.IP " 1." 4 +Writing Network Configuration Managers +.RS 4 +\%https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers +.RE +.IP " 2." 4 +Writing Resolver Clients +.RS 4 +\%https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients +.RE +.IP " 3." 4 +RFC\ \&1035 +.RS 4 +\%https://www.ietf.org/rfc/rfc1035.txt +.RE +.IP " 4." 4 +DNS\ \&RCODEs +.RS 4 +\%https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6 +.RE +.IP " 5." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.systemd1.5 b/upstream/fedora-40/man5/org.freedesktop.systemd1.5 new file mode 100644 index 00000000..7f3378a8 --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.systemd1.5 @@ -0,0 +1,7603 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.SYSTEMD1" "5" "" "systemd 255" "org.freedesktop.systemd1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.systemd1 \- The D\-Bus interface of systemd +.SH "INTRODUCTION" +.PP +\fBsystemd\fR(1) +and its auxiliary daemons expose a number of APIs over D\-Bus\&. This page only describes the various APIs exposed by the system and service manager itself\&. It does not cover the auxiliary daemons\&. +.PP +The service manager exposes a number of objects on the bus: one +Manager +object as a central entry point for clients along with individual objects for each unit and for each queued job\&. The unit objects implement a generic +Unit +interface as well as a type\-specific interface\&. For example, service units implement both +org\&.freedesktop\&.systemd1\&.Unit +and +org\&.freedesktop\&.system1\&.Service\&. The manager object can list unit and job objects or directly convert a unit name or job identifier to a bus path of the corresponding D\-Bus object\&. +.PP +Properties exposing time values are usually encoded in microseconds (μs) on the bus, even if their corresponding settings in the unit files are in seconds\&. +.PP +PID 1 uses +\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2 +to allow access to privileged operations for unprivileged processes\&. Some operations (such as shutdown/reboot/suspend) are also available through the D\-Bus API of logind, see +\fBorg.freedesktop.login1\fR(5)\&. +.SH "THE MANAGER OBJECT" +.PP +The main entry point object is available on the fixed +\fB/org/freedesktop/systemd1\fR +object path: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1 { + interface org\&.freedesktop\&.systemd1\&.Manager { + methods: + GetUnit(in s name, + out o unit); + GetUnitByPID(in u pid, + out o unit); + GetUnitByInvocationID(in ay invocation_id, + out o unit); + GetUnitByControlGroup(in s cgroup, + out o unit); + GetUnitByPIDFD(in h pidfd, + out o unit, + out s unit_id, + out ay invocation_id); + LoadUnit(in s name, + out o unit); + StartUnit(in s name, + in s mode, + out o job); + StartUnitWithFlags(in s name, + in s mode, + in t flags, + out o job); + StartUnitReplace(in s old_unit, + in s new_unit, + in s mode, + out o job); + StopUnit(in s name, + in s mode, + out o job); + ReloadUnit(in s name, + in s mode, + out o job); + RestartUnit(in s name, + in s mode, + out o job); + TryRestartUnit(in s name, + in s mode, + out o job); + ReloadOrRestartUnit(in s name, + in s mode, + out o job); + ReloadOrTryRestartUnit(in s name, + in s mode, + out o job); + EnqueueUnitJob(in s name, + in s job_type, + in s job_mode, + out u job_id, + out o job_path, + out s unit_id, + out o unit_path, + out s job_type, + out a(uosos) affected_jobs); + KillUnit(in s name, + in s whom, + in i signal); + QueueSignalUnit(in s name, + in s whom, + in i signal, + in i value); + CleanUnit(in s name, + in as mask); + FreezeUnit(in s name); + ThawUnit(in s name); + ResetFailedUnit(in s name); + SetUnitProperties(in s name, + in b runtime, + in a(sv) properties); + BindMountUnit(in s name, + in s source, + in s destination, + in b read_only, + in b mkdir); + MountImageUnit(in s name, + in s source, + in s destination, + in b read_only, + in b mkdir, + in a(ss) options); + RefUnit(in s name); + UnrefUnit(in s name); + StartTransientUnit(in s name, + in s mode, + in a(sv) properties, + in a(sa(sv)) aux, + out o job); + GetUnitProcesses(in s name, + out a(sus) processes); + AttachProcessesToUnit(in s unit_name, + in s subcgroup, + in au pids); + AbandonScope(in s name); + GetJob(in u id, + out o job); + GetJobAfter(in u id, + out a(usssoo) jobs); + GetJobBefore(in u id, + out a(usssoo) jobs); + CancelJob(in u id); + ClearJobs(); + ResetFailed(); + SetShowStatus(in s mode); + ListUnits(out a(ssssssouso) units); + ListUnitsFiltered(in as states, + out a(ssssssouso) units); + ListUnitsByPatterns(in as states, + in as patterns, + out a(ssssssouso) units); + ListUnitsByNames(in as names, + out a(ssssssouso) units); + ListJobs(out a(usssoo) jobs); + Subscribe(); + Unsubscribe(); + Dump(out s output); + DumpUnitsMatchingPatterns(in as patterns, + out s output); + DumpByFileDescriptor(out h fd); + DumpUnitsMatchingPatternsByFileDescriptor(in as patterns, + out h fd); + Reload(); + @org\&.freedesktop\&.DBus\&.Method\&.NoReply("true") + Reexecute(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Exit(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Reboot(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + SoftReboot(in s new_root); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + PowerOff(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + Halt(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + KExec(); + @org\&.freedesktop\&.systemd1\&.Privileged("true") + SwitchRoot(in s new_root, + in s init); + SetEnvironment(in as assignments); + UnsetEnvironment(in as names); + UnsetAndSetEnvironment(in as names, + in as assignments); + EnqueueMarkedJobs(out ao jobs); + ListUnitFiles(out a(ss) unit_files); + ListUnitFilesByPatterns(in as states, + in as patterns, + out a(ss) unit_files); + GetUnitFileState(in s file, + out s state); + EnableUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + DisableUnitFiles(in as files, + in b runtime, + out a(sss) changes); + EnableUnitFilesWithFlags(in as files, + in t flags, + out b carries_install_info, + out a(sss) changes); + DisableUnitFilesWithFlags(in as files, + in t flags, + out a(sss) changes); + DisableUnitFilesWithFlagsAndInstallInfo(in as files, + in t flags, + out b carries_install_info, + out a(sss) changes); + ReenableUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + LinkUnitFiles(in as files, + in b runtime, + in b force, + out a(sss) changes); + PresetUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + PresetUnitFilesWithMode(in as files, + in s mode, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + MaskUnitFiles(in as files, + in b runtime, + in b force, + out a(sss) changes); + UnmaskUnitFiles(in as files, + in b runtime, + out a(sss) changes); + RevertUnitFiles(in as files, + out a(sss) changes); + SetDefaultTarget(in s name, + in b force, + out a(sss) changes); + GetDefaultTarget(out s name); + PresetAllUnitFiles(in s mode, + in b runtime, + in b force, + out a(sss) changes); + AddDependencyUnitFiles(in as files, + in s target, + in s type, + in b runtime, + in b force, + out a(sss) changes); + GetUnitFileLinks(in s name, + in b runtime, + out as links); + SetExitCode(in y number); + LookupDynamicUserByName(in s name, + out u uid); + LookupDynamicUserByUID(in u uid, + out s name); + GetDynamicUsers(out a(us) users); + DumpUnitFileDescriptorStore(in s name, + out a(suuutuusu) entries); + signals: + UnitNew(s id, + o unit); + UnitRemoved(s id, + o unit); + JobNew(u id, + o job, + s unit); + JobRemoved(u id, + o job, + s unit, + s result); + StartupFinished(t firmware, + t loader, + t kernel, + t initrd, + t userspace, + t total); + UnitFilesChanged(); + Reloading(b active); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Version = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Features = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Virtualization = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ConfidentialVirtualization = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Architecture = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Tainted = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t FirmwareTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t FirmwareTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LoaderTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LoaderTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t KernelTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t KernelTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UserspaceTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UserspaceTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t FinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t FinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t SecurityStartTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t SecurityStartTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t SecurityFinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t SecurityFinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t GeneratorsStartTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t GeneratorsStartTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t GeneratorsFinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t GeneratorsFinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UnitsLoadStartTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UnitsLoadStartTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UnitsLoadFinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UnitsLoadFinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UnitsLoadTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t UnitsLoadTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDSecurityStartTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDSecurityStartTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDSecurityFinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDSecurityFinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDGeneratorsStartTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDGeneratorsStartTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDGeneratorsFinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDGeneratorsFinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDUnitsLoadStartTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDUnitsLoadStartTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDUnitsLoadFinishTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t InitRDUnitsLoadFinishTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite s LogLevel = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite s LogTarget = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NNames = \&.\&.\&.; + readonly u NFailedUnits = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NJobs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NInstalledJobs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NFailedJobs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly d Progress = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as Environment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ConfirmSpawn = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b ShowStatus = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as UnitPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s DefaultStandardOutput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s DefaultStandardError = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s WatchdogDevice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t WatchdogLastPingTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t WatchdogLastPingTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite t RuntimeWatchdogUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite t RuntimeWatchdogPreUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite s RuntimeWatchdogPreGovernor = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite t RebootWatchdogUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite t KExecWatchdogUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + @org\&.freedesktop\&.systemd1\&.Privileged("true") + readwrite b ServiceWatchdogs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s SystemState = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly y ExitCode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultTimerAccuracyUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultTimeoutStartUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultTimeoutStopUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultTimeoutAbortUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultDeviceTimeoutUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultRestartUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultStartLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u DefaultStartLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultCPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultBlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultIPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultMemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultTasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitCPU = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitCPUSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitFSIZE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitFSIZESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitDATA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitDATASoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitSTACK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitSTACKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitCORE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitCORESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitRSS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitRSSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitNOFILE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitNOFILESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitAS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitASSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitNPROC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitNPROCSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitMEMLOCK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitMEMLOCKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitLOCKS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitLOCKSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitSIGPENDING = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitSIGPENDINGSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitMSGQUEUE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitMSGQUEUESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitNICE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitNICESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitRTPRIO = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitRTPRIOSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitRTTIME = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DefaultLimitRTTIMESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultTasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DefaultMemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimerSlackNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s DefaultOOMPolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i DefaultOOMScoreAdjust = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s CtrlAltDelBurstAction = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +Note that many of the methods exist twice: once on the +Manager +object and once on the respective unit objects\&. This is to optimize access times so that methods that belong to unit objects do not have to be called with a resolved unit path, but can be called with only the unit id, too\&. +.PP +\fBGetUnit()\fR +may be used to get the unit object path for a unit name\&. It takes the unit name and returns the object path\&. If a unit has not been loaded yet by this name this method will fail\&. +.PP +\fBGetUnitByPID()\fR +may be used to get the unit object path of the unit a process ID belongs to\&. It takes a UNIX PID and returns the object path\&. The PID must refer to an existing system process\&. +\fBGetUnitByPIDFD()\fR +may be used to query with a Linux PIDFD (see: +\fBpidfd_open\fR(2)) instead of a PID, which is safer as UNIX PIDs can be recycled\&. The latter method returns the unit id and the invocation id together with the unit object path\&. +.PP +\fBLoadUnit()\fR +is similar to +\fBGetUnit()\fR +but will load the unit from disk if possible\&. +.PP +\fBStartUnit()\fR +enqueues a start job and possibly depending jobs\&. It takes the unit to activate and a mode string as arguments\&. The mode needs to be one of +"replace", +"fail", +"isolate", +"ignore\-dependencies", or +"ignore\-requirements"\&. If +"replace", the method will start the unit and its dependencies, possibly replacing already queued jobs that conflict with it\&. If +"fail", the method will start the unit and its dependencies, but will fail if this would change an already queued job\&. If +"isolate", the method will start the unit in question and terminate all units that aren\*(Aqt dependencies of it\&. If +"ignore\-dependencies", it will start a unit but ignore all its dependencies\&. If +"ignore\-requirements", it will start a unit but only ignore the requirement dependencies\&. It is not recommended to make use of the latter two options\&. On completion, this method returns the newly created job object\&. +.PP +\fBStartUnitReplace()\fR +is similar to +\fBStartUnit()\fR +but replaces a job that is queued for one unit by a job for another unit\&. +.PP +\fBStartUnitWithFlags()\fR +is similar to +\fBStartUnit()\fR +but allows the caller to pass an extra +\fIflags\fR +parameter, which does not support any flags for now, and is reserved for future extensions\&. +.PP +\fBStopUnit()\fR +is similar to +\fBStartUnit()\fR +but stops the specified unit rather than starting it\&. Note that the +"isolate" +mode is invalid for this method\&. +.PP +\fBReloadUnit()\fR, +\fBRestartUnit()\fR, +\fBTryRestartUnit()\fR, +\fBReloadOrRestartUnit()\fR, or +\fBReloadOrTryRestartUnit()\fR +may be used to restart and/or reload a unit\&. These methods take similar arguments as +\fBStartUnit()\fR\&. Reloading is done only if the unit is already running and fails otherwise\&. If a service is restarted that isn\*(Aqt running, it will be started unless the "Try" flavor is used in which case a service that isn\*(Aqt running is not affected by the restart\&. The "ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise\&. +.PP +\fBEnqueueMarkedJobs()\fR +creates reload/restart jobs for units which have been appropriately marked, see +\fIMarkers\fR +property above\&. This is equivalent to calling +\fBTryRestartUnit()\fR +or +\fBReloadOrTryRestartUnit()\fR +for the marked units\&. +.PP +\fBBindMountUnit()\fR +can be used to bind mount new files or directories into a running service mount namespace\&. If supported by the kernel, any prior mount on the selected target will be replaced by the new mount\&. If not supported, any prior mount will be over\-mounted, but remain pinned and inaccessible\&. +.PP +\fBMountImageUnit()\fR +can be used to mount new images into a running service mount namespace\&. If supported by the kernel, any prior mount on the selected target will be replaced by the new mount\&. If not supported, any prior mount will be over\-mounted, but remain pinned and inaccessible\&. +.PP +\fBKillUnit()\fR +may be used to kill (i\&.e\&. send a signal to) all processes of a unit\&. It takes the unit +\fIname\fR, an enum +\fIwho\fR +and a UNIX +\fIsignal\fR +number to send\&. The +\fIwho\fR +enum is one of +"main", +"control" +or +"all"\&. If +"main", only the main process of the unit is killed\&. If +"control", only the control process of the unit is killed\&. If +"all", all processes are killed\&. A +"control" +process is for example a process that is configured via +\fIExecStop=\fR +and is spawned in parallel to the main daemon process in order to shut it down\&. +.PP +\fBQueueSignalUnit()\fR +is similar to +\fBKillUnit()\fR +but may be used to enqueue a POSIX Realtime Signal (i\&.e\&. +\fBSIGRTMIN+\&...\fR +and +\fBSIGRTMAX\-\&...\fR) to the selected process(es)\&. Takes the same parameters as +\fBKillUnit()\fR +with one additional argument: an integer that is passed in the +\fIsival_int\fR +value accompanying the queued signal\&. See +\fBsigqueue\fR(3) +for details\&. +.PP +\fBGetJob()\fR +returns the job object path for a specific job, identified by its id\&. +.PP +\fBCancelJob()\fR +cancels a specific job identified by its numeric ID\&. This operation is also available in the +\fBCancel()\fR +method of Job objects (see below) and exists primarily to reduce the necessary round trips to execute this operation\&. Note that this will not have any effect on jobs whose execution has already begun\&. +.PP +\fBClearJobs()\fR +flushes the job queue, removing all jobs that are still queued\&. Note that this does not have any effect on jobs whose execution has already begun\&. It only flushes jobs that are queued and have not yet begun execution\&. +.PP +\fBResetFailedUnit()\fR +resets the "failed" state of a specific unit\&. +.PP +\fBResetFailed()\fR +resets the "failed" state of all units\&. +.PP +\fBListUnits()\fR +returns an array of all currently loaded units\&. Note that units may be known by multiple names at the same time, and hence there might be more unit names loaded than actual units behind them\&. The array consists of structures with the following elements: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The primary unit name as string +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The human readable description string +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The load state (i\&.e\&. whether the unit file has been loaded successfully) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The active state (i\&.e\&. whether the unit is currently started or not) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The sub state (a more fine\-grained version of the active state that is specific to the unit type, which the active state is not) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A unit that is being followed in its state by this unit, if there is any, otherwise the empty string\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The unit object path +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If there is a job queued for the job unit, the numeric job id, 0 otherwise +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The job type as string +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The job object path +.RE +.PP +\fBListJobs()\fR +returns an array with all currently queued jobs\&. Returns an array consisting of structures with the following elements: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The numeric job id +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The primary unit name for this job +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The job type as string +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The job state as string +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The job object path +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The unit object path +.RE +.PP +\fBSubscribe()\fR +enables most bus signals to be sent out\&. Clients which are interested in signals need to call this method\&. Signals are only sent out if at least one client invoked this method\&. +\fBUnsubscribe()\fR +reverts the signal subscription that +\fBSubscribe()\fR +implements\&. It is not necessary to invoke +\fBUnsubscribe()\fR +as clients are tracked\&. Signals are no longer sent out as soon as all clients which previously asked for +\fBSubscribe()\fR +either closed their connection to the bus or invoked +\fBUnsubscribe()\fR\&. +.PP +\fBDump()\fR +returns a text dump of the internal service manager state\&. This is a privileged, low\-level debugging interface only\&. The returned string is supposed to be readable exclusively by developers, and not programmatically\&. There\*(Aqs no interface stability on the returned string guaranteed, and new fields may be added any time, and old fields removed\&. The general structure may be rearranged drastically between releases\&. This is exposed by +\fBsystemd-analyze\fR(1)\*(Aqs +\fBdump\fR +command\&. Similarly, +\fBDumpUnitsMatchingPatterns()\fR +returns the internal state of units whose names match the glob expressions specified in the +\fIpatterns\fR +argument\&. The +\fBDumpByFileDescriptor()\fR/\fBDumpUnitsMatchingPatternsByFileDescriptor()\fR +methods are identical to +\fBDump()\fR/\fBDumpUnitsMatchingPatterns()\fR, but return data serialized into a file descriptor (the client should read the text data from it until hitting EOF)\&. Given the size limits on D\-Bus messages and the possibly large size of the returned strings, +\fBDumpByFileDescriptor()\fR/\fBDumpUnitsMatchingPatternsByFileDescriptor()\fR +are usually the preferred interface, since it ensures the data can be passed reliably from the service manager to the client\&. Note though that they cannot work when communicating with the service manager remotely, as file descriptors are strictly local to a system\&. All the +\fBDump*()\fR +methods are rate limited for unprivileged users\&. +.PP +\fBReload()\fR +may be invoked to reload all unit files\&. +.PP +\fBReexecute()\fR +may be invoked to reexecute the main manager process\&. It will serialize its state, reexecute, and deserizalize the state again\&. This is useful for upgrades and is a more comprehensive version of +\fBReload()\fR\&. +.PP +\fBExit()\fR +may be invoked to ask the manager to exit\&. This is not available for the system manager and is useful only for user session managers\&. +.PP +\fBReboot()\fR, +\fBPowerOff()\fR, +\fBHalt()\fR, +\fBKExec()\fR +and +\fBSoftReboot()\fR +may be used to ask for immediate reboot, powering down, halt, kexec based reboot, or soft reboot of the system\&. Note that this does not shut down any services and immediately transitions into the later shutdown operation\&. These functions are normally only called as the last step of shutdown and should not be called directly\&. To shut down the machine, it is generally a better idea to invoke +\fBReboot()\fR, +\fBRebootWithFlags()\fR +or +\fBPowerOff()\fR +on the +systemd\-logind +manager object; see +\fBorg.freedesktop.login1\fR(5) +for more information\&. +\fBSoftReboot()\fR +accepts an argument indicating the path for the root file system to activate for the next boot cycle\&. If an empty string is specified the +/run/nextroot/ +path is used if it exists\&. +.PP +\fBSwitchRoot()\fR +may be used to transition to a new root directory\&. This is intended to be used in the initrd, and also to transition from the host system into a shutdown initrd\&. The method takes two arguments: the new root directory (which needs to be specified) and an init binary path (which may be left empty, in which case it is automatically searched for)\&. The state of the system manager will be serialized before the transition\&. After the transition, the manager binary on the main system is invoked and replaces the old PID 1\&. All state will then be deserialized\&. +.PP +\fBSetEnvironment()\fR +may be used to alter the environment block that is passed to all spawned processes\&. It takes a string array of environment variable assignments\&. Any previously set environment variables will be overridden\&. +.PP +\fBUnsetEnvironment()\fR +may be used to unset environment variables\&. It takes a string array of environment variable names\&. All variables specified will be unset (if they have been set previously) and no longer be passed to all spawned processes\&. This method has no effect for variables that were previously not set, but will not fail in that case\&. +.PP +\fBUnsetAndSetEnvironment()\fR +is a combination of +\fBUnsetEnvironment()\fR +and +\fBSetEnvironment()\fR\&. It takes two lists\&. The first list contains variables to unset, the second one contains assignments to set\&. If a variable is listed in both, the variable is set after this method returns, i\&.e\&. the set list overrides the unset list\&. +.PP +\fBListUnitFiles()\fR +returns an array of unit names and their enablement status\&. Note that +\fBListUnit()\fR +returns a list of units currently loaded into memory, while +\fBListUnitFiles()\fR +returns a list of unit +\fIfiles\fR +that were found on disk\&. Note that while most units are read directly from a unit file with the same name, some units are not backed by files and some files (templates) cannot directly be loaded as units but need to be instantiated instead\&. +.PP +\fBGetUnitFileState()\fR +returns the current enablement status of a specific unit file\&. +.PP +\fBEnableUnitFiles()\fR +may be used to enable one or more units in the system (by creating symlinks to them in +/etc/ +or +/run/)\&. It takes a list of unit files to enable (either just file names or full absolute paths if the unit files are residing outside the usual unit search paths) and two booleans: the first controls whether the unit shall be enabled for runtime only (true, +/run/), or persistently (false, +/etc/)\&. The second one controls whether symlinks pointing to other units shall be replaced if necessary\&. This method returns one boolean and an array of the changes made\&. The boolean signals whether the unit files contained any enablement information (i\&.e\&. an [Install] section)\&. The changes array consists of structures with three strings: the type of the change (one of +"symlink" +or +"unlink"), the file name of the symlink and the destination of the symlink\&. Note that most of the following calls return a changes list in the same format\&. +.PP +Similarly, +\fBDisableUnitFiles()\fR +disables one or more units in the system, i\&.e\&. removes all symlinks to them in +/etc/ +and +/run/\&. +.PP +The +\fBEnableUnitFilesWithFlags()\fR +and +\fBDisableUnitFilesWithFlags()\fR +take in options as flags instead of booleans to allow for extendability, defined as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#define SD_SYSTEMD_UNIT_RUNTIME (UINT64_C(1) << 0) +#define SD_SYSTEMD_UNIT_FORCE (UINT64_C(1) << 1) +#define SD_SYSTEMD_UNIT_PORTABLE (UINT64_C(1) << 2) + +.fi +.if n \{\ +.RE +.\} +.PP +\fISD_SYSTEMD_UNIT_RUNTIME\fR +will enable or disable the unit for runtime only, +\fISD_SYSTEMD_UNIT_FORCE\fR +controls whether symlinks pointing to other units shall be replaced if necessary\&. +\fISD_SYSTEMD_UNIT_PORTABLE\fR +will add or remove the symlinks in +/etc/systemd/system\&.attached +and +/run/systemd/system\&.attached\&. +.PP +\fBDisableUnitFilesWithFlagsAndInstallInfo()\fR +is similar to +\fBDisableUnitFilesWithFlags()\fR +and takes the same arguments, but returns a boolean to indicate whether the unit files contain any enablement information, like +\fBEnableUnitFiles()\fR\&. The changes made are still returned in an array\&. +.PP +Similarly, +\fBReenableUnitFiles()\fR +applies the changes to one or more units that would result from disabling and enabling the unit quickly one after the other in an atomic fashion\&. This is useful to apply updated [Install] information contained in unit files\&. +.PP +Similarly, +\fBLinkUnitFiles()\fR +links unit files (that are located outside of the usual unit search paths) into the unit search path\&. +.PP +Similarly, +\fBPresetUnitFiles()\fR +enables/disables one or more unit files according to the preset policy\&. See +\fBsystemd.preset\fR(7) +for more information\&. +.PP +Similarly, +\fBMaskUnitFiles()\fR +masks unit files and +\fBUnmaskUnitFiles()\fR +unmasks them again\&. +.PP +\fBSetDefaultTarget()\fR +changes the +default\&.target +link\&. See +\fBbootup\fR(7) +for more information\&. +.PP +\fBGetDefaultTarget()\fR +retrieves the name of the unit to which +default\&.target +is aliased\&. +.PP +\fBSetUnitProperties()\fR +may be used to modify certain unit properties at runtime\&. Not all properties may be changed at runtime, but many resource management settings (primarily those listed in +\fBsystemd.resource-control\fR(5)) may\&. The changes are applied instantly and stored on disk for future boots, unless +\fIruntime\fR +is true, in which case the settings only apply until the next reboot\&. +\fIname\fR +is the name of the unit to modify\&. +\fIproperties\fR +are the settings to set, encoded as an array of property name and value pairs\&. Note that this is not a dictionary! Also note that when setting array properties with this method usually results in appending to the pre\-configured array\&. To reset the configured arrays, set the property to an empty array first and then append to it\&. +.PP +\fBStartTransientUnit()\fR +may be used to create and start a transient unit which will be released as soon as it is not running or referenced anymore or the system is rebooted\&. +\fIname\fR +is the unit name including its suffix and must be unique\&. +\fImode\fR +is the same as in +\fBStartUnit()\fR, +\fIproperties\fR +contains properties of the unit, specified like in +\fBSetUnitProperties()\fR\&. +\fIaux\fR +is currently unused and should be passed as an empty array\&. See the +\m[blue]\fBNew Control Group Interface\fR\m[]\&\s-2\u[2]\d\s+2 +for more information how to make use of this functionality for resource control purposes\&. +.PP +\fBDumpUnitFileDescriptorStore()\fR +returns an array with information about the file descriptors currently in the file descriptor store of the specified unit\&. This call is equivalent to +\fBDumpFileDescriptorStore()\fR +on the +org\&.freedesktop\&.systemd1\&.Service\&. For further details, see below\&. +.SS "Signals" +.PP +Note that most signals are sent out only after +\fBSubscribe()\fR +has been invoked by at least one client\&. Make sure to invoke this method when subscribing to these signals! +.PP +\fBUnitNew()\fR +and +\fBUnitRemoved()\fR +are sent out each time a new unit is loaded or unloaded\&. Note that this has little to do with whether a unit is available on disk or not, and simply reflects the units that are currently loaded into memory\&. The signals take two parameters: the primary unit name and the object path\&. +.PP +\fBJobNew()\fR +and +\fBJobRemoved()\fR +are sent out each time a new job is queued or dequeued\&. Both signals take the numeric job ID, the bus path and the primary unit name for this job as arguments\&. +\fBJobRemoved()\fR +also includes a result string which is one of +"done", +"canceled", +"timeout", +"failed", +"dependency", or +"skipped"\&. +"done" +indicates successful execution of a job\&. +"canceled" +indicates that a job has been canceled (via +\fBCancelJob()\fR +above) before it finished execution (this doesn\*(Aqt necessarily mean though that the job operation is actually cancelled too, see above)\&. +"timeout" +indicates that the job timeout was reached\&. +"failed" +indicates that the job failed\&. +"dependency" +indicates that a job this job depended on failed and the job hence was removed as well\&. +"skipped" +indicates that a job was skipped because it didn\*(Aqt apply to the unit\*(Aqs current state\&. +.PP +\fBStartupFinished()\fR +is sent out when startup finishes\&. It carries six microsecond timespan values, each indicating how much boot time has been spent in the firmware (if known), in the boot loader (if known), in the kernel initialization phase, in the initrd (if known), in userspace and in total\&. These values may also be calculated from the +\fIFirmwareTimestampMonotonic\fR, +\fILoaderTimestampMonotonic\fR, +\fIInitRDTimestampMonotonic\fR, +\fIUserspaceTimestampMonotonic\fR, and +\fIFinishTimestampMonotonic\fR +properties (see below)\&. +.PP +\fBUnitFilesChanged()\fR +is sent out each time the list of enabled or masked unit files on disk have changed\&. +.PP +\fBReloading()\fR +is sent out immediately before a daemon reload is done (with the boolean parameter set to True) and after a daemon reload is completed (with the boolean parameter set to False)\&. This may be used by UIs to optimize UI updates\&. +.SS "Properties" +.PP +Most properties simply reflect the respective options in +/etc/systemd/system\&.conf +and the kernel command line\&. +.PP +The others: +.PP +\fIVersion\fR +encodes the version string of the running systemd instance\&. Note that the version string is purely informational\&. It should not be parsed and one may not assume the version to be formatted in any particular way\&. We take the liberty to change the versioning scheme at any time and it is not part of the public API\&. +.PP +\fIFeatures\fR +encodes the features that have been enabled and disabled for this build\&. Enabled options are prefixed with +"+", disabled options with +"\-"\&. +.PP +\fITainted\fR +encodes taint flags as a colon\-separated list\&. When systemd detects it is running on a system with a certain problem, it will set an appropriate taint flag\&. Taints may be used to lower the chance of bogus bug reports\&. The following taints are currently known: +.PP +"unmerged\-usr" +.RS 4 +/bin, +/sbin +and +/lib* +are not symlinks to their counterparts under +/usr/\&. For more information on this issue consult +\m[blue]\fBThe Case for the /usr Merge\fR\m[]\&\s-2\u[3]\d\s+2\&. +.sp +Added in version 252\&. +.RE +.PP +"cgroups\-missing" +.RS 4 +Support for cgroups is unavailable\&. +.sp +Added in version 252\&. +.RE +.PP +"cgroupsv1" +.RS 4 +The system is using the old cgroup hierarchy\&. +.sp +Added in version 252\&. +.RE +.PP +"local\-hwclock" +.RS 4 +The local hardware clock (RTC) is configured to be in local time rather than UTC\&. +.sp +Added in version 252\&. +.RE +.PP +"support\-ended" +.RS 4 +The system is running past the end of support declared by the vendor\&. See the description of +\fISUPPORT_END=\fR +in +\fBos-release\fR(5)\&. +.sp +Added in version 252\&. +.RE +.PP +"old\-kernel" +.RS 4 +The system is running a kernel version that is older than the minimum supported by this version of systemd\&. +.sp +Added in version 252\&. +.RE +.PP +"var\-run\-bad" +.RS 4 +/run/ +does not exist or +/var/run +is not a symlink to +/run/\&. +.sp +Added in version 252\&. +.RE +.PP +"overflowuid\-not\-65534", "overflowgid\-not\-65534" +.RS 4 +The kernel overflow UID or GID have a value other than 65534\&. +.sp +Added in version 252\&. +.RE +.PP +"short\-uid\-range", "short\-gid\-range" +.RS 4 +The UID or GID range assigned to the running systemd instance covers less than 0\&...65534\&. +.sp +Added in version 252\&. +.RE +.PP +\fIFirmwareTimestamp\fR, +\fIFirmwareTimestampMonotonic\fR, +\fILoaderTimestamp\fR, +\fILoaderTimestampMonotonic\fR, +\fIKernelTimestamp\fR, +\fIKernelTimestampMonotonic\fR, +\fIInitRDTimestamp\fR, +\fIInitRDTimestampMonotonic\fR, +\fIUserspaceTimestamp\fR, +\fIUserspaceTimestampMonotonic\fR, +\fIFinishTimestamp\fR, and +\fIFinishTimestampMonotonic\fR +encode +\fBCLOCK_REALTIME\fR +and +\fBCLOCK_MONOTONIC\fR +microsecond timestamps taken when the firmware first began execution, when the boot loader first began execution, when the kernel first began execution, when the initrd first began execution, when the main systemd instance began execution and finally, when all queued startup jobs finished execution\&. These values are useful for determining boot\-time performance\&. Note that as monotonic time begins with the kernel startup, the +\fIKernelTimestampMonotonic\fR +timestamp will always be 0 and +\fIFirmwareTimestampMonotonic\fR +and +\fILoaderTimestampMonotonic\fR +are to be read as negative values\&. Also, not all fields are always available, depending on the used firmware, boot loader or initrd implementation\&. In these cases the respective pairs of timestamps are both 0, indicating that no data is available\&. +.PP +\fIUnitsLoadTimestamp\fR +and +\fIUnitsLoadTimestampMonotonic\fR +encode +\fBCLOCK_REALTIME\fR +and +\fBCLOCK_MONOTONIC\fR +microseconds timestamps (as described above)\&. The timestamps are taken every time when the manager starts loading unit files\&. +.PP +Similarly, the +\fISecurityStartTimestamp\fR, +\fIGeneratorsStartTimestamp\fR +and +\fILoadUnitTimestamp\fR +(as well as their monotonic and stop counterparts) expose performance data for uploading the security policies to the kernel (such as the SELinux, IMA, or SMACK policies), for running the generator tools and for loading the unit files\&. +.PP +\fINNames\fR +encodes how many unit names are currently known\&. This only includes names of units that are currently loaded and can be more than the amount of actually loaded units since units may have more than one name\&. +.PP +\fINJobs\fR +encodes how many jobs are currently queued\&. +.PP +\fINInstalledJobs\fR +encodes how many jobs have ever been queued in total\&. +.PP +\fINFailedJobs\fR +encodes how many jobs have ever failed in total\&. +.PP +\fIProgress\fR +encodes boot progress as a floating point value between 0\&.0 and 1\&.0\&. This value begins at 0\&.0 at early\-boot and ends at 1\&.0 when boot is finished and is based on the number of executed and queued jobs\&. After startup, this field is always 1\&.0 indicating a finished boot\&. +.PP +\fIEnvironment\fR +encodes the environment block passed to all executed services\&. It may be altered with bus calls such as +\fBSetEnvironment()\fR +(see above)\&. +.PP +\fIUnitPath\fR +encodes the currently active unit file search path\&. It is an array of file system paths encoded as strings\&. +.PP +\fIVirtualization\fR +contains a short ID string describing the virtualization technology the system runs in\&. On bare\-metal hardware this is the empty string\&. Otherwise, it contains an identifier such as +"kvm", +"vmware" +and so on\&. For a full list of IDs see +\fBsystemd-detect-virt\fR(1)\&. Note that only the "innermost" virtualization technology is exported here\&. This detects both full\-machine virtualizations (VMs) and shared\-kernel virtualization (containers)\&. +.PP +\fIConfidentialVirtualization\fR +contains a short ID string describing the confidential virtualization technology the system runs in\&. On bare\-metal hardware this is the empty string\&. Otherwise, it contains an identifier such as +"sev", +"sev\-es", +"sev\-snp", +"tdx" +and so on\&. For a full list of IDs see +\fBsystemd-detect-virt\fR(1) +\&. + + .PP +\fIArchitecture\fR +contains a short ID string describing the architecture the systemd instance is running on\&. This follows the same vocabulary as +\fIConditionArchitectures=\fR\&. +.PP +\fIControlGroup\fR +contains the root control group path of this system manager\&. Note that the root path is encoded as the empty string here (not as +"/"!), so that it can be appended to +/sys/fs/cgroup/systemd +easily\&. This value will be set to the empty string for the host instance and some other string for container instances\&. +.PP +\fIAccessSELinuxContext\fR +contains the SELinux context that is used to control access to the unit\&. It\*(Aqs read from the unit file when it is loaded and cached until the service manager is reloaded\&. This property contains an empty string if SELinux is not used or if no label could be read (for example because the unit is not backed by a file on disk)\&. +.PP +\fISystemState\fR +contains the current state of the system manager\&. The possible values are: +.PP +"initializing" +.RS 4 +The system is booting, and +basic\&.target +has not been reached yet\&. +.RE +.PP +"starting" +.RS 4 +The system is booting, and +basic\&.target +has been reached\&. +.RE +.PP +"running" +.RS 4 +The system has finished booting, and no units are in the failed state\&. +.RE +.PP +"degraded" +.RS 4 +The system has finished booting, but some units are in the failed state\&. +.RE +.PP +"maintenance" +.RS 4 +The system has finished booting, but it has been put in rescue or maintenance mode\&. +.RE +.PP +"stopping" +.RS 4 +The system is shutting down\&. +.RE +.SS "Security" +.PP +Read access is generally granted to all clients\&. Additionally, for unprivileged clients, some operations are allowed through the polkit privilege system\&. Operations which modify unit state (\fBStartUnit()\fR, +\fBStopUnit()\fR, +\fBKillUnit()\fR, +\fBQueueSignalUnit()\fR, +\fBRestartUnit()\fR +and similar, +\fBSetProperty()\fR) require +org\&.freedesktop\&.systemd1\&.manage\-units\&. Operations which modify unit file enablement state (\fBEnableUnitFiles()\fR, +\fBDisableUnitFiles()\fR, +\fBEnableUnitFilesWithFlags()\fR, +\fBDisableUnitFilesWithFlags()\fR, +\fBReenableUnitFiles()\fR, +\fBLinkUnitFiles()\fR, +\fBPresetUnitFiles\fR, +\fBMaskUnitFiles\fR, and similar) require +org\&.freedesktop\&.systemd1\&.manage\-unit\-files\&. Operations which modify the exported environment (\fBSetEnvironment()\fR, +\fBUnsetEnvironment()\fR, +\fBUnsetAndSetEnvironment()\fR) require +org\&.freedesktop\&.systemd1\&.set\-environment\&. +\fBReload()\fR +and +\fBReexecute()\fR +require +org\&.freedesktop\&.systemd1\&.reload\-daemon\&. Operations which dump internal state require +org\&.freedesktop\&.systemd1\&.bypass\-dump\-ratelimit +to avoid rate limits\&. +.SH "UNIT OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + interface org\&.freedesktop\&.systemd1\&.Unit { + methods: + Start(in s mode, + out o job); + Stop(in s mode, + out o job); + Reload(in s mode, + out o job); + Restart(in s mode, + out o job); + TryRestart(in s mode, + out o job); + ReloadOrRestart(in s mode, + out o job); + ReloadOrTryRestart(in s mode, + out o job); + EnqueueJob(in s job_type, + in s job_mode, + out u job_id, + out o job_path, + out s unit_id, + out o unit_path, + out s job_type, + out a(uosos) affected_jobs); + Kill(in s whom, + in i signal); + QueueSignal(in s whom, + in i signal, + in i value); + ResetFailed(); + SetProperties(in b runtime, + in a(sv) properties); + Ref(); + Unref(); + Clean(in as mask); + Freeze(); + Thaw(); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Id = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Names = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Following = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Requires = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Requisite = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Wants = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as BindsTo = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PartOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Upholds = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RequiredBy = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RequisiteOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as WantedBy = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as BoundBy = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as UpheldBy = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ConsistsOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Conflicts = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ConflictedBy = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Before = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as After = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as OnSuccess = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as OnSuccessOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as OnFailure = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as OnFailureOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Triggers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as TriggeredBy = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PropagatesReloadTo = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReloadPropagatedFrom = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PropagatesStopTo = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as StopPropagatedFrom = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as JoinsNamespaceOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SliceOf = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RequiresMountsFor = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Documentation = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Description = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s AccessSELinuxContext = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s LoadState = \*(Aq\&.\&.\&.\*(Aq; + readonly s ActiveState = \*(Aq\&.\&.\&.\*(Aq; + readonly s FreezerState = \*(Aq\&.\&.\&.\*(Aq; + readonly s SubState = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s FragmentPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SourcePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as DropInPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s UnitFileState = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s UnitFilePreset = \*(Aq\&.\&.\&.\*(Aq; + readonly t StateChangeTimestamp = \&.\&.\&.; + readonly t StateChangeTimestampMonotonic = \&.\&.\&.; + readonly t InactiveExitTimestamp = \&.\&.\&.; + readonly t InactiveExitTimestampMonotonic = \&.\&.\&.; + readonly t ActiveEnterTimestamp = \&.\&.\&.; + readonly t ActiveEnterTimestampMonotonic = \&.\&.\&.; + readonly t ActiveExitTimestamp = \&.\&.\&.; + readonly t ActiveExitTimestampMonotonic = \&.\&.\&.; + readonly t InactiveEnterTimestamp = \&.\&.\&.; + readonly t InactiveEnterTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CanStart = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CanStop = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CanReload = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CanIsolate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as CanClean = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CanFreeze = \&.\&.\&.; + readonly (uo) Job = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b StopWhenUnneeded = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RefuseManualStart = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RefuseManualStop = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b AllowIsolate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DefaultDependencies = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SurviveFinalKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s OnSuccessJobMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s OnFailureJobMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b IgnoreOnIsolate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b NeedDaemonReload = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as Markers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t JobTimeoutUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t JobRunningTimeoutUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s JobTimeoutAction = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s JobTimeoutRebootArgument = \*(Aq\&.\&.\&.\*(Aq; + readonly b ConditionResult = \&.\&.\&.; + readonly b AssertResult = \&.\&.\&.; + readonly t ConditionTimestamp = \&.\&.\&.; + readonly t ConditionTimestampMonotonic = \&.\&.\&.; + readonly t AssertTimestamp = \&.\&.\&.; + readonly t AssertTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sbbsi) Conditions = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sbbsi) Asserts = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (ss) LoadError = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Transient = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Perpetual = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t StartLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u StartLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StartLimitAction = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s FailureAction = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i FailureActionExitStatus = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SuccessAction = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SuccessActionExitStatus = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RebootArgument = \*(Aq\&.\&.\&.\*(Aq; + readonly ay InvocationID = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s CollectMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as Refs = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + readonly a(ss) ActivationDetails = [\&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBStart()\fR, +\fBStop()\fR, +\fBReload()\fR, +\fBRestart()\fR, +\fBTryRestart()\fR, +\fBReloadOrRestart()\fR, +\fBReloadOrTryRestart()\fR, +\fBKill()\fR, +\fBQueueSignal()\fR, +\fBResetFailed()\fR, and +\fBSetProperties()\fR +implement the same operation as the respective methods on the +Manager +object (see above)\&. However, these methods operate on the unit object and hence do not take a unit name parameter\&. Invoking the methods directly on the Manager object has the advantage of not requiring a +\fBGetUnit()\fR +call to get the unit object for a specific unit name\&. Calling the methods on the Manager object is hence a round trip optimization\&. +.SS "Properties" +.PP +\fIId\fR +contains the primary name of the unit\&. +.PP +\fINames\fR +contains all names of the unit, including the primary name that is also exposed in +\fIId\fR\&. +.PP +\fIFollowing\fR +either contains the empty string or contains the name of another unit that this unit follows in state\&. This is used for some device units which reflect the unit state machine of another unit, and which other unit this is might possibly change\&. +.PP +\fIRequires\fR, +\fIRequiresOverridable\fR, +\fIRequisite\fR, +\fIRequisiteOverridable\fR, +\fIWants\fR, +\fIBindsTo\fR, +\fIRequiredBy\fR, +\fIRequiredByOverridable\fR, +\fIWantedBy\fR, +\fIBoundBy\fR, +\fIConflicts\fR, +\fIConflictedBy\fR, +\fIBefore\fR, +\fIAfter\fR, +\fIOnFailure\fR, +\fITriggers\fR, +\fITriggeredBy\fR, +\fIPropagatesReloadTo\fR, and +\fIRequiresMountsFor\fR +contain arrays which encode the dependencies and their inverse dependencies (where this applies) as configured in the unit file or determined automatically\&. +.PP +\fIDescription\fR +contains the human readable description string for the unit\&. +.PP +\fISourcePath\fR +contains the path to a configuration file this unit is automatically generated from in case it is not a native unit (in which case it contains the empty string)\&. For example, all mount units generated from +/etc/fstab +have this field set to +/etc/fstab\&. +.PP +\fIDocumentation\fR +contains a string array with URLs of documentation for this unit\&. +.PP +\fILoadState\fR +contains a state value that reflects whether the configuration file of this unit has been loaded\&. The following states are currently defined: +"loaded", +"error", and +"masked"\&. +"loaded" +indicates that the configuration was successfully loaded\&. +"error" +indicates that the configuration failed to load\&. The +\fILoadError\fR +field (see below) contains information about the cause of this failure\&. +"masked" +indicates that the unit is currently masked out (i\&.e\&. symlinked to +/dev/null +or empty)\&. Note that the +\fILoadState\fR +is fully orthogonal to the +\fIActiveState\fR +(see below) as units without valid loaded configuration might be active (because configuration might have been reloaded at a time where a unit was already active)\&. +.PP +\fIActiveState\fR +contains a state value that reflects whether the unit is currently active or not\&. The following states are currently defined: +"active", +"reloading", +"inactive", +"failed", +"activating", and +"deactivating"\&. +"active" +indicates that unit is active (obviously\&.\&.\&.)\&. +"reloading" +indicates that the unit is active and currently reloading its configuration\&. +"inactive" +indicates that it is inactive and the previous run was successful or no previous run has taken place yet\&. +"failed" +indicates that it is inactive and the previous run was not successful (more information about the reason for this is available on the unit type specific interfaces, for example for services in the +\fIResult\fR +property, see below)\&. +"activating" +indicates that the unit has previously been inactive but is currently in the process of entering an active state\&. Conversely +"deactivating" +indicates that the unit is currently in the process of deactivation\&. +.PP +\fISubState\fR +encodes states of the same state machine that +\fIActiveState\fR +covers, but knows more fine\-grained states that are unit\-type\-specific\&. Where +\fIActiveState\fR +only covers six high\-level states, +\fISubState\fR +covers possibly many more low\-level unit\-type\-specific states that are mapped to the six high\-level states\&. Note that multiple low\-level states might map to the same high\-level state, but not vice versa\&. Not all high\-level states have low\-level counterparts on all unit types\&. At this point the low\-level states are not documented here, and are more likely to be extended later on than the common high\-level states explained above\&. +.PP +\fIFragmentPath\fR +contains the unit file path this unit was read from, if there is one (if not, it contains the empty string)\&. +.PP +\fIUnitFileState\fR +encodes the install state of the unit file of +\fIFragmentPath\fR\&. It currently knows the following states: +"enabled", +"enabled\-runtime", +"linked", +"linked\-runtime", +"masked", +"masked\-runtime", +"static", +"disabled", and +"invalid"\&. +"enabled" +indicates that a unit file is permanently enabled\&. +"enable\-runtime" +indicates the unit file is only temporarily enabled and will no longer be enabled after a reboot (that means, it is enabled via +/run/ +symlinks, rather than +/etc/)\&. +"linked" +indicates that a unit is linked into +/etc/ +permanently\&. +"linked\-runtime" +indicates that a unit is linked into +/run/ +temporarily (until the next reboot)\&. +"masked" +indicates that the unit file is masked permanently\&. +"masked\-runtime" +indicates that it is masked in +/run/ +temporarily (until the next reboot)\&. +"static" +indicates that the unit is statically enabled, i\&.e\&. always enabled and doesn\*(Aqt need to be enabled explicitly\&. +"invalid" +indicates that it could not be determined whether the unit file is enabled\&. +.PP +\fIInactiveExitTimestamp\fR, +\fIInactiveExitTimestampMonotonic\fR, +\fIActiveEnterTimestamp\fR, +\fIActiveEnterTimestampMonotonic\fR, +\fIActiveExitTimestamp\fR, +\fIActiveExitTimestampMonotonic\fR, +\fIInactiveEnterTimestamp\fR, and +\fIInactiveEnterTimestampMonotonic\fR +contain +\fBCLOCK_REALTIME\fR +and +\fBCLOCK_MONOTONIC\fR +64\-bit microsecond timestamps of the last time a unit left the inactive state, entered the active state, exited the active state, or entered an inactive state\&. These are the points in time where the unit transitioned +"inactive"/"failed" +→ +"activating", +"activating" +→ +"active", +"active" +→ +"deactivating", and finally +"deactivating" +→ +"inactive"/"failed"\&. The fields are 0 in case such a transition has not yet been recorded on this boot\&. +.PP +\fICanStart\fR, +\fICanStop\fR, and +\fICanReload\fR +encode as booleans whether the unit supports the start, stop or reload operations\&. Even if a unit supports such an operation, the client might not necessary have the necessary privileges to execute them\&. +.PP +\fICanIsolate\fR +encodes as a boolean whether the unit may be started in isolation mode\&. +.PP +\fIJob\fR +encodes the job ID and job object path of the job currently scheduled or executed for this unit, if there is any\&. If no job is scheduled or executed, the job id field will be 0\&. +.PP +\fIStopWhenUnneeded\fR, +\fIRefuseManualStart\fR, +\fIRefuseManualStop\fR, +\fIAllowIsolate\fR, +\fIDefaultDependencies\fR, +\fIOnFailureIsolate\fR, +\fIIgnoreOnIsolate\fR, +\fIIgnoreOnSnapshot\fR +map directly to the corresponding configuration booleans in the unit file\&. +.PP +\fINeedDaemonReload\fR +is a boolean that indicates whether the configuration file this unit is loaded from (i\&.e\&. +\fIFragmentPath\fR +or +\fISourcePath\fR) has changed since the configuration was read and hence whether a configuration reload is recommended\&. +.PP +\fIMarkers\fR +is an array of string flags that can be set using +\fBSetUnitProperties()\fR +to indicate that the service should be reloaded or restarted\&. Currently known values are +"needs\-restart" +and +"needs\-reload"\&. Package scripts may use the first to mark units for later restart when a new version of the package is installed\&. Configuration management scripts may use the second to mark units for a later reload when the configuration is adjusted\&. Those flags are not set by the manager, except to unset as appropriate when the unit is stopped, restarted, or reloaded\&. +.PP +\fIJobTimeoutUSec\fR +maps directly to the corresponding configuration setting in the unit file\&. +.PP +\fIConditionTimestamp\fR +and +\fIConditionTimestampMonotonic\fR +contain the +\fBCLOCK_REALTIME\fR/\fBCLOCK_MONOTONIC\fR +microsecond timestamps of the last time the configured conditions of the unit have been checked or 0 if they have never been checked\&. Conditions are checked when a unit is requested to start\&. +.PP +\fIConditionResult\fR +contains the condition result of the last time the configured conditions of this unit were checked\&. +.PP +\fIConditions\fR +contains all configured conditions of the unit\&. For each condition, five fields are given: condition type (e\&.g\&. +\fIConditionPathExists\fR), whether the condition is a trigger condition, whether the condition is reversed, the right hand side of the condition (e\&.g\&. the path in case of +\fIConditionPathExists\fR), and the status\&. The status can be 0, in which case the condition hasn\*(Aqt been checked yet, a positive value, in which case the condition passed, or a negative value, in which case the condition is not met\&. Currently only 0, +1, and \-1 are used, but additional values may be used in the future, retaining the meaning of zero/positive/negative values\&. +.PP +\fILoadError\fR +contains a pair of strings\&. If the unit failed to load (as encoded in +\fILoadState\fR, see above), then this will include a D\-Bus error pair consisting of the error ID and an explanatory human readable string of what happened\&. If it loaded successfully, this will be a pair of empty strings\&. +.PP +\fITransient\fR +contains a boolean that indicates whether the unit was created as a transient unit (i\&.e\&. via +\fBStartTransientUnit()\fR +on the manager object)\&. +.PP +\fIActivationDetails\fR +contains a list of string pairs, key and value, that describe the event that caused the unit to be activated, if any\&. The key describes the information (e\&.g\&.: +\fItrigger_unit\fR, with value +\fIfoo\&.service\fR)\&. This is only filled in if the unit was triggered by a +\fIPath\fR +or +\fITimer\fR +unit, and it is only provided in a best effort fashion: it is not guaranteed to be set, and it is not guaranteed to be the only trigger\&. It is only guaranteed to be a valid trigger that caused the activation job to be enqueued and complete successfully\&. The key value pairs correspond (in lowercase) to the environment variables described in the +"Environment Variables Set or Propagated by the Service Manager" +section in +\fBsystemd.exec\fR(5)\&. Note that new key value pair may be added at any time in future versions\&. Existing entries will not be removed\&. +.SS "Security" +.PP +Similarly to methods on the +Manager +object, read\-only access is allowed for everyone\&. All operations are allowed for clients with the +\fBCAP_SYS_ADMIN\fR +capability or when the +org\&.freedesktop\&.systemd1\&.manage\-units +privilege is granted by polkit\&. +.SH "SERVICE UNIT OBJECTS" +.PP +All service unit objects implement the +org\&.freedesktop\&.systemd1\&.Service +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + interface org\&.freedesktop\&.systemd1\&.Service { + methods: + BindMount(in s source, + in s destination, + in b read_only, + in b mkdir); + MountImage(in s source, + in s destination, + in b read_only, + in b mkdir, + in a(ss) options); + DumpFileDescriptorStore(out a(suuutuusu) entries); + GetProcesses(out a(sus) processes); + AttachProcesses(in s subcgroup, + in au pids); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Type = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ExitType = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Restart = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RestartMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s PIDFile = \*(Aq\&.\&.\&.\*(Aq; + readonly s NotifyAccess = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RestartUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u RestartSteps = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RestartMaxDelayUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t RestartUSecNext = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutStartUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutStopUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TimeoutAbortUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TimeoutStartFailureMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TimeoutStopFailureMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RuntimeMaxUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RuntimeRandomizedExtraUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t WatchdogUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t WatchdogTimestamp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t WatchdogTimestampMonotonic = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RootDirectoryStartOnly = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemainAfterExit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b GuessMainPID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (aiai) RestartPreventExitStatus = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (aiai) RestartForceExitStatus = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (aiai) SuccessExitStatus = \&.\&.\&.; + readonly u MainPID = \&.\&.\&.; + readonly u ControlPID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s BusName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u FileDescriptorStoreMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NFileDescriptorStore = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s FileDescriptorStorePreserve = \*(Aq\&.\&.\&.\*(Aq; + readonly s StatusText = \*(Aq\&.\&.\&.\*(Aq; + readonly i StatusErrno = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + readonly s ReloadResult = \*(Aq\&.\&.\&.\*(Aq; + readonly s CleanResult = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s USBFunctionDescriptors = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s USBFunctionStrings = \*(Aq\&.\&.\&.\*(Aq; + readonly u UID = \&.\&.\&.; + readonly u GID = \&.\&.\&.; + readonly u NRestarts = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s OOMPolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) OpenFile = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i ReloadSignal = \&.\&.\&.; + readonly t ExecMainStartTimestamp = \&.\&.\&.; + readonly t ExecMainStartTimestampMonotonic = \&.\&.\&.; + readonly t ExecMainExitTimestamp = \&.\&.\&.; + readonly t ExecMainExitTimestampMonotonic = \&.\&.\&.; + readonly u ExecMainPID = \&.\&.\&.; + readonly i ExecMainCode = \&.\&.\&.; + readonly i ExecMainStatus = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecCondition = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecConditionEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStartPre = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecStartPreEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStart = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecStartEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStartPost = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecStartPostEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecReload = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecReloadEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStop = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecStopEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStopPost = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasasttttuii) ExecStopPostEx = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ControlGroupId = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryAvailable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUUsageNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Delegate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DelegateControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DelegateSubgroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPerSecUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPeriodUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceLatencyTargetUSec = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b BlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t BlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupBlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOReadBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOWriteBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b MemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultStartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DevicePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) DeviceAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b TasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPIngressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPEgressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DisableControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMSwap = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMMemoryPressure = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u ManagedOOMMemoryPressureLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMPreference = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) BPFProgram = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (bas) RestrictNetworkInterfaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiss) NFTSet = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CoredumpReceive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Environment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sb) EnvironmentFiles = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PassEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as UnsetEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u UMask = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPU = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPUSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATASoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitAS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitASSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROCSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDING = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDINGSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIO = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIOSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIME = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIMESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s WorkingDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImage = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) RootImageOptions = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHash = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHashSignature = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashSignaturePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootVerity = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RootEphemeral = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExtensionDirectories = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sba(ss)) ExtensionImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssba(ss)) MountImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i OOMScoreAdjust = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CoredumpFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i Nice = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingClass = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay CPUAffinity = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUAffinityFromNUMA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i NUMAPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay NUMAMask = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimerSlackNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUSchedulingResetOnFork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NonBlocking = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay StandardInputData = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardError = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardErrorFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TTYPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYReset = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVHangup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVTDisallocate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYRows = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYColumns = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SyslogIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SyslogLevelPrefix = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogLevel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogFacility = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i LogLevelMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LogRateLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogRateLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly aay LogExtraFields = [[\&.\&.\&.], \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(bs) LogFilterPatterns = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s LogNamespace = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SecureBits = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CapabilityBoundingSet = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t AmbientCapabilities = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s User = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Group = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DynamicUser = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SetLoginEnvironment = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemoveIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ImportCredential = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SupplementaryGroups = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s PAMName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadWritePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadOnlyPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as InaccessiblePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as NoExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecSearchPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t MountFlags = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateTmp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateDevices = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectClock = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelTunables = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelModules = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelLogs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectControlGroups = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateNetwork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateUsers = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateMounts = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectHome = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectSystem = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SameProcessGroup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SELinuxContext = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) AppArmorProfile = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SmackProcessLabel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b IgnoreSIGPIPE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NoNewPrivileges = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SystemCallArchitectures = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SystemCallErrorNumber = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallLog = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Personality = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b LockPersonality = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictAddressFamilies = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) RuntimeDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RuntimeDirectoryPreserve = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u RuntimeDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RuntimeDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) StateDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u StateDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as StateDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) CacheDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u CacheDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as CacheDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) LogsDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogsDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as LogsDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u ConfigurationDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ConfigurationDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutCleanUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryDenyWriteExecute = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictRealtime = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictSUIDSGID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RestrictNamespaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictFileSystems = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindReadOnlyPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) TemporaryFileSystem = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MountAPIVFS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KeyringMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectProc = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProcSubset = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectHostname = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryKSM = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s NetworkNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s IPCNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s MountImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KillMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i KillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i RestartKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i FinalKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGKILL = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGHUP = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i WatchdogSignal = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBBindMount()\fR +and +\fBMountImage()\fR +implement the same operations as the respective methods on the +Manager +object (see above)\&. However, these methods operate on the service object and hence do not take a unit name parameter\&. Invoking the methods directly on the Manager object has the advantage of not requiring a +\fBGetUnit()\fR +call to get the unit object for a specific unit name\&. Calling the methods on the Manager object is hence a round trip optimization\&. +.PP +\fBDumpFileDescriptorStore()\fR +returns an array with information about the file descriptors currently in the file descriptor store of the service\&. Each entry consists of a file descriptor name (i\&.e\&. the +\fIFDNAME=\fR +field), the file descriptor inode type and access mode as integer (i\&.e\&. a +\fBmode_t\fR +value, flags such as +\fBS_IFREG\fR, +\fBS_IRUSR\fR, \&...), the major and minor numbers of the device number of the file system backing the inode of the file descriptor, the inode number, the major and minor numbers of the device number if this refers to a character or block device node, a file system path pointing to the inode, and the file descriptor flags (i\&.e\&. +\fBO_RDWR\fR, +\fBO_RDONLY\fR, \&...)\&. +.SS "Properties" +.PP +Most properties of the Service interface map directly to the corresponding settings in service unit files\&. For the sake of brevity, here\*(Aqs a list of all exceptions only: +.PP +\fITimeoutStartUSec\fR, +\fITimeoutStopUSec\fR +and +\fITimeoutAbortUSec\fR +contain the start, stop and abort timeouts, in microseconds\&. Note the slight difference in naming when compared to the matching unit file settings (see +\fBsystemd.service\fR(7)): these bus properties strictly use microseconds (and thus are suffixed +\fI\&...USec\fR) while the unit file settings default to a time unit of seconds (and thus are suffixed +\fI\&...Sec\fR), unless a different unit is explicitly specified\&. This reflects that fact that internally the service manager deals in microsecond units only, and the bus properties are a relatively low\-level (binary) concept exposing this\&. The unit file settings on the other hand are relatively high\-level (string\-based) concepts and thus support more user friendly time specifications which default to second time units but allow other units too, if specified\&. +.PP +\fIWatchdogTimestamp\fR +and +\fIWatchdogTimestampMonotonic\fR +contain +\fBCLOCK_REALTIME\fR/\fBCLOCK_MONOTONIC\fR +microsecond timestamps of the last watchdog ping received from the service, or 0 if none was ever received\&. +.PP +\fIExecStartPre\fR, +\fIExecStart\fR, +\fIExecStartPost\fR, +\fIExecReload\fR, +\fIExecStop\fR, and +\fIExecStop\fR +are arrays of structures where each struct contains: the binary path to execute; an array with all arguments to pass to the executed command, starting with argument 0; a boolean whether it should be considered a failure if the process exits uncleanly; two pairs of +\fBCLOCK_REALTIME\fR/\fBCLOCK_MONOTONIC\fR +microsecond timestamps when the process began and finished running the last time, or 0 if it never ran or never finished running; the PID of the process, or 0 if it has not run yet; the exit code and status of the last run\&. This field hence maps more or less to the corresponding setting in the service unit file but is augmented with runtime data\&. +.PP +\fILimitCPU\fR +(and related properties) map more or less directly to the corresponding settings in the service unit files except that if they aren\*(Aqt set, their value is 18446744073709551615 (i\&.e\&. \-1)\&. +.PP +\fICapabilities\fR +contains the configured capabilities, as formatted with +\fBcap_to_text\fR(3)\&. +.PP +\fISecureBits\fR, +\fICapabilityBoundingSet\fR, +\fIMountFlags\fR +also correspond to the configured settings of the unit files, but instead of being formatted as strings, they are encoded as the actual binary flags they are\&. +.PP +\fIExecMainStartTimestamp\fR, +\fIExecMainStartTimestampMonotonic\fR, +\fIExecMainExitTimestamp\fR, +\fIExecMainExitTimestampMonotonic\fR, +\fIExecMainPID\fR, +\fIExecMainCode\fR, +\fIExecMainStatus\fR +contain information about the main process of the service as far as it is known\&. This is often the same runtime information that is stored in +\fIExecStart\fR\&. However, it deviates for +\fIType=forking\fR +services where the main process of the service is not forked off systemd directly\&. These fields either contain information of the last run of the process or of the current running process\&. +.PP +\fIMainPID\fR +and +\fIControlPID\fR +contain the main and control PID of the service\&. The main PID is the current main PID of the service and is 0 when the service currently has no main PID\&. The control PID is the PID of the current start/stop/reload process running and is 0 if no such process is currently running\&. That means that +\fIExecMainPID\fR +and +\fIMainPID\fR +differ in the way that the latter immediately reflects whether a main process is currently running while the latter possible contains information collected from the last run even if the process is no longer around\&. +.PP +\fIStatusText\fR +contains the status text passed to the service manager via a call to +\fBsd_notify\fR(3)\&. This may be used by services to inform the service manager about its internal state with a nice explanatory string\&. +.PP +\fIResult\fR +encodes the execution result of the last run of the service\&. It is useful to determine the reason a service failed if it is in the +"failed" +state (see +\fIActiveState\fR +above)\&. The following values are currently known: +"success" +is set if the unit didn\*(Aqt fail\&. +"resources" +indicates that not enough resources were available to fork off and execute the service processes\&. +"timeout" +indicates that a timeout occurred while executing a service operation\&. +"exit\-code" +indicates that a service process exited with an unclean exit code\&. +"signal" +indicates that a service process exited with an uncaught signal\&. +"core\-dump" +indicates that a service process exited uncleanly and dumped core\&. +"watchdog" +indicates that a service did not send out watchdog ping messages often enough\&. +"start\-limit" +indicates that a service has been started too frequently in a specific time frame (as configured in +\fIStartLimitInterval\fR, +\fIStartLimitBurst\fR)\&. +.PP +\fIControlGroup\fR +indicates the control group path the processes of this service unit are placed in\&. +.PP +The following properties map 1:1 to corresponding settings in the unit file: +\fIRootDirectory\fR +\fIRootImage\fR +\fIRootImageOptions\fR +\fIRootVerity\fR +\fIRootHash\fR +\fIRootHashSignature\fR +\fIMountImages\fR +\fIExtensionImages\fR +\fIExtensionDirectories\fR +see systemd\&.exec(5) for their meaning\&. +.PP +\fIMemoryAvailable\fR +takes into account unit\*(Aqs and parents\*(Aq +"MemoryMax" +or +"MemoryHigh" +or physically available RAM versus given level\*(Aqs memory consumption and takes minimum\&. Beware that other units below the tightest parent slice may consume the memory quicker and less than reported value would remain for own allocation\&. It works better in conjunction with +\fIMemoryAccounting=yes\fR +on involved units\&. +.PP +\fIDelegateSubgroup\fR +contains the cgroup subgroup to place invoked unit processes in\&. As configured by the option of the same name in unit files\&. This is set to the empty string when it does not apply or no subgroup has been configured\&. +.PP +\fIRuntimeDirectorySymlink\fR, +\fIStateDirectorySymlink\fR, +\fICacheDirectorySymlink\fR +and +\fILogsDirectorySymlink\fR +respectively implement the destination parameter of the unit files settings +\fIRuntimeDirectory\fR, +\fIStateDirectory\fR, +\fICacheDirectory\fR +and +\fILogsDirectory\fR, which will create a symlink of the given name to the respective directory\&. The messages take an unused +\fIflags\fR +parameter, reserved for future backward\-compatible changes\&. +.SH "SOCKET UNIT OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { + interface org\&.freedesktop\&.systemd1\&.Socket { + methods: + GetProcesses(out a(sus) processes); + AttachProcesses(in s subcgroup, + in au pids); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s BindIPv6Only = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u Backlog = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s BindToDevice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SocketUser = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SocketGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u SocketMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u DirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Accept = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b FlushPending = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Writable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b KeepAlive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t KeepAliveTimeUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t KeepAliveIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u KeepAliveProbes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t DeferAcceptUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NoDelay = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i Priority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t ReceiveBuffer = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t SendBuffer = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IPTOS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IPTTL = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t PipeSize = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b FreeBind = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Transparent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Broadcast = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PassCredentials = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PassSecurity = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PassPacketInfo = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Timestamping = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemoveOnStop = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) Listen = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Symlinks = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i Mark = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u MaxConnections = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u MaxConnectionsPerSource = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly x MessageQueueMaxMessages = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly x MessageQueueMessageSize = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TCPCongestion = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ReusePort = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SmackLabel = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SmackLabelIPIn = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SmackLabelIPOut = \*(Aq\&.\&.\&.\*(Aq; + readonly u ControlPID = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NConnections = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NAccepted = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u NRefused = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s FileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SocketProtocol = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TriggerLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u TriggerLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t PollLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u PollLimitBurst = \&.\&.\&.; + readonly u UID = \&.\&.\&.; + readonly u GID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStartPre = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStartPost = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStopPre = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecStopPost = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ControlGroupId = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryAvailable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUUsageNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Delegate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DelegateControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DelegateSubgroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPerSecUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPeriodUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceLatencyTargetUSec = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b BlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t BlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupBlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOReadBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOWriteBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b MemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultStartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DevicePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) DeviceAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b TasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPIngressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPEgressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DisableControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMSwap = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMMemoryPressure = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u ManagedOOMMemoryPressureLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMPreference = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) BPFProgram = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (bas) RestrictNetworkInterfaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiss) NFTSet = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CoredumpReceive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Environment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sb) EnvironmentFiles = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PassEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as UnsetEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u UMask = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPU = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPUSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATASoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitAS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitASSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROCSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDING = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDINGSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIO = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIOSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIME = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIMESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s WorkingDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImage = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) RootImageOptions = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHash = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHashSignature = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashSignaturePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootVerity = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RootEphemeral = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExtensionDirectories = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sba(ss)) ExtensionImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssba(ss)) MountImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i OOMScoreAdjust = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CoredumpFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i Nice = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingClass = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay CPUAffinity = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUAffinityFromNUMA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i NUMAPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay NUMAMask = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimerSlackNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUSchedulingResetOnFork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NonBlocking = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay StandardInputData = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardError = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardErrorFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TTYPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYReset = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVHangup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVTDisallocate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYRows = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYColumns = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SyslogIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SyslogLevelPrefix = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogLevel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogFacility = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i LogLevelMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LogRateLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogRateLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly aay LogExtraFields = [[\&.\&.\&.], \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(bs) LogFilterPatterns = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s LogNamespace = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SecureBits = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CapabilityBoundingSet = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t AmbientCapabilities = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s User = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Group = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DynamicUser = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SetLoginEnvironment = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemoveIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ImportCredential = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SupplementaryGroups = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s PAMName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadWritePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadOnlyPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as InaccessiblePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as NoExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecSearchPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t MountFlags = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateTmp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateDevices = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectClock = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelTunables = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelModules = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelLogs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectControlGroups = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateNetwork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateUsers = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateMounts = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectHome = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectSystem = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SameProcessGroup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SELinuxContext = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) AppArmorProfile = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SmackProcessLabel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b IgnoreSIGPIPE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NoNewPrivileges = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SystemCallArchitectures = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SystemCallErrorNumber = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallLog = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Personality = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b LockPersonality = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictAddressFamilies = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) RuntimeDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RuntimeDirectoryPreserve = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u RuntimeDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RuntimeDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) StateDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u StateDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as StateDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) CacheDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u CacheDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as CacheDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) LogsDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogsDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as LogsDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u ConfigurationDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ConfigurationDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutCleanUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryDenyWriteExecute = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictRealtime = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictSUIDSGID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RestrictNamespaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictFileSystems = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindReadOnlyPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) TemporaryFileSystem = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MountAPIVFS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KeyringMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectProc = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProcSubset = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectHostname = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryKSM = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s NetworkNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s IPCNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s MountImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KillMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i KillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i RestartKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i FinalKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGKILL = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGHUP = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i WatchdogSignal = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.sp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.PP +\fIPollLimitIntervalUSec\fR/\fIPollLimitBurst\fR +properties configure the polling limit for the socket unit\&. Expects a time in \(mcs, resp\&. an unsigned integer\&. If either is set to zero the limiting feature is turned off\&. +.SS "Properties" +.PP +Most of the properties map directly to the corresponding settings in socket unit files\&. As socket units can include +\fIExecStartPre\fR +(and similar) fields which contain information about processes to execute\&. They also share most of the fields related to the execution context that Service objects expose (see above)\&. +.PP +In addition to these properties there are the following: +.PP +\fINAccepted\fR +contains the accumulated number of connections ever accepted on this socket\&. This only applies to sockets with +\fIAccept\fR +set to +"yes", i\&.e\&. those where systemd is responsible for accepted connections\&. +.PP +Similarly +\fINConnections\fR +contains the number of currently open connections on this socket\&. It only applies only to socket units with +\fIAccept\fR +set to +"yes"\&. +.PP +\fIResult\fR +encodes the reason why a socket unit failed if it is in the +"failed" +state (see +\fIActiveState\fR +above)\&. The values +"success", +"resources", +"timeout", +"exit\-code", +"signal" +and +"core\-dump" +have the same meaning as they have for the corresponding field of service units (see above)\&. In addition to that, the value +"service\-failed\-permanent" +indicates that the service of this socket failed continuously\&. +.PP +\fIFlushPending\fR +specifies whether to flush the socket just before entering the listening state\&. This setting only applies to sockets with +\fIAccept=\fR +set to +"no"\&. +.SH "TARGET UNIT OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/basic_2etarget { + interface org\&.freedesktop\&.systemd1\&.Target { + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} +.PP +Target units have neither type\-specific methods nor properties\&. +.SH "DEVICE UNIT OBJECTS" +.PP +All device unit objects implement the +org\&.freedesktop\&.systemd1\&.Device +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/dev_2dttyS0_2edevice { + interface org\&.freedesktop\&.systemd1\&.Device { + properties: + readonly s SysFSPath = \*(Aq\&.\&.\&.\*(Aq; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + +.SS "Properties" +.PP +Device units only expose a single type\-specific property: +.PP +\fISysFSPath\fR +contains the sysfs path of the kernel device this object corresponds to\&. +.SH "MOUNT UNIT OBJECTS" +.PP +All mount unit objects implement the +org\&.freedesktop\&.systemd1\&.Mount +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/home_2emount { + interface org\&.freedesktop\&.systemd1\&.Mount { + methods: + GetProcesses(out a(sus) processes); + AttachProcesses(in s subcgroup, + in au pids); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Where = \*(Aq\&.\&.\&.\*(Aq; + readonly s What = \*(Aq\&.\&.\&.\*(Aq; + readonly s Options = \*(Aq\&.\&.\&.\*(Aq; + readonly s Type = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutUSec = \&.\&.\&.; + readonly u ControlPID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u DirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SloppyOptions = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b LazyUnmount = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ForceUnmount = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ReadWriteOnly = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + readonly u UID = \&.\&.\&.; + readonly u GID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecMount = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecUnmount = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecRemount = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ControlGroupId = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryAvailable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUUsageNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Delegate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DelegateControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DelegateSubgroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPerSecUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPeriodUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceLatencyTargetUSec = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b BlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t BlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupBlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOReadBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOWriteBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b MemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultStartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DevicePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) DeviceAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b TasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPIngressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPEgressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DisableControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMSwap = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMMemoryPressure = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u ManagedOOMMemoryPressureLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMPreference = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) BPFProgram = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (bas) RestrictNetworkInterfaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiss) NFTSet = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CoredumpReceive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Environment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sb) EnvironmentFiles = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PassEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as UnsetEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u UMask = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPU = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPUSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATASoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitAS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitASSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROCSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDING = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDINGSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIO = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIOSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIME = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIMESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s WorkingDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImage = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) RootImageOptions = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHash = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHashSignature = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashSignaturePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootVerity = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RootEphemeral = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExtensionDirectories = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sba(ss)) ExtensionImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssba(ss)) MountImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i OOMScoreAdjust = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CoredumpFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i Nice = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingClass = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay CPUAffinity = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUAffinityFromNUMA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i NUMAPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay NUMAMask = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimerSlackNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUSchedulingResetOnFork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NonBlocking = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay StandardInputData = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardError = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardErrorFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TTYPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYReset = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVHangup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVTDisallocate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYRows = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYColumns = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SyslogIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SyslogLevelPrefix = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogLevel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogFacility = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i LogLevelMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LogRateLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogRateLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly aay LogExtraFields = [[\&.\&.\&.], \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(bs) LogFilterPatterns = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s LogNamespace = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SecureBits = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CapabilityBoundingSet = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t AmbientCapabilities = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s User = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Group = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DynamicUser = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SetLoginEnvironment = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemoveIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ImportCredential = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SupplementaryGroups = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s PAMName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadWritePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadOnlyPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as InaccessiblePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as NoExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecSearchPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t MountFlags = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateTmp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateDevices = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectClock = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelTunables = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelModules = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelLogs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectControlGroups = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateNetwork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateUsers = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateMounts = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectHome = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectSystem = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SameProcessGroup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SELinuxContext = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) AppArmorProfile = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SmackProcessLabel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b IgnoreSIGPIPE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NoNewPrivileges = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SystemCallArchitectures = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SystemCallErrorNumber = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallLog = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Personality = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b LockPersonality = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictAddressFamilies = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) RuntimeDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RuntimeDirectoryPreserve = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u RuntimeDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RuntimeDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) StateDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u StateDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as StateDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) CacheDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u CacheDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as CacheDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) LogsDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogsDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as LogsDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u ConfigurationDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ConfigurationDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutCleanUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryDenyWriteExecute = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictRealtime = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictSUIDSGID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RestrictNamespaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictFileSystems = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindReadOnlyPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) TemporaryFileSystem = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MountAPIVFS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KeyringMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectProc = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProcSubset = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectHostname = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryKSM = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s NetworkNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s IPCNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s MountImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KillMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i KillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i RestartKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i FinalKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGKILL = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGHUP = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i WatchdogSignal = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Properties" +.PP +Most of the properties map directly to the corresponding settings in mount unit files\&. As mount units invoke the +/usr/bin/mount +command, their bus objects include implicit +\fIExecMount\fR +(and similar) fields which contain information about processes to execute\&. They also share most of the fields related to the execution context that Service objects expose (see above)\&. In addition to these properties there are the following: +.PP +\fIControlPID\fR +contains the PID of the currently running +/usr/bin/mount +or +/usr/bin/umount +command if there is one running, otherwise 0\&. +.PP +\fIResult\fR +contains a value explaining why a mount unit failed if it failed\&. It can take the values +"success", +"resources", +"timeout", +"exit\-code", +"signal", or +"core\-dump" +which have the identical meaning as the corresponding values of the corresponding field of service unit objects (see above)\&. +.SH "AUTOMOUNT UNIT OBJECTS" +.PP +All automount unit objects implement the +org\&.freedesktop\&.systemd1\&.Automount +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount { + interface org\&.freedesktop\&.systemd1\&.Automount { + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Where = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ExtraOptions = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u DirectoryMode = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutIdleUSec = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + +.SS "Properties" +.PP +Most of the properties map directly to the corresponding settings in the automount unit files\&. +.PP +\fIResult\fR +knows the values +"success" +and +"resources" +at this time\&. They have the same meanings as the corresponding values of the corresponding field of the Service object\&. +.SH "TIMER UNIT OBJECTS" +.PP +All timer unit objects implement the +org\&.freedesktop\&.systemd1\&.Timer +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer { + interface org\&.freedesktop\&.systemd1\&.Timer { + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Unit = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(stt) TimersMonotonic = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sst) TimersCalendar = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b OnClockChange = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b OnTimezoneChange = \&.\&.\&.; + readonly t NextElapseUSecRealtime = \&.\&.\&.; + readonly t NextElapseUSecMonotonic = \&.\&.\&.; + readonly t LastTriggerUSec = \&.\&.\&.; + readonly t LastTriggerUSecMonotonic = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t AccuracyUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RandomizedDelayUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b FixedRandomDelay = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b Persistent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b WakeSystem = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemainAfterElapse = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + +.SS "Properties" +.PP +\fIUnit\fR +contains the name of the unit to activate when the timer elapses\&. +.PP +\fITimersMonotonic\fR +contains an array of structs that contain information about all monotonic timers of this timer unit\&. The structs contain a string identifying the timer base, which is one of +"OnActiveUSec", +"OnBootUSec", +"OnStartupUSec", +"OnUnitActiveUSec", or +"OnUnitInactiveUSec" +which correspond to the settings of the same names in the timer unit files; the microsecond offset from this timer base in monotonic time; the next elapsation point on the +\fBCLOCK_MONOTONIC\fR +clock, relative to its epoch\&. +.PP +\fITimersCalendar\fR +contains an array of structs that contain information about all realtime/calendar timers of this timer unit\&. The structs contain a string identifying the timer base, which may only be +"OnCalendar" +for now; the calendar specification string; the next elapsation point on the +\fBCLOCK_REALTIME\fR +clock, relative to its epoch\&. +.PP +\fINextElapseUSecRealtime\fR +contains the next elapsation point on the +\fBCLOCK_REALTIME\fR +clock in miscroseconds since the epoch, or 0 if this timer event does not include at least one calendar event\&. +.PP +Similarly, +\fINextElapseUSecMonotonic\fR +contains the next elapsation point on the +\fBCLOCK_MONOTONIC\fR +clock in microseconds since the epoch, or 0 if this timer event does not include at least one monotonic event\&. +.PP +\fIResult\fR +knows the values +"success" +and +"resources" +with the same meanings as the matching values of the corresponding property of the service interface\&. +.SH "SWAP UNIT OBJECTS" +.PP +All swap unit objects implement the +org\&.freedesktop\&.systemd1\&.Swap +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { + interface org\&.freedesktop\&.systemd1\&.Swap { + methods: + GetProcesses(out a(sus) processes); + AttachProcesses(in s subcgroup, + in au pids); + properties: + readonly s What = \*(Aq\&.\&.\&.\*(Aq; + readonly i Priority = \&.\&.\&.; + readonly s Options = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutUSec = \&.\&.\&.; + readonly u ControlPID = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + readonly u UID = \&.\&.\&.; + readonly u GID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecActivate = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates") + readonly a(sasbttttuii) ExecDeactivate = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ControlGroupId = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryAvailable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUUsageNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Delegate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DelegateControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DelegateSubgroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPerSecUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPeriodUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceLatencyTargetUSec = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b BlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t BlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupBlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOReadBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOWriteBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b MemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultStartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DevicePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) DeviceAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b TasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPIngressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPEgressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DisableControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMSwap = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMMemoryPressure = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u ManagedOOMMemoryPressureLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMPreference = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) BPFProgram = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (bas) RestrictNetworkInterfaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiss) NFTSet = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CoredumpReceive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as Environment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sb) EnvironmentFiles = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as PassEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as UnsetEnvironment = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u UMask = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPU = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCPUSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitFSIZESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitDATASoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSTACKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitCORESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRSSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNOFILESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitAS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitASSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNPROCSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCK = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMEMLOCKSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitLOCKSSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDING = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitSIGPENDINGSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitMSGQUEUESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitNICESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIO = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTPRIOSoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIME = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LimitRTTIMESoft = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s WorkingDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImage = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) RootImageOptions = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHash = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay RootHashSignature = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootHashSignaturePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootVerity = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RootEphemeral = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExtensionDirectories = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sba(ss)) ExtensionImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssba(ss)) MountImages = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i OOMScoreAdjust = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CoredumpFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i Nice = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingClass = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i IOSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i CPUSchedulingPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay CPUAffinity = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUAffinityFromNUMA = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i NUMAPolicy = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay NUMAMask = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimerSlackNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b CPUSchedulingResetOnFork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NonBlocking = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardInputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly ay StandardInputData = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutput = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardOutputFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardError = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s StandardErrorFileDescriptorName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s TTYPath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYReset = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVHangup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b TTYVTDisallocate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYRows = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly q TTYColumns = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogPriority = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s SyslogIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SyslogLevelPrefix = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogLevel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SyslogFacility = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i LogLevelMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t LogRateLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogRateLimitBurst = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly aay LogExtraFields = [[\&.\&.\&.], \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(bs) LogFilterPatterns = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s LogNamespace = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SecureBits = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t CapabilityBoundingSet = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t AmbientCapabilities = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s User = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Group = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b DynamicUser = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SetLoginEnvironment = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RemoveIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(say) SetCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredential = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) LoadCredentialEncrypted = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ImportCredential = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SupplementaryGroups = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s PAMName = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadWritePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ReadOnlyPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as InaccessiblePaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as NoExecPaths = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ExecSearchPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t MountFlags = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateTmp = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateDevices = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectClock = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelTunables = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelModules = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectKernelLogs = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectControlGroups = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateNetwork = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateUsers = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateMounts = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b PrivateIPC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectHome = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectSystem = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SameProcessGroup = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpIdentifier = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s UtmpMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SELinuxContext = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) AppArmorProfile = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bs) SmackProcessLabel = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b IgnoreSIGPIPE = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b NoNewPrivileges = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallFilter = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as SystemCallArchitectures = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i SystemCallErrorNumber = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) SystemCallLog = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Personality = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b LockPersonality = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictAddressFamilies = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) RuntimeDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RuntimeDirectoryPreserve = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u RuntimeDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as RuntimeDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) StateDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u StateDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as StateDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) CacheDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u CacheDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as CacheDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(sst) LogsDirectorySymlink = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u LogsDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as LogsDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u ConfigurationDirectoryMode = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly as ConfigurationDirectory = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutCleanUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryDenyWriteExecute = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictRealtime = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b RestrictSUIDSGID = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RestrictNamespaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (bas) RestrictFileSystems = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ssbt) BindReadOnlyPaths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) TemporaryFileSystem = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MountAPIVFS = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KeyringMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProtectProc = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ProcSubset = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b ProtectHostname = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MemoryKSM = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s NetworkNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s IPCNamespacePath = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s RootImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s MountImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s ExtensionImagePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KillMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i KillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i RestartKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i FinalKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGKILL = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGHUP = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i WatchdogSignal = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Properties" +.PP +Most of the properties map directly to the corresponding settings in swap unit files\&. As mount units invoke the +\fBswapon\fR(8) +command, their bus objects include implicit +\fIExecActivate\fR +(and similar) fields which contain information about processes to execute\&. They also share most of the fields related to the execution context that Service objects expose (see above)\&. In addition to these properties there are the following: +.PP +\fIControlPID\fR +contains the PID of the currently running +\fBswapon\fR(8) +or +\fBswapoff\fR(8) +command if there is one running, otherwise 0\&. +.PP +\fIResult\fR +contains a value explaining why a mount unit failed if it failed\&. It can take the values +"success", +"resources", +"timeout", +"exit\-code", +"signal", or +"core\-dump" +which have the identical meanings as the corresponding values of the corresponding field of service unit objects (see above)\&. +.SH "PATH UNIT OBJECTS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/cups_2epath { + interface org\&.freedesktop\&.systemd1\&.Path { + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s Unit = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) Paths = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b MakeDirectory = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u DirectoryMode = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TriggerLimitIntervalUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u TriggerLimitBurst = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + +.SS "Properties" +.PP +Most properties correspond directly with the matching settings in path unit files\&. +.PP +The others: +.PP +\fIPaths\fR +contains an array of structs\&. Each struct contains the condition to watch, which can be one of +"PathExists", +"PathExistsGlob", +"PathChanged", +"PathModified", or +"DirectoryNotEmpty" +which correspond directly to the matching settings in the path unit files; and the path to watch, possibly including glob expressions\&. +.PP +\fIResult\fR +contains a result value which can be +"success" +or +"resources" +which have the same meaning as the corresponding field of the Service interface\&. +.SH "SLICE UNIT OBJECTS" +.PP +All slice unit objects implement the +org\&.freedesktop\&.systemd1\&.Slice +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/system_2eslice { + interface org\&.freedesktop\&.systemd1\&.Slice { + methods: + GetProcesses(out a(sus) processes); + AttachProcesses(in s subcgroup, + in au pids); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ControlGroupId = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryAvailable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUUsageNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Delegate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DelegateControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DelegateSubgroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPerSecUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPeriodUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceLatencyTargetUSec = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b BlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t BlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupBlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOReadBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOWriteBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b MemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultStartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DevicePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) DeviceAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b TasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPIngressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPEgressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DisableControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMSwap = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMMemoryPressure = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u ManagedOOMMemoryPressureLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMPreference = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) BPFProgram = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (bas) RestrictNetworkInterfaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiss) NFTSet = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CoredumpReceive = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Properties" +.PP +Most properties correspond directly with the matching settings in slice unit files\&. +.SH "SCOPE UNIT OBJECTS" +.PP +All scope unit objects implement the +org\&.freedesktop\&.systemd1\&.Scope +interface (described here) in addition to the generic +org\&.freedesktop\&.systemd1\&.Unit +interface (see above)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/unit/session_2d1_2escope { + interface org\&.freedesktop\&.systemd1\&.Scope { + methods: + Abandon(); + GetProcesses(out a(sus) processes); + AttachProcesses(in s subcgroup, + in au pids); + signals: + RequestStop(); + properties: + readonly s Controller = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t TimeoutStopUSec = \&.\&.\&.; + readonly s Result = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RuntimeMaxUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly t RuntimeRandomizedExtraUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s OOMPolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s Slice = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ControlGroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t ControlGroupId = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapPeak = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryAvailable = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUUsageNSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay EffectiveMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksCurrent = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPIngressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IPEgressPackets = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOReadOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteBytes = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWriteOperations = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b Delegate = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DelegateControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DelegateSubgroup = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CPUAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupCPUShares = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPerSecUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t CPUQuotaPeriodUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedCPUs = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay AllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly ay StartupAllowedMemoryNodes = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t IOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteBandwidthMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOReadIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IOWriteIOPSMax = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) IODeviceLatencyTargetUSec = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b BlockIOAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t BlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupBlockIOWeight = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIODeviceWeight = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOReadBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(st) BlockIOWriteBandwidth = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b MemoryAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultStartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t DefaultMemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMin = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryLow = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryHigh = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemorySwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t StartupMemoryZSwapMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s DevicePolicy = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) DeviceAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b TasksAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TasksMax = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b IPAccounting = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iayu) IPAddressDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPIngressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as IPEgressFilterPath = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly as DisableControllers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMSwap = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMMemoryPressure = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly u ManagedOOMMemoryPressureLimit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s ManagedOOMPreference = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(ss) BPFProgram = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindAllow = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiqq) SocketBindDeny = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly (bas) RestrictNetworkInterfaces = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly s MemoryPressureWatch = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t MemoryPressureThresholdUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly a(iiss) NFTSet = [\&.\&.\&.]; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CoredumpReceive = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s KillMode = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i KillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i RestartKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i FinalKillSignal = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGKILL = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly b SendSIGHUP = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly i WatchdogSignal = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; + interface org\&.freedesktop\&.systemd1\&.Unit { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.SS "Methods" +.PP +\fBAbandon()\fR +may be used to place a scope unit in the "abandoned" state\&. This may be used to inform the system manager that the manager that created the scope lost interest in the scope (for example, because it is terminating), without wanting to shut down the scope entirely\&. +.SS "Signals" +.PP +\fBRequestStop\fR +is sent to the peer that is configured in the +\fIController\fR +property when systemd is requested to terminate the scope unit\&. A program registering a scope can use this to cleanly shut down the processes it added to the scope instead of letting systemd do it with the usual +\fBSIGTERM\fR +logic\&. +.SS "Properties" +.PP +All properties correspond directly with the matching properties of service units\&. +.PP +\fIController\fR +contains the bus name (unique or well\-known) that is notified when the scope unit is to be shut down via a +\fBRequestStop\fR +signal (see below)\&. This is set when the scope is created\&. If not set, the scope\*(Aqs processes will terminated with +\fBSIGTERM\fR +directly\&. +.SH "JOB OBJECTS" +.PP +Job objects encapsulate scheduled or running jobs\&. Each unit can have none or one jobs in the execution queue\&. Each job is attached to exactly one unit\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/systemd1/job/666 { + interface org\&.freedesktop\&.systemd1\&.Job { + methods: + Cancel(); + GetAfter(out a(usssoo) jobs); + GetBefore(out a(usssoo) jobs); + properties: + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly u Id = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly (so) Unit = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly s JobType = \*(Aq\&.\&.\&.\*(Aq; + readonly s State = \*(Aq\&.\&.\&.\*(Aq; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const") + readonly a(ss) ActivationDetails = [\&.\&.\&.]; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + +.SS "Methods" +.PP +\fBCancel()\fR +cancels the job\&. Note that this will remove a job from the queue if it is not yet executed but generally will not cause a job that is already in the process of being executed to be aborted\&. This operation may also be requested via the +\fBCancelJob()\fR +method of the Manager object (see above), which is sometimes useful to reduce roundtrips\&. +.SS "Properties" +.PP +\fIId\fR +is the numeric Id of the job\&. During the runtime of a systemd instance each numeric ID is only assigned once\&. +.PP +\fIUnit\fR +refers to the unit this job belongs to\&. It is a structure consisting of the name of the unit and a bus path to the unit\*(Aqs object\&. +.PP +\fIJobType\fR +refers to the job\*(Aqs type and is one of +"start", +"verify\-active", +"stop", +"reload", +"restart", +"try\-restart", or +"reload\-or\-start"\&. Note that later versions might define additional values\&. +.PP +\fIState\fR +refers to the job\*(Aqs state and is one of +"waiting" +and +"running"\&. The former indicates that a job is currently queued but has not begun to execute yet\&. The latter indicates that a job is currently being executed\&. +.PP +\fIActivationDetails\fR +has the same content as the property of the same name under the +\fIorg\&.freedesktop\&.systemd1\&.Unit\fR +interface\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.systemd1\&.Manager on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.systemd1 \e + \-\-object\-path /org/freedesktop/systemd1 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Introspect a unit on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ busctl introspect org\&.freedesktop\&.systemd1 \e + $(busctl call org\&.freedesktop\&.systemd1 \e + /org/freedesktop/systemd1 \e + org\&.freedesktop\&.systemd1\&.Manager \e + GetUnit s systemd\-resolved\&.service | cut \-d\*(Aq"\*(Aq \-f2) + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Introspect org\&.freedesktop\&.systemd1\&.Job on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.systemd1 \e + \-\-object\-path /org/freedesktop/systemd1/job/1292 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[4]\d\s+2\&. +.SH "HISTORY" +.SS "The Manager Object" +.PP +\fIRuntimeWatchdogPreUSec\fR +and +\fIRuntimeWatchdogPreGovernor\fR +were added in version 251\&. +.PP +\fIWatchdogDevice\fR, +\fIWatchdogLastPingTimestamp\fR, +\fIWatchdogLastPingTimestampMonotonic\fR, +\fIDefaultDeviceTimeoutUSec\fR, +\fBDumpUnitsMatchingPatterns()\fR, and +\fBDumpUnitsMatchingPatternsByFileDescriptor()\fR +were added in version 252\&. +.PP +\fBGetUnitByPIDFD()\fR +and +\fBDisableUnitFilesWithFlagsAndInstallInfo()\fR +were added in version 253\&. +.PP +\fIConfidentialVirtualization\fR, +\fIDefaultIOAccounting\fR, +\fIDefaultIPAccounting\fR, +\fIDefaultMemoryPressureThresholdUSec\fR, +\fIDefaultMemoryPressureWatch\fR, +\fBQueueSignalUnit()\fR, +\fBSoftReboot()\fR, and +\fBDumpUnitFileDescriptorStore()\fR +were added in version 254\&. +.SS "Unit Objects" +.PP +\fIUpholds\fR +and +\fIUpheldBy\fR +were added in version 251\&. +.PP +\fIAccessSELinuxContext\fR +and +\fIActivationDetails\fR +were added in version 252\&. +.PP +\fBQueueSignal()\fR +was added in version 254\&. +.PP +\fISurviveFinalKillSignal\fR +was added in version 255\&. +.SS "Service Unit Objects" +.PP +\fIControlGroupId\fR +and +\fIExtensionDirectories\fR +were added in version 251\&. +.PP +\fIOpenFile\fR, +\fIReloadSignal\fR, +\fIMemoryZSwapMax\fR, and +\fILogFilterPatterns\fR +were added in version 253\&. +.PP +\fIRestartMode\fR, +\fIRestartSteps\fR, +\fIRestartMaxDelayUSec\fR, +\fIRestartUSecNext\fR, +\fIFileDescriptorStorePreserve\fR, +\fBDumpFileDescriptorStore()\fR, +\fIDelegateSubgroup\fR, +\fIDefaultStartupMemoryLow\fR, +\fIStartupMemoryLow\fR, +\fIStartupMemoryHigh\fR, +\fIStartupMemoryMax\fR, +\fIStartupMemorySwapMax\fR, +\fIStartupMemoryZSwapMax\fR, +\fIMemoryPressureWatch\fR, +\fIMemoryPressureThresholdUSec\fR, +\fIRootEphemeral\fR, +\fIImportCredential\fR, +\fIMemoryKSM\fR, +\fIRootImagePolicy\fR, +\fIMountImagePolicy\fR, and +\fIExtensionImagePolicy\fR +were added in version 254\&. +.PP +\fINFTSet\fR, +\fISetLoginEnvironment\fR, +\fICoredumpReceive\fR, +\fIMemoryPeak\fR, +\fIMemorySwapCurrent\fR, +\fIMemorySwapPeak\fR, and +\fIMemoryZSwapCurrent\fR +were added in version 255\&. +.SS "Socket Unit Objects" +.PP +\fIControlGroupId\fR +and +\fIExtensionDirectories\fR +were added in version 251\&. +.PP +\fIMemoryZSwapMax\fR +and +\fILogFilterPatterns\fR +were added in version 253\&. +.PP +\fIDelegateSubgroup\fR, +\fIDefaultStartupMemoryLow\fR, +\fIStartupMemoryLow\fR, +\fIStartupMemoryHigh\fR, +\fIStartupMemoryMax\fR, +\fIStartupMemorySwapMax\fR, +\fIStartupMemoryZSwapMax\fR, +\fIMemoryPressureWatch\fR, +\fIMemoryPressureThresholdUSec\fR, +\fIRootEphemeral\fR, +\fIImportCredential\fR, +\fIMemoryKSM\fR, +\fIRootImagePolicy\fR, +\fIMountImagePolicy\fR, and +\fIExtensionImagePolicy\fR +were added in version 254\&. +.PP +\fIPollLimitIntervalUSec\fR, +\fIPollLimitBurst\fR, +\fINFTSet\fR, +\fISetLoginEnvironment\fR, +\fICoredumpReceive\fR, +\fIMemoryPeak\fR, +\fIMemorySwapCurrent\fR, +\fIMemorySwapPeak\fR, and +\fIMemoryZSwapCurrent\fR +were added in version 255\&. +.SS "Mount Unit Objects" +.PP +\fIControlGroupId\fR +and +\fIExtensionDirectories\fR +were added in version 251\&. +.PP +\fIMemoryZSwapMax\fR +and +\fILogFilterPatterns\fR +were added in version 253\&. +.PP +\fIDelegateSubgroup\fR, +\fIDefaultStartupMemoryLow\fR, +\fIStartupMemoryLow\fR, +\fIStartupMemoryHigh\fR, +\fIStartupMemoryMax\fR, +\fIStartupMemorySwapMax\fR, +\fIStartupMemoryZSwapMax\fR, +\fIMemoryPressureWatch\fR, +\fIMemoryPressureThresholdUSec\fR, +\fIRootEphemeral\fR, +\fIImportCredential\fR, +\fIMemoryKSM\fR, +\fIRootImagePolicy\fR, +\fIMountImagePolicy\fR, and +\fIExtensionImagePolicy\fR +were added in version 254\&. +.PP +\fINFTSet\fR, +\fISetLoginEnvironment\fR, +\fICoredumpReceive\fR, +\fIMemoryPeak\fR, +\fIMemorySwapCurrent\fR, +\fIMemorySwapPeak\fR, and +\fIMemoryZSwapCurrent\fR +were added in version 255\&. +.SS "Swap Unit Objects" +.PP +\fIControlGroupId\fR +and +\fIExtensionDirectories\fR +were added in version 251\&. +.PP +\fIMemoryZSwapMax\fR +and +\fILogFilterPatterns\fR +were added in version 253\&. +.PP +\fIDelegateSubgroup\fR, +\fIDefaultStartupMemoryLow\fR, +\fIStartupMemoryLow\fR, +\fIStartupMemoryHigh\fR, +\fIStartupMemoryMax\fR, +\fIStartupMemorySwapMax\fR, +\fIStartupMemoryZSwapMax\fR, +\fIMemoryPressureWatch\fR, +\fIMemoryPressureThresholdUSec\fR, +\fIRootEphemeral\fR, +\fIImportCredential\fR, +\fIMemoryKSM\fR, +\fIRootImagePolicy\fR, +\fIMountImagePolicy\fR, and +\fIExtensionImagePolicy\fR +were added in version 254\&. +.PP +\fINFTSet\fR, +\fISetLoginEnvironment\fR, +\fICoredumpReceive\fR, +\fIMemoryPeak\fR, +\fIMemorySwapCurrent\fR, +\fIMemorySwapPeak\fR, and +\fIMemoryZSwapCurrent\fR +were added in version 255\&. +.SS "Slice Unit Objects" +.PP +\fIControlGroupId\fR +was added in version 251\&. +.PP +\fIMemoryZSwapMax\fR +was added in version 253\&. +.PP +\fIDelegateSubgroup\fR, +\fIDefaultStartupMemoryLow\fR, +\fIStartupMemoryLow\fR, +\fIStartupMemoryHigh\fR, +\fIStartupMemoryMax\fR, +\fIStartupMemorySwapMax\fR, +\fIStartupMemoryZSwapMax\fR, +\fIMemoryPressureWatch\fR, and +\fIMemoryPressureThresholdUSec\fR +were added in version 254\&. +.PP +\fINFTSet\fR, +\fICoredumpReceive\fR, +\fIMemoryPeak\fR, +\fIMemorySwapCurrent\fR, +\fIMemorySwapPeak\fR, and +\fIMemoryZSwapCurrent\fR +were added in version 255\&. +.SS "Scope Unit Objects" +.PP +\fIControlGroupId\fR +was added in version 251\&. +.PP +\fIOOMPolicy\fR +and +\fIMemoryZSwapMax\fR +were added in version 253\&. +.PP +\fIDelegateSubgroup\fR, +\fIDefaultStartupMemoryLow\fR, +\fIStartupMemoryLow\fR, +\fIStartupMemoryHigh\fR, +\fIStartupMemoryMax\fR, +\fIStartupMemorySwapMax\fR, +\fIStartupMemoryZSwapMax\fR, +\fIMemoryPressureWatch\fR, and +\fIMemoryPressureThresholdUSec\fR +were added in version 254\&. +.PP +\fINFTSet\fR, +\fICoredumpReceive\fR, +\fIMemoryPeak\fR, +\fIMemorySwapCurrent\fR, +\fIMemorySwapPeak\fR, and +\fIMemoryZSwapCurrent\fR +were added in version 255\&. +.SS "Job Objects" +.PP +\fIActivationDetails\fR +was added in version 252\&. +.SH "NOTES" +.IP " 1." 4 +polkit +.RS 4 +\%https://www.freedesktop.org/software/polkit/docs/latest/ +.RE +.IP " 2." 4 +New Control Group Interface +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface +.RE +.IP " 3." 4 +The Case for the /usr Merge +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge +.RE +.IP " 4." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE diff --git a/upstream/fedora-40/man5/org.freedesktop.timedate1.5 b/upstream/fedora-40/man5/org.freedesktop.timedate1.5 new file mode 100644 index 00000000..63adbcd7 --- /dev/null +++ b/upstream/fedora-40/man5/org.freedesktop.timedate1.5 @@ -0,0 +1,217 @@ +'\" t +.TH "ORG\&.FREEDESKTOP\&.TIMEDATE1" "5" "" "systemd 255" "org.freedesktop.timedate1" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +org.freedesktop.timedate1 \- The D\-Bus interface of systemd\-timedated +.SH "INTRODUCTION" +.PP +\fBsystemd-timedated.service\fR(8) +is a system service that can be used to control the system time and related settings\&. This page describes the D\-Bus interface\&. +.SH "THE D\-BUS API" +.PP +The service exposes the following interfaces on the bus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +node /org/freedesktop/timedate1 { + interface org\&.freedesktop\&.timedate1 { + methods: + SetTime(in x usec_utc, + in b relative, + in b interactive); + SetTimezone(in s timezone, + in b interactive); + SetLocalRTC(in b local_rtc, + in b fix_system, + in b interactive); + SetNTP(in b use_ntp, + in b interactive); + ListTimezones(out as timezones); + properties: + readonly s Timezone = \*(Aq\&.\&.\&.\*(Aq; + readonly b LocalRTC = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b CanNTP = \&.\&.\&.; + readonly b NTP = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly b NTPSynchronized = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t TimeUSec = \&.\&.\&.; + @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false") + readonly t RTCTimeUSec = \&.\&.\&.; + }; + interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. }; + interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. }; +}; + +.fi +.if n \{\ +.RE +.\} + + + + + + + + + + + + + +.SS "Methods" +.PP +Use +\fBSetTime()\fR +to change the system clock\&. Pass a value of microseconds since the UNIX epoch (1 Jan 1970 UTC)\&. If +\fIrelative\fR +is true, the passed usec value will be added to the current system time\&. If it is false, the current system time will be set to the passed usec value\&. If the system time is set with this method, the RTC will be updated as well\&. +.PP +Use +\fBSetTimezone()\fR +to set the system timezone\&. Pass a value like +"Europe/Berlin" +to set the timezone\&. Valid timezones are listed in +/usr/share/zoneinfo/zone\&.tab\&. If the RTC is configured to be maintained in local time, it will be updated accordingly\&. +.PP +Use +\fBSetLocalRTC()\fR +to control whether the RTC is in local time or UTC\&. It is strongly recommended to maintain the RTC in UTC\&. However, some OSes (Windows) maintain the RTC in local time, which might make it necessary to enable this feature\&. Note that this might create various problems as daylight changes could be missed\&. If +\fIfix_system\fR +is +"true", the time from the RTC is read again and the system clock is adjusted according to the new setting\&. If +\fIfix_system\fR +is +"false", the system time is written to the RTC taking the new setting into account\&. Use +\fIfix_system=true\fR +in installers and livecds where the RTC is probably more reliable than the system time\&. Use +\fIfix_system=false\fR +in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC\&. +.PP +Use +\fBSetNTP()\fR +to control whether the system clock is synchronized with the network using +systemd\-timesyncd\&. This will enable and start or disable and stop the chosen time synchronization service\&. +.PP +\fBListTimezones()\fR +returns a list of time zones known on the local system as an array of names ("["Africa/Abidjan", "Africa/Accra", \&.\&.\&., "UTC"]")\&. +.SS "Properties" +.PP +\fITimezone\fR +shows the currently configured time zone\&. +\fILocalRTC\fR +shows whether the RTC is configured to use UTC (false), or the local time zone (true)\&. +\fICanNTP\fR +shows whether a service to perform time synchronization over the network is available, and +\fINTP\fR +shows whether such a service is enabled\&. +.PP +\fINTPSynchronized\fR +shows whether the kernel reports the time as synchronized (c\&.f\&. +\fBadjtimex\fR(3))\&. +\fITimeUSec\fR +and +\fIRTCTimeUSec\fR +show the current time on the system and in the RTC\&. The purpose of those three properties is to allow remote clients to access this information over D\-Bus\&. Local clients can access the information directly\&. +.PP +Whenever the +\fITimezone\fR +and +\fILocalRTC\fR +settings are changed via the daemon, +\fBPropertyChanged\fR +signals are sent out to which clients can subscribe\&. +.PP +Note that this service will not inform you about system time changes\&. Use +\fBtimerfd\fR(3) +with +\fBCLOCK_REALTIME\fR +and +\fBTFD_TIMER_CANCEL_ON_SET\fR +for that\&. +.SS "Security" +.PP +The +\fIinteractive\fR +boolean parameters can be used to control whether +\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2 +should interactively ask the user for authentication credentials if required\&. +.PP +The polkit action for +\fBSetTimezone()\fR +is +org\&.freedesktop\&.timedate1\&.set\-timezone\&. For +\fBSetLocalRTC()\fR +it is +org\&.freedesktop\&.timedate1\&.set\-local\-rtc, for +\fBSetTime()\fR +it is +org\&.freedesktop\&.timedate1\&.set\-time +and for +\fBSetNTP()\fR +it is +org\&.freedesktop\&.timedate1\&.set\-ntp\&. +\fBListTimezones()\fR +does not require any privileges\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.timedate1 on the bus\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ gdbus introspect \-\-system \e + \-\-dest org\&.freedesktop\&.timedate1 \e + \-\-object\-path /org/freedesktop/timedate1 + +.fi +.if n \{\ +.RE +.\} +.SH "VERSIONING" +.PP +These D\-Bus interfaces follow +\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "SEE ALSO" +.PP +\m[blue]\fBMore information on how the system clock and RTC interact\fR\m[]\&\s-2\u[3]\d\s+2 +.SH "NOTES" +.IP " 1." 4 +polkit +.RS 4 +\%https://www.freedesktop.org/software/polkit/docs/latest/ +.RE +.IP " 2." 4 +the usual interface versioning guidelines +.RS 4 +\%https://0pointer.de/blog/projects/versioning-dbus.html +.RE +.IP " 3." 4 +More information on how the system clock and RTC interact +.RS 4 +\%https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html +.RE diff --git a/upstream/fedora-40/man5/os-release.5 b/upstream/fedora-40/man5/os-release.5 new file mode 100644 index 00000000..795363d3 --- /dev/null +++ b/upstream/fedora-40/man5/os-release.5 @@ -0,0 +1,718 @@ +'\" t +.TH "OS\-RELEASE" "5" "" "systemd 255" "os-release" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +os-release, initrd-release, extension-release \- Operating system identification +.SH "SYNOPSIS" +.PP +/etc/os\-release +.PP +/usr/lib/os\-release +.PP +/etc/initrd\-release +.PP +/usr/lib/extension\-release\&.d/extension\-release\&.\fIIMAGE\fR +.SH "DESCRIPTION" +.PP +The +/etc/os\-release +and +/usr/lib/os\-release +files contain operating system identification data\&. +.PP +The format of +os\-release +is a newline\-separated list of environment\-like shell\-compatible variable assignments\&. It is possible to source the configuration from Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this means variable expansion is explicitly not supported), allowing applications to read the file without implementing a shell compatible execution engine\&. Variable assignment values must be enclosed in double or single quotes if they include spaces, semicolons or other special characters outside of A\(enZ, a\(enz, 0\(en9\&. (Assignments that do not include these special characters may be enclosed in quotes too, but this is optional\&.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes, following shell style\&. All strings should be in UTF\-8 encoding, and non\-printable characters should not be used\&. Concatenation of multiple individually quoted strings is not supported\&. Lines beginning with "#" are treated as comments\&. Blank lines are permitted and ignored\&. +.PP +The file +/etc/os\-release +takes precedence over +/usr/lib/os\-release\&. Applications should check for the former, and exclusively use its data if it exists, and only fall back to +/usr/lib/os\-release +if it is missing\&. Applications should not read data from both files at the same time\&. +/usr/lib/os\-release +is the recommended place to store OS release information as part of vendor trees\&. +/etc/os\-release +should be a relative symlink to +/usr/lib/os\-release, to provide compatibility with applications only looking at +/etc/\&. A relative symlink instead of an absolute symlink is necessary to avoid breaking the link in a chroot or initrd environment such as dracut\&. +.PP +os\-release +contains data that is defined by the operating system vendor and should generally not be changed by the administrator\&. +.PP +As this file only encodes names and identifiers it should not be localized\&. +.PP +The +/etc/os\-release +and +/usr/lib/os\-release +files might be symlinks to other files, but it is important that the file is available from earliest boot on, and hence must be located on the root file system\&. +.PP +os\-release +must not contain repeating keys\&. Nevertheless, readers should pick the entries later in the file in case of repeats, similarly to how a shell sourcing the file would\&. A reader may warn about repeating entries\&. +.PP +For a longer rationale for +os\-release +please refer to the +\m[blue]\fBAnnouncement of /etc/os\-release\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SS "/etc/initrd\-release" +.PP +In the +\m[blue]\fBinitrd\fR\m[]\&\s-2\u[2]\d\s+2, +/etc/initrd\-release +plays the same role as +os\-release +in the main system\&. Additionally, the presence of that file means that the system is in the initrd phase\&. +/etc/os\-release +should be symlinked to +/etc/initrd\-release +(or vice versa), so programs that only look for +/etc/os\-release +(as described above) work correctly\&. +.PP +The rest of this document that talks about +os\-release +should be understood to apply to +initrd\-release +too\&. +.SS "/usr/lib/extension\-release\&.d/extension\-release\&.\fIIMAGE\fR" +.PP +/usr/lib/extension\-release\&.d/extension\-release\&.\fIIMAGE\fR +plays the same role for extension images as +os\-release +for the main system, and follows the syntax and rules as described in the +\m[blue]\fBPortable Services\fR\m[]\&\s-2\u[3]\d\s+2 +page\&. The purpose of this file is to identify the extension and to allow the operating system to verify that the extension image matches the base OS\&. This is typically implemented by checking that the +\fIID=\fR +options match, and either +\fISYSEXT_LEVEL=\fR +exists and matches too, or if it is not present, +\fIVERSION_ID=\fR +exists and matches\&. This ensures ABI/API compatibility between the layers and prevents merging of an incompatible image in an overlay\&. +.PP +In order to identify the extension image itself, the same fields defined below can be added to the +extension\-release +file with a +\fISYSEXT_\fR +prefix (to disambiguate from fields used to match on the base image)\&. E\&.g\&.: +\fISYSEXT_ID=myext\fR, +\fISYSEXT_VERSION_ID=1\&.2\&.3\fR\&. +.PP +In the +extension\-release\&.\fIIMAGE\fR +filename, the +\fIIMAGE\fR +part must exactly match the file name of the containing image with the suffix removed\&. In case it is not possible to guarantee that an image file name is stable and doesn\*(Aqt change between the build and the deployment phases, it is possible to relax this check: if exactly one file whose name matches +"extension\-release\&.*" +is present in this directory, and the file is tagged with a +\fIuser\&.extension\-release\&.strict\fR +\fBxattr\fR(7) +set to the string +"0", it will be used instead\&. +.PP +The rest of this document that talks about +os\-release +should be understood to apply to +extension\-release +too\&. +.SH "OPTIONS" +.PP +The following OS identifications parameters may be set using +os\-release: +.SS "General information identifying the operating system" +.PP +\fINAME=\fR +.RS 4 +A string identifying the operating system, without a version component, and suitable for presentation to the user\&. If not set, a default of +"NAME=Linux" +may be used\&. +.sp +Examples: +"NAME=Fedora", +"NAME="Debian GNU/Linux""\&. +.RE +.PP +\fIID=\fR +.RS 4 +A lower\-case string (no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-") identifying the operating system, excluding any version information and suitable for processing by scripts or usage in generated filenames\&. If not set, a default of +"ID=linux" +may be used\&. Note that even though this string may not include characters that require shell quoting, quoting may nevertheless be used\&. +.sp +Examples: +"ID=fedora", +"ID=debian"\&. +.RE +.PP +\fIID_LIKE=\fR +.RS 4 +A space\-separated list of operating system identifiers in the same syntax as the +\fIID=\fR +setting\&. It should list identifiers of operating systems that are closely related to the local operating system in regards to packaging and programming interfaces, for example listing one or more OS identifiers the local OS is a derivative from\&. An OS should generally only list other OS identifiers it itself is a derivative of, and not any OSes that are derived from it, though symmetric relationships are possible\&. Build scripts and similar should check this variable if they need to identify the local operating system and the value of +\fIID=\fR +is not recognized\&. Operating systems should be listed in order of how closely the local operating system relates to the listed ones, starting with the closest\&. This field is optional\&. +.sp +Examples: for an operating system with +"ID=centos", an assignment of +"ID_LIKE="rhel fedora"" +would be appropriate\&. For an operating system with +"ID=ubuntu", an assignment of +"ID_LIKE=debian" +is appropriate\&. +.RE +.PP +\fIPRETTY_NAME=\fR +.RS 4 +A pretty operating system name in a format suitable for presentation to the user\&. May or may not contain a release code name or OS version of some kind, as suitable\&. If not set, a default of +"PRETTY_NAME="Linux"" +may be used +.sp +Example: +"PRETTY_NAME="Fedora 17 (Beefy Miracle)""\&. +.RE +.PP +\fICPE_NAME=\fR +.RS 4 +A CPE name for the operating system, in URI binding syntax, following the +\m[blue]\fBCommon Platform Enumeration Specification\fR\m[]\&\s-2\u[4]\d\s+2 +as proposed by the NIST\&. This field is optional\&. +.sp +Example: +"CPE_NAME="cpe:/o:fedoraproject:fedora:17"" +.RE +.PP +\fIVARIANT=\fR +.RS 4 +A string identifying a specific variant or edition of the operating system suitable for presentation to the user\&. This field may be used to inform the user that the configuration of this system is subject to a specific divergent set of rules or default configuration settings\&. This field is optional and may not be implemented on all systems\&. +.sp +Examples: +"VARIANT="Server Edition"", +"VARIANT="Smart Refrigerator Edition""\&. +.sp +Note: this field is for display purposes only\&. The +\fIVARIANT_ID\fR +field should be used for making programmatic decisions\&. +.sp +Added in version 220\&. +.RE +.PP +\fIVARIANT_ID=\fR +.RS 4 +A lower\-case string (no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-"), identifying a specific variant or edition of the operating system\&. This may be interpreted by other packages in order to determine a divergent default configuration\&. This field is optional and may not be implemented on all systems\&. +.sp +Examples: +"VARIANT_ID=server", +"VARIANT_ID=embedded"\&. +.sp +Added in version 220\&. +.RE +.SS "Information about the version of the operating system" +.PP +\fIVERSION=\fR +.RS 4 +A string identifying the operating system version, excluding any OS name information, possibly including a release code name, and suitable for presentation to the user\&. This field is optional\&. +.sp +Examples: +"VERSION=17", +"VERSION="17 (Beefy Miracle)""\&. +.RE +.PP +\fIVERSION_ID=\fR +.RS 4 +A lower\-case string (mostly numeric, no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-") identifying the operating system version, excluding any OS name information or release code name, and suitable for processing by scripts or usage in generated filenames\&. This field is optional\&. +.sp +Examples: +"VERSION_ID=17", +"VERSION_ID=11\&.04"\&. +.RE +.PP +\fIVERSION_CODENAME=\fR +.RS 4 +A lower\-case string (no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-") identifying the operating system release code name, excluding any OS name information or release version, and suitable for processing by scripts or usage in generated filenames\&. This field is optional and may not be implemented on all systems\&. +.sp +Examples: +"VERSION_CODENAME=buster", +"VERSION_CODENAME=xenial"\&. +.sp +Added in version 231\&. +.RE +.PP +\fIBUILD_ID=\fR +.RS 4 +A string uniquely identifying the system image originally used as the installation base\&. In most cases, +\fIVERSION_ID\fR +or +\fIIMAGE_ID\fR+\fIIMAGE_VERSION\fR +are updated when the entire system image is replaced during an update\&. +\fIBUILD_ID\fR +may be used in distributions where the original installation image version is important: +\fIVERSION_ID\fR +would change during incremental system updates, but +\fIBUILD_ID\fR +would not\&. This field is optional\&. +.sp +Examples: +"BUILD_ID="2013\-03\-20\&.3"", +"BUILD_ID=201303203"\&. +.sp +Added in version 200\&. +.RE +.PP +\fIIMAGE_ID=\fR +.RS 4 +A lower\-case string (no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-"), identifying a specific image of the operating system\&. This is supposed to be used for environments where OS images are prepared, built, shipped and updated as comprehensive, consistent OS images\&. This field is optional and may not be implemented on all systems, in particularly not on those that are not managed via images but put together and updated from individual packages and on the local system\&. +.sp +Examples: +"IMAGE_ID=vendorx\-cashier\-system", +"IMAGE_ID=netbook\-image"\&. +.sp +Added in version 249\&. +.RE +.PP +\fIIMAGE_VERSION=\fR +.RS 4 +A lower\-case string (mostly numeric, no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-") identifying the OS image version\&. This is supposed to be used together with +\fIIMAGE_ID\fR +described above, to discern different versions of the same image\&. +.sp +Examples: +"IMAGE_VERSION=33", +"IMAGE_VERSION=47\&.1rc1"\&. +.sp +Added in version 249\&. +.RE +.PP +To summarize: if the image updates are built and shipped as comprehensive units, +\fIIMAGE_ID\fR+\fIIMAGE_VERSION\fR +is the best fit\&. Otherwise, if updates eventually completely replace previously installed contents, as in a typical binary distribution, +\fIVERSION_ID\fR +should be used to identify major releases of the operating system\&. +\fIBUILD_ID\fR +may be used instead or in addition to +\fIVERSION_ID\fR +when the original system image version is important\&. +.SS "Presentation information and links" +.PP +\fIHOME_URL=\fR, \fIDOCUMENTATION_URL=\fR, \fISUPPORT_URL=\fR, \fIBUG_REPORT_URL=\fR, \fIPRIVACY_POLICY_URL=\fR +.RS 4 +Links to resources on the Internet related to the operating system\&. +\fIHOME_URL=\fR +should refer to the homepage of the operating system, or alternatively some homepage of the specific version of the operating system\&. +\fIDOCUMENTATION_URL=\fR +should refer to the main documentation page for this operating system\&. +\fISUPPORT_URL=\fR +should refer to the main support page for the operating system, if there is any\&. This is primarily intended for operating systems which vendors provide support for\&. +\fIBUG_REPORT_URL=\fR +should refer to the main bug reporting page for the operating system, if there is any\&. This is primarily intended for operating systems that rely on community QA\&. +\fIPRIVACY_POLICY_URL=\fR +should refer to the main privacy policy page for the operating system, if there is any\&. These settings are optional, and providing only some of these settings is common\&. These URLs are intended to be exposed in "About this system" UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a Bug", or "Privacy Policy"\&. The values should be in +\m[blue]\fBRFC3986 format\fR\m[]\&\s-2\u[5]\d\s+2, and should be +"http:" +or +"https:" +URLs, and possibly +"mailto:" +or +"tel:"\&. Only one URL shall be listed in each setting\&. If multiple resources need to be referenced, it is recommended to provide an online landing page linking all available resources\&. +.sp +Examples: +"HOME_URL="https://fedoraproject\&.org/"", +"BUG_REPORT_URL="https://bugzilla\&.redhat\&.com/""\&. +.RE +.PP +\fISUPPORT_END=\fR +.RS 4 +The date at which support for this version of the OS ends\&. (What exactly "lack of support" means varies between vendors, but generally users should assume that updates, including security fixes, will not be provided\&.) The value is a date in the ISO 8601 format +"YYYY\-MM\-DD", and specifies the first day on which support +\fIis not\fR +provided\&. +.sp +For example, +"SUPPORT_END=2001\-01\-01" +means that the system was supported until the end of the last day of the previous millennium\&. +.sp +Added in version 252\&. +.RE +.PP +\fILOGO=\fR +.RS 4 +A string, specifying the name of an icon as defined by +\m[blue]\fBfreedesktop\&.org Icon Theme Specification\fR\m[]\&\s-2\u[6]\d\s+2\&. This can be used by graphical applications to display an operating system\*(Aqs or distributor\*(Aqs logo\&. This field is optional and may not necessarily be implemented on all systems\&. +.sp +Examples: +"LOGO=fedora\-logo", +"LOGO=distributor\-logo\-opensuse" +.sp +Added in version 240\&. +.RE +.PP +\fIANSI_COLOR=\fR +.RS 4 +A suggested presentation color when showing the OS name on the console\&. This should be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA\-48 escape code for setting graphical rendition\&. This field is optional\&. +.sp +Examples: +"ANSI_COLOR="0;31"" +for red, +"ANSI_COLOR="1;34"" +for light blue, or +"ANSI_COLOR="0;38;2;60;110;180"" +for Fedora blue\&. +.RE +.PP +\fIVENDOR_NAME=\fR +.RS 4 +The name of the OS vendor\&. This is the name of the organization or company which produces the OS\&. This field is optional\&. +.sp +This name is intended to be exposed in "About this system" UIs or software update UIs when needed to distinguish the OS vendor from the OS itself\&. It is intended to be human readable\&. +.sp +Examples: +"VENDOR_NAME="Fedora Project"" +for Fedora Linux, +"VENDOR_NAME="Canonical"" +for Ubuntu\&. +.sp +Added in version 254\&. +.RE +.PP +\fIVENDOR_URL=\fR +.RS 4 +The homepage of the OS vendor\&. This field is optional\&. The +\fIVENDOR_NAME=\fR +field should be set if this one is, although clients must be robust against either field not being set\&. +.sp +The value should be in +\m[blue]\fBRFC3986 format\fR\m[]\&\s-2\u[5]\d\s+2, and should be +"http:" +or +"https:" +URLs\&. Only one URL shall be listed in the setting\&. +.sp +Examples: +"VENDOR_URL="https://fedoraproject\&.org/"", +"VENDOR_URL="https://canonical\&.com/""\&. +.sp +Added in version 254\&. +.RE +.SS "Distribution\-level defaults and metadata" +.PP +\fIDEFAULT_HOSTNAME=\fR +.RS 4 +A string specifying the hostname if +\fBhostname\fR(5) +is not present and no other configuration source specifies the hostname\&. Must be either a single DNS label (a string composed of 7\-bit ASCII lower\-case characters and no spaces or dots, limited to the format allowed for DNS domain name labels), or a sequence of such labels separated by single dots that forms a valid DNS FQDN\&. The hostname must be at most 64 characters, which is a Linux limitation (DNS allows longer names)\&. +.sp +See +\fBorg.freedesktop.hostname1\fR(5) +for a description of how +\fBsystemd-hostnamed.service\fR(8) +determines the fallback hostname\&. +.sp +Added in version 248\&. +.RE +.PP +\fIARCHITECTURE=\fR +.RS 4 +A string that specifies which CPU architecture the userspace binaries require\&. The architecture identifiers are the same as for +\fIConditionArchitecture=\fR +described in +\fBsystemd.unit\fR(5)\&. The field is optional and should only be used when just single architecture is supported\&. It may provide redundant information when used in a GPT partition with a GUID type that already encodes the architecture\&. If this is not the case, the architecture should be specified in e\&.g\&., an extension image, to prevent an incompatible host from loading it\&. +.sp +Added in version 252\&. +.RE +.PP +\fISYSEXT_LEVEL=\fR +.RS 4 +A lower\-case string (mostly numeric, no spaces or other characters outside of 0\(en9, a\(enz, "\&.", "_" and "\-") identifying the operating system extensions support level, to indicate which extension images are supported\&. See +/usr/lib/extension\-release\&.d/extension\-release\&.\fIIMAGE\fR, +\m[blue]\fBinitrd\fR\m[]\&\s-2\u[2]\d\s+2 +and +\fBsystemd-sysext\fR(8)) for more information\&. +.sp +Examples: +"SYSEXT_LEVEL=2", +"SYSEXT_LEVEL=15\&.14"\&. +.sp +Added in version 248\&. +.RE +.PP +\fICONFEXT_LEVEL=\fR +.RS 4 +Semantically the same as +\fISYSEXT_LEVEL=\fR +but for confext images\&. See +/etc/extension\-release\&.d/extension\-release\&.\fIIMAGE\fR +for more information\&. +.sp +Examples: +"CONFEXT_LEVEL=2", +"CONFEXT_LEVEL=15\&.14"\&. +.sp +Added in version 254\&. +.RE +.PP +\fISYSEXT_SCOPE=\fR +.RS 4 +Takes a space\-separated list of one or more of the strings +"system", +"initrd" +and +"portable"\&. This field is only supported in +extension\-release\&.d/ +files and indicates what environments the system extension is applicable to: i\&.e\&. to regular systems, to initrds, or to portable service images\&. If unspecified, +"SYSEXT_SCOPE=system portable" +is implied, i\&.e\&. any system extension without this field is applicable to regular systems and to portable service environments, but not to initrd environments\&. +.sp +Added in version 250\&. +.RE +.PP +\fICONFEXT_SCOPE=\fR +.RS 4 +Semantically the same as +\fISYSEXT_SCOPE=\fR +but for confext images\&. +.sp +Added in version 254\&. +.RE +.PP +\fIPORTABLE_PREFIXES=\fR +.RS 4 +Takes a space\-separated list of one or more valid prefix match strings for the +\m[blue]\fBPortable Services\fR\m[]\&\s-2\u[3]\d\s+2 +logic\&. This field serves two purposes: it is informational, identifying portable service images as such (and thus allowing them to be distinguished from other OS images, such as bootable system images)\&. It is also used when a portable service image is attached: the specified or implied portable service prefix is checked against the list specified here, to enforce restrictions how images may be attached to a system\&. +.sp +Added in version 250\&. +.RE +.SS "Notes" +.PP +If you are using this file to determine the OS or a specific version of it, use the +\fIID\fR +and +\fIVERSION_ID\fR +fields, possibly with +\fIID_LIKE\fR +as fallback for +\fIID\fR\&. When looking for an OS identification string for presentation to the user use the +\fIPRETTY_NAME\fR +field\&. +.PP +Note that operating system vendors may choose not to provide version information, for example to accommodate for rolling releases\&. In this case, +\fIVERSION\fR +and +\fIVERSION_ID\fR +may be unset\&. Applications should not rely on these fields to be set\&. +.PP +Operating system vendors may extend the file format and introduce new fields\&. It is highly recommended to prefix new fields with an OS specific name in order to avoid name clashes\&. Applications reading this file must ignore unknown fields\&. +.PP +Example: +"DEBIAN_BTS="debbugs://bugs\&.debian\&.org/""\&. +.PP +Container and sandbox runtime managers may make the host\*(Aqs identification data available to applications by providing the host\*(Aqs +/etc/os\-release +(if available, otherwise +/usr/lib/os\-release +as a fallback) as +/run/host/os\-release\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&os\-release file for Fedora Workstation\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +NAME=Fedora +VERSION="32 (Workstation Edition)" +ID=fedora +VERSION_ID=32 +PRETTY_NAME="Fedora 32 (Workstation Edition)" +ANSI_COLOR="0;38;2;60;110;180" +LOGO=fedora\-logo\-icon +CPE_NAME="cpe:/o:fedoraproject:fedora:32" +HOME_URL="https://fedoraproject\&.org/" +DOCUMENTATION_URL="https://docs\&.fedoraproject\&.org/en\-US/fedora/f32/system\-administrators\-guide/" +SUPPORT_URL="https://fedoraproject\&.org/wiki/Communicating_and_getting_help" +BUG_REPORT_URL="https://bugzilla\&.redhat\&.com/" +REDHAT_BUGZILLA_PRODUCT="Fedora" +REDHAT_BUGZILLA_PRODUCT_VERSION=32 +REDHAT_SUPPORT_PRODUCT="Fedora" +REDHAT_SUPPORT_PRODUCT_VERSION=32 +PRIVACY_POLICY_URL="https://fedoraproject\&.org/wiki/Legal:PrivacyPolicy" +VARIANT="Workstation Edition" +VARIANT_ID=workstation +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&extension\-release file for an extension for Fedora Workstation 32\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +ID=fedora +VERSION_ID=32 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Reading os\-release in sh(1)\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +#!/bin/sh \-eu +# SPDX\-License\-Identifier: MIT\-0 + +test \-e /etc/os\-release && os_release=\*(Aq/etc/os\-release\*(Aq || os_release=\*(Aq/usr/lib/os\-release\*(Aq +\&. "${os_release}" + +echo "Running on ${PRETTY_NAME:\-Linux}" + +if [ "${ID:\-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]; then + echo "Looks like Debian!" +fi +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&Reading os\-release in python(1) (versions >= 3\&.10)\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +#!/usr/bin/python +# SPDX\-License\-Identifier: MIT\-0 + +import platform +os_release = platform\&.freedesktop_os_release() + +pretty_name = os_release\&.get(\*(AqPRETTY_NAME\*(Aq, \*(AqLinux\*(Aq) +print(f\*(AqRunning on {pretty_name!r}\*(Aq) + +if \*(Aqfedora\*(Aq in [os_release\&.get(\*(AqID\*(Aq, \*(Aqlinux\*(Aq), + *os_release\&.get(\*(AqID_LIKE\*(Aq, \*(Aq\*(Aq)\&.split()]: + print(\*(AqLooks like Fedora!\*(Aq) +.fi +.if n \{\ +.RE +.\} +.PP +See docs for +\m[blue]\fB\fBplatform\&.freedesktop_os_release\fR\fR\m[]\&\s-2\u[7]\d\s+2 +for more details\&. +.PP +\fBExample\ \&5.\ \&Reading os\-release in python(1) (any version)\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +#!/usr/bin/python +# SPDX\-License\-Identifier: MIT\-0 + +import ast +import re +import sys + +def read_os_release(): + try: + filename = \*(Aq/etc/os\-release\*(Aq + f = open(filename) + except FileNotFoundError: + filename = \*(Aq/usr/lib/os\-release\*(Aq + f = open(filename) + + for line_number, line in enumerate(f, start=1): + line = line\&.rstrip() + if not line or line\&.startswith(\*(Aq#\*(Aq): + continue + m = re\&.match(r\*(Aq([A\-Z][A\-Z_0\-9]+)=(\&.*)\*(Aq, line) + if m: + name, val = m\&.groups() + if val and val[0] in \*(Aq"\e\*(Aq\*(Aq: + val = ast\&.literal_eval(val) + yield name, val + else: + print(f\*(Aq{filename}:{line_number}: bad line {line!r}\*(Aq, + file=sys\&.stderr) + +os_release = dict(read_os_release()) + +pretty_name = os_release\&.get(\*(AqPRETTY_NAME\*(Aq, \*(AqLinux\*(Aq) +print(f\*(AqRunning on {pretty_name!r}\*(Aq) + +if \*(Aqdebian\*(Aq in [os_release\&.get(\*(AqID\*(Aq, \*(Aqlinux\*(Aq), + *os_release\&.get(\*(AqID_LIKE\*(Aq, \*(Aq\*(Aq)\&.split()]: + print(\*(AqLooks like Debian!\*(Aq) +.fi +.if n \{\ +.RE +.\} +.PP +Note that the above version that uses the built\-in implementation is preferred in most cases, and the open\-coded version here is provided for reference\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBlsb_release\fR(1), +\fBhostname\fR(5), +\fBmachine-id\fR(5), +\fBmachine-info\fR(5) +.SH "NOTES" +.IP " 1." 4 +Announcement of /etc/os-release +.RS 4 +\%https://0pointer.de/blog/projects/os-release +.RE +.IP " 2." 4 +initrd +.RS 4 +\%https://docs.kernel.org/admin-guide/initrd.html +.RE +.IP " 3." 4 +Portable Services +.RS 4 +\%https://systemd.io/PORTABLE_SERVICES +.RE +.IP " 4." 4 +Common Platform Enumeration Specification +.RS 4 +\%http://scap.nist.gov/specifications/cpe/ +.RE +.IP " 5." 4 +RFC3986 format +.RS 4 +\%https://tools.ietf.org/html/rfc3986 +.RE +.IP " 6." 4 +freedesktop.org Icon Theme Specification +.RS 4 +\%https://standards.freedesktop.org/icon-theme-spec/latest +.RE +.IP " 7." 4 + + \fBplatform.freedesktop_os_release\fR +.RS 4 +\%https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release +.RE diff --git a/upstream/fedora-40/man5/pacman.conf.5 b/upstream/fedora-40/man5/pacman.conf.5 new file mode 100644 index 00000000..9e994376 --- /dev/null +++ b/upstream/fedora-40/man5/pacman.conf.5 @@ -0,0 +1,595 @@ +'\" t +.\" Title: pacman.conf +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2024-01-25 +.\" Manual: Pacman Manual +.\" Source: Pacman 6.0.2 +.\" Language: English +.\" +.TH "PACMAN\&.CONF" "5" "2024\-01\-25" "Pacman 6\&.0\&.2" "Pacman Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pacman.conf \- pacman package manager configuration file +.SH "SYNOPSIS" +.sp +/etc/pacman\&.conf +.SH "DESCRIPTION" +.sp +Pacman, using \fBlibalpm\fR(3), will attempt to read pacman\&.conf each time it is invoked\&. This configuration file is divided into sections or repositories\&. Each section defines a package repository that pacman can use when searching for packages in \fI\-\-sync\fR mode\&. The exception to this is the options section, which defines global options\&. +.sp +Comments are only supported by beginning a line with the hash (#) symbol\&. Comments cannot begin in the middle of a line\&. +.SH "EXAMPLE" +.sp +.if n \{\ +.RS 4 +.\} +.nf +# +# pacman\&.conf +# +[options] +NoUpgrade = etc/passwd etc/group etc/shadow +NoUpgrade = etc/fstab + +[core] +Include = /etc/pacman\&.d/core + +[custom] +Server = file:///home/pkgs +.fi +.if n \{\ +.RE +.\} +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +Each directive must be in CamelCase\&. If the case isn\(cqt respected, the directive won\(cqt be recognized\&. For example\&. noupgrade or NOUPGRADE will not work\&. +.sp .5v +.RE +.SH "OPTIONS" +.PP +\fBRootDir =\fR /path/to/root/dir +.RS 4 +Set the default root directory for pacman to install to\&. This option is used if you want to install a package on a temporary mounted partition which is "owned" by another system, or for a chroot install\&. +\fBNOTE\fR: If database path or log file are not specified on either the command line or in +\fBpacman.conf\fR(5), their default location will be inside this root path\&. +.RE +.PP +\fBDBPath =\fR /path/to/db/dir +.RS 4 +Overrides the default location of the toplevel database directory\&. The default is +/var/lib/pacman/\&. Most users will not need to set this option\&. +\fBNOTE\fR: if specified, this is an absolute path and the root path is not automatically prepended\&. +.RE +.PP +\fBCacheDir =\fR /path/to/cache/dir +.RS 4 +Overrides the default location of the package cache directory\&. The default is +/var/cache/pacman/pkg/\&. Multiple cache directories can be specified, and they are tried in the order they are listed in the config file\&. If a file is not found in any cache directory, it will be downloaded to the first cache directory with write access\&. +\fBNOTE\fR: this is an absolute path, the root path is not automatically prepended\&. +.RE +.PP +\fBHookDir =\fR /path/to/hook/dir +.RS 4 +Add directories to search for alpm hooks in addition to the system hook directory (/usr/share/libalpm/hooks/)\&. The default is +/etc/pacman\&.d/hooks\&. Multiple directories can be specified with hooks in later directories taking precedence over hooks in earlier directories\&. +\fBNOTE\fR: this is an absolute path, the root path is not automatically prepended\&. For more information on the alpm hooks, see +\fBalpm-hooks\fR(5)\&. +.RE +.PP +\fBGPGDir =\fR /path/to/gpg/dir +.RS 4 +Overrides the default location of the directory containing configuration files for GnuPG\&. The default is +/etc/pacman\&.d/gnupg/\&. This directory should contain two files: +pubring\&.gpg +and +trustdb\&.gpg\&. +pubring\&.gpg +holds the public keys of all packagers\&. +trustdb\&.gpg +contains a so\-called trust database, which specifies that the keys are authentic and trusted\&. +\fBNOTE\fR: this is an absolute path, the root path is not automatically prepended\&. +.RE +.PP +\fBLogFile =\fR /path/to/log/file +.RS 4 +Overrides the default location of the pacman log file\&. The default is +/var/log/pacman\&.log\&. This is an absolute path and the root directory is not prepended\&. +.RE +.PP +\fBHoldPkg =\fR package \&... +.RS 4 +If a user tries to +\fI\-\-remove\fR +a package that\(cqs listed in +HoldPkg, pacman will ask for confirmation before proceeding\&. Shell\-style glob patterns are allowed\&. +.RE +.PP +\fBIgnorePkg =\fR package \&... +.RS 4 +Instructs pacman to ignore any upgrades for this package when performing a +\fI\-\-sysupgrade\fR\&. Shell\-style glob patterns are allowed\&. +.RE +.PP +\fBIgnoreGroup =\fR group \&... +.RS 4 +Instructs pacman to ignore any upgrades for all packages in this group when performing a +\fI\-\-sysupgrade\fR\&. Shell\-style glob patterns are allowed\&. +.RE +.PP +\fBInclude =\fR /path/to/config/file +.RS 4 +Include another configuration file\&. This file can include repositories or general configuration options\&. Wildcards in the specified paths will get expanded based on +\fBglob\fR(7) +rules\&. +.RE +.PP +\fBArchitecture =\fR auto &| i686 &| x86_64 | \&... +.RS 4 +If set, pacman will only allow installation of packages with the given architectures (e\&.g\&. +\fIi686\fR, +\fIx86_64\fR, etc)\&. The special value +\fIauto\fR +will use the system architecture, provided via \(lquname \-m\(rq\&. If unset, no architecture checks are made\&. +\fBNOTE\fR: Packages with the special architecture +\fIany\fR +can always be installed, as they are meant to be architecture independent\&. +.RE +.PP +\fBXferCommand =\fR /path/to/command %u +.RS 4 +If set, an external program will be used to download all remote files\&. All instances of +%u +will be replaced with the download URL\&. If present, instances of +%o +will be replaced with the local filename, plus a \(lq\&.part\(rq extension, which allows programs like wget to do file resumes properly\&. + +This option is useful for users who experience problems with built\-in HTTP/FTP support, or need the more advanced proxy support that comes with utilities like wget\&. +.RE +.PP +\fBNoUpgrade =\fR file \&... +.RS 4 +All files listed with a +NoUpgrade +directive will never be touched during a package install/upgrade, and the new files will be installed with a +\fI\&.pacnew\fR +extension\&. These files refer to files in the package archive, so do not include the leading slash (the RootDir) when specifying them\&. Shell\-style glob patterns are allowed\&. It is possible to invert matches by prepending a file with an exclamation mark\&. Inverted files will result in previously blacklisted files being whitelisted again\&. Subsequent matches will override previous ones\&. A leading literal exclamation mark or backslash needs to be escaped\&. +.RE +.PP +\fBNoExtract =\fR file \&... +.RS 4 +All files listed with a +NoExtract +directive will never be extracted from a package into the filesystem\&. This can be useful when you don\(cqt want part of a package to be installed\&. For example, if your httpd root uses an +\fIindex\&.php\fR, then you would not want the +\fIindex\&.html\fR +file to be extracted from the +\fIapache\fR +package\&. These files refer to files in the package archive, so do not include the leading slash (the RootDir) when specifying them\&. Shell\-style glob patterns are allowed\&. It is possible to invert matches by prepending a file with an exclamation mark\&. Inverted files will result in previously blacklisted files being whitelisted again\&. Subsequent matches will override previous ones\&. A leading literal exclamation mark or backslash needs to be escaped\&. +.RE +.PP +\fBCleanMethod =\fR KeepInstalled &| KeepCurrent +.RS 4 +If set to +KeepInstalled +(the default), the +\fI\-Sc\fR +operation will clean packages that are no longer installed (not present in the local database)\&. If set to +KeepCurrent, +\fI\-Sc\fR +will clean outdated packages (not present in any sync database)\&. The second behavior is useful when the package cache is shared among multiple machines, where the local databases are usually different, but the sync databases in use could be the same\&. If both values are specified, packages are only cleaned if not installed locally and not present in any known sync database\&. +.RE +.PP +\fBSigLevel =\fR \&... +.RS 4 +Set the default signature verification level\&. For more information, see +Package and Database Signature Checking +below\&. +.RE +.PP +\fBLocalFileSigLevel =\fR \&... +.RS 4 +Set the signature verification level for installing packages using the "\-U" operation on a local file\&. Uses the value from SigLevel as the default\&. +.RE +.PP +\fBRemoteFileSigLevel =\fR \&... +.RS 4 +Set the signature verification level for installing packages using the "\-U" operation on a remote file URL\&. Uses the value from SigLevel as the default\&. +.RE +.PP +\fBUseSyslog\fR +.RS 4 +Log action messages through syslog()\&. This will insert log entries into +/var/log/messages +or equivalent\&. +.RE +.PP +\fBColor\fR +.RS 4 +Automatically enable colors only when pacman\(cqs output is on a tty\&. +.RE +.PP +\fBNoProgressBar\fR +.RS 4 +Disables progress bars\&. This is useful for terminals which do not support escape characters\&. +.RE +.PP +\fBCheckSpace\fR +.RS 4 +Performs an approximate check for adequate available disk space before installing packages\&. +.RE +.PP +\fBVerbosePkgLists\fR +.RS 4 +Displays name, version and size of target packages formatted as a table for upgrade, sync and remove operations\&. +.RE +.PP +\fBDisableDownloadTimeout\fR +.RS 4 +Disable defaults for low speed limit and timeout on downloads\&. Use this if you have issues downloading files with proxy and/or security gateway\&. +.RE +.PP +\fBParallelDownloads =\fR \&... +.RS 4 +Specifies number of concurrent download streams\&. The value needs to be a positive integer\&. If this config option is not set then only one download stream is used (i\&.e\&. downloads happen sequentially)\&. +.RE +.SH "REPOSITORY SECTIONS" +.sp +Each repository section defines a section name and at least one location where the packages can be found\&. The section name is defined by the string within square brackets (the two above are \fIcore\fR and \fIcustom\fR)\&. Repository names must be unique and the name \fIlocal\fR is reserved for the database of installed packages\&. Locations are defined with the \fIServer\fR directive and follow a URL naming structure\&. If you want to use a local directory, you can specify the full path with a \(lqfile://\(rq prefix, as shown above\&. +.sp +A common way to define DB locations utilizes the \fIInclude\fR directive\&. For each repository defined in the configuration file, a single \fIInclude\fR directive can contain a file that lists the servers for that repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[core] +# use this server first +Server = ftp://ftp\&.archlinux\&.org/$repo/os/$arch +# next use servers as defined in the mirrorlist below +Include = {sysconfdir}/pacman\&.d/mirrorlist +.fi +.if n \{\ +.RE +.\} +.sp +The order of repositories in the configuration files matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number\&. +.PP +\fBInclude =\fR path +.RS 4 +Include another config file\&. This file can include repositories or general configuration options\&. Wildcards in the specified paths will get expanded based on +\fBglob\fR(7) +rules\&. +.RE +.PP +\fBServer =\fR url +.RS 4 +A full URL to a location where the database, packages, and signatures (if available) for this repository can be found\&. +.sp +During parsing, pacman will define the +$repo +variable to the name of the current section\&. This is often utilized in files specified using the +\fIInclude\fR +directive so all repositories can use the same mirrorfile\&. pacman also defines the +$arch +variable to the first (or only) value of the +Architecture +option, so the same mirrorfile can even be used for different architectures\&. +.RE +.PP +\fBSigLevel =\fR \&... +.RS 4 +Set the signature verification level for this repository\&. For more information, see +Package and Database Signature Checking +below\&. +.RE +.PP +\fBUsage =\fR \&... +.RS 4 +Set the usage level for this repository\&. This option takes a list of tokens which must be at least one of the following: +.PP +\fBSync\fR +.RS 4 +Enables refreshes for this repository\&. +.RE +.PP +\fBSearch\fR +.RS 4 +Enables searching for this repository\&. +.RE +.PP +\fBInstall\fR +.RS 4 +Enables installation of packages from this repository during a +\fI\-\-sync\fR +operation\&. +.RE +.PP +\fBUpgrade\fR +.RS 4 +Allows this repository to be a valid source of packages when performing a +\fI\-\-sysupgrade\fR\&. +.RE +.PP +\fBAll\fR +.RS 4 +Enables all of the above features for the repository\&. This is the default if not specified\&. +.sp +Note that an enabled repository can be operated on explicitly, regardless of the Usage level set\&. +.RE +.RE +.SH "PACKAGE AND DATABASE SIGNATURE CHECKING" +.sp +The \fISigLevel\fR directive is valid in both the [options] and repository sections\&. If used in [options], it sets a default value for any repository that does not provide the setting\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBNever\fR, no signature checking will take place\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBOptional\fR +, signatures will be checked when present, but unsigned databases and packages will also be accepted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBRequired\fR, signatures will be required on all packages and databases\&. +.RE +.sp +Alternatively, you can get more fine\-grained control by combining some of the options and prefixes described below\&. All options in a config file are processed in top\-to\-bottom, left\-to\-right fashion, where later options override and/or supplement earlier ones\&. If \fISigLevel\fR is specified in a repository section, the starting value is that from the [options] section, or the built\-in system default as shown below if not specified\&. +.sp +The options are split into two main groups, described below\&. Terms used such as \(lqmarginally trusted\(rq are terms used by GnuPG, for more information please consult \fBgpg\fR(1)\&. +.PP +When to Check +.RS 4 +These options control if and when signature checks should take place\&. +.PP +\fBNever\fR +.RS 4 +All signature checking is suppressed, even if signatures are present\&. +.RE +.PP +\fBOptional\fR (default) +.RS 4 +Signatures are checked if present; absence of a signature is not an error\&. An invalid signature is a fatal error, as is a signature from a key not in the keyring\&. +.RE +.PP +\fBRequired\fR +.RS 4 +Signatures are required; absence of a signature or an invalid signature is a fatal error, as is a signature from a key not in the keyring\&. +.RE +.RE +.PP +What is Allowed +.RS 4 +These options control what signatures are viewed as permissible\&. Note that neither of these options allows acceptance of invalid or expired signatures, or those from revoked keys\&. +.PP +\fBTrustedOnly\fR (default) +.RS 4 +If a signature is checked, it must be in the keyring and fully trusted; marginal trust does not meet this criteria\&. +.RE +.PP +\fBTrustAll\fR +.RS 4 +If a signature is checked, it must be in the keyring, but is not required to be assigned a trust level (e\&.g\&., unknown or marginal trust)\&. +.RE +.RE +.sp +Options in both groups can additionally be prefixed with either \fBPackage\fR or \fBDatabase\fR, which will cause it to only take effect on the specified object type\&. For example, PackageTrustAll would allow marginal and unknown trust level signatures for packages\&. +.sp +The built\-in default is the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SigLevel = Optional TrustedOnly +.fi +.if n \{\ +.RE +.\} +.SH "USING YOUR OWN REPOSITORY" +.sp +If you have numerous custom packages of your own, it is often easier to generate your own custom local repository than install them all with the \fI\-\-upgrade\fR option\&. All you need to do is generate a compressed package database in the directory with these packages so pacman can find it when run with \fI\-\-refresh\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +repo\-add /home/pkgs/custom\&.db\&.tar\&.gz /home/pkgs/*\&.pkg\&.tar\&.gz +.fi +.if n \{\ +.RE +.\} +.sp +The above command will generate a compressed database named \fI/home/pkgs/custom\&.db\&.tar\&.gz\fR\&. Note that the database must be of the form defined in the configuration file and \fI{ext}\fR is a valid compression type as documented in \fBrepo-add\fR(8)\&. That\(cqs it! Now configure your custom section in the configuration file as shown in the config example above\&. Pacman will now use your package repository\&. If you add new packages to the repository, remember to re\-generate the database and use pacman\(cqs \fI\-\-refresh\fR option\&. +.sp +For more information on the repo\-add command, see \(lqrepo\-add \-\-help\(rq or \fBrepo-add\fR(8)\&. +.SH "SEE ALSO" +.sp +\fBpacman\fR(8), \fBlibalpm\fR(3) +.sp +See the pacman website at https://archlinux\&.org/pacman/ for current information on pacman and its related tools\&. +.SH "BUGS" +.sp +Bugs? You must be kidding; there are no bugs in this software\&. But if we happen to be wrong, submit a bug report with as much detail as possible at the Arch Linux Bug Tracker in the Pacman section\&. +.SH "AUTHORS" +.sp +Current maintainers: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Allan McRae +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Andrew Gregory +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Eli Schwartz +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Morgan Adamiec +.RE +.sp +Past major contributors: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Judd Vinet +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aurelien Foret +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Aaron Griffin +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dan McGee +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Xavier Chantry +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Nagy Gabor +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Dave Reisner +.RE +.sp +For additional contributors, use git shortlog \-s on the pacman\&.git repository\&. diff --git a/upstream/fedora-40/man5/pam.5 b/upstream/fedora-40/man5/pam.5 new file mode 100644 index 00000000..9e8174a5 --- /dev/null +++ b/upstream/fedora-40/man5/pam.5 @@ -0,0 +1,331 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "PAM format specification" 5 "27 November 2013" "netpbm documentation" + +.SH NAME +pam - Netpbm common 2-dimensional bitmap format + +.UN general +.SH GENERAL +.PP +The PAM image format is a lowest common denominator 2 dimensional map +format. +.PP +It is designed to be used for any of myriad kinds of graphics, but can +theoretically be used for any kind of data that is arranged as a two +dimensional rectangular array. Actually, from another perspective it +can be seen as a format for data arranged as a three dimensional +array. +.PP +The name "PAM" is an acronym derived from "Portable +Arbitrary Map." This derivation makes more sense if you consider +it in the context of the other Netpbm format names: PBM, PGM, and PPM. +.PP +This format does not define the meaning of the data at any particular +point in the array. It could be red, green, and blue light +intensities such that the array represents a visual image, or it could +be the same red, green, and blue components plus a transparency +component, or it could contain annual rainfalls for places on the +surface of the Earth. Any process that uses the PAM format must +further define the format to specify the meanings of the data. +.PP +A PAM image describes a two dimensional grid of tuples. The tuples are +arranged in rows and columns. The width of the image is the number of +columns. The height of the image is the number of rows. All rows are the +same width and all columns are the same height. The tuples may have any +degree, but all tuples have the same degree. The degree of the tuples is +called the depth of the image. Each member of a tuple is called a sample. A +sample is an unsigned integer which represents a locus along a scale which +starts at zero and ends at a certain maximum value called the maxval. The +maxval is the same for every sample in the image. The two dimensional array +of all the Nth samples of each tuple is called the Nth plane or Nth channel of +the image. +.PP +Though the basic format does not assign any meaning to the tuple values, it +does include an optional string that describes that meaning. The +contents of this string, called the tuple type, are arbitrary from the +point of view of the basic PAM format, but users of the format may assign +meaning to it by convention so they can identify their particular +implementations of the PAM format. Some tuple types are defined as +official subformats of PAM. See +.UR #tupletype +Defined Tuple Types +.UE +\&. + +.UN format_universe +.SH The Confusing Universe of Netpbm Formats +.PP +It is easy to get confused about the relationship between the PAM +format and PBM, PGM, PPM, and PNM. Here is a little enlightenment: +.PP +"PNM" is not really a format. It is a shorthand for the PBM, PGM, +and PPM formats collectively. It is also the name of a group of +library functions that can each handle all three of those formats. +.PP +"PAM" is in fact a fourth format. But it is so general +that you can represent the same information in a PAM image as you can +in a PBM, PGM, or PPM image. And in fact a program that is designed +to read PBM, PGM, or PPM and does so with a recent version of the +Netpbm library will read an equivalent PAM image just fine and the +program will never know the difference. +.PP +To confuse things more, there is a collection of library routines +called the "pam" functions that read and write the PAM +format, but also read and write the PBM, PGM, and PPM formats. They +do this because the latter formats are much older and more popular, so +even a new program must work with them. Having the library handle all +the formats makes it convenient to write programs that use the newer +PAM format as well. + +.UN layout +.SH THE LAYOUT +.PP +A convenient way to read and write the PAM format accurately is via the +.BR "libnetpbm" (1)\c +\& C subroutine library. +.PP +A PAM file consists of a sequence of one or more PAM images. There are +no data, delimiters, or padding before, after, or between images. +.PP +Each PAM image consists of a header followed immediately by a raster. +.PP +Here is an example header: + +.nf + +P7 +WIDTH 227 +HEIGHT 149 +DEPTH 3 +MAXVAL 255 +TUPLTYPE RGB +ENDHDR + + +.fi +.PP +The header begins with the ASCII characters "P7" followed +by newline. This is the magic number. +.PP +Note: \fBxv\fP thumbnail images also start with the "P7" magic number. +(This and PAM were independent extensions to the Netpbm formats). The rest +of the format makes it easy to distinguish PAM from that format, though). +.PP +The header continues with an arbitrary number of lines of ASCII +text. Each line ends with and is delimited by a newline character. +.PP +Each header line consists of zero or more whitespace-delimited +tokens or begins with "#". If it begins with "#" +it is a comment and the rest of this specification does not apply to +it. +.PP +A header line which has zero tokens is valid but has no meaning. +.PP +The type of header line is identified by its first token, which is +8 characters or less: + + +.TP +\fBENDHDR \fP +This is the last line in the header. The header must contain +exactly one of these header lines. + +.TP +\fBHEIGHT \fP +The second token is a decimal number representing the height +of the image (number of rows). The header must contain exactly one +of these header lines. + +.TP +\fBWIDTH\fP +The second token is a decimal number representing the width of the +image (number of columns). The header must contain exactly one of +these header lines. + +.TP +\fBDEPTH\fP +The second token is a decimal number representing the depth of the +image (number of planes or channels). The header must contain exactly +one of these header lines. + +.TP +\fBMAXVAL\fP +The second token is a decimal number representing the maxval of the image. +The header must contain exactly one of these header lines. + +.TP +\fBTUPLTYPE\fP +The header may contain any number of these header lines, including +zero. The rest of the line is part of the tuple type. The rest of +the line is not tokenized, but the tuple type does not include any +white space immediately following \fBTUPLTYPE \fP or at the very end +of the line. It does not include a newline. There must be something +other than white space after the \fBTUPLTYPE\fP token. +.sp +If there are multiple \fBTUPLTYPE\fP header lines, the tuple type +is the concatenation of the values from each of them, separated by a +single blank, in the order in which they appear in the header. If +there are no \fBTUPLTYPE\fP header lines the tuple type is the null +string. + + +.PP +The raster consists of each row of the image, in order from top to bottom, +consecutive with no delimiter of any kind between, before, or after, rows. +.PP +Each row consists of every tuple in the row, in order from left to +right, consecutive with no delimiter of any kind between, before, or +after, tuples. +.PP +Each tuple consists of every sample in the tuple, in order, +consecutive with no delimiter of any kind between, before, or after, +samples. +.PP +Each sample consists of an unsigned integer in pure binary format, +with the most significant byte first. The number of bytes is the +minimum number of bytes required to represent the maxval of the image. +.PP +The character referred to as "newline" herein is the +character known in ASCII as Line Feed or LF. + +.UN limitations +.SH LIMITATIONS +.PP +Height, width, depth, and maxval are at least 1. +.PP +Height, width, and depth have no defined maximum, but processors and +generators of images usually have their own limitations. +.PP +The maxval of an image is never greater than 65535. (The reason it is +limited is to make it easier to build an image processor, in which +intermediate arithmetic values often have to fit within 31 or 32 bits). +There was no specified limitation before October, 2005, but essentially +all implementations have always observed it. + +.UN tupletype +.SH DEFINED TUPLE TYPES +.PP +Some tuple types are defined in this specification to specify +official subformats of PAM for especially popular applications of the +format. Users of the format may also define their own tuple types, +and thus their own subformats. +.PP +Tuple type affects \fIonly\fP the meanings of the samples (which are +unsigned integers) in the tuples of the image. It does not affect how the +samples or tuples are encoded. Tuple type may affect the meaning of a tuple's +position in the array (e.g. it may indicate in a visual image that a tuple +in Row 1 is one at the top of the image rather than the bottom). +.PP +Tuple type never determines how many samples are in a tuple (that is +instead determined by the DEPTH header line). Tuple type could be said to +imply a depth (number of samples per tuple) because certain tuple types are +valid only in combination with certain DEPTH values, but it is good +programming practice to use DEPTH for the depth when decoding the raster and +separately validate that the depth is consistent with the tuple type. Also, +it is good practice to accept a depth that is too great and just ignore the +higher numbered planes. + +.UN visual +.SS PAM Used For Visual Images +.PP +A common use of PAM images is to represent visual images such +as are typically represented by images in the older and more concrete +PBM, PGM, and PPM formats. + +.B Black And White +.PP +A black and white image, such as would alternatively be represented by a +PBM image, has a tuple type of "BLACKANDWHITE". Such a PAM image has a depth +of 1 and maxval 1 where the one sample in each tuple is 0 to represent a black +pixel and 1 to represent a white one. The maxval, height, width, and order of +tuples in the raster bear the obvious relationship to those of the equivalent +PGM image. +.PP +Note that in the PBM format, a sample value of zero means white, but in +PAM, zero means black. + +.B Grayscale +.PP +A grayscale image, such as would alternatively be represented by a PGM +image, has a tuple type of "GRAYSCALE". Such a PAM image has a depth of 1. +The maxval, height, width, and raster bear the obvious relationship to those +of the equivalent PGM image. + +.B Color +.PP +A color image, such as would alternatively be represented by a PPM image, +has a tuple type of "RGB". Such a PAM image has a depth of 3. The maxval, +height, width, and raster bear the obvious relationship to those of the PPM +image. The first plane represents red, the second green, and the third blue. + +.B Transparent +.PP +Each of the visual image formats mentioned above has a variation that +contains transparency information. In that variation, the tuple type +has "_ALPHA" added to it (e.g. "RGB_ALPHA") and one +more plane. The highest numbered plane is the opacity plane (sometimes +called an alpha plane or transparency plane). +.PP +In this kind of image, the color represented by a pixel is actually +a combination of an explicitly specified foreground color and a background +color to be identified later. +.PP +The planes other than the opacity plane describe the foreground +color. A sample in the opacity plane tells how opaque the pixel is, by +telling what fraction of the pixel's light comes from the foreground +color. The rest of the pixel's light comes from the (unspecified) +background color. +.PP +For example, in a GRAYSCALE_ALPHA image, assume Plane 0 indicates +a gray tone 60% of white and Plane 1 indicates opacity 25%. The +foreground color is the 60% gray, and 25% of that contributes to the +ultimate color of the pixel. The other 75% comes from some background +color. So let's assume further that the background color of the pixel +is full white. Then the color of the pixel is 90% of white: 25% of +the foreground 60%, plus 75% of the background 100%. +.PP +The sample value is the opacity fraction just described, as a fraction +of the maxval. Note that it is \fInot\fP gamma-adjusted like the +foreground color samples. + + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PBM has been +registered with IANA, but the unofficial value +image/x-portable-arbitrarymap is +assigned by this specification, to be consistent with conventional values for +the older Netpbm formats. + +.UN filename +.SH FILE NAME +.PP +The conventional suffix for the name of a PAM file is ".pam". +But this is not required. + + +.UN seealso +.SH SEE ALSO +.BR "Netpbm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +.BR "pnm" (1)\c +\&, +.BR "libnetpbm" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pam.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man5/passwd.5 b/upstream/fedora-40/man5/passwd.5 new file mode 100644 index 00000000..e4bcb8e0 --- /dev/null +++ b/upstream/fedora-40/man5/passwd.5 @@ -0,0 +1,160 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 10:46:28 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 18:12:27 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jun 18 01:53:57 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Jan 5 20:24:40 MET 1998 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.TH passwd 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +passwd \- password file +.SH DESCRIPTION +The +.I /etc/passwd +file is a text file that describes user login accounts for the system. +It should have read permission allowed for all users (many utilities, like +.BR ls (1) +use it to map user IDs to usernames), but write access only for the +superuser. +.P +In the good old days there was no great problem with this general +read permission. +Everybody could read the encrypted passwords, but the +hardware was too slow to crack a well-chosen password, and moreover the +basic assumption used to be that of a friendly user-community. +These days many people run some version of the shadow password suite, where +.I /etc/passwd +has an \[aq]x\[aq] character in the password field, +and the encrypted passwords are in +.IR /etc/shadow , +which is readable by the superuser only. +.P +If the encrypted password, whether in +.I /etc/passwd +or in +.IR /etc/shadow , +is an empty string, login is allowed without even asking for a password. +Note that this functionality may be intentionally disabled in applications, +or configurable (for example using the +.RB \[dq] nullok \[dq] +or +.RB \[dq] nonull \[dq] +arguments to +.BR pam_unix (8)). +.P +If the encrypted password in +.I /etc/passwd +is "\fI*NP*\fP" (without the quotes), +the shadow record should be obtained from an NIS+ server. +.P +Regardless of whether shadow passwords are used, many system administrators +use an asterisk (*) in the encrypted password field to make sure +that this user can not authenticate themself using a +password. +(But see NOTES below.) +.P +If you create a new login, first put an asterisk (*) in the password field, +then use +.BR passwd (1) +to set it. +.P +Each line of the file describes a single user, +and contains seven colon-separated fields: +.P +.in +4n +.EX +name:password:UID:GID:GECOS:directory:shell +.EE +.in +.P +The field are as follows: +.TP 12 +.I name +This is the user's login name. +It should not contain capital letters. +.TP +.I password +This is either the encrypted user password, +an asterisk (*), or the letter \[aq]x\[aq]. +(See +.BR pwconv (8) +for an explanation of \[aq]x\[aq].) +.TP +.I UID +The privileged +.I root +login account (superuser) has the user ID 0. +.TP +.I GID +This is the numeric primary group ID for this user. +(Additional groups for the user are defined in the system group file; see +.BR group (5)). +.TP +.I GECOS +This field (sometimes called the "comment field") +is optional and used only for informational purposes. +Usually, it contains the full username. +Some programs (for example, +.BR finger (1)) +display information from this field. +.IP +GECOS stands for "General Electric Comprehensive Operating System", +which was renamed to GCOS when +GE's large systems division was sold to Honeywell. +Dennis Ritchie has reported: "Sometimes we sent printer output or +batch jobs to the GCOS machine. +The gcos field in the password file was a place to stash the +information for the $IDENTcard. +Not elegant." +.TP +.I directory +This is the user's home directory: +the initial directory where the user is placed after logging in. +The value in this field is used to set the +.B HOME +environment variable. +.TP +.I shell +This is the program to run at login (if empty, use +.IR /bin/sh ). +If set to a nonexistent executable, the user will be unable to login +through +.BR login (1). +The value in this field is used to set the +.B SHELL +environment variable. +.SH FILES +.I /etc/passwd +.SH NOTES +If you want to create user groups, there must be an entry in +.IR /etc/group , +or no group will exist. +.P +If the encrypted password is set to an asterisk (*), the user will be unable +to login using +.BR login (1), +but may still login using +.BR rlogin (1), +run existing processes and initiate new ones through +.BR rsh (1), +.BR cron (8), +.BR at (1), +or mail filters, etc. +Trying to lock an account by simply changing the +shell field yields the same result and additionally allows the use of +.BR su (1). +.SH SEE ALSO +.BR chfn (1), +.BR chsh (1), +.BR login (1), +.BR passwd (1), +.BR su (1), +.BR crypt (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR group (5), +.BR shadow (5), +.BR vipw (8) diff --git a/upstream/fedora-40/man5/pbm.5 b/upstream/fedora-40/man5/pbm.5 new file mode 100644 index 00000000..69570e83 --- /dev/null +++ b/upstream/fedora-40/man5/pbm.5 @@ -0,0 +1,212 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "The PBM Format" 5 "27 November 2013" "netpbm documentation" + +.SH NAME + +pbm - Netpbm bi-level image format + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +The PBM format is a lowest common denominator monochrome file +format. It serves as the common language of a large family of bitmap +image conversion filters. Because the format pays no heed to +efficiency, it is simple and general enough that one can easily +develop programs to convert to and from just about any other graphics +format, or to manipulate the image. +.PP +The name "PBM" is an acronym derived from "Portable Bit Map." +.PP +This is not a format that one would normally use to store a file +or to transmit it to someone -- it's too expensive and not expressive +enough for that. It's just an intermediary format. In it's purest +use, it lives only in a pipe between two other programs. + +.UN layout +.SH THE LAYOUT +.PP +The format definition is as follows. +.PP +A PBM file consists of a sequence of one or more PBM images. There are +no data, delimiters, or padding before, after, or between images. +.PP +Each PBM image consists of the following: + + + +.IP \(bu +A "magic number" for identifying the file type. +A pbm image's magic number is the two characters "P4". + +.IP \(bu +Whitespace (blanks, TABs, CRs, LFs). + +.IP \(bu +The width in pixels of the image, formatted as ASCII characters in decimal. + +.IP \(bu +Whitespace. + +.IP \(bu +The height in pixels of the image, again in ASCII decimal. + +.IP \(bu +A single whitespace character (usually a newline). + +.IP \(bu +A raster of Height rows, in order from top to bottom. Each row is +Width bits, packed 8 to a byte, with don't care bits to fill out the +last byte in the row. Each bit represents a pixel: 1 is black, 0 is +white. The order of the pixels is left to right. The order of their +storage within each file byte is most significant bit to least +significant bit. The order of the file bytes is from the beginning of +the file toward the end of the file. +.sp +A row of an image is horizontal. A column is vertical. The pixels +in the image are square and contiguous. + +.IP \(bu +Before the whitespace character that delimits the raster, any +characters from a "#" through the next carriage return or +newline character, is a comment and is ignored. Note that this is +rather unconventional, because a comment can actually be in the middle +of what you might consider a token. Note also that this means if you +have a comment right before the raster, the newline at the end of the +comment is not sufficient to delimit the raster. + + +.PP +All characters referred to herein are encoded in ASCII. +"newline" refers to the character known in ASCII as Line +Feed or LF. A "white space" character is space, CR, LF, +TAB, VT, or FF (I.e. what the ANSI standard C isspace() function +calls white space). + + +.UN plainpbm +.SS Plain PBM +.PP +There is actually another version of the PBM format, even more +simplistic, more lavishly wasteful of space than PBM, called Plain +PBM. Plain PBM actually came first, but even its inventor couldn't +stand its recklessly squanderous use of resources after a while and +switched to what we now know as the regular PBM format. But Plain PBM +is so redundant -- so overstated -- that it's virtually impossible to +break. You can send it through the most liberal mail system (which +was the original purpose of the PBM format) and it will arrive still +readable. You can flip a dozen random bits and easily piece back +together the original image. And we hardly need to define the format +here, because you can decode it by inspection. +.PP +Netpbm programs generate Raw PBM format instead of Plain PBM by +default, but the +.UR index.html#commonoptions +common option +.UE +\& +\fB-plain\fP chooses Plain PBM. +.PP +The difference is: + +.IP \(bu + +There is exactly one image in a file. +.IP \(bu + +The "magic number" is "P1" instead of "P4". +.IP \(bu + +Each pixel in the raster is represented by a byte containing ASCII '1' or '0', +representing black and white respectively. There are no fill bits at the +end of a row. +.IP \(bu + +White space in the raster section is ignored. +.IP \(bu + +You can put any junk you want after the raster, if it starts with a +white space character. +.IP \(bu + +No line should be longer than 70 characters. + + +Here is an example of a small image in the plain PBM format. +.nf +P1 +# feep.pbm +24 7 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 +0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0 +0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0 +0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 +0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 + +.fi +.PP +There is a newline character at the end of each of these lines. +.PP +You can generate the Plain PBM format from the regular PBM format +(first image in the file only) with the \fBpnmtoplainpnm\fP program. +.PP +Programs that read this format should be as lenient as possible, +accepting anything that looks remotely like a bitmap. + + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PBM has been +registered with IANA, but the value \f(CWimage/x-portable-bitmap\fP +is conventional. +.PP +Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP +also applies. + + +.UN filename +.SH FILE NAME +.PP +There are no requirements on the name of a PBM file, but the convention is +to use the suffix ".pbm". "pnm" is also conventional, for +cases where distinguishing between the particular subformats of PNM is not +convenient. + + +.UN compatibility +.SH COMPATIBILITY +.PP +Before July 2000, there could be at most one image in a PBM file. As +a result, most tools to process PBM files ignore (and don't read) any +data after the first image. + +.UN seealso +.SH SEE ALSO +.BR "libnetpbm" (1)\c +\&, +.BR "pnm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +.BR "pam" (1)\c +\&, +.BR "programs that process PBM" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pbm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man5/pfm.5 b/upstream/fedora-40/man5/pfm.5 new file mode 100644 index 00000000..ca00fc56 --- /dev/null +++ b/upstream/fedora-40/man5/pfm.5 @@ -0,0 +1,96 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "PFM Format Description" 5 "19 April 2012" "netpbm documentation" + + +.SH NAME + +PFM - PFM graphic image file format + +.SH DESCRIPTION +.PP +This document describes the PFM graphic image file format as understood by +the Netpbm converters +.BR "\fBpamtopfm\fP" (1)\c +\& and +.BR "\fBpfmtopam\fP" (1)\c +\&. +.PP +There are multiple similar formats known as PFM in the world, none +of them authoritatively documented. The format described here is one +that Bryan Henderson deduced from a program he found somewhere that +dealt with a "PFM" format. +.PP +The PFM format is inspired by the Netpbm formats, and you will see +lots of similarity. It is not, however, an official Netpbm format. +Its goal is not consistent with those of Netpbm formats. + +.SH The format +.PP +A PFM image is a stream of bytes. The stream consists of a header +followed immediately by a raster. These two components are described +below. There are no delimeters before or after the sections as +described. + +.SS PFM header +.PP +The PFM header is 3 consecutive "lines" of ASCII text. +After each line is a white space character. That character is +typically a newline character, hence the term "line," but +doesn't have to be. +.PP +\fBpamtopfm\fP uses a newline in the PFM it generates. + +.B Identifier Line +.PP +The identifier line contains the characters "PF" or +"Pf". PF means it's a color PFM. Pf means it's a grayscale +PFM. + +.B Dimensions Line +.PP +The dimensions line contains two positive decimal integers, +separated by a blank. The first is the width of the image; the second +is the height. Both are in pixels. + +.B Scale Factor / Endianness +.PP +The Scale Factor / Endianness line is a queer line that jams +endianness information into an otherwise sane description of a scale. +The line consists of a nonzero decimal number, not necessarily an +integer. If the number is negative, that means the PFM raster is +little endian. Otherwise, it is big endian. The absolute value of +the number is the scale factor for the image. +.PP +The scale factor tells the units of the samples in the raster. You +use somehow it along with some separately understood unit information +to turn a sample value into something meaningful, such as watts per +square meter. + + +.SS PFM raster +.PP +The raster is a sequence of pixels, packed one after another, with no +delimiters of any kind. They are grouped by row, with the pixels in each +row ordered left to right and the rows ordered bottom to top. +.PP +Each pixel consists of 1 or 3 samples, packed one after another, +with no delimiters of any kind. 1 sample for a grayscale PFM and 3 for a +color PFM (see the Identifier Line of the PFM header). +.PP +Each sample consists of 4 consecutive bytes. The bytes represent a +32 bit string, in either big endian or little endian format, as determined +by the Scale Factor / Endianness line of the PFM header. That string is +an IEEE 32 bit floating point number code. Since that's the same format +that most CPUs and compiler use, you can usually just make a program use +the bytes directly as a floating point number, after taking care of the +endianness variation. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pfm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man5/pgm.5 b/upstream/fedora-40/man5/pgm.5 new file mode 100644 index 00000000..78a5373d --- /dev/null +++ b/upstream/fedora-40/man5/pgm.5 @@ -0,0 +1,247 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "PGM Format Specification" 5 "09 October 2016" "netpbm documentation" + +.SH NAME + +pgm - Netpbm grayscale image format + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +The PGM format is a lowest common denominator grayscale file format. +It is designed to be extremely easy to learn and write programs for. +(It's so simple that most people will simply reverse engineer it +because it's easier than reading this specification). +.PP +A PGM image represents a grayscale graphic image. There are many +pseudo-PGM formats in use where everything is as specified herein except +for the meaning of individual pixel values. For most purposes, a PGM +image can just be thought of an array of arbitrary integers, and all the +programs in the world that think they're processing a grayscale image +can easily be tricked into processing something else. +.PP +The name "PGM" is an acronym derived from "Portable Gray Map." +.PP +One official variant of PGM is the transparency mask. A transparency +mask in Netpbm is represented by a PGM image, except that in place of +pixel intensities, there are opaqueness values. See below. + +.UN format +.SH THE FORMAT +.PP +The format definition is as follows. You can use the +.BR "libnetpbm" (1)\c +\& C subroutine library to conveniently +and accurately read and interpret the format. +.PP +A PGM file consists of a sequence of one or more PGM images. There are +no data, delimiters, or padding before, after, or between images. +.PP +Each PGM image consists of the following: + + + +.IP \(bu +A "magic number" for identifying the file type. +A pgm image's magic number is the two characters "P5". + +.IP \(bu +Whitespace (blanks, TABs, CRs, LFs). + +.IP \(bu +A width, formatted as ASCII characters in decimal. + +.IP \(bu +Whitespace. + +.IP \(bu +A height, again in ASCII decimal. + +.IP \(bu +Whitespace. + +.IP \(bu +The maximum gray value (Maxval), again in ASCII decimal. Must be less +than 65536, and more than zero. + +.IP \(bu +A single whitespace character (usually a newline). + +.IP \(bu +A raster of Height rows, in order from top to bottom. Each row +consists of Width gray values, in order from left to right. Each gray +value is a number from 0 through Maxval, with 0 being black and Maxval +being white. Each gray value is represented in pure binary by either +1 or 2 bytes. If the Maxval is less than 256, it is 1 byte. +Otherwise, it is 2 bytes. The most significant byte is first. +.sp +A row of an image is horizontal. A column is vertical. The pixels +in the image are square and contiguous. +.sp +Each gray value is a number proportional to the intensity of the +pixel, adjusted by the ITU-R Recommendation BT.709 gamma transfer +function. (That transfer function specifies a gamma number of 2.2 and +has a linear section for small intensities). A value of zero is +therefore black. A value of Maxval represents CIE D65 white and the +most intense value in the image and any other image to which the image +might be compared. +.sp +BT.709's range of channel values (16-240) is irrelevant to PGM. +.sp +Note that a common variation from the PGM format is to have the +gray value be "linear," i.e. as specified above except +without the gamma adjustment. \fBpnmgamma\fP takes such a PGM +variant as input and produces a true PGM as output. +.sp +Another popular variation from PGM is to substitute the newer sRGB transfer +function for the BT.709 one. You can use \fBpnmgamma\fP to convert between +this variation and true PGM. +.sp +In the transparency mask variation from PGM, the value represents +opaqueness. It is proportional to the fraction of intensity of a +pixel that would show in place of an underlying pixel. So what +normally means white represents total opaqueness and what normally +means black represents total transparency. In between, you would +compute the intensity of a composite pixel of an "under" and +"over" pixel as under * (1-(alpha/alpha_maxval)) + over * +(alpha/alpha_maxval). Note that there is no gamma transfer function +in the transparency mask. + + +.PP +Strings starting with "#" may be comments, the same as +with +.BR "PBM" (1)\c +\&. +.PP +Note that you can use \fBpamdepth\fP to convert between a the +format with 1 byte per gray value and the one with 2 bytes per gray +value. +.PP +All characters referred to herein are encoded in ASCII. +"newline" refers to the character known in ASCII as Line +Feed or LF. A "white space" character is space, CR, LF, +TAB, VT, or FF (I.e. what the ANSI standard C isspace() function +calls white space). + +.UN plainpgm +.SS Plain PGM +.PP +There is actually another version of the PGM format that is fairly +rare: "plain" PGM format. The format above, which generally +considered the normal one, is known as the "raw" PGM format. +See +.BR "pbm" (1)\c +\& for some commentary on how plain +and raw formats relate to one another and how to use them. +.PP +The difference in the plain format is: + + +.IP \(bu + +There is exactly one image in a file. +.IP \(bu + +The magic number is P2 instead of P5. +.IP \(bu + +Each pixel in the raster is represented as an ASCII decimal number +(of arbitrary size). +.IP \(bu + +Each pixel in the raster has white space before and after it. There must +be at least one character of white space between any two pixels, but there +is no maximum. +.IP \(bu + +No line should be longer than 70 characters. + +.PP +Here is an example of a small image in the plain PGM format. + +.nf +P2 +# feep.pgm +24 7 +15 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 3 3 3 3 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 15 15 15 0 +0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 15 0 +0 3 3 3 0 0 0 7 7 7 0 0 0 11 11 11 0 0 0 15 15 15 15 0 +0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 0 0 +0 3 0 0 0 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 0 0 0 0 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 + +.fi +.PP +There is a newline character at the end of each of these lines. +.PP +Programs that read this format should be as lenient as possible, +accepting anything that looks remotely like a PGM. + + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PGM has been +registered with IANA, but the value \f(CWimage/x-portable-graymap\fP +is conventional. +.PP +Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP +also applies. + + +.UN filename +.SH FILE NAME +.PP +There are no requirements on the name of a PGM file, but the convention is +to use the suffix ".pgm". "pnm" is also conventional, for +cases where distinguishing between the particular subformats of PNM is not +convenient. + + +.UN compatibility +.SH COMPATIBILITY +.PP +Before April 2000, a raw format PGM file could not have a maxval greater +than 255. Hence, it could not have more than one byte per sample. Old +programs may depend on this. +.PP +Before July 2000, there could be at most one image in a PGM file. As +a result, most tools to process PGM files ignore (and don't read) any +data after the first image. + +.UN seealso +.SH SEE ALSO +.BR "pnm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +.BR "pam" (1)\c +\&, +.BR "libnetpbm" (1)\c +\&, +.BR "programs that process PGM" (1)\c +\&, + +.UN author +.SH AUTHOR + +Copyright (C) 1989, 1991 by Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pgm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man5/pnm.5 b/upstream/fedora-40/man5/pnm.5 new file mode 100644 index 00000000..a1e68a03 --- /dev/null +++ b/upstream/fedora-40/man5/pnm.5 @@ -0,0 +1,85 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "The PNM Format" 5 "27 November 2013" "netpbm documentation" + +.SH NAME + +pnm - Netpbm superformat + +.UN description +.SH DESCRIPTION +.PP +The PNM format is just an abstraction of the PBM, PGM, and PPM +formats. I.e. the name "PNM" refers collectively to +PBM, PGM, and PPM. +.PP +The name "PNM" is an acronym derived from "Portable +Any Map." This derivation makes more sense if you consider +it in the context of the other Netpbm format names: PBM, PGM, and PPM. +.PP +The more general term "Netpbm format" refers to the PNM +formats plus PAM. +.PP +PNM is principally used with +.BR "Netpbm" (1)\c +\&. +.PP +Note that besides being names of formats, PBM, PGM, PPM, and PNM +are also classes of programs. A PNM program can take PBM, PGM, or PPM +input. That's nothing special -- a PPM program can too. But a PNM +program can often produce multiple output formats as well, and a PNM +program can see the difference between PBM, PGM, and PPM input and +respond to each differently whereas a PPM program sees everything as +if it were PPM. This is discussed more in +.BR "the +description of the netpbm programs" (1)\c +\&. +.PP +"pnm" also appears in the names of the most general +.BR "Netpbm library routines" (1)\c +\&, some of which aren't even +related to the PNM format. + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PNM has been +registered with the IANA, but the value \f(CWimage/x-portable-anymap\fP +is conventional. +.PP +Note that there are also conventional Internet Media Types for each of the +PNM subformats. The recommended practice is to use those in preference to the +PNM code when it is convenient to do so. + +.UN filename +.SH FILE NAME +.PP +There are no requirements on the name of a PNM file, but the convention is +to use the suffix "pbm", "pgm", or "ppm", +depending on the particular subformat, or "pnm" if it is not +convenient to distinguish the subformats. + + +.UN seealso +.SH SEE ALSO +.BR "ppm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "pam" (1)\c +\&, +.BR "programs that process PNM" (1)\c +\&, +.BR "libnetpbm" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pnm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man5/ppm.5 b/upstream/fedora-40/man5/ppm.5 new file mode 100644 index 00000000..1f54ee0d --- /dev/null +++ b/upstream/fedora-40/man5/ppm.5 @@ -0,0 +1,240 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "PPM Format Specification" 5 "09 October 2016" "netpbm documentation" + +.SH NAME + +PPM - Netpbm color image format + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +The PPM format is a lowest common denominator color image file +format. +.PP +It should be noted that this format is egregiously inefficient. +It is highly redundant, while containing a lot of information that the +human eye can't even discern. Furthermore, the format allows very +little information about the image besides basic color, which means +you may have to couple a file in this format with other independent +information to get any decent use out of it. However, it is very easy +to write and analyze programs to process this format, and that is the +point. +.PP +It should also be noted that files often conform to this format in +every respect except the precise semantics of the sample values. +These files are useful because of the way PPM is used as an +intermediary format. They are informally called PPM files, but to be +absolutely precise, you should indicate the variation from true PPM. +For example, "PPM using the red, green, and blue colors that the +scanner in question uses." +.PP +The name "PPM" is an acronym derived from "Portable Pixel Map." +Images in this format (or a precursor of it) were once also called +"portable pixmaps." + +.UN format +.SH THE FORMAT +.PP +The format definition is as follows. You can use the +.BR "libnetpbm" (1)\c +\& C subroutine library to read and +interpret the format conveniently and accurately. +.PP +A PPM file consists of a sequence of one or more PPM images. There are +no data, delimiters, or padding before, after, or between images. +.PP +Each PPM image consists of the following: + + +.IP \(bu +A "magic number" for identifying the file type. +A ppm image's magic number is the two characters "P6". +.IP \(bu + +Whitespace (blanks, TABs, CRs, LFs). +.IP \(bu + +A width, formatted as ASCII characters in decimal. +.IP \(bu + +Whitespace. +.IP \(bu + +A height, again in ASCII decimal. +.IP \(bu + +Whitespace. +.IP \(bu + +The maximum color value (Maxval), again in ASCII decimal. Must be less +than 65536 and more than zero. + +.IP \(bu +A single whitespace character (usually a newline). + +.IP \(bu +A raster of Height rows, in order from top to bottom. Each row +consists of Width pixels, in order from left to right. Each pixel is +a triplet of red, green, and blue samples, in that order. Each sample +is represented in pure binary by either 1 or 2 bytes. If the Maxval +is less than 256, it is 1 byte. Otherwise, it is 2 bytes. The most +significant byte is first. +.sp +A row of an image is horizontal. A column is vertical. The pixels +in the image are square and contiguous. +.sp +In the raster, the sample values are "nonlinear." They are +proportional to the intensity of the ITU-R Recommendation BT.709 red, +green, and blue in the pixel, adjusted by the BT.709 gamma transfer +function. (That transfer function specifies a gamma number of 2.2 and +has a linear section for small intensities). A value of Maxval for +all three samples represents CIE D65 white and the most intense color +in the color universe of which the image is part (the color universe +is all the colors in all images to which this image might be +compared). +.sp +BT.709's range of channel values (16-240) is irrelevant to PPM. +.sp +ITU-R Recommendation BT.709 is a renaming of the former CCIR +Recommendation 709. When CCIR was absorbed into its parent +organization, the ITU, ca. 2000, the standard was renamed. This +document once referred to the standard as CIE Rec. 709, but it isn't +clear now that CIE ever sponsored such a standard. +.sp +Note that another popular color space is the newer sRGB. A common +variation from PPM is to substitute this color space for the one specified. +You can use \fBpnmgamma\fP to convert between this variation and true PPM. +.sp +Note that a common variation from the PPM format is to have the sample +values be "linear," i.e. as specified above except without +the gamma adjustment. \fBpnmgamma\fP takes such a PPM variant as +input and produces a true PPM as output. + + +.PP +Strings starting with "#" may be comments, the same as +with +.BR "PBM" (1)\c +\&. +.PP +Note that you can use \fBpamdepth\fP to convert between a the +format with 1 byte per sample and the one with 2 bytes per sample. +.PP +All characters referred to herein are encoded in ASCII. +"newline" refers to the character known in ASCII as Line +Feed or LF. A "white space" character is space, CR, LF, +TAB, VT, or FF (I.e. what the ANSI standard C isspace() function +calls white space). + +.UN plainppm +.SS Plain PPM +.PP +There is actually another version of the PPM format that is fairly +rare: "plain" PPM format. The format above, which generally +considered the normal one, is known as the "raw" PPM format. +See +.BR "pbm" (1)\c +\& for some commentary on how plain +and raw formats relate to one another and how to use them. +.PP +The difference in the plain format is: + + +.IP \(bu + +There is exactly one image in a file. +.IP \(bu + +The magic number is P3 instead of P6. +.IP \(bu + +Each sample in the raster is represented as an ASCII decimal number +(of arbitrary size). +.IP \(bu + +Each sample in the raster has white space before and after it. There must +be at least one character of white space between any two samples, but there +is no maximum. There is no particular separation of one pixel from another -- +just the required separation between the blue sample of one pixel from the +red sample of the next pixel. +.IP \(bu + +No line should be longer than 70 characters. + +.PP +Here is an example of a small image in this format. +.nf +P3 +# feep.ppm +4 4 +15 + 0 0 0 0 0 0 0 0 0 15 0 15 + 0 0 0 0 15 7 0 0 0 0 0 0 + 0 0 0 0 0 0 0 15 7 0 0 0 +15 0 15 0 0 0 0 0 0 0 0 0 + +.fi +.PP +There is a newline character at the end of each of these lines. +.PP +Programs that read this format should be as lenient as possible, +accepting anything that looks remotely like a PPM image. + + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PPM has been +registered with IANA, but the value \f(CWimage/x-portable-pixmap\fP is +conventional. +.PP +Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP +also applies. + + +.UN filename +.SH FILE NAME +.PP +There are no requirements on the name of a PPM file, but the convention is +to use the suffix ".ppm". "pnm" is also conventional, for +cases where distinguishing between the particular subformats of PNM is not +convenient. + + +.UN compatibility +.SH COMPATIBILITY +.PP +Before April 2000, a raw format PPM file could not have a maxval greater +than 255. Hence, it could not have more than one byte per sample. Old +programs may depend on this. +.PP +Before July 2000, there could be at most one image in a PPM file. As +a result, most tools to process PPM files ignore (and don't read) any +data after the first image. + +.UN seealso +.SH SEE ALSO +.BR "pnm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "pam" (1)\c +\&, +.BR "programs that process PPM" (1)\c +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/ppm.html +.PP \ No newline at end of file diff --git a/upstream/fedora-40/man5/proc.5 b/upstream/fedora-40/man5/proc.5 new file mode 100644 index 00000000..788cb97e --- /dev/null +++ b/upstream/fedora-40/man5/proc.5 @@ -0,0 +1,259 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +proc \- process information, system information, and sysctl pseudo-filesystem +.SH DESCRIPTION +The +.B proc +filesystem is a pseudo-filesystem which provides an interface to +kernel data structures. +It is commonly mounted at +.IR /proc . +Typically, it is mounted automatically by the system, +but it can also be mounted manually using a command such as: +.P +.in +4n +.EX +mount \-t proc proc /proc +.EE +.in +.P +Most of the files in the +.B proc +filesystem are read-only, +but some files are writable, allowing kernel variables to be changed. +.\" +.SS Mount options +The +.B proc +filesystem supports the following mount options: +.TP +.BR hidepid "=\fIn\fP (since Linux 3.3)" +.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201 +This option controls who can access the information in +.IR /proc/ pid +directories. +The argument, +.IR n , +is one of the following values: +.RS +.TP 4 +0 +Everybody may access all +.IR /proc/ pid +directories. +This is the traditional behavior, +and the default if this mount option is not specified. +.TP +1 +Users may not access files and subdirectories inside any +.IR /proc/ pid +directories but their own (the +.IR /proc/ pid +directories themselves remain visible). +Sensitive files such as +.IR /proc/ pid /cmdline +and +.IR /proc/ pid /status +are now protected against other users. +This makes it impossible to learn whether any user is running a +specific program +(so long as the program doesn't otherwise reveal itself by its behavior). +.\" As an additional bonus, since +.\" .IR /proc/[pid]/cmdline +.\" is inaccessible for other users, +.\" poorly written programs passing sensitive information via +.\" program arguments are now protected against local eavesdroppers. +.TP +2 +As for mode 1, but in addition the +.IR /proc/ pid +directories belonging to other users become invisible. +This means that +.IR /proc/ pid +entries can no longer be used to discover the PIDs on the system. +This doesn't hide the fact that a process with a specific PID value exists +(it can be learned by other means, for example, by "kill \-0 $PID"), +but it hides a process's UID and GID, +which could otherwise be learned by employing +.BR stat (2) +on a +.IR /proc/ pid +directory. +This greatly complicates an attacker's task of gathering +information about running processes (e.g., discovering whether +some daemon is running with elevated privileges, +whether another user is running some sensitive program, +whether other users are running any program at all, and so on). +.RE +.TP +.BR gid "=\fIgid\fP (since Linux 3.3)" +.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201 +Specifies the ID of a group whose members are authorized to +learn process information otherwise prohibited by +.B hidepid +(i.e., users in this group behave as though +.I /proc +was mounted with +.IR hidepid=0 ). +This group should be used instead of approaches such as putting +nonroot users into the +.BR sudoers (5) +file. +.\" +.SS Overview +Underneath +.IR /proc , +there are the following general groups of files and subdirectories: +.TP +.IR /proc/ "pid subdirectories" +Each one of these subdirectories contains files and subdirectories +exposing information about the process with the corresponding process ID. +.IP +Underneath each of the +.IR /proc/ pid +directories, a +.I task +subdirectory contains subdirectories of the form +.IR task/ tid, +which contain corresponding information about each of the threads +in the process, where +.I tid +is the kernel thread ID of the thread. +.IP +The +.IR /proc/ pid +subdirectories are visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +.TP +.IR /proc/ "tid subdirectories" +Each one of these subdirectories contains files and subdirectories +exposing information about the thread with the corresponding thread ID. +The contents of these directories are the same as the corresponding +.IR /proc/ pid /task/ tid +directories. +.IP +The +.IR /proc/ tid +subdirectories are +.I not +visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are +.I not +visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +.TP +.I /proc/self +When a process accesses this magic symbolic link, +it resolves to the process's own +.IR /proc/ pid +directory. +.TP +.I /proc/thread\-self +When a thread accesses this magic symbolic link, +it resolves to the process's own +.IR /proc/self/task/ tid +directory. +.TP +.I /proc/[a\-z]* +Various other files and subdirectories under +.I /proc +expose system-wide information. +.P +All of the above are described in more detail below. +.\" +.\" .SH FILES +.\" FIXME Describe /proc/[pid]/sessionid +.\" commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc +.\" CONFIG_AUDITSYSCALL +.\" Added in Linux 2.6.25; read-only; only readable by real UID +.\" +.\" FIXME Describe /proc/[pid]/sched +.\" Added in Linux 2.6.23 +.\" CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS +.\" Displays various scheduling parameters +.\" This file can be written, to reset stats +.\" The set of fields exposed by this file have changed +.\" significantly over time. +.\" commit 43ae34cb4cd650d1eb4460a8253a8e747ba052ac +.\" +.\" FIXME Describe /proc/[pid]/schedstats and +.\" /proc/[pid]/task/[tid]/schedstats +.\" Added in Linux 2.6.9 +.\" CONFIG_SCHEDSTATS +.\" FIXME Document /proc/sched_debug (since Linux 2.6.23) +.\" See also /proc/[pid]/sched +.\" FIXME 2.6.13 seems to have /proc/vmcore implemented; document this +.\" See Documentation/kdump/kdump.txt +.\" commit 666bfddbe8b8fd4fd44617d6c55193d5ac7edb29 +.\" Needs CONFIG_VMCORE +.\" +.SH NOTES +Many files contain strings (e.g., the environment and command line) +that are in the internal format, +with subfields terminated by null bytes (\[aq]\e0\[aq]). +When inspecting such files, you may find that the results are more readable +if you use a command of the following form to display them: +.P +.in +4n +.EX +.RB "$" " cat \fIfile\fP | tr \[aq]\e000\[aq] \[aq]\en\[aq]" +.EE +.in +.\" .SH ACKNOWLEDGEMENTS +.\" The material on /proc/sys/fs and /proc/sys/kernel is closely based on +.\" kernel source documentation files written by Rik van Riel. +.SH SEE ALSO +.BR cat (1), +.BR dmesg (1), +.BR find (1), +.BR free (1), +.BR htop (1), +.BR init (1), +.BR ps (1), +.BR pstree (1), +.BR tr (1), +.BR uptime (1), +.BR chroot (2), +.BR mmap (2), +.BR readlink (2), +.BR syslog (2), +.BR slabinfo (5), +.BR sysfs (5), +.BR hier (7), +.BR namespaces (7), +.BR time (7), +.BR arp (8), +.BR hdparm (8), +.BR ifconfig (8), +.BR lsmod (8), +.BR lspci (8), +.BR mount (8), +.BR netstat (8), +.BR procinfo (8), +.BR route (8), +.BR sysctl (8) +.P +The Linux kernel source files: +.IR Documentation/filesystems/proc.rst , +.IR Documentation/admin\-guide/sysctl/fs.rst , +.IR Documentation/admin\-guide/sysctl/kernel.rst , +.IR Documentation/admin\-guide/sysctl/net.rst , +and +.IR Documentation/admin\-guide/sysctl/vm.rst . diff --git a/upstream/fedora-40/man5/proc_apm.5 b/upstream/fedora-40/man5/proc_apm.5 new file mode 100644 index 00000000..03462ace --- /dev/null +++ b/upstream/fedora-40/man5/proc_apm.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_apm 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/apm \- advanced power management +.SH DESCRIPTION +.TP +.I /proc/apm +Advanced power management version and battery information when +.B CONFIG_APM +is defined at kernel compilation time. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_buddyinfo.5 b/upstream/fedora-40/man5/proc_buddyinfo.5 new file mode 100644 index 00000000..7b3db6c6 --- /dev/null +++ b/upstream/fedora-40/man5/proc_buddyinfo.5 @@ -0,0 +1,58 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_buddyinfo 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/buddyinfo \- memory fragmentation +.SH DESCRIPTION +.TP +.I /proc/buddyinfo +This file contains information which is used for diagnosing memory +fragmentation issues. +Each line starts with the identification of the node and the name +of the zone which together identify a memory region. +This is then +followed by the count of available chunks of a certain order in +which these zones are split. +The size in bytes of a certain order is given by the formula: +.IP +.in +4n +.EX +(2\[ha]order)\ *\ PAGE_SIZE +.EE +.in +.IP +The binary buddy allocator algorithm inside the kernel will split +one chunk into two chunks of a smaller order (thus with half the +size) or combine two contiguous chunks into one larger chunk of +a higher order (thus with double the size) to satisfy allocation +requests and to counter memory fragmentation. +The order matches the column number, when starting to count at zero. +.IP +For example on an x86-64 system: +.RS -12 +.EX +Node 0, zone DMA 1 1 1 0 2 1 1 0 1 1 3 +Node 0, zone DMA32 65 47 4 81 52 28 13 10 5 1 404 +Node 0, zone Normal 216 55 189 101 84 38 37 27 5 3 587 +.EE +.RE +.IP +In this example, there is one node containing three zones and there +are 11 different chunk sizes. +If the page size is 4 kilobytes, then the first zone called +.I DMA +(on x86 the first 16 megabyte of memory) has 1 chunk of 4 kilobytes +(order 0) available and has 3 chunks of 4 megabytes (order 10) available. +.IP +If the memory is heavily fragmented, the counters for higher +order chunks will be zero and allocation of large contiguous areas +will fail. +.IP +Further information about the zones can be found in +.IR /proc/zoneinfo . +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_bus.5 b/upstream/fedora-40/man5/proc_bus.5 new file mode 100644 index 00000000..aeb8ec62 --- /dev/null +++ b/upstream/fedora-40/man5/proc_bus.5 @@ -0,0 +1,35 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_bus 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/bus/ \- installed buses +.SH DESCRIPTION +.TP +.I /proc/bus/ +Contains subdirectories for installed buses. +.TP +.I /proc/bus/pccard/ +Subdirectory for PCMCIA devices when +.B CONFIG_PCMCIA +is set at kernel compilation time. +.TP +.I /proc/bus/pccard/drivers +.TP +.I /proc/bus/pci/ +Contains various bus subdirectories and pseudo-files containing +information about PCI buses, installed devices, and device +drivers. +Some of these files are not ASCII. +.TP +.I /proc/bus/pci/devices +Information about PCI devices. +They may be accessed through +.BR lspci (8) +and +.BR setpci (8). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_cgroups.5 b/upstream/fedora-40/man5/proc_cgroups.5 new file mode 100644 index 00000000..61a675e0 --- /dev/null +++ b/upstream/fedora-40/man5/proc_cgroups.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cgroups 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/cgroups \- control groups +.SH DESCRIPTION +.TP +.IR /proc/cgroups " (since Linux 2.6.24)" +See +.BR cgroups (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_cmdline.5 b/upstream/fedora-40/man5/proc_cmdline.5 new file mode 100644 index 00000000..f030d61b --- /dev/null +++ b/upstream/fedora-40/man5/proc_cmdline.5 @@ -0,0 +1,22 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cmdline 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/cmdline \- kernel boot arguments +.SH DESCRIPTION +.TP +.I /proc/cmdline +Arguments passed to the Linux kernel at boot time. +Often done via a boot manager such as +.BR lilo (8) +or +.BR grub (8). +Any arguments embedded in the kernel image or initramfs via +.B CONFIG_BOOT_CONFIG +will also be displayed. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_config.gz.5 b/upstream/fedora-40/man5/proc_config.gz.5 new file mode 100644 index 00000000..eedafc80 --- /dev/null +++ b/upstream/fedora-40/man5/proc_config.gz.5 @@ -0,0 +1,40 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_config.gz 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/config.gz \- kernel build configuration +.SH DESCRIPTION +.TP +.IR /proc/config.gz " (since Linux 2.6)" +This file exposes the configuration options that were used +to build the currently running kernel, +in the same format as they would be shown in the +.I .config +file that resulted when configuring the kernel (using +.IR "make xconfig" , +.IR "make config" , +or similar). +The file contents are compressed; view or search them using +.BR zcat (1) +and +.BR zgrep (1). +As long as no changes have been made to the following file, +the contents of +.I /proc/config.gz +are the same as those provided by: +.IP +.in +4n +.EX +cat /lib/modules/$(uname \-r)/build/.config +.EE +.in +.IP +.I /proc/config.gz +is provided only if the kernel is configured with +.BR CONFIG_IKCONFIG_PROC . +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_cpuinfo.5 b/upstream/fedora-40/man5/proc_cpuinfo.5 new file mode 100644 index 00000000..648f5057 --- /dev/null +++ b/upstream/fedora-40/man5/proc_cpuinfo.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cpuinfo 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/cpuinfo \- CPU and system architecture information +.SH DESCRIPTION +.TP +.I /proc/cpuinfo +This is a collection of CPU and system architecture dependent items, +for each supported architecture a different list. +Two common entries are \fIprocessor\fP which gives CPU number and +\fIbogomips\fP; a system constant that is calculated +during kernel initialization. +SMP machines have information for +each CPU. +The +.BR lscpu (1) +command gathers its information from this file. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_crypto.5 b/upstream/fedora-40/man5/proc_crypto.5 new file mode 100644 index 00000000..a3e0096d --- /dev/null +++ b/upstream/fedora-40/man5/proc_crypto.5 @@ -0,0 +1,26 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_crypto 5 2023-11-24 "Linux man-pages 6.06" +.SH NAME +/proc/crypto \- ciphers provided by kernel crypto API +.SH DESCRIPTION +.TP +.I /proc/crypto +A list of the ciphers provided by the kernel crypto API. +For details, see the kernel +.I "Linux Kernel Crypto API" +documentation available under the kernel source directory +.I Documentation/crypto/ +.\" commit 3b72c814a8e8cd638e1ba0da4dfce501e9dff5af +(or +.I Documentation/DocBook +before Linux 4.10; +the documentation can be built using a command such as +.I make htmldocs +in the root directory of the kernel source tree). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_devices.5 b/upstream/fedora-40/man5/proc_devices.5 new file mode 100644 index 00000000..b17fb81a --- /dev/null +++ b/upstream/fedora-40/man5/proc_devices.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_devices 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/devices \- major numbers and device groups +.SH DESCRIPTION +.TP +.I /proc/devices +Text listing of major numbers and device groups. +This can be used by MAKEDEV scripts for consistency with the kernel. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_diskstats.5 b/upstream/fedora-40/man5/proc_diskstats.5 new file mode 100644 index 00000000..59c028f9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_diskstats.5 @@ -0,0 +1,21 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_diskstats 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/diskstats \- disk I/O statistics +.SH DESCRIPTION +.TP +.IR /proc/diskstats " (since Linux 2.5.69)" +This file contains disk I/O statistics for each disk device. +See the Linux kernel source file +.I Documentation/admin\-guide/iostats.rst +(or +.I Documentation/iostats.txt +before Linux 5.3) +for further information. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_dma.5 b/upstream/fedora-40/man5/proc_dma.5 new file mode 100644 index 00000000..ddc4dd94 --- /dev/null +++ b/upstream/fedora-40/man5/proc_dma.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_dma 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/dma \- ISA DMA channels +.SH DESCRIPTION +.TP +.I /proc/dma +This is a list of the registered \fIISA\fP DMA (direct memory access) +channels in use. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_driver.5 b/upstream/fedora-40/man5/proc_driver.5 new file mode 100644 index 00000000..ec17a4c4 --- /dev/null +++ b/upstream/fedora-40/man5/proc_driver.5 @@ -0,0 +1,15 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_driver 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/driver/ \- empty dir +.SH DESCRIPTION +.TP +.I /proc/driver/ +Empty subdirectory. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_execdomains.5 b/upstream/fedora-40/man5/proc_execdomains.5 new file mode 100644 index 00000000..f77465b3 --- /dev/null +++ b/upstream/fedora-40/man5/proc_execdomains.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_execdomains 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/execdomains \- ABI personalities (obsolete) +.SH DESCRIPTION +.TP +.I /proc/execdomains +Used to list ABI personalities before Linux 4.1; +now contains a constant string for userspace compatibility. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_fb.5 b/upstream/fedora-40/man5/proc_fb.5 new file mode 100644 index 00000000..96336075 --- /dev/null +++ b/upstream/fedora-40/man5/proc_fb.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_fb 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/fb \- frame buffer +.SH DESCRIPTION +.TP +.I /proc/fb +Frame buffer information when +.B CONFIG_FB +is defined during kernel compilation. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_filesystems.5 b/upstream/fedora-40/man5/proc_filesystems.5 new file mode 100644 index 00000000..c7f002a6 --- /dev/null +++ b/upstream/fedora-40/man5/proc_filesystems.5 @@ -0,0 +1,33 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.\" FIXME cross check against Documentation/filesystems/proc.txt +.\" to see what information could be imported from that file +.\" into this file. +.\" +.TH proc_filesystems 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/filesystems \- supported filesystems +.SH DESCRIPTION +.TP +.I /proc/filesystems +A text listing of the filesystems which are supported by the kernel, +namely filesystems which were compiled into the kernel or whose kernel +modules are currently loaded. +(See also +.BR filesystems (5).) +If a filesystem is marked with "nodev", +this means that it does not require a block device to be mounted +(e.g., virtual filesystem, network filesystem). +.IP +Incidentally, this file may be used by +.BR mount (8) +when no filesystem is specified and it didn't manage to determine the +filesystem type. +Then filesystems contained in this file are tried +(excepted those that are marked with "nodev"). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_fs.5 b/upstream/fedora-40/man5/proc_fs.5 new file mode 100644 index 00000000..57bcbfc9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_fs.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_fs 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/fs/ \- mounted filesystems +.SH DESCRIPTION +.TP +.I /proc/fs/ +.\" FIXME Much more needs to be said about /proc/fs +.\" +Contains subdirectories that in turn contain files +with information about (certain) mounted filesystems. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_ide.5 b/upstream/fedora-40/man5/proc_ide.5 new file mode 100644 index 00000000..41521a63 --- /dev/null +++ b/upstream/fedora-40/man5/proc_ide.5 @@ -0,0 +1,37 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_ide 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/ide/ \- IDE channels and attached devices +.SH DESCRIPTION +.TP +.I /proc/ide +This directory +exists on systems with the IDE bus. +There are directories for each IDE channel and attached device. +Files include: +.IP +.in +4n +.EX +cache buffer size in KB +capacity number of sectors +driver driver version +geometry physical and logical geometry +identify in hexadecimal +media media type +model manufacturer\[aq]s model number +settings drive settings +smart_thresholds IDE disk management thresholds (in hex) +smart_values IDE disk management values (in hex) +.EE +.in +.IP +The +.BR hdparm (8) +utility provides access to this information in a friendly format. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_interrupts.5 b/upstream/fedora-40/man5/proc_interrupts.5 new file mode 100644 index 00000000..c9874bca --- /dev/null +++ b/upstream/fedora-40/man5/proc_interrupts.5 @@ -0,0 +1,22 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_interrupts 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/interrupts \- number of interrupts +.SH DESCRIPTION +.TP +.I /proc/interrupts +This is used to record the number of interrupts per CPU per IO device. +Since Linux 2.6.24, +for the i386 and x86-64 architectures, at least, this also includes +interrupts internal to the system (that is, not associated with a device +as such), such as NMI (nonmaskable interrupt), LOC (local timer interrupt), +and for SMP systems, TLB (TLB flush interrupt), RES (rescheduling +interrupt), CAL (remote function call interrupt), and possibly others. +Very easy to read formatting, done in ASCII. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_iomem.5 b/upstream/fedora-40/man5/proc_iomem.5 new file mode 100644 index 00000000..e9c17dfd --- /dev/null +++ b/upstream/fedora-40/man5/proc_iomem.5 @@ -0,0 +1,15 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_iomem 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/iomem \- I/O memory map +.SH DESCRIPTION +.TP +.I /proc/iomem +I/O memory map in Linux 2.4. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_ioports.5 b/upstream/fedora-40/man5/proc_ioports.5 new file mode 100644 index 00000000..968cf555 --- /dev/null +++ b/upstream/fedora-40/man5/proc_ioports.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_ioports 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/ioports \- I/O port regions +.SH DESCRIPTION +.TP +.I /proc/ioports +This is a list of currently registered Input-Output port regions that +are in use. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_kallsyms.5 b/upstream/fedora-40/man5/proc_kallsyms.5 new file mode 100644 index 00000000..91b53638 --- /dev/null +++ b/upstream/fedora-40/man5/proc_kallsyms.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kallsyms 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/kallsyms \- kernel exported symbols +.SH DESCRIPTION +.TP +.IR /proc/kallsyms " (since Linux 2.5.71)" +This holds the kernel exported symbol definitions used by the +.BR modules (X) +tools to dynamically link and bind loadable modules. +In Linux 2.5.47 and earlier, a similar file with slightly different syntax +was named +.IR ksyms . +.SH HISTORY +.TP +.IR /proc/ksyms " (Linux 1.1.23\[en]2.5.47)" +See +.IR /proc/kallsyms . +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_kcore.5 b/upstream/fedora-40/man5/proc_kcore.5 new file mode 100644 index 00000000..269b73c5 --- /dev/null +++ b/upstream/fedora-40/man5/proc_kcore.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kcore 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/kcore \- physical memory +.SH DESCRIPTION +.TP +.I /proc/kcore +This file represents the physical memory of the system and is stored +in the ELF core file format. +With this pseudo-file, and an unstripped +kernel +.RI ( /usr/src/linux/vmlinux ) +binary, GDB can be used to +examine the current state of any kernel data structures. +.IP +The total length of the file is the size of physical memory (RAM) plus +4\ KiB. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_keys.5 b/upstream/fedora-40/man5/proc_keys.5 new file mode 100644 index 00000000..9c4f2d5b --- /dev/null +++ b/upstream/fedora-40/man5/proc_keys.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_keys 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/keys, /proc/key\-users \- in-kernel key management +.SH DESCRIPTION +.TP +.IR /proc/keys " (since Linux 2.6.10)" +See +.BR keyrings (7). +.TP +.IR /proc/key\-users " (since Linux 2.6.10)" +See +.BR keyrings (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_kmsg.5 b/upstream/fedora-40/man5/proc_kmsg.5 new file mode 100644 index 00000000..a64e0361 --- /dev/null +++ b/upstream/fedora-40/man5/proc_kmsg.5 @@ -0,0 +1,28 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kmsg 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/kmsg \- kernel messages +.SH DESCRIPTION +.TP +.I /proc/kmsg +This file can be used instead of the +.BR syslog (2) +system call to read kernel messages. +A process must have superuser +privileges to read this file, and only one process should read this +file. +This file should not be read if a syslog process is running +which uses the +.BR syslog (2) +system call facility to log kernel messages. +.IP +Information in this file is retrieved with the +.BR dmesg (1) +program. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_kpagecgroup.5 b/upstream/fedora-40/man5/proc_kpagecgroup.5 new file mode 100644 index 00000000..ee0877e6 --- /dev/null +++ b/upstream/fedora-40/man5/proc_kpagecgroup.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpagecgroup 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/kpagecgroup \- memory cgroups +.SH DESCRIPTION +.TP +.IR /proc/kpagecgroup " (since Linux 4.3)" +.\" commit 80ae2fdceba8313b0433f899bdd9c6c463291a17 +This file contains a 64-bit inode number of +the memory cgroup each page is charged to, +indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +.IP +The +.I /proc/kpagecgroup +file is present only if the +.B CONFIG_MEMCG +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_kpagecount.5 b/upstream/fedora-40/man5/proc_kpagecount.5 new file mode 100644 index 00000000..8bb8230a --- /dev/null +++ b/upstream/fedora-40/man5/proc_kpagecount.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpagecount 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/kpagecount \- count of mappings of physical pages +.SH DESCRIPTION +.TP +.IR /proc/kpagecount " (since Linux 2.6.25)" +This file contains a 64-bit count of the number of +times each physical page frame is mapped, +indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +.IP +The +.I /proc/kpagecount +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_kpageflags.5 b/upstream/fedora-40/man5/proc_kpageflags.5 new file mode 100644 index 00000000..e0f9b751 --- /dev/null +++ b/upstream/fedora-40/man5/proc_kpageflags.5 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpageflags 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/kpageflags \- physical pages frame masks +.SH DESCRIPTION +.TP +.IR /proc/kpageflags " (since Linux 2.6.25)" +This file contains 64-bit masks corresponding to each physical page frame; +it is indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +The bits are as follows: +.RS +.IP +.TS +r l l l. +0 - KPF_LOCKED +1 - KPF_ERROR +2 - KPF_REFERENCED +3 - KPF_UPTODATE +4 - KPF_DIRTY +5 - KPF_LRU +6 - KPF_ACTIVE +7 - KPF_SLAB +8 - KPF_WRITEBACK +9 - KPF_RECLAIM +10 - KPF_BUDDY +11 - KPF_MMAP (since Linux 2.6.31) +12 - KPF_ANON (since Linux 2.6.31) +13 - KPF_SWAPCACHE (since Linux 2.6.31) +14 - KPF_SWAPBACKED (since Linux 2.6.31) +15 - KPF_COMPOUND_HEAD (since Linux 2.6.31) +16 - KPF_COMPOUND_TAIL (since Linux 2.6.31) +17 - KPF_HUGE (since Linux 2.6.31) +18 - KPF_UNEVICTABLE (since Linux 2.6.31) +19 - KPF_HWPOISON (since Linux 2.6.31) +20 - KPF_NOPAGE (since Linux 2.6.31) +21 - KPF_KSM (since Linux 2.6.32) +22 - KPF_THP (since Linux 3.4) +23 - KPF_BALLOON (since Linux 3.18) +.\" KPF_BALLOON: commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +24 - KPF_ZERO_PAGE (since Linux 4.0) +.\" KPF_ZERO_PAGE: commit 56873f43abdcd574b25105867a990f067747b2f4 +25 - KPF_IDLE (since Linux 4.3) +.\" KPF_IDLE: commit f074a8f49eb87cde95ac9d040ad5e7ea4f029738 +26 - KPF_PGTABLE (since Linux 4.18) +.\" KPF_PGTABLE: commit 1d40a5ea01d53251c23c7be541d3f4a656cfc537 +.TE +.RE +.IP +For further details on the meanings of these bits, +see the kernel source file +.IR Documentation/admin\-guide/mm/pagemap.rst . +Before Linux 2.6.29, +.\" commit ad3bdefe877afb47480418fdb05ecd42842de65e +.\" commit e07a4b9217d1e97d2f3a62b6b070efdc61212110 +.BR KPF_WRITEBACK , +.BR KPF_RECLAIM , +.BR KPF_BUDDY , +and +.B KPF_LOCKED +did not report correctly. +.IP +The +.I /proc/kpageflags +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_loadavg.5 b/upstream/fedora-40/man5/proc_loadavg.5 new file mode 100644 index 00000000..3403a2b1 --- /dev/null +++ b/upstream/fedora-40/man5/proc_loadavg.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_loadavg 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/loadavg \- load average +.SH DESCRIPTION +.TP +.I /proc/loadavg +The first three fields in this file are load average figures +giving the number of jobs in the run queue (state R) +or waiting for disk I/O (state D) averaged over 1, 5, and 15 minutes. +They are the same as the load average numbers given by +.BR uptime (1) +and other programs. +The fourth field consists of two numbers separated by a slash (/). +The first of these is the number of currently runnable kernel +scheduling entities (processes, threads). +The value after the slash is the number of kernel scheduling entities +that currently exist on the system. +The fifth field is the PID of the process that was most +recently created on the system. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_locks.5 b/upstream/fedora-40/man5/proc_locks.5 new file mode 100644 index 00000000..5269cce1 --- /dev/null +++ b/upstream/fedora-40/man5/proc_locks.5 @@ -0,0 +1,122 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_locks 5 2023-11-19 "Linux man-pages 6.06" +.SH NAME +/proc/locks \- current file locks and leases +.SH DESCRIPTION +.TP +.I /proc/locks +This file shows current file locks +(\c +.BR flock (2) +and +.BR fcntl (2)) +and leases +(\c +.BR fcntl (2)). +.IP +An example of the content shown in this file is the following: +.IP +.in +4n +.EX +1: POSIX ADVISORY READ 5433 08:01:7864448 128 128 +2: FLOCK ADVISORY WRITE 2001 08:01:7864554 0 EOF +3: FLOCK ADVISORY WRITE 1568 00:2f:32388 0 EOF +4: POSIX ADVISORY WRITE 699 00:16:28457 0 EOF +5: POSIX ADVISORY WRITE 764 00:16:21448 0 0 +6: POSIX ADVISORY READ 3548 08:01:7867240 1 1 +7: POSIX ADVISORY READ 3548 08:01:7865567 1826 2335 +8: OFDLCK ADVISORY WRITE \-1 08:01:8713209 128 191 +.EE +.in +.IP +The fields shown in each line are as follows: +.RS +.IP [1] 5 +The ordinal position of the lock in the list. +.IP [2] +The lock type. +Values that may appear here include: +.RS +.TP +.B FLOCK +This is a BSD file lock created using +.BR flock (2). +.TP +.B OFDLCK +This is an open file description (OFD) lock created using +.BR fcntl (2). +.TP +.B POSIX +This is a POSIX byte-range lock created using +.BR fcntl (2). +.RE +.IP [3] +Among the strings that can appear here are the following: +.RS +.TP +.B ADVISORY +This is an advisory lock. +.TP +.B MANDATORY +This is a mandatory lock. +.RE +.IP [4] +The type of lock. +Values that can appear here are: +.RS +.TP +.B READ +This is a POSIX or OFD read lock, or a BSD shared lock. +.TP +.B WRITE +This is a POSIX or OFD write lock, or a BSD exclusive lock. +.RE +.IP [5] +The PID of the process that owns the lock. +.IP +Because OFD locks are not owned by a single process +(since multiple processes may have file descriptors that +refer to the same open file description), +the value \-1 is displayed in this field for OFD locks. +(Before Linux 4.14, +.\" commit 9d5b86ac13c573795525ecac6ed2db39ab23e2a8 +a bug meant that the PID of the process that +initially acquired the lock was displayed instead of the value \-1.) +.IP [6] +Three colon-separated subfields that identify the major and minor device +ID of the device containing the filesystem where the locked file resides, +followed by the inode number of the locked file. +.IP [7] +The byte offset of the first byte of the lock. +For BSD locks, this value is always 0. +.IP [8] +The byte offset of the last byte of the lock. +.B EOF +in this field means that the lock extends to the end of the file. +For BSD locks, the value shown is always +.IR EOF . +.RE +.IP +Since Linux 4.9, +.\" commit d67fd44f697dff293d7cdc29af929241b669affe +the list of locks shown in +.I /proc/locks +is filtered to show just the locks for the processes in the PID +namespace (see +.BR pid_namespaces (7)) +for which the +.I /proc +filesystem was mounted. +(In the initial PID namespace, +there is no filtering of the records shown in this file.) +.IP +The +.BR lslocks (8) +command provides a bit more information about each lock. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_malloc.5 b/upstream/fedora-40/man5/proc_malloc.5 new file mode 100644 index 00000000..9ed444e2 --- /dev/null +++ b/upstream/fedora-40/man5/proc_malloc.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_malloc 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/malloc \- debug malloc (obsolete) +.SH DESCRIPTION +.TP +.IR /proc/malloc " (only up to and including Linux 2.2)" +.\" It looks like this only ever did something back in 1.0 days +This file is present only if +.B CONFIG_DEBUG_MALLOC +was defined during compilation. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_meminfo.5 b/upstream/fedora-40/man5/proc_meminfo.5 new file mode 100644 index 00000000..d2454114 --- /dev/null +++ b/upstream/fedora-40/man5/proc_meminfo.5 @@ -0,0 +1,327 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_meminfo 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/meminfo \- memory usage +.SH DESCRIPTION +.TP +.I /proc/meminfo +This file reports statistics about memory usage on the system. +It is used by +.BR free (1) +to report the amount of free and used memory (both physical and swap) +on the system as well as the shared memory and buffers used by the +kernel. +Each line of the file consists of a parameter name, followed by a colon, +the value of the parameter, and an option unit of measurement (e.g., "kB"). +The list below describes the parameter names and +the format specifier required to read the field value. +Except as noted below, +all of the fields have been present since at least Linux 2.6.0. +Some fields are displayed only if the kernel was configured +with various options; those dependencies are noted in the list. +.RS +.TP +.IR MemTotal " %lu" +Total usable RAM (i.e., physical RAM minus a few reserved +bits and the kernel binary code). +.TP +.IR MemFree " %lu" +The sum of +.IR LowFree + HighFree . +.TP +.IR MemAvailable " %lu (since Linux 3.14)" +An estimate of how much memory is available for starting new +applications, without swapping. +.TP +.IR Buffers " %lu" +Relatively temporary storage for raw disk blocks that +shouldn't get tremendously large (20 MB or so). +.TP +.IR Cached " %lu" +In-memory cache for files read from the disk (the page cache). +Doesn't include +.IR SwapCached . +.TP +.IR SwapCached " %lu" +Memory that once was swapped out, is swapped back in but +still also is in the swap file. +(If memory pressure is high, these pages +don't need to be swapped out again because they are already +in the swap file. +This saves I/O.) +.TP +.IR Active " %lu" +Memory that has been used more recently and usually not +reclaimed unless absolutely necessary. +.TP +.IR Inactive " %lu" +Memory which has been less recently used. +It is more eligible to be reclaimed for other purposes. +.TP +.IR Active(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Active(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Unevictable " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to Linux 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR Mlocked " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to Linux 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR HighTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of highmem. +Highmem is all memory above \[ti]860 MB of physical memory. +Highmem areas are for use by user-space programs, +or for the page cache. +The kernel must use tricks to access +this memory, making it slower to access than lowmem. +.TP +.IR HighFree " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free highmem. +.TP +.IR LowTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of lowmem. +Lowmem is memory which can be used for everything that +highmem can be used for, but it is also available for the +kernel's use for its own data structures. +Among many other things, +it is where everything from +.I Slab +is allocated. +Bad things happen when you're out of lowmem. +.TP +.IR LowFree " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free lowmem. +.TP +.IR MmapCopy " %lu (since Linux 2.6.29)" +.RB ( CONFIG_MMU +is required.) +[To be documented.] +.TP +.IR SwapTotal " %lu" +Total amount of swap space available. +.TP +.IR SwapFree " %lu" +Amount of swap space that is currently unused. +.TP +.IR Dirty " %lu" +Memory which is waiting to get written back to the disk. +.TP +.IR Writeback " %lu" +Memory which is actively being written back to the disk. +.TP +.IR AnonPages " %lu (since Linux 2.6.18)" +Non-file backed pages mapped into user-space page tables. +.TP +.IR Mapped " %lu" +Files which have been mapped into memory (with +.BR mmap (2)), +such as libraries. +.TP +.IR Shmem " %lu (since Linux 2.6.32)" +Amount of memory consumed in +.BR tmpfs (5) +filesystems. +.TP +.IR KReclaimable " %lu (since Linux 4.20)" +Kernel allocations that the kernel will attempt to reclaim +under memory pressure. +Includes +.I SReclaimable +(below), and other direct allocations with a shrinker. +.TP +.IR Slab " %lu" +In-kernel data structures cache. +(See +.BR slabinfo (5).) +.TP +.IR SReclaimable " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that might be reclaimed, such as caches. +.TP +.IR SUnreclaim " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that cannot be reclaimed on memory pressure. +.TP +.IR KernelStack " %lu (since Linux 2.6.32)" +Amount of memory allocated to kernel stacks. +.TP +.IR PageTables " %lu (since Linux 2.6.18)" +Amount of memory dedicated to the lowest level of page tables. +.TP +.IR Quicklists " %lu (since Linux 2.6.27)" +(\fBCONFIG_QUICKLIST\fP is required.) +[To be documented.] +.TP +.IR NFS_Unstable " %lu (since Linux 2.6.18)" +NFS pages sent to the server, but not yet committed to stable storage. +.TP +.IR Bounce " %lu (since Linux 2.6.18)" +Memory used for block device "bounce buffers". +.TP +.IR WritebackTmp " %lu (since Linux 2.6.26)" +Memory used by FUSE for temporary writeback buffers. +.TP +.IR CommitLimit " %lu (since Linux 2.6.10)" +This is the total amount of memory currently available to +be allocated on the system, expressed in kilobytes. +This limit is adhered to +only if strict overcommit accounting is enabled (mode 2 in +.IR /proc/sys/vm/overcommit_memory ). +The limit is calculated according to the formula described under +.IR /proc/sys/vm/overcommit_memory . +For further details, see the kernel source file +.IR Documentation/vm/overcommit\-accounting.rst . +.TP +.IR Committed_AS " %lu" +The amount of memory presently allocated on the system. +The committed memory is a sum of all of the memory which +has been allocated by processes, even if it has not been +"used" by them as of yet. +A process which allocates 1 GB of memory (using +.BR malloc (3) +or similar), but touches only 300 MB of that memory will show up +as using only 300 MB of memory even if it has the address space +allocated for the entire 1 GB. +.IP +This 1 GB is memory which has been "committed" to by the VM +and can be used at any time by the allocating application. +With strict overcommit enabled on the system (mode 2 in +.IR /proc/sys/vm/overcommit_memory ), +allocations which would exceed the +.I CommitLimit +will not be permitted. +This is useful if one needs to guarantee that processes will not +fail due to lack of memory once that memory has been successfully allocated. +.TP +.IR VmallocTotal " %lu" +Total size of vmalloc memory area. +.TP +.IR VmallocUsed " %lu" +Amount of vmalloc area which is used. +Since Linux 4.4, +.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 +this field is no longer calculated, and is hard coded as 0. +See +.IR /proc/vmallocinfo . +.TP +.IR VmallocChunk " %lu" +Largest contiguous block of vmalloc area which is free. +Since Linux 4.4, +.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 +this field is no longer calculated and is hard coded as 0. +See +.IR /proc/vmallocinfo . +.TP +.IR HardwareCorrupted " %lu (since Linux 2.6.32)" +(\fBCONFIG_MEMORY_FAILURE\fP is required.) +[To be documented.] +.TP +.IR LazyFree " %lu (since Linux 4.12)" +Shows the amount of memory marked by +.BR madvise (2) +.BR MADV_FREE . +.TP +.IR AnonHugePages " %lu (since Linux 2.6.38)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Non-file backed huge pages mapped into user-space page tables. +.TP +.IR ShmemHugePages " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Memory used by shared memory (shmem) and +.BR tmpfs (5) +allocated with huge pages. +.TP +.IR ShmemPmdMapped " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Shared memory mapped into user space with huge pages. +.TP +.IR CmaTotal " %lu (since Linux 3.1)" +Total CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR CmaFree " %lu (since Linux 3.1)" +Free CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR HugePages_Total " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of the pool of huge pages. +.TP +.IR HugePages_Free " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The number of huge pages in the pool that are not yet allocated. +.TP +.IR HugePages_Rsvd " %lu (since Linux 2.6.17)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages for +which a commitment to allocate from the pool has been made, +but no allocation has yet been made. +These reserved huge pages +guarantee that an application will be able to allocate a +huge page from the pool of huge pages at fault time. +.TP +.IR HugePages_Surp " %lu (since Linux 2.6.24)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages in +the pool above the value in +.IR /proc/sys/vm/nr_hugepages . +The maximum number of surplus huge pages is controlled by +.IR /proc/sys/vm/nr_overcommit_hugepages . +.TP +.IR Hugepagesize " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of huge pages. +.TP +.IR DirectMap4k " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4 kB pages. +(x86.) +.TP +.IR DirectMap4M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4 MB pages. +(x86 with +.B CONFIG_X86_64 +or +.B CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap2M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 2 MB pages. +(x86 with neither +.B CONFIG_X86_64 +nor +.B CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap1G " %lu (since Linux 2.6.27)" +(x86 with +.B CONFIG_X86_64 +and +.B CONFIG_X86_DIRECT_GBPAGES +enabled.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_modules.5 b/upstream/fedora-40/man5/proc_modules.5 new file mode 100644 index 00000000..56ad8f9e --- /dev/null +++ b/upstream/fedora-40/man5/proc_modules.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_modules 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/modules \- loaded modules +.SH DESCRIPTION +.TP +.I /proc/modules +A text list of the modules that have been loaded by the system. +See also +.BR lsmod (8). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_mtrr.5 b/upstream/fedora-40/man5/proc_mtrr.5 new file mode 100644 index 00000000..6860d112 --- /dev/null +++ b/upstream/fedora-40/man5/proc_mtrr.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_mtrr 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/mtrr \- memory type range registers +.SH DESCRIPTION +.TP +.I /proc/mtrr +Memory Type Range Registers. +See the Linux kernel source file +.I Documentation/x86/mtrr.rst +(or +.I Documentation/x86/mtrr.txt +.\" commit 7225e75144b9718cbbe1820d9c011c809d5773fd +before Linux 5.2, or +.I Documentation/mtrr.txt +before Linux 2.6.28) +for details. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_partitions.5 b/upstream/fedora-40/man5/proc_partitions.5 new file mode 100644 index 00000000..ef5874d8 --- /dev/null +++ b/upstream/fedora-40/man5/proc_partitions.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_partitions 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/partitions \- major and minor numbers of partitions +.SH DESCRIPTION +.TP +.I /proc/partitions +Contains the major and minor numbers of each partition as well as the number +of 1024-byte blocks and the partition name. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pci.5 b/upstream/fedora-40/man5/proc_pci.5 new file mode 100644 index 00000000..0fa2cc88 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pci.5 @@ -0,0 +1,28 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pci 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pci \- PCI devices +.SH DESCRIPTION +.TP +.I /proc/pci +This is a listing of all PCI devices found during kernel initialization +and their configuration. +.IP +This file has been deprecated in favor of a new +.I /proc +interface for PCI +.RI ( /proc/bus/pci ). +It became optional in Linux 2.2 (available with +.B CONFIG_PCI_OLD_PROC +set at kernel compilation). +It became once more nonoptionally enabled in Linux 2.4. +Next, it was deprecated in Linux 2.6 (still available with +.B CONFIG_PCI_LEGACY_PROC +set), and finally removed altogether since Linux 2.6.17. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid.5 b/upstream/fedora-40/man5/proc_pid.5 new file mode 100644 index 00000000..172b7805 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid.5 @@ -0,0 +1,73 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/, /proc/self/ \- process information +.SH DESCRIPTION +.TP +.IR /proc/ pid / +There is a numerical subdirectory for each running process; the +subdirectory is named by the process ID. +Each +.IR /proc/ pid +subdirectory contains the pseudo-files and directories described below. +.IP +The files inside each +.IR /proc/ pid +directory are normally owned by the effective user and +effective group ID of the process. +However, as a security measure, the ownership is made +.I root:root +if the process's "dumpable" attribute is set to a value other than 1. +.IP +Before Linux 4.11, +.\" commit 68eb94f16227336a5773b83ecfa8290f1d6b78ce +.I root:root +meant the "global" root user ID and group ID +(i.e., UID 0 and GID 0 in the initial user namespace). +Since Linux 4.11, +if the process is in a noninitial user namespace that has a +valid mapping for user (group) ID 0 inside the namespace, then +the user (group) ownership of the files under +.IR /proc/ pid +is instead made the same as the root user (group) ID of the namespace. +This means that inside a container, +things work as expected for the container "root" user. +.IP +The process's "dumpable" attribute may change for the following reasons: +.RS +.IP \[bu] 3 +The attribute was explicitly set via the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation. +.IP \[bu] +The attribute was reset to the value in the file +.I /proc/sys/fs/suid_dumpable +(described below), for the reasons described in +.BR prctl (2). +.RE +.IP +Resetting the "dumpable" attribute to 1 reverts the ownership of the +.IR /proc/ pid /* +files to the process's effective UID and GID. +Note, however, that if the effective UID or GID is subsequently modified, +then the "dumpable" attribute may be reset, as described in +.BR prctl (2). +Therefore, it may be desirable to reset the "dumpable" attribute +.I after +making any desired changes to the process's effective UID or GID. +.TP +.I /proc/self/ +This directory refers to the process accessing the +.I /proc +filesystem, +and is identical to the +.I /proc +directory named by the process ID of the same process. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_attr.5 b/upstream/fedora-40/man5/proc_pid_attr.5 new file mode 100644 index 00000000..2f8fa2a8 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_attr.5 @@ -0,0 +1,137 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_attr 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/attr/ \- security-related attributes +.SH DESCRIPTION +.TP +.IR /proc/ pid /attr/ +.\" https://lwn.net/Articles/28222/ +.\" From: Stephen Smalley +.\" To: LKML and others +.\" Subject: [RFC][PATCH] Process Attribute API for Security Modules +.\" Date: 08 Apr 2003 16:17:52 -0400 +.\" +.\" http://www.nsa.gov/research/_files/selinux/papers/module/x362.shtml +.\" +The files in this directory provide an API for security modules. +The contents of this directory are files that can be read and written +in order to set security-related attributes. +This directory was added to support SELinux, +but the intention was that the API be general enough to support +other security modules. +For the purpose of explanation, +examples of how SELinux uses these files are provided below. +.IP +This directory is present only if the kernel was configured with +.BR CONFIG_SECURITY . +.TP +.IR /proc/ pid /attr/current " (since Linux 2.6.0)" +The contents of this file represent the current +security attributes of the process. +.IP +In SELinux, this file is used to get the security context of a process. +Prior to Linux 2.6.11, this file could not be used to set the security +context (a write was always denied), since SELinux limited process security +transitions to +.BR execve (2) +(see the description of +.IR /proc/ pid /attr/exec , +below). +Since Linux 2.6.11, SELinux lifted this restriction and began supporting +"set" operations via writes to this node if authorized by policy, +although use of this operation is only suitable for applications that are +trusted to maintain any desired separation between the old and new security +contexts. +.IP +Prior to Linux 2.6.28, SELinux did not allow threads within a +multithreaded process to set their security context via this node +as it would yield an inconsistency among the security contexts of the +threads sharing the same memory space. +Since Linux 2.6.28, SELinux lifted +this restriction and began supporting "set" operations for threads within +a multithreaded process if the new security context is bounded by the old +security context, where the bounded relation is defined in policy and +guarantees that the new security context has a subset of the permissions +of the old security context. +.IP +Other security modules may choose to support "set" operations via +writes to this node. +.TP +.IR /proc/ pid /attr/exec " (since Linux 2.6.0)" +This file represents the attributes to assign to the +process upon a subsequent +.BR execve (2). +.IP +In SELinux, +this is needed to support role/domain transitions, and +.BR execve (2) +is the preferred point to make such transitions because it offers better +control over the initialization of the process in the new security label +and the inheritance of state. +In SELinux, this attribute is reset on +.BR execve (2) +so that the new program reverts to the default behavior for any +.BR execve (2) +calls that it may make. +In SELinux, a process can set +only its own +.IR /proc/ pid /attr/exec +attribute. +.TP +.IR /proc/ pid /attr/fscreate " (since Linux 2.6.0)" +This file represents the attributes to assign to files +created by subsequent calls to +.BR open (2), +.BR mkdir (2), +.BR symlink (2), +and +.BR mknod (2) +.IP +SELinux employs this file to support creation of a file +(using the aforementioned system calls) +in a secure state, +so that there is no risk of inappropriate access being obtained +between the time of creation and the time that attributes are set. +In SELinux, this attribute is reset on +.BR execve (2), +so that the new program reverts to the default behavior for +any file creation calls it may make, but the attribute will persist +across multiple file creation calls within a program unless it is +explicitly reset. +In SELinux, a process can set only its own +.IR /proc/ pid /attr/fscreate +attribute. +.TP +.IR /proc/ pid /attr/keycreate " (since Linux 2.6.18)" +.\" commit 4eb582cf1fbd7b9e5f466e3718a59c957e75254e +If a process writes a security context into this file, +all subsequently created keys +.RB ( add_key (2)) +will be labeled with this context. +For further information, see the kernel source file +.I Documentation/security/keys/core.rst +(or file +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.I Documentation/security/keys.txt +between Linux 3.0 and Linux 4.13, or +.\" commit d410fa4ef99112386de5f218dd7df7b4fca910b4 +.I Documentation/keys.txt +before Linux 3.0). +.TP +.IR /proc/ pid /attr/prev " (since Linux 2.6.0)" +This file contains the security context of the process before the last +.BR execve (2); +that is, the previous value of +.IR /proc/ pid /attr/current . +.TP +.IR /proc/ pid /attr/socketcreate " (since Linux 2.6.18)" +.\" commit 42c3e03ef6b298813557cdb997bd6db619cd65a2 +If a process writes a security context into this file, +all subsequently created sockets will be labeled with this context. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_autogroup.5 b/upstream/fedora-40/man5/proc_pid_autogroup.5 new file mode 100644 index 00000000..7765d533 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_autogroup.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_autogroup 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +proc_pid_autogroup \- group tasks for the scheduler +.SH DESCRIPTION +.TP +.IR /proc/ pid /autogroup " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_auxv.5 b/upstream/fedora-40/man5/proc_pid_auxv.5 new file mode 100644 index 00000000..ce36368a --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_auxv.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_auxv 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/auxv \- exec(3) information +.SH DESCRIPTION +.TP +.IR /proc/ pid /auxv " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test7 +This contains the contents of the ELF interpreter information passed +to the process at exec time. +The format is one \fIunsigned long\fP ID +plus one \fIunsigned long\fP value for each entry. +The last entry contains two zeros. +See also +.BR getauxval (3). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_cgroup.5 b/upstream/fedora-40/man5/proc_pid_cgroup.5 new file mode 100644 index 00000000..2605b502 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_cgroup.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cgroup 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/cgroup \- control group +.SH DESCRIPTION +.TP +.IR /proc/ pid /cgroup " (since Linux 2.6.24)" +See +.BR cgroups (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_clear_refs.5 b/upstream/fedora-40/man5/proc_pid_clear_refs.5 new file mode 100644 index 00000000..d98144aa --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_clear_refs.5 @@ -0,0 +1,87 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_clear_refs 5 2023-09-07 "Linux man-pages 6.06" +.SH NAME +/proc/pid/clear_refs \- reset the PG_Referenced and ACCESSED/YOUNG bits +.SH DESCRIPTION +.TP +.IR /proc/ pid /clear_refs " (since Linux 2.6.22)" +.\" commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22) +.\" commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32) +.\" commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11) +.\" +.\" "Clears page referenced bits shown in smaps output" +.\" write-only, writable only by the owner of the process +.IP +This is a write-only file, writable only by owner of the process. +.IP +The following values may be written to the file: +.RS +.TP +1 (since Linux 2.6.22) +.\" Internally: CLEAR_REFS_ALL +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all the pages associated with the process. +(Before Linux 2.6.32, writing any nonzero value to this file +had this effect.) +.TP +2 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_ANON +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all anonymous pages associated with the process. +.TP +3 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_MAPPED +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all file-mapped pages associated with the process. +.RE +.IP +Clearing the PG_Referenced and ACCESSED/YOUNG bits provides a method +to measure approximately how much memory a process is using. +One first inspects the values in the "Referenced" fields +for the VMAs shown in +.IR /proc/ pid /smaps +to get an idea of the memory footprint of the +process. +One then clears the PG_Referenced and ACCESSED/YOUNG bits +and, after some measured time interval, +once again inspects the values in the "Referenced" fields +to get an idea of the change in memory footprint of the +process during the measured interval. +If one is interested only in inspecting the selected mapping types, +then the value 2 or 3 can be used instead of 1. +.IP +Further values can be written to affect different properties: +.RS +.TP +4 (since Linux 3.11) +Clear the soft-dirty bit for all the pages associated with the process. +.\" Internally: CLEAR_REFS_SOFT_DIRTY +This is used (in conjunction with +.IR /proc/ pid /pagemap ) +by the check-point restore system to discover which pages of a process +have been dirtied since the file +.IR /proc/ pid /clear_refs +was written to. +.TP +5 (since Linux 4.0) +.\" Internally: CLEAR_REFS_MM_HIWATER_RSS +Reset the peak resident set size ("high water mark") to the process's +current resident set size value. +.RE +.IP +Writing any value to +.IR /proc/ pid /clear_refs +other than those listed above has no effect. +.IP +The +.IR /proc/ pid /clear_refs +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_cmdline.5 b/upstream/fedora-40/man5/proc_pid_cmdline.5 new file mode 100644 index 00000000..25c43b5e --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_cmdline.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cmdline 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/cmdline \- command line +.SH DESCRIPTION +.TP +.IR /proc/ pid /cmdline +This read-only file holds the complete command line for the process, +unless the process is a zombie. +.\" In Linux 2.3.26, this also used to be true if the process was swapped out. +In the latter case, there is nothing in this file: +that is, a read on this file will return 0 characters. +.IP +For processes which are still running, +the command-line arguments appear in this file +in the same layout as they do in process memory: +If the process is well-behaved, +it is a set of strings separated by null bytes (\[aq]\e0\[aq]), +with a further null byte after the last string. +.IP +This is the common case, +but processes have the freedom to +override the memory region and +break assumptions about the contents or format of the +.IR /proc/ pid /cmdline +file. +.IP +If, after an +.BR execve (2), +the process modifies its +.I argv +strings, those changes will show up here. +This is not the same thing as modifying the +.I argv +array. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ARG_START . +.IP +Think of this file as the command line that the process wants you to see. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_comm.5 b/upstream/fedora-40/man5/proc_pid_comm.5 new file mode 100644 index 00000000..18566e95 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_comm.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_comm 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/comm \- command name +.SH DESCRIPTION +.TP +.IR /proc/ pid /comm " (since Linux 2.6.33)" +.\" commit 4614a696bd1c3a9af3a08f0e5874830a85b889d4 +This file exposes the process's +.I comm +value\[em]that is, the command name associated with the process. +Different threads in the same process may have different +.I comm +values, accessible via +.IR /proc/ pid /task/ tid /comm . +A thread may modify its +.I comm +value, or that of any of other thread in the same thread group (see +the discussion of +.B CLONE_THREAD +in +.BR clone (2)), +by writing to the file +.IR /proc/self/task/ tid /comm . +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +.IP +This file provides a superset of the +.BR prctl (2) +.B PR_SET_NAME +and +.B PR_GET_NAME +operations, and is employed by +.BR pthread_setname_np (3) +when used to rename threads other than the caller. +The value in this file is used for the +.I %e +specifier in +.IR /proc/sys/kernel/core_pattern ; +see +.BR core (5). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_coredump_filter.5 b/upstream/fedora-40/man5/proc_pid_coredump_filter.5 new file mode 100644 index 00000000..638020bc --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_coredump_filter.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_coredump_filter 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/coredump_filter \- core dump filter +.SH DESCRIPTION +.TP +.IR /proc/ pid /coredump_filter " (since Linux 2.6.23)" +See +.BR core (5). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_cpuset.5 b/upstream/fedora-40/man5/proc_pid_cpuset.5 new file mode 100644 index 00000000..26314704 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_cpuset.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cpuset 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/cpuset \- CPU affinity sets +.SH DESCRIPTION +.TP +.IR /proc/ pid /cpuset " (since Linux 2.6.12)" +.\" and/proc/[pid]/task/[tid]/cpuset +See +.BR cpuset (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_cwd.5 b/upstream/fedora-40/man5/proc_pid_cwd.5 new file mode 100644 index 00000000..5ed1b137 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_cwd.5 @@ -0,0 +1,36 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cwd 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/cwd \- symbolic link to current working directory +.SH DESCRIPTION +.TP +.IR /proc/ pid /cwd +This is a symbolic link to the current working directory of the process. +To find out the current working directory of process 20, +for instance, you can do this: +.IP +.in +4n +.EX +.RB "$" " cd /proc/20/cwd; pwd \-P" +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_environ.5 b/upstream/fedora-40/man5/proc_pid_environ.5 new file mode 100644 index 00000000..075a2674 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_environ.5 @@ -0,0 +1,48 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_environ 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/environ \- initial environment +.SH DESCRIPTION +.TP +.IR /proc/ pid /environ +This file contains the initial environment that was set +when the currently executing program was started via +.BR execve (2). +The entries are separated by null bytes (\[aq]\e0\[aq]), +and there may be a null byte at the end. +Thus, to print out the environment of process 1, you would do: +.IP +.in +4n +.EX +.RB "$" " cat /proc/1/environ | tr \[aq]\e000\[aq] \[aq]\en\[aq]" +.EE +.in +.IP +If, after an +.BR execve (2), +the process modifies its environment +(e.g., by calling functions such as +.BR putenv (3) +or modifying the +.BR environ (7) +variable directly), +this file will +.I not +reflect those changes. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ENV_START . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_exe.5 b/upstream/fedora-40/man5/proc_pid_exe.5 new file mode 100644 index 00000000..ca9b7f09 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_exe.5 @@ -0,0 +1,59 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_exe 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/exe \- symbolic link to program pathname +.SH DESCRIPTION +.TP +.IR /proc/ pid /exe +Under Linux 2.2 and later, this file is a symbolic link +containing the actual pathname of the executed command. +This symbolic link can be dereferenced normally; attempting to open +it will open the executable. +You can even type +.IR /proc/ pid /exe +to run another copy of the same executable that is being run by +process +.IR pid . +If the pathname has been unlinked, the symbolic link will contain the +string \[aq]\ (deleted)\[aq] appended to the original pathname. +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Under Linux 2.0 and earlier, +.IR /proc/ pid /exe +is a pointer to the binary which was executed, +and appears as a symbolic link. +A +.BR readlink (2) +call on this file under Linux 2.0 returns a string in the format: +.IP +.in +4n +.EX +[device]:inode +.EE +.in +.IP +For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, +MFM, etc. drives) minor 01 (first partition on the first drive). +.IP +.BR find (1) +with the +.I \-inum +option can be used to locate the file. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_fd.5 b/upstream/fedora-40/man5/proc_pid_fd.5 new file mode 100644 index 00000000..bb86075d --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_fd.5 @@ -0,0 +1,161 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_fd 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/fd/ \- file descriptors +.SH DESCRIPTION +.TP +.IR /proc/ pid /fd/ +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor, and which is a +symbolic link to the actual file. +Thus, 0 is standard input, 1 standard output, 2 standard error, and so on. +.IP +For file descriptors for pipes and sockets, +the entries will be symbolic links whose content is the +file type with the inode. +A +.BR readlink (2) +call on this file returns a string in the format: +.IP +.in +4n +.EX +type:[inode] +.EE +.in +.IP +For example, +.I socket:[2248868] +will be a socket and its inode is 2248868. +For sockets, that inode can be used to find more information +in one of the files under +.IR /proc/net/ . +.IP +For file descriptors that have no corresponding inode +(e.g., file descriptors produced by +.BR bpf (2), +.BR epoll_create (2), +.BR eventfd (2), +.BR inotify_init (2), +.BR perf_event_open (2), +.BR signalfd (2), +.BR timerfd_create (2), +and +.BR userfaultfd (2)), +the entry will be a symbolic link with contents of the form +.IP +.in +4n +.EX +.RI anon_inode: file-type +.EE +.in +.IP +In many cases (but not all), the +.I file-type +is surrounded by square brackets. +.IP +For example, an epoll file descriptor will have a symbolic link +whose content is the string +.IR "anon_inode:[eventpoll]" . +.IP +.\"The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this directory +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Programs that take a filename as a command-line argument, +but don't take input from standard input if no argument is supplied, +and programs that write to a file named as a command-line argument, +but don't send their output to standard output +if no argument is supplied, can nevertheless be made to use +standard input or standard output by using +.IR /proc/ pid /fd +files as command-line arguments. +For example, assuming that +.I \-i +is the flag designating an input file and +.I \-o +is the flag designating an output file: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /proc/self/fd/0 \-o /proc/self/fd/1 ..." +.EE +.in +.IP +and you have a working filter. +.\" The following is not true in my tests (MTK): +.\" Note that this will not work for +.\" programs that seek on their files, as the files in the fd directory +.\" are not seekable. +.IP +.I /proc/self/fd/N +is approximately the same as +.I /dev/fd/N +in some UNIX and UNIX-like systems. +Most Linux MAKEDEV scripts symbolically link +.I /dev/fd +to +.IR /proc/self/fd , +in fact. +.IP +Most systems provide symbolic links +.IR /dev/stdin , +.IR /dev/stdout , +and +.IR /dev/stderr , +which respectively link to the files +.IR 0 , +.IR 1 , +and +.I 2 +in +.IR /proc/self/fd . +Thus the example command above could be written as: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /dev/stdin \-o /dev/stdout ..." +.EE +.in +.IP +Permission to dereference or read +.RB ( readlink (2)) +the symbolic links in this directory is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Note that for file descriptors referring to inodes +(pipes and sockets, see above), +those inodes still have permission bits and ownership information +distinct from those of the +.IR /proc/ pid /fd +entry, +and that the owner may differ from the user and group IDs of the process. +An unprivileged process may lack permissions to open them, as in this example: +.IP +.in +4n +.EX +.RB "$" " echo test | sudo \-u nobody cat" +test +.RB "$" " echo test | sudo \-u nobody cat /proc/self/fd/0" +cat: /proc/self/fd/0: Permission denied +.EE +.in +.IP +File descriptor 0 refers to the pipe created by the shell +and owned by that shell's user, which is not +.IR nobody , +so +.B cat +does not have permission +to create a new file descriptor to read from that inode, +even though it can still read from its existing file descriptor 0. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_fdinfo.5 b/upstream/fedora-40/man5/proc_pid_fdinfo.5 new file mode 100644 index 00000000..3703012b --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_fdinfo.5 @@ -0,0 +1,300 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_fdinfo 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/fdinfo/ \- information about file descriptors +.SH DESCRIPTION +.TP +.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)" +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor. +The files in this directory are readable only by the owner of the process. +The contents of each file can be read to obtain information +about the corresponding file descriptor. +The content depends on the type of file referred to by the +corresponding file descriptor. +.IP +For regular files and directories, we see something like: +.IP +.in +4n +.EX +.RB "$" " cat /proc/12015/fdinfo/4" +pos: 1000 +flags: 01002002 +mnt_id: 21 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I pos +This is a decimal number showing the file offset. +.TP +.I flags +This is an octal number that displays the +file access mode and file status flags (see +.BR open (2)). +If the close-on-exec file descriptor flag is set, then +.I flags +will also include the value +.BR O_CLOEXEC . +.IP +Before Linux 3.1, +.\" commit 1117f72ea0217ba0cc19f05adbbd8b9a397f5ab7 +this field incorrectly displayed the setting of +.B O_CLOEXEC +at the time the file was opened, +rather than the current setting of the close-on-exec flag. +.TP +.I +.I mnt_id +This field, present since Linux 3.15, +.\" commit 49d063cb353265c3af701bab215ac438ca7df36d +is the ID of the mount containing this file. +See the description of +.IR /proc/ pid /mountinfo . +.RE +.IP +For eventfd file descriptors (see +.BR eventfd (2)), +we see (since Linux 3.8) +.\" commit cbac5542d48127b546a23d816380a7926eee1c25 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +eventfd\-count: 40 +.EE +.in +.IP +.I eventfd\-count +is the current value of the eventfd counter, in hexadecimal. +.IP +For epoll file descriptors (see +.BR epoll (7)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +tfd: 9 events: 19 data: 74253d2500000009 +tfd: 7 events: 19 data: 74253d2500000007 +.EE +.in +.IP +Each of the lines beginning +.I tfd +describes one of the file descriptors being monitored via +the epoll file descriptor (see +.BR epoll_ctl (2) +for some details). +The +.I tfd +field is the number of the file descriptor. +The +.I events +field is a hexadecimal mask of the events being monitored for this file +descriptor. +The +.I data +field is the data value associated with this file descriptor. +.IP +For signalfd file descriptors (see +.BR signalfd (2)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +sigmask: 0000000000000006 +.EE +.in +.IP +.I sigmask +is the hexadecimal mask of signals that are accepted via this +signalfd file descriptor. +(In this example, bits 2 and 3 are set, corresponding to the signals +.B SIGINT +and +.BR SIGQUIT ; +see +.BR signal (7).) +.IP +For inotify file descriptors (see +.BR inotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 00 +mnt_id: 11 +inotify wd:2 ino:7ef82a sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:2af87e00220ffd73 +inotify wd:1 ino:192627 sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:27261900802dfd73 +.EE +.in +.IP +Each of the lines beginning with "inotify" displays information about +one file or directory that is being monitored. +The fields in this line are as follows: +.RS +.TP +.I wd +A watch descriptor number (in decimal). +.TP +.I ino +The inode number of the target file (in hexadecimal). +.TP +.I sdev +The ID of the device where the target file resides (in hexadecimal). +.TP +.I mask +The mask of events being monitored for the target file (in hexadecimal). +.RE +.IP +If the kernel was built with exportfs support, the path to the target +file is exposed as a file handle, via three hexadecimal fields: +.IR fhandle\-bytes , +.IR fhandle\-type , +and +.IR f_handle . +.IP +For fanotify file descriptors (see +.BR fanotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 11 +fanotify flags:0 event\-flags:88002 +fanotify ino:19264f sdev:800001 mflags:0 mask:1 ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:4f261900a82dfd73 +.EE +.in +.IP +The fourth line displays information defined when the fanotify group +was created via +.BR fanotify_init (2): +.RS +.TP +.I flags +The +.I flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.TP +.I event\-flags +The +.I event_f_flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.RE +.IP +Each additional line shown in the file contains information +about one of the marks in the fanotify group. +Most of these fields are as for inotify, except: +.RS +.TP +.I mflags +The flags associated with the mark +(expressed in hexadecimal). +.TP +.I mask +The events mask for this mark +(expressed in hexadecimal). +.TP +.I ignored_mask +The mask of events that are ignored for this mark +(expressed in hexadecimal). +.RE +.IP +For details on these fields, see +.BR fanotify_mark (2). +.IP +For timerfd file descriptors (see +.BR timerfd (2)), +we see (since Linux 3.17) +.\" commit af9c4957cf212ad9cf0bee34c95cb11de5426e85 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02004002 +mnt_id: 13 +clockid: 0 +ticks: 0 +settime flags: 03 +it_value: (7695568592, 640020877) +it_interval: (0, 0) +.EE +.in +.RS +.TP +.I clockid +This is the numeric value of the clock ID +(corresponding to one of the +.B CLOCK_* +constants defined via +.IR ) +that is used to mark the progress of the timer (in this example, 0 is +.BR CLOCK_REALTIME ). +.TP +.I ticks +This is the number of timer expirations that have occurred, +(i.e., the value that +.BR read (2) +on it would return). +.TP +.I settime flags +This field lists the flags with which the timerfd was last armed (see +.BR timerfd_settime (2)), +in octal +(in this example, both +.B TFD_TIMER_ABSTIME +and +.B TFD_TIMER_CANCEL_ON_SET +are set). +.TP +.I it_value +This field contains the amount of time until the timer will next expire, +expressed in seconds and nanoseconds. +This is always expressed as a relative value, +regardless of whether the timer was created using the +.B TFD_TIMER_ABSTIME +flag. +.TP +.I it_interval +This field contains the interval of the timer, +in seconds and nanoseconds. +(The +.I it_value +and +.I it_interval +fields contain the values that +.BR timerfd_gettime (2) +on this file descriptor would return.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_io.5 b/upstream/fedora-40/man5/proc_pid_io.5 new file mode 100644 index 00000000..f989e493 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_io.5 @@ -0,0 +1,98 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_io 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/io \- I/O statistics +.SH DESCRIPTION +.TP +.IR /proc/ pid /io " (since Linux 2.6.20)" +.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2 +This file contains I/O statistics for the process, for example: +.IP +.in +4n +.EX +.RB "#" " cat /proc/3828/io" +rchar: 323934931 +wchar: 323929600 +syscr: 632687 +syscw: 632675 +read_bytes: 0 +write_bytes: 323932160 +cancelled_write_bytes: 0 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.IR rchar ": characters read" +The number of bytes which this task has caused to be read from storage. +This is simply the sum of bytes which this process passed to +.BR read (2) +and similar system calls. +It includes things such as terminal I/O and +is unaffected by whether or not actual +physical disk I/O was required (the read might have been satisfied from +pagecache). +.TP +.IR wchar ": characters written" +The number of bytes which this task has caused, or shall cause to be written +to disk. +Similar caveats apply here as with +.IR rchar . +.TP +.IR syscr ": read syscalls" +Attempt to count the number of read I/O operations\[em]that is, +system calls such as +.BR read (2) +and +.BR pread (2). +.TP +.IR syscw ": write syscalls" +Attempt to count the number of write I/O operations\[em]that is, +system calls such as +.BR write (2) +and +.BR pwrite (2). +.TP +.IR read_bytes ": bytes read" +Attempt to count the number of bytes which this process really did cause to +be fetched from the storage layer. +This is accurate for block-backed filesystems. +.TP +.IR write_bytes ": bytes written" +Attempt to count the number of bytes which this process caused to be sent to +the storage layer. +.TP +.IR cancelled_write_bytes : +The big inaccuracy here is truncate. +If a process writes 1 MB to a file and then deletes the file, +it will in fact perform no writeout. +But it will have been accounted as having caused 1 MB of write. +In other words: this field represents the number of bytes which this process +caused to not happen, by truncating pagecache. +A task can cause "negative" I/O too. +If this task truncates some dirty pagecache, +some I/O which another task has been accounted for +(in its +.IR write_bytes ) +will not be happening. +.RE +.IP +.IR Note : +In the current implementation, things are a bit racy on 32-bit systems: +if process A reads process B's +.IR /proc/ pid /io +while process B is updating one of these 64-bit counters, +process A could see an intermediate result. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_limits.5 b/upstream/fedora-40/man5/proc_pid_limits.5 new file mode 100644 index 00000000..70ad07d0 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_limits.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_oid_limits 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/limits \- resource limits +.SH DESCRIPTION +.TP +.IR /proc/ pid /limits " (since Linux 2.6.24)" +This file displays the soft limit, hard limit, and units of measurement +for each of the process's resource limits (see +.BR getrlimit (2)). +Up to and including Linux 2.6.35, +this file is protected to allow reading only by the real UID of the process. +Since Linux 2.6.36, +.\" commit 3036e7b490bf7878c6dae952eec5fb87b1106589 +this file is readable by all users on the system. +.\" FIXME Describe /proc/[pid]/loginuid +.\" Added in Linux 2.6.11; updating requires CAP_AUDIT_CONTROL +.\" CONFIG_AUDITSYSCALL +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_map_files.5 b/upstream/fedora-40/man5/proc_pid_map_files.5 new file mode 100644 index 00000000..e1ba8024 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_map_files.5 @@ -0,0 +1,72 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_map_files 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/map_files/ \- memory-mapped files +.SH DESCRIPTION +.TP +.IR /proc/ pid /map_files/ " (since Linux 3.3)" +.\" commit 640708a2cff7f81e246243b0073c66e6ece7e53e +This subdirectory contains entries corresponding to memory-mapped +files (see +.BR mmap (2)). +Entries are named by memory region start and end +address pair (expressed as hexadecimal numbers), +and are symbolic links to the mapped files themselves. +Here is an example, +with the output wrapped and reformatted to fit on an 80-column display: +.IP +.in +4n +.EX +.RB "#" " ls \-l /proc/self/map_files/" +lr\-\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:31 + 3252e00000\-3252e20000 \-> /usr/lib64/ld\-2.15.so +\&... +.EE +.in +.IP +Although these entries are present for memory regions that were +mapped with the +.B MAP_FILE +flag, the way anonymous shared memory (regions created with the +.B MAP_ANON | MAP_SHARED +flags) +is implemented in Linux +means that such regions also appear on this directory. +Here is an example where the target file is the deleted +.I /dev/zero +one: +.IP +.in +4n +.EX +lrw\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:33 + 7fc075d2f000\-7fc075e6f000 \-> /dev/zero (deleted) +.EE +.in +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Until Linux 4.3, +.\" commit bdb4d100afe9818aebd1d98ced575c5ef143456c +this directory appeared only if the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option was enabled. +.IP +Capabilities are required to read the contents of the symbolic links in +this directory: before Linux 5.9, the reading process requires +.B CAP_SYS_ADMIN +in the initial user namespace; +since Linux 5.9, the reading process must have either +.B CAP_SYS_ADMIN +or +.B CAP_CHECKPOINT_RESTORE +in the initial (i.e. root) user namespace. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_maps.5 b/upstream/fedora-40/man5/proc_pid_maps.5 new file mode 100644 index 00000000..22c220f3 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_maps.5 @@ -0,0 +1,156 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_maps 5 2023-09-07 "Linux man-pages 6.06" +.SH NAME +/proc/pid/maps \- mapped memory regions +.SH DESCRIPTION +.TP +.IR /proc/ pid /maps +A file containing the currently mapped memory regions and their access +permissions. +See +.BR mmap (2) +for some further information about memory mappings. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +The format of the file is: +.IP +.in +4n +.EX +.I "address perms offset dev inode pathname" +00400000\-00452000 r\-xp 00000000 08:02 173521 /usr/bin/dbus\-daemon +00651000\-00652000 r\-\-p 00051000 08:02 173521 /usr/bin/dbus\-daemon +00652000\-00655000 rw\-p 00052000 08:02 173521 /usr/bin/dbus\-daemon +00e03000\-00e24000 rw\-p 00000000 00:00 0 [heap] +00e24000\-011f7000 rw\-p 00000000 00:00 0 [heap] +\&... +35b1800000\-35b1820000 r\-xp 00000000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a1f000\-35b1a20000 r\-\-p 0001f000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a20000\-35b1a21000 rw\-p 00020000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a21000\-35b1a22000 rw\-p 00000000 00:00 0 +35b1c00000\-35b1dac000 r\-xp 00000000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1dac000\-35b1fac000 \-\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fac000\-35b1fb0000 r\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fb0000\-35b1fb2000 rw\-p 001b0000 08:02 135870 /usr/lib64/libc\-2.15.so +\&... +f2c6ff8c000\-7f2c7078c000 rw\-p 00000000 00:00 0 [stack:986] +\&... +7fffb2c0d000\-7fffb2c2e000 rw\-p 00000000 00:00 0 [stack] +7fffb2d48000\-7fffb2d49000 r\-xp 00000000 00:00 0 [vdso] +.EE +.in +.IP +The +.I address +field is the address space in the process that the mapping occupies. +The +.I perms +field is a set of permissions: +.IP +.in +4n +.EX +r = read +w = write +x = execute +s = shared +p = private (copy on write) +.EE +.in +.IP +The +.I offset +field is the offset into the file/whatever; +.I dev +is the device +(major:minor); +.I inode +is the inode on that device. +0 indicates that no inode is associated with the memory region, +as would be the case with BSS (uninitialized data). +.IP +The +.I pathname +field will usually be the file that is backing the mapping. +For ELF files, +you can easily coordinate with the +.I offset +field by looking at the +Offset field in the ELF program headers +.RI ( "readelf\ \-l" ). +.IP +There are additional helpful pseudo-paths: +.RS +.TP +.I [stack] +The initial process's (also known as the main thread's) stack. +.TP +.IR [stack: tid ] " (from Linux 3.4 to Linux 4.4)" +.\" commit b76437579d1344b612cf1851ae610c636cec7db0 (added) +.\" commit 65376df582174ffcec9e6471bf5b0dd79ba05e4a (removed) +A thread's stack (where the +.I tid +is a thread ID). +It corresponds to the +.IR /proc/ pid /task/ tid / +path. +This field was removed in Linux 4.5, since providing this information +for a process with large numbers of threads is expensive. +.TP +.I [vdso] +The virtual dynamically linked shared object. +See +.BR vdso (7). +.TP +.I [heap] +The process's heap. +.TP +.IR [anon: name ] " (since Linux 5.17)" +.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b +A named private anonymous mapping. +Set with +.BR prctl (2) +.BR PR_SET_VMA_ANON_NAME . +.TP +.IR [anon_shmem: name ] " (since Linux 6.2)" +.\" Commit d09e8ca6cb93bb4b97517a18fbbf7eccb0e9ff43 +A named shared anonymous mapping. +Set with +.BR prctl (2) +.BR PR_SET_VMA_ANON_NAME . +.in +.RE +.IP +If the +.I pathname +field is blank, +this is an anonymous mapping as obtained via +.BR mmap (2). +There is no easy way to coordinate this back to a process's source, +short of running it through +.BR gdb (1), +.BR strace (1), +or similar. +.IP +.I pathname +is shown unescaped except for newline characters, which are replaced +with an octal escape sequence. +As a result, it is not possible to determine whether the original +pathname contained a newline character or the literal +.I \e012 +character sequence. +.IP +If the mapping is file-backed and the file has been deleted, the string +" (deleted)" is appended to the pathname. +Note that this is ambiguous too. +.IP +Under Linux 2.0, there is no field giving pathname. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_mem.5 b/upstream/fedora-40/man5/proc_pid_mem.5 new file mode 100644 index 00000000..8cea82e2 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_mem.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mem 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/mem \- memory +.SH DESCRIPTION +.TP +.IR /proc/ pid /mem +This file can be used to access the pages of a process's memory through +.BR open (2), +.BR read (2), +and +.BR lseek (2). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_mountinfo.5 b/upstream/fedora-40/man5/proc_pid_mountinfo.5 new file mode 100644 index 00000000..2ff0da3d --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_mountinfo.5 @@ -0,0 +1,124 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mountinfo 5 2023-11-24 "Linux man-pages 6.06" +.SH NAME +/proc/pid/mountinfo \- mount information +.SH DESCRIPTION +.TP +.IR /proc/ pid /mountinfo " (since Linux 2.6.26)" +.\" This info adapted from Documentation/filesystems/proc.txt +.\" commit 2d4d4864ac08caff5c204a752bd004eed4f08760 +This file contains information about mounts +in the process's mount namespace (see +.BR mount_namespaces (7)). +It supplies various information +(e.g., propagation state, root of mount for bind mounts, +identifier for each mount and its parent) that is missing from the (older) +.IR /proc/ pid /mounts +file, and fixes various other problems with that file +(e.g., nonextensibility, +failure to distinguish per-mount versus per-superblock options). +.IP +The file contains lines of the form: +.IP +.EX +36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 \- ext3 /dev/root rw,errors=continue +(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11) +.EE +.IP +The numbers in parentheses are labels for the descriptions below: +.RS 7 +.TP 5 +(1) +mount ID: a unique ID for the mount (may be reused after +.BR umount (2)). +.TP +(2) +parent ID: the ID of the parent mount +(or of self for the root of this mount namespace's mount tree). +.IP +If a new mount is stacked on top of a previous existing mount +(so that it hides the existing mount) at pathname P, +then the parent of the new mount is the previous mount at that location. +Thus, when looking at all the mounts stacked at a particular location, +the top-most mount is the one that is not the parent +of any other mount at the same location. +(Note, however, that this top-most mount will be accessible only if +the longest path subprefix of P that is a mount point +is not itself hidden by a stacked mount.) +.IP +If the parent mount lies outside the process's root directory (see +.BR chroot (2)), +the ID shown here won't have a corresponding record in +.I mountinfo +whose mount ID (field 1) matches this parent mount ID +(because mounts that lie outside the process's root directory +are not shown in +.IR mountinfo ). +As a special case of this point, +the process's root mount may have a parent mount +(for the initramfs filesystem) that lies +.\" Miklos Szeredi, Nov 2017: The hidden one is the initramfs, I believe +.\" mtk: In the initial mount namespace, this hidden ID has the value 0 +outside the process's root directory, +and an entry for that mount will not appear in +.IR mountinfo . +.TP +(3) +major:minor: the value of +.I st_dev +for files on this filesystem (see +.BR stat (2)). +.TP +(4) +root: the pathname of the directory in the filesystem +which forms the root of this mount. +.TP +(5) +mount point: the pathname of the mount point relative +to the process's root directory. +.TP +(6) +mount options: per-mount options (see +.BR mount (2)). +.TP +(7) +optional fields: zero or more fields of the form "tag[:value]"; see below. +.TP +(8) +separator: the end of the optional fields is marked by a single hyphen. +.TP +(9) +filesystem type: the filesystem type in the form "type[.subtype]". +.TP +(10) +mount source: filesystem-specific information or "none". +.TP +(11) +super options: per-superblock options (see +.BR mount (2)). +.RE +.IP +Currently, the possible optional fields are +.IR shared , +.IR master , +.IR propagate_from , +and +.IR unbindable . +See +.BR mount_namespaces (7) +for a description of these fields. +Parsers should ignore all unrecognized optional fields. +.IP +For more information on mount propagation see +.I Documentation/filesystems/sharedsubtree.rst +(or +.I Documentation/filesystems/sharedsubtree.txt +before Linux 5.8) +in the Linux kernel source tree. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_mounts.5 b/upstream/fedora-40/man5/proc_pid_mounts.5 new file mode 100644 index 00000000..3084ce13 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_mounts.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mounts 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/mounts \- mounted filesystems +.SH DESCRIPTION +.TP +.IR /proc/ pid /mounts " (since Linux 2.4.19)" +This file lists all the filesystems currently mounted in the +process's mount namespace (see +.BR mount_namespaces (7)). +The format of this file is documented in +.BR fstab (5). +.IP +Since Linux 2.6.15, this file is pollable: +after opening the file for reading, a change in this file +(i.e., a filesystem mount or unmount) causes +.BR select (2) +to mark the file descriptor as having an exceptional condition, and +.BR poll (2) +and +.BR epoll_wait (2) +mark the file as having a priority event +.RB ( POLLPRI ). +(Before Linux 2.6.30, +a change in this file was indicated by the file descriptor +being marked as readable for +.BR select (2), +and being marked as having an error condition for +.BR poll (2) +and +.BR epoll_wait (2).) +.TP +.I /proc/mounts +Before Linux 2.4.19, this file was a list +of all the filesystems currently mounted on the system. +With the introduction of per-process mount namespaces in Linux 2.4.19 (see +.BR mount_namespaces (7)), +this file became a link to +.IR /proc/self/mounts , +which lists the mounts of the process's own mount namespace. +The format of this file is documented in +.BR fstab (5). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_mountstats.5 b/upstream/fedora-40/man5/proc_pid_mountstats.5 new file mode 100644 index 00000000..024d69a8 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_mountstats.5 @@ -0,0 +1,46 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mountstats 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/mountstats \- mount statistics +.SH DESCRIPTION +.TP +.IR /proc/ pid /mountstats " (since Linux 2.6.17)" +This file exports information (statistics, configuration information) +about the mounts in the process's mount namespace (see +.BR mount_namespaces (7)). +Lines in this file have the form: +.IP +.in +4n +.EX +device /dev/sda7 mounted on /home with fstype ext3 [stats] +( 1 ) ( 2 ) (3 ) ( 4 ) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The name of the mounted device +(or "nodevice" if there is no corresponding device). +.TP +(2) +The mount point within the filesystem tree. +.TP +(3) +The filesystem type. +.TP +(4) +Optional statistics and configuration information. +Currently (as at Linux 2.6.26), only NFS filesystems export +information via this field. +.RE +.IP +This file is readable only by the owner of the process. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_net.5 b/upstream/fedora-40/man5/proc_pid_net.5 new file mode 100644 index 00000000..21ae4a6f --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_net.5 @@ -0,0 +1,298 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Alan Cox +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_net 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/net/, /proc/net/ \- network layer information +.SH DESCRIPTION +.TP +.IR /proc/ pid /net/ " (since Linux 2.6.25)" +See the description of +.IR /proc/net . +.TP +.I /proc/net/ +This directory contains various files and subdirectories containing +information about the networking layer. +The files contain ASCII structures and are, +therefore, readable with +.BR cat (1). +However, the standard +.BR netstat (8) +suite provides much cleaner access to these files. +.IP +With the advent of network namespaces, +various information relating to the network stack is virtualized (see +.BR network_namespaces (7)). +Thus, since Linux 2.6.25, +.\" commit e9720acd728a46cb40daa52c99a979f7c4ff195c +.I /proc/net +is a symbolic link to the directory +.IR /proc/self/net , +which contains the same files and directories as listed below. +However, these files and directories now expose information +for the network namespace of which the process is a member. +.TP +.I /proc/net/arp +This holds an ASCII readable dump of the kernel ARP table used for +address resolutions. +It will show both dynamically learned and preprogrammed ARP entries. +The format is: +.IP +.in +4n +.EX +IP address HW type Flags HW address Mask Device +192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0 +192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0 +.EE +.in +.IP +Here "IP address" is the IPv4 address of the machine and the "HW type" +is the hardware type of the address from RFC\ 826. +The flags are the internal +flags of the ARP structure (as defined in +.IR /usr/include/linux/if_arp.h ) +and +the "HW address" is the data link layer mapping for that IP address if +it is known. +.TP +.I /proc/net/dev +The dev pseudo-file contains network device status information. +This gives +the number of received and sent packets, the number of errors and +collisions +and other basic statistics. +These are used by the +.BR ifconfig (8) +program to report device status. +The format is: +.IP +.EX +Inter\-| Receive | Transmit + face |bytes packets errs drop fifo frame compressed multicast|bytes packets errs drop fifo colls carrier compressed + lo: 2776770 11307 0 0 0 0 0 0 2776770 11307 0 0 0 0 0 0 + eth0: 1215645 2751 0 0 0 0 0 0 1782404 4324 0 0 0 427 0 0 + ppp0: 1622270 5552 1 0 0 0 0 0 354130 5669 0 0 0 0 0 0 + tap0: 7714 81 0 0 0 0 0 0 7714 81 0 0 0 0 0 0 +.EE +.\" .TP +.\" .I /proc/net/ipx +.\" No information. +.\" .TP +.\" .I /proc/net/ipx_route +.\" No information. +.TP +.I /proc/net/dev_mcast +Defined in +.IR /usr/src/linux/net/core/dev_mcast.c : +.IP +.in +4n +.EX +indx interface_name dmi_u dmi_g dmi_address +2 eth0 1 0 01005e000001 +3 eth1 1 0 01005e000001 +4 eth2 1 0 01005e000001 +.EE +.in +.TP +.I /proc/net/igmp +Internet Group Management Protocol. +Defined in +.IR /usr/src/linux/net/core/igmp.c . +.TP +.I /proc/net/rarp +This file uses the same format as the +.I arp +file and contains the current reverse mapping database used to provide +.BR rarp (8) +reverse address lookup services. +If RARP is not configured into the +kernel, +this file will not be present. +.TP +.I /proc/net/raw +Holds a dump of the RAW socket table. +Much of the information is not of +use +apart from debugging. +The "sl" value is the kernel hash slot for the +socket, +the "local_address" is the local address and protocol number pair. +\&"St" is +the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields are not used by RAW. +The "uid" +field holds the effective UID of the creator of the socket. +.\" .TP +.\" .I /proc/net/route +.\" No information, but looks similar to +.\" .BR route (8). +.TP +.I /proc/net/snmp +This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP +management +information bases for an SNMP agent. +.TP +.I /proc/net/tcp +Holds a dump of the TCP socket table. +Much of the information is not +of use apart from debugging. +The "sl" value is the kernel hash slot +for the socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +\&"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields hold internal information of +the kernel socket state and are useful only for debugging. +The "uid" +field holds the effective UID of the creator of the socket. +.TP +.I /proc/net/udp +Holds a dump of the UDP socket table. +Much of the information is not of +use apart from debugging. +The "sl" value is the kernel hash slot for the +socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the outgoing and incoming data queue +in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields +are not used by UDP. +The "uid" +field holds the effective UID of the creator of the socket. +The format is: +.IP +.EX +sl local_address rem_address st tx_queue rx_queue tr rexmits tm\->when uid + 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 + 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 + 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 +.EE +.TP +.I /proc/net/unix +Lists the UNIX domain sockets present within the system and their +status. +The format is: +.IP +.EX +Num RefCount Protocol Flags Type St Inode Path + 0: 00000002 00000000 00000000 0001 03 42 + 1: 00000001 00000000 00010000 0001 01 1948 /dev/printer +.EE +.IP +The fields are as follows: +.RS +.TP 10 +.IR Num : +the kernel table slot number. +.TP +.IR RefCount : +the number of users of the socket. +.TP +.IR Protocol : +currently always 0. +.TP +.IR Flags : +the internal kernel flags holding the status of the socket. +.TP +.IR Type : +the socket type. +For +.B SOCK_STREAM +sockets, this is 0001; for +.B SOCK_DGRAM +sockets, it is 0002; and for +.B SOCK_SEQPACKET +sockets, it is 0005. +.TP +.IR St : +the internal state of the socket. +.TP +.IR Inode : +the inode number of the socket. +.TP +.IR Path : +the bound pathname (if any) of the socket. +Sockets in the abstract namespace are included in the list, +and are shown with a +.I Path +that commences with the character '@'. +.RE +.TP +.I /proc/net/netfilter/nfnetlink_queue +This file contains information about netfilter user-space queueing, if used. +Each line represents a queue. +Queues that have not been subscribed to +by user space are not shown. +.IP +.in +4n +.EX + 1 4207 0 2 65535 0 0 0 1 + (1) (2) (3)(4) (5) (6) (7) (8) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The ID of the queue. +This matches what is specified in the +.B \-\-queue\-num +or +.B \-\-queue\-balance +options to the +.BR iptables (8) +NFQUEUE target. +See +.BR iptables\-extensions (8) +for more information. +.TP +(2) +The netlink port ID subscribed to the queue. +.TP +(3) +The number of packets currently queued and waiting to be processed by +the application. +.TP +(4) +The copy mode of the queue. +It is either 1 (metadata only) or 2 +(also copy payload data to user space). +.TP +(5) +Copy range; that is, how many bytes of packet payload should be copied to +user space at most. +.TP +(6) +queue dropped. +Number of packets that had to be dropped by the kernel because +too many packets are already waiting for user space to send back the mandatory +accept/drop verdicts. +.TP +(7) +queue user dropped. +Number of packets that were dropped within the netlink +subsystem. +Such drops usually happen when the corresponding socket buffer is +full; that is, user space is not able to read messages fast enough. +.TP +(8) +sequence number. +Every queued packet is associated with a (32-bit) +monotonically increasing sequence number. +This shows the ID of the most recent packet queued. +.RE +.IP +The last number exists only for compatibility reasons and is always 1. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_ns.5 b/upstream/fedora-40/man5/proc_pid_ns.5 new file mode 100644 index 00000000..37517e35 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_ns.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_ns 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/ns/ \- namespaces +.SH DESCRIPTION +.TP +.IR /proc/ pid /ns/ " (since Linux 3.0)" +.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f +This is a subdirectory containing one entry for each namespace that +supports being manipulated by +.BR setns (2). +For more information, see +.BR namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_numa_maps.5 b/upstream/fedora-40/man5/proc_pid_numa_maps.5 new file mode 100644 index 00000000..cad08414 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_numa_maps.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_numa_maps 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/numa_maps \- NUMA memory policy and allocation +.SH DESCRIPTION +.TP +.IR /proc/ pid /numa_maps " (since Linux 2.6.14)" +See +.BR numa (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_oom_score.5 b/upstream/fedora-40/man5/proc_pid_oom_score.5 new file mode 100644 index 00000000..96975fc6 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_oom_score.5 @@ -0,0 +1,58 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_oom_score 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/oom_score \- OOM-killer score +.SH DESCRIPTION +.TP +.IR /proc/ pid /oom_score " (since Linux 2.6.11)" +.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +This file displays the current score that the kernel gives to +this process for the purpose of selecting a process +for the OOM-killer. +A higher score means that the process is more likely to be +selected by the OOM-killer. +The basis for this score is the amount of memory used by the process, +with increases (+) or decreases (\-) for factors including: +.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +.RS +.IP \[bu] 3 +whether the process is privileged (\-). +.\" More precisely, if it has CAP_SYS_ADMIN or (pre 2.6.36) CAP_SYS_RESOURCE +.RE +.IP +Before Linux 2.6.36 +the following factors were also used in the calculation of oom_score: +.RS +.IP \[bu] 3 +whether the process creates a lot of children using +.BR fork (2) +(+); +.IP \[bu] +whether the process has been running a long time, +or has used a lot of CPU time (\-); +.IP \[bu] +whether the process has a low nice value (i.e., > 0) (+); and +.IP \[bu] +whether the process is making direct hardware access (\-). +.\" More precisely, if it has CAP_SYS_RAWIO +.RE +.IP +The +.I oom_score +also reflects the adjustment specified by the +.I oom_score_adj +or +.I oom_adj +setting for the process. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_oom_score_adj (5) diff --git a/upstream/fedora-40/man5/proc_pid_oom_score_adj.5 b/upstream/fedora-40/man5/proc_pid_oom_score_adj.5 new file mode 100644 index 00000000..8eb725e9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_oom_score_adj.5 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_oom_score_adj 5 2023-11-24 "Linux man-pages 6.06" +.SH NAME +/proc/pid/oom_score_adj \- OOM-killer score adjustment +.SH DESCRIPTION +.TP +.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)" +.\" Text taken from Linux 3.7 Documentation/filesystems/proc.txt +This file can be used to adjust the badness heuristic used to select which +process gets killed in out-of-memory conditions. +.IP +The badness heuristic assigns a value to each candidate task ranging from 0 +(never kill) to 1000 (always kill) to determine which process is targeted. +The units are roughly a proportion along that range of +allowed memory the process may allocate from, +based on an estimation of its current memory and swap use. +For example, if a task is using all allowed memory, +its badness score will be 1000. +If it is using half of its allowed memory, its score will be 500. +.IP +There is an additional factor included in the badness score: root +processes are given 3% extra memory over other tasks. +.IP +The amount of "allowed" memory depends on the context +in which the OOM-killer was called. +If it is due to the memory assigned to the allocating task's cpuset +being exhausted, +the allowed memory represents the set of mems assigned to that +cpuset (see +.BR cpuset (7)). +If it is due to a mempolicy's node(s) being exhausted, +the allowed memory represents the set of mempolicy nodes. +If it is due to a memory limit (or swap limit) being reached, +the allowed memory is that configured limit. +Finally, if it is due to the entire system being out of memory, the +allowed memory represents all allocatable resources. +.IP +The value of +.I oom_score_adj +is added to the badness score before it +is used to determine which task to kill. +Acceptable values range from \-1000 +(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). +This allows user space to control the preference for OOM-killing, +ranging from always preferring a certain +task or completely disabling it from OOM-killing. +The lowest possible value, \-1000, is +equivalent to disabling OOM-killing entirely for that task, +since it will always report a badness score of 0. +.IP +Consequently, it is very simple for user space to define +the amount of memory to consider for each task. +Setting an +.I oom_score_adj +value of +500, for example, +is roughly equivalent to allowing the remainder of tasks sharing the +same system, cpuset, mempolicy, or memory controller resources +to use at least 50% more memory. +A value of \-500, on the other hand, would be roughly +equivalent to discounting 50% of the task's +allowed memory from being considered as scoring against the task. +.IP +For backward compatibility with previous kernels, +.IR /proc/ pid /oom_adj +can still be used to tune the badness score. +Its value is +scaled linearly with +.IR oom_score_adj . +.IP +Writing to +.IR /proc/ pid /oom_score_adj +or +.IR /proc/ pid /oom_adj +will change the other with its scaled value. +.IP +The +.BR choom (1) +program provides a command-line interface for adjusting the +.I oom_score_adj +value of a running process or a newly executed command. +.SH HISTORY +.TP +.IR /proc/ pid /oom_adj " (since Linux 2.6.11)" +This file can be used to adjust the score used to select which process +should be killed in an out-of-memory (OOM) situation. +The kernel uses this value for a bit-shift operation of the process's +.I oom_score +value: +valid values are in the range \-16 to +15, +plus the special value \-17, +which disables OOM-killing altogether for this process. +A positive score increases the likelihood of this +process being killed by the OOM-killer; +a negative score decreases the likelihood. +.IP +The default value for this file is 0; +a new process inherits its parent's +.I oom_adj +setting. +A process must be privileged +.RB ( CAP_SYS_RESOURCE ) +to update this file, +although a process can always increase its own +.I oom_adj +setting (since Linux 2.6.20). +.IP +Since Linux 2.6.36, use of this file is deprecated in favor of +.IR /proc/ pid /oom_score_adj , +and finally removed in Linux 3.7. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_oom_score (5) diff --git a/upstream/fedora-40/man5/proc_pid_pagemap.5 b/upstream/fedora-40/man5/proc_pid_pagemap.5 new file mode 100644 index 00000000..85d4ea86 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_pagemap.5 @@ -0,0 +1,77 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_pagemap 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/pagemap \- mapping of virtual pages +.SH DESCRIPTION +.TP +.IR /proc/ pid /pagemap " (since Linux 2.6.25)" +This file shows the mapping of each of the process's virtual pages +into physical page frames or swap area. +It contains one 64-bit value for each virtual page, +with the bits set as follows: +.RS +.TP +63 +If set, the page is present in RAM. +.TP +62 +If set, the page is in swap space +.TP +61 (since Linux 3.5) +The page is a file-mapped page or a shared anonymous page. +.TP +60\[en]58 (since Linux 3.11) +Zero +.\" Not quite true; see commit 541c237c0923f567c9c4cabb8a81635baadc713f +.TP +57 (since Linux 5.14) +If set, the page is write-protected through +.BR userfaultfd (2). +.TP +56 (since Linux 4.2) +.\" commit 77bb499bb60f4b79cca7d139c8041662860fcf87 +.\" commit 83b4b0bb635eee2b8e075062e4e008d1bc110ed7 +The page is exclusively mapped. +.TP +55 (since Linux 3.11) +PTE is soft-dirty +(see the kernel source file +.IR Documentation/admin\-guide/mm/soft\-dirty.rst ). +.TP +54\[en]0 +If the page is present in RAM (bit 63), then these bits +provide the page frame number, which can be used to index +.I /proc/kpageflags +and +.IR /proc/kpagecount . +If the page is present in swap (bit 62), +then bits 4\[en]0 give the swap type, and bits 54\[en]5 encode the swap offset. +.RE +.IP +Before Linux 3.11, bits 60\[en]55 were +used to encode the base-2 log of the page size. +.IP +To employ +.IR /proc/ pid /pagemap +efficiently, use +.IR /proc/ pid /maps +to determine which areas of memory are actually mapped and seek +to skip over unmapped regions. +.IP +The +.IR /proc/ pid /pagemap +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_personality.5 b/upstream/fedora-40/man5/proc_pid_personality.5 new file mode 100644 index 00000000..2bef64f9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_personality.5 @@ -0,0 +1,23 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_personality 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/personality \- execution domain +.SH DESCRIPTION +.TP +.IR /proc/ pid /personality " (since Linux 2.6.28)" +.\" commit 478307230810d7e2a753ed220db9066dfdf88718 +This read-only file exposes the process's execution domain, as set by +.BR personality (2). +The value is displayed in hexadecimal notation. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_projid_map.5 b/upstream/fedora-40/man5/proc_pid_projid_map.5 new file mode 100644 index 00000000..33090b5b --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_projid_map.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_projid_map 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/projid_map \- project ID mappings +.SH DESCRIPTION +.TP +.IR /proc/ pid /projid_map " (since Linux 3.7)" +.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_root.5 b/upstream/fedora-40/man5/proc_pid_root.5 new file mode 100644 index 00000000..b6b31752 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_root.5 @@ -0,0 +1,75 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_root 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/root/ \- symbolic link to root directory +.SH DESCRIPTION +.TP +.IR /proc/ pid /root/ +UNIX and Linux support the idea of a per-process root of the +filesystem, set by the +.BR chroot (2) +system call. +This file is a symbolic link that points to the process's +root directory, and behaves in the same way as +.IR exe , +and +.IR fd/* . +.IP +Note however that this file is not merely a symbolic link. +It provides the same view of the filesystem (including namespaces and the +set of per-process mounts) as the process itself. +An example illustrates this point. +In one terminal, we start a shell in new user and mount namespaces, +and in that shell we create some new mounts: +.IP +.in +4n +.EX +$ \fBPS1=\[aq]sh1# \[aq] unshare \-Urnm\fP +sh1# \fBmount \-t tmpfs tmpfs /etc\fP # Mount empty tmpfs at /etc +sh1# \fBmount \-\-bind /usr /dev\fP # Mount /usr at /dev +sh1# \fBecho $$\fP +27123 +.EE +.in +.IP +In a second terminal window, in the initial mount namespace, +we look at the contents of the corresponding mounts in +the initial and new namespaces: +.IP +.in +4n +.EX +$ \fBPS1=\[aq]sh2# \[aq] sudo sh\fP +sh2# \fBls /etc | wc \-l\fP # In initial NS +309 +sh2# \fBls /proc/27123/root/etc | wc \-l\fP # /etc in other NS +0 # The empty tmpfs dir +sh2# \fBls /dev | wc \-l\fP # In initial NS +205 +sh2# \fBls /proc/27123/root/dev | wc \-l\fP # /dev in other NS +11 # Actually bind + # mounted to /usr +sh2# \fBls /usr | wc \-l\fP # /usr in initial NS +11 +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.IR /proc/ pid /root +symbolic link are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_seccomp.5 b/upstream/fedora-40/man5/proc_pid_seccomp.5 new file mode 100644 index 00000000..031dc5ca --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_seccomp.5 @@ -0,0 +1,36 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_seccomp 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/seccomp \- secure computing mode +.SH DESCRIPTION +.TP +.IR /proc/ pid /seccomp " (Linux 2.6.12 to Linux 2.6.22)" +This file can be used to read and change the process's +secure computing (seccomp) mode setting. +It contains the value 0 if the process is not in seccomp mode, +and 1 if the process is in strict seccomp mode (see +.BR seccomp (2)). +Writing 1 to this file places the process irreversibly in strict seccomp mode. +(Further attempts to write to the file fail with the +.B EPERM +error.) +.IP +In Linux 2.6.23, +this file went away, to be replaced by the +.BR prctl (2) +.B PR_GET_SECCOMP +and +.B PR_SET_SECCOMP +operations (and later by +.BR seccomp (2) +and the +.I Seccomp +field in +.IR /proc/ pid /status ). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_setgroups.5 b/upstream/fedora-40/man5/proc_pid_setgroups.5 new file mode 100644 index 00000000..10dda201 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_setgroups.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_setgroups 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/setgroups \- allow or deny setting groups +.SH DESCRIPTION +.TP +.IR /proc/ pid /setgroups " (since Linux 3.19)" +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_smaps.5 b/upstream/fedora-40/man5/proc_pid_smaps.5 new file mode 100644 index 00000000..f0e0b8ae --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_smaps.5 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_smaps 5 2023-09-07 "Linux man-pages 6.06" +.SH NAME +/proc/pid/smaps \- XXX: What does 's' in "smaps" stand for? +.SH DESCRIPTION +.TP +.IR /proc/ pid /smaps " (since Linux 2.6.14)" +This file shows memory consumption for each of the process's mappings. +(The +.BR pmap (1) +command displays similar information, +in a form that may be easier for parsing.) +For each mapping there is a series of lines such as the following: +.IP +.in +4n +.EX +00400000\-0048a000 r\-xp 00000000 fd:03 960637 /bin/bash +Size: 552 kB +Rss: 460 kB +Pss: 100 kB +Shared_Clean: 452 kB +Shared_Dirty: 0 kB +Private_Clean: 8 kB +Private_Dirty: 0 kB +Referenced: 460 kB +Anonymous: 0 kB +AnonHugePages: 0 kB +ShmemHugePages: 0 kB +ShmemPmdMapped: 0 kB +Swap: 0 kB +KernelPageSize: 4 kB +MMUPageSize: 4 kB +Locked: 0 kB +ProtectionKey: 0 +VmFlags: rd ex mr mw me dw +.EE +.in +.IP +The first of these lines shows the same information as is displayed +for the mapping in +.IR /proc/ pid /maps . +The following lines show the size of the mapping, +the amount of the mapping that is currently resident in RAM ("Rss"), +the process's proportional share of this mapping ("Pss"), +the number of clean and dirty shared pages in the mapping, +and the number of clean and dirty private pages in the mapping. +"Referenced" indicates the amount of memory currently marked as +referenced or accessed. +"Anonymous" shows the amount of memory +that does not belong to any file. +"Swap" shows how much +would-be-anonymous memory is also used, but out on swap. +.IP +The "KernelPageSize" line (available since Linux 2.6.29) +is the page size used by the kernel to back the virtual memory area. +This matches the size used by the MMU in the majority of cases. +However, one counter-example occurs on PPC64 kernels +whereby a kernel using 64 kB as a base page size may still use 4 kB +pages for the MMU on older processors. +To distinguish the two attributes, the "MMUPageSize" line +(also available since Linux 2.6.29) +reports the page size used by the MMU. +.IP +The "Locked" indicates whether the mapping is locked in memory +or not. +.IP +The "ProtectionKey" line (available since Linux 4.9, on x86 only) +contains the memory protection key (see +.BR pkeys (7)) +associated with the virtual memory area. +This entry is present only if the kernel was built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +configuration option (since Linux 4.6). +.IP +The "VmFlags" line (available since Linux 3.8) +represents the kernel flags associated with the virtual memory area, +encoded using the following two-letter codes: +.RS +.IP +.TS +l l l. +rd - readable +wr - writable +ex - executable +sh - shared +mr - may read +mw - may write +me - may execute +ms - may share +gd - stack segment grows down +pf - pure PFN range +dw - disabled write to the mapped file +lo - pages are locked in memory +io - memory mapped I/O area +sr - sequential read advise provided +rr - random read advise provided +dc - do not copy area on fork +de - do not expand area on remapping +ac - area is accountable +nr - swap space is not reserved for the area +ht - area uses huge tlb pages +sf - perform synchronous page faults (since Linux 4.15) +nl - non-linear mapping (removed in Linux 4.0) +ar - architecture specific flag +wf - wipe on fork (since Linux 4.14) +dd - do not include area into core dump +sd - soft-dirty flag (since Linux 3.13) +mm - mixed map area +hg - huge page advise flag +nh - no-huge page advise flag +mg - mergeable advise flag +um - userfaultfd missing pages tracking (since Linux 4.3) +uw - userfaultfd wprotect pages tracking (since Linux 4.3) +.TE +.RE +.IP +The +.IR /proc/ pid /smaps +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_stack.5 b/upstream/fedora-40/man5/proc_pid_stack.5 new file mode 100644 index 00000000..b2e88261 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_stack.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_stack 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/stack \- kernel stack +.SH DESCRIPTION +.TP +.IR /proc/ pid /stack " (since Linux 2.6.29)" +.\" 2ec220e27f5040aec1e88901c1b6ea3d135787ad +This file provides a symbolic trace of the function calls in this +process's kernel stack. +This file is provided only if the kernel was built with the +.B CONFIG_STACKTRACE +configuration option. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_stat.5 b/upstream/fedora-40/man5/proc_pid_stat.5 new file mode 100644 index 00000000..85f42135 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_stat.5 @@ -0,0 +1,380 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_stat 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/stat \- status information +.SH DESCRIPTION +.TP +.IR /proc/ pid /stat +Status information about the process. +This is used by +.BR ps (1). +It is defined in the kernel source file +.IR fs/proc/array.c "." +.IP +The fields, in order, with their proper +.BR scanf (3) +format specifiers, are listed below. +Whether or not certain of these fields display valid information is governed by +a ptrace access mode +.BR PTRACE_MODE_READ_FSCREDS " | " PTRACE_MODE_NOAUDIT +check (refer to +.BR ptrace (2)). +If the check denies access, then the field value is displayed as 0. +The affected fields are indicated with the marking [PT]. +.RS +.TP +(1) \fIpid\fP \ %d +.br +The process ID. +.TP +(2) \fIcomm\fP \ %s +The filename of the executable, in parentheses. +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +This is visible whether or not the executable is swapped out. +.TP +(3) \fIstate\fP \ %c +One of the following characters, indicating process state: +.RS +.TP +R +Running +.TP +S +Sleeping in an interruptible wait +.TP +D +Waiting in uninterruptible +disk sleep +.TP +Z +Zombie +.TP +T +Stopped (on a signal) or (before Linux 2.6.33) trace stopped +.TP +t +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Tracing stop (Linux 2.6.33 onward) +.TP +W +Paging (only before Linux 2.6.0) +.TP +X +Dead (from Linux 2.6.0 onward) +.TP +x +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Dead (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +K +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Wakekill (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +W +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Waking (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +P +.\" commit f2530dc71cf0822f90bb63ea4600caaef33a66bb +Parked (Linux 3.9 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +I +.\" commit 06eb61844d841d0032a9950ce7f8e783ee49c0d0 +Idle (Linux 4.14 onward) +.RE +.TP +(4) \fIppid\fP \ %d +The PID of the parent of this process. +.TP +(5) \fIpgrp\fP \ %d +The process group ID of the process. +.TP +(6) \fIsession\fP \ %d +The session ID of the process. +.TP +(7) \fItty_nr\fP \ %d +The controlling terminal of the process. +(The minor device number is contained in the combination of bits +31 to 20 and 7 to 0; +the major device number is in bits 15 to 8.) +.TP +(8) \fItpgid\fP \ %d +.\" This field and following, up to and including wchan added 0.99.1 +The ID of the foreground process group of the controlling +terminal of the process. +.TP +(9) \fIflags\fP \ %u +The kernel flags word of the process. +For bit meanings, +see the PF_* defines in the Linux kernel source file +.IR include/linux/sched.h . +Details depend on the kernel version. +.IP +The format for this field was %lu before Linux 2.6. +.TP +(10) \fIminflt\fP \ %lu +The number of minor faults the process has made which have not +required loading a memory page from disk. +.TP +(11) \fIcminflt\fP \ %lu +The number of minor faults that the process's +waited-for children have made. +.TP +(12) \fImajflt\fP \ %lu +The number of major faults the process has made which have +required loading a memory page from disk. +.TP +(13) \fIcmajflt\fP \ %lu +The number of major faults that the process's +waited-for children have made. +.TP +(14) \fIutime\fP \ %lu +Amount of time that this process has been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +This includes guest time, \fIguest_time\fP +(time spent running a virtual CPU, see below), +so that applications that are not aware of the guest time field +do not lose that time from their calculations. +.TP +(15) \fIstime\fP \ %lu +Amount of time that this process has been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(16) \fIcutime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +(See also +.BR times (2).) +This includes guest time, \fIcguest_time\fP +(time spent running a virtual CPU, see below). +.TP +(17) \fIcstime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(18) \fIpriority\fP \ %ld +(Explanation for Linux 2.6) +For processes running a real-time scheduling policy +.RI ( policy +below; see +.BR sched_setscheduler (2)), +this is the negated scheduling priority, minus one; +that is, a number in the range \-2 to \-100, +corresponding to real-time priorities 1 to 99. +For processes running under a non-real-time scheduling policy, +this is the raw nice value +.RB ( setpriority (2)) +as represented in the kernel. +The kernel stores nice values as numbers +in the range 0 (high) to 39 (low), +corresponding to the user-visible nice range of \-20 to 19. +.IP +Before Linux 2.6, this was a scaled value based on +the scheduler weighting given to this process. +.\" And back in Linux 1.2 days things were different again. +.TP +(19) \fInice\fP \ %ld +The nice value (see +.BR setpriority (2)), +a value in the range 19 (low priority) to \-20 (high priority). +.\" Back in Linux 1.2 days things were different. +.\" .TP +.\" \fIcounter\fP %ld +.\" The current maximum size in jiffies of the process's next timeslice, +.\" or what is currently left of its current timeslice, if it is the +.\" currently running process. +.\" .TP +.\" \fItimeout\fP %u +.\" The time in jiffies of the process's next timeout. +.\" timeout was removed sometime around 2.1/2.2 +.TP +(20) \fInum_threads\fP \ %ld +Number of threads in this process (since Linux 2.6). +Before Linux 2.6, this field was hard coded to 0 as a placeholder +for an earlier removed field. +.TP +(21) \fIitrealvalue\fP \ %ld +The time in jiffies before the next +.B SIGALRM +is sent to the process due to an interval timer. +Since Linux 2.6.17, this field is no longer maintained, +and is hard coded as 0. +.TP +(22) \fIstarttime\fP \ %llu +The time the process started after system boot. +Before Linux 2.6, this value was expressed in jiffies. +Since Linux 2.6, the value is expressed in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.IP +The format for this field was %lu before Linux 2.6. +.TP +(23) \fIvsize\fP \ %lu +Virtual memory size in bytes. +.TP +(24) \fIrss\fP \ %ld +Resident Set Size: number of pages the process has in real memory. +This is just the pages which +count toward text, data, or stack space. +This does not include pages +which have not been demand-loaded in, or which are swapped out. +This value is inaccurate; see +.IR /proc/ pid /statm +below. +.TP +(25) \fIrsslim\fP \ %lu +Current soft limit in bytes on the rss of the process; +see the description of +.B RLIMIT_RSS +in +.BR getrlimit (2). +.TP +(26) \fIstartcode\fP \ %lu \ [PT] +The address above which program text can run. +.TP +(27) \fIendcode\fP \ %lu \ [PT] +The address below which program text can run. +.TP +(28) \fIstartstack\fP \ %lu \ [PT] +The address of the start (i.e., bottom) of the stack. +.TP +(29) \fIkstkesp\fP \ %lu \ [PT] +The current value of ESP (stack pointer), as found in the +kernel stack page for the process. +.TP +(30) \fIkstkeip\fP \ %lu \ [PT] +The current EIP (instruction pointer). +.TP +(31) \fIsignal\fP \ %lu +The bitmap of pending signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(32) \fIblocked\fP \ %lu +The bitmap of blocked signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(33) \fIsigignore\fP \ %lu +The bitmap of ignored signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(34) \fIsigcatch\fP \ %lu +The bitmap of caught signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(35) \fIwchan\fP \ %lu \ [PT] +This is the "channel" in which the process is waiting. +It is the address of a location in the kernel where the process is sleeping. +The corresponding symbolic name can be found in +.IR /proc/ pid /wchan . +.TP +(36) \fInswap\fP \ %lu +.\" nswap was added in Linux 2.0 +Number of pages swapped (not maintained). +.TP +(37) \fIcnswap\fP \ %lu +.\" cnswap was added in Linux 2.0 +Cumulative \fInswap\fP for child processes (not maintained). +.TP +(38) \fIexit_signal\fP \ %d \ (since Linux 2.1.22) +Signal to be sent to parent when we die. +.TP +(39) \fIprocessor\fP \ %d \ (since Linux 2.2.8) +CPU number last executed on. +.TP +(40) \fIrt_priority\fP \ %u \ (since Linux 2.5.19) +Real-time scheduling priority, a number in the range 1 to 99 for +processes scheduled under a real-time policy, +or 0, for non-real-time processes (see +.BR sched_setscheduler (2)). +.TP +(41) \fIpolicy\fP \ %u \ (since Linux 2.5.19) +Scheduling policy (see +.BR sched_setscheduler (2)). +Decode using the SCHED_* constants in +.IR linux/sched.h . +.IP +The format for this field was %lu before Linux 2.6.22. +.TP +(42) \fIdelayacct_blkio_ticks\fP \ %llu \ (since Linux 2.6.18) +Aggregated block I/O delays, measured in clock ticks (centiseconds). +.TP +(43) \fIguest_time\fP \ %lu \ (since Linux 2.6.24) +Guest time of the process (time spent running a virtual CPU +for a guest operating system), measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(44) \fIcguest_time\fP \ %ld \ (since Linux 2.6.24) +Guest time of the process's children, measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(45) \fIstart_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program initialized and +uninitialized (BSS) data are placed. +.TP +(46) \fIend_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address below which program initialized and +uninitialized (BSS) data are placed. +.TP +(47) \fIstart_brk\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program heap can be expanded with +.BR brk (2). +.TP +(48) \fIarg_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program command-line arguments +.RI ( argv ) +are placed. +.TP +(49) \fIarg_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below program command-line arguments +.RI ( argv ) +are placed. +.TP +(50) \fIenv_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program environment is placed. +.TP +(51) \fIenv_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below which program environment is placed. +.TP +(52) \fIexit_code\fP \ %d \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +The thread's exit status in the form reported by +.BR waitpid (2). +.RE +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_status (5) diff --git a/upstream/fedora-40/man5/proc_pid_statm.5 b/upstream/fedora-40/man5/proc_pid_statm.5 new file mode 100644 index 00000000..6b02d572 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_statm.5 @@ -0,0 +1,46 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_statm 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/statm \- memory usage information +.SH DESCRIPTION +.TP +.IR /proc/ pid /statm +Provides information about memory usage, measured in pages. +The columns are: +.IP +.in +4n +.EX +size (1) total program size + (same as VmSize in \fI/proc/\fPpid\fI/status\fP) +resident (2) resident set size + (inaccurate; same as VmRSS in \fI/proc/\fPpid\fI/status\fP) +shared (3) number of resident shared pages + (i.e., backed by a file) + (inaccurate; same as RssFile+RssShmem in + \fI/proc/\fPpid\fI/status\fP) +text (4) text (code) +.\" (not including libs; broken, includes data segment) +lib (5) library (unused since Linux 2.6; always 0) +data (6) data + stack +.\" (including libs; broken, includes library text) +dt (7) dirty pages (unused since Linux 2.6; always 0) +.EE +.in +.IP +.\" See SPLIT_RSS_COUNTING in the kernel. +.\" Inaccuracy is bounded by TASK_RSS_EVENTS_THRESH. +Some of these values are inaccurate because +of a kernel-internal scalability optimization. +If accurate values are required, use +.IR /proc/ pid /smaps +or +.IR /proc/ pid /smaps_rollup +instead, which are much slower but provide accurate, detailed information. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_status (5) diff --git a/upstream/fedora-40/man5/proc_pid_status.5 b/upstream/fedora-40/man5/proc_pid_status.5 new file mode 100644 index 00000000..eddd21b9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_status.5 @@ -0,0 +1,384 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_status 5 2023-10-23 "Linux man-pages 6.06" +.SH NAME +/proc/pid/status \- memory usage and status information +.SH DESCRIPTION +.TP +.IR /proc/ pid /status +Provides much of the information in +.IR /proc/ pid /stat +and +.IR /proc/ pid /statm +in a format that's easier for humans to parse. +Here's an example: +.IP +.in +4n +.EX +.RB "$" " cat /proc/$$/status" +Name: bash +Umask: 0022 +State: S (sleeping) +Tgid: 17248 +Ngid: 0 +Pid: 17248 +PPid: 17200 +TracerPid: 0 +Uid: 1000 1000 1000 1000 +Gid: 100 100 100 100 +FDSize: 256 +Groups: 16 33 100 +NStgid: 17248 +NSpid: 17248 +NSpgid: 17248 +NSsid: 17200 +VmPeak: 131168 kB +VmSize: 131168 kB +VmLck: 0 kB +VmPin: 0 kB +VmHWM: 13484 kB +VmRSS: 13484 kB +RssAnon: 10264 kB +RssFile: 3220 kB +RssShmem: 0 kB +VmData: 10332 kB +VmStk: 136 kB +VmExe: 992 kB +VmLib: 2104 kB +VmPTE: 76 kB +VmPMD: 12 kB +VmSwap: 0 kB +HugetlbPages: 0 kB # 4.4 +CoreDumping: 0 # 4.15 +Threads: 1 +SigQ: 0/3067 +SigPnd: 0000000000000000 +ShdPnd: 0000000000000000 +SigBlk: 0000000000010000 +SigIgn: 0000000000384004 +SigCgt: 000000004b813efb +CapInh: 0000000000000000 +CapPrm: 0000000000000000 +CapEff: 0000000000000000 +CapBnd: ffffffffffffffff +CapAmb: 0000000000000000 +NoNewPrivs: 0 +Seccomp: 0 +Seccomp_filters: 0 +Speculation_Store_Bypass: vulnerable +Cpus_allowed: 00000001 +Cpus_allowed_list: 0 +Mems_allowed: 1 +Mems_allowed_list: 0 +voluntary_ctxt_switches: 150 +nonvoluntary_ctxt_switches: 545 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I Name +Command run by this process. +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +.TP +.I Umask +Process umask, expressed in octal with a leading zero; see +.BR umask (2). +(Since Linux 4.7.) +.TP +.I State +Current state of the process. +One of +"R (running)", +"S (sleeping)", +"D (disk sleep)", +"T (stopped)", +"t (tracing stop)", +"Z (zombie)", +or +"X (dead)". +.TP +.I Tgid +Thread group ID (i.e., Process ID). +.TP +.I Ngid +NUMA group ID (0 if none; since Linux 3.13). +.TP +.I Pid +Thread ID (see +.BR gettid (2)). +.TP +.I PPid +PID of parent process. +.TP +.I TracerPid +PID of process tracing this process (0 if not being traced). +.TP +.I Uid +.TQ +.I Gid +Real, effective, saved set, and filesystem UIDs (GIDs). +.TP +.I FDSize +Number of file descriptor slots currently allocated. +.TP +.I Groups +Supplementary group list. +.TP +.I NStgid +Thread group ID (i.e., PID) in each of the PID namespaces of which +.I pid +is a member. +The leftmost entry shows the value with respect to the PID namespace +of the process that mounted this procfs (or the root namespace +if mounted by the kernel), +followed by the value in successively nested inner namespaces. +.\" commit e4bc33245124db69b74a6d853ac76c2976f472d5 +(Since Linux 4.1.) +.TP +.I NSpid +Thread ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I NSpgid +Process group ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I NSsid +descendant namespace session ID hierarchy +Session ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I VmPeak +Peak virtual memory size. +.TP +.I VmSize +Virtual memory size. +.TP +.I VmLck +Locked memory size (see +.BR mlock (2)). +.TP +.I VmPin +Pinned memory size +.\" commit bc3e53f682d93df677dbd5006a404722b3adfe18 +(since Linux 3.2). +These are pages that can't be moved because something needs to +directly access physical memory. +.TP +.I VmHWM +Peak resident set size ("high water mark"). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I VmRSS +Resident set size. +Note that the value here is the sum of +.IR RssAnon , +.IR RssFile , +and +.IR RssShmem . +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssAnon +Size of resident anonymous memory. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssFile +Size of resident file mappings. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssShmem +Size of resident shared memory (includes System V shared memory, +mappings from +.BR tmpfs (5), +and shared anonymous mappings). +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +.TP +.I VmData +.TQ +.I VmStk +.TQ +.I VmExe +Size of data, stack, and text segments. +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I VmLib +Shared library code size. +.TP +.I VmPTE +Page table entries size (since Linux 2.6.10). +.TP +.I VmPMD +.\" commit dc6c9a35b66b520cf67e05d8ca60ebecad3b0479 +Size of second-level page tables (added in Linux 4.0; removed in Linux 4.15). +.TP +.I VmSwap +.\" commit b084d4353ff99d824d3bc5a5c2c22c70b1fba722 +Swapped-out virtual memory size by anonymous private pages; +shmem swap usage is not included (since Linux 2.6.34). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I HugetlbPages +Size of hugetlb memory portions +.\" commit 5d317b2b6536592a9b51fe65faed43d65ca9158e +(since Linux 4.4). +.TP +.I CoreDumping +Contains the value 1 if the process is currently dumping core, +and 0 if it is not +.\" commit c643401218be0f4ab3522e0c0a63016596d6e9ca +(since Linux 4.15). +This information can be used by a monitoring process to avoid killing +a process that is currently dumping core, +which could result in a corrupted core dump file. +.TP +.I Threads +Number of threads in process containing this thread. +.TP +.I SigQ +This field contains two slash-separated numbers that relate to +queued signals for the real user ID of this process. +The first of these is the number of currently queued +signals for this real user ID, and the second is the +resource limit on the number of queued signals for this process +(see the description of +.B RLIMIT_SIGPENDING +in +.BR getrlimit (2)). +.TP +.I SigPnd +.TQ +.I ShdPnd +Mask (expressed in hexadecimal) +of signals pending for thread and for process as a whole (see +.BR pthreads (7) +and +.BR signal (7)). +.TP +.I SigBlk +.TQ +.I SigIgn +.TQ +.I SigCgt +Masks (expressed in hexadecimal) +indicating signals being blocked, ignored, and caught (see +.BR signal (7)). +.TP +.I CapInh +.TQ +.I CapPrm +.TQ +.I CapEff +Masks (expressed in hexadecimal) +of capabilities enabled in inheritable, permitted, and effective sets +(see +.BR capabilities (7)). +.TP +.I CapBnd +Capability bounding set, expressed in hexadecimal +(since Linux 2.6.26, see +.BR capabilities (7)). +.TP +.I CapAmb +Ambient capability set, expressed in hexadecimal +(since Linux 4.3, see +.BR capabilities (7)). +.TP +.I NoNewPrivs +.\" commit af884cd4a5ae62fcf5e321fecf0ec1014730353d +Value of the +.I no_new_privs +bit +(since Linux 4.10, see +.BR prctl (2)). +.TP +.I Seccomp +.\" commit 2f4b3bf6b2318cfaa177ec5a802f4d8d6afbd816 +Seccomp mode of the process +(since Linux 3.8, see +.BR seccomp (2)). +0 means +.BR SECCOMP_MODE_DISABLED ; +1 means +.BR SECCOMP_MODE_STRICT ; +2 means +.BR SECCOMP_MODE_FILTER . +This field is provided only if the kernel was built with the +.B CONFIG_SECCOMP +kernel configuration option enabled. +.TP +.I Seccomp_filters +.\" commit c818c03b661cd769e035e41673d5543ba2ebda64 +Number of seccomp filters attached to the process +(since Linux 5.9, see +.BR seccomp (2)). +.TP +.I Speculation_Store_Bypass +.\" commit fae1fa0fc6cca8beee3ab8ed71d54f9a78fa3f64 +Speculation flaw mitigation state +(since Linux 4.17, see +.BR prctl (2)). +.TP +.I Cpus_allowed +Hexadecimal mask of CPUs on which this process may run +(since Linux 2.6.24, see +.BR cpuset (7)). +.TP +.I Cpus_allowed_list +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.TP +.I Mems_allowed +Mask of memory nodes allowed to this process +(since Linux 2.6.24, see +.BR cpuset (7)). +.TP +.I Mems_allowed_list +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.TP +.I voluntary_ctxt_switches +.TQ +.I nonvoluntary_ctxt_switches +Number of voluntary and involuntary context switches (since Linux 2.6.23). +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_syscall.5 b/upstream/fedora-40/man5/proc_pid_syscall.5 new file mode 100644 index 00000000..c5b6188c --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_syscall.5 @@ -0,0 +1,33 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_syscall 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/syscall \- currently executed system call +.SH DESCRIPTION +.TP +.IR /proc/ pid /syscall " (since Linux 2.6.27)" +.\" commit ebcb67341fee34061430f3367f2e507e52ee051b +This file exposes the system call number and argument registers for the +system call currently being executed by the process, +followed by the values of the stack pointer and program counter registers. +The values of all six argument registers are exposed, +although most system calls use fewer registers. +.IP +If the process is blocked, but not in a system call, +then the file displays \-1 in place of the system call number, +followed by just the values of the stack pointer and program counter. +If process is not blocked, then the file contains just the string "running". +.IP +This file is present only if the kernel was configured with +.BR CONFIG_HAVE_ARCH_TRACEHOOK . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_task.5 b/upstream/fedora-40/man5/proc_pid_task.5 new file mode 100644 index 00000000..4b04c84f --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_task.5 @@ -0,0 +1,97 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_task 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/task/, /proc/tid/, /proc/thread\-self/ \- thread information +.SH DESCRIPTION +.TP +.IR /proc/ pid /task/ " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test6 +This is a directory that contains one subdirectory +for each thread in the process. +The name of each subdirectory is the numerical thread ID +.RI ( tid ) +of the thread (see +.BR gettid (2)). +.IP +Within each of these subdirectories, there is a set of +files with the same names and contents as under the +.IR /proc/ pid +directories. +For attributes that are shared by all threads, the contents for +each of the files under the +.IR task/ tid +subdirectories will be the same as in the corresponding +file in the parent +.IR /proc/ pid +directory +(e.g., in a multithreaded process, all of the +.IR task/ tid /cwd +files will have the same value as the +.IR /proc/ pid /cwd +file in the parent directory, since all of the threads in a process +share a working directory). +For attributes that are distinct for each thread, +the corresponding files under +.IR task/ tid +may have different values (e.g., various fields in each of the +.IR task/ tid /status +files may be different for each thread), +.\" in particular: "children" :/ +or they might not exist in +.IR /proc/ pid +at all. +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.IR /proc/ pid /task +directory are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.TP +.IR /proc/ tid / +There is a numerical subdirectory for each running thread +that is not a thread group leader +(i.e., a thread whose thread ID is not the same as its process ID); +the subdirectory is named by the thread ID. +Each one of these subdirectories contains files and subdirectories +exposing information about the thread with the thread ID +.IR tid . +The contents of these directories are the same as the corresponding +.IR /proc/ pid /task/ tid +directories. +.IP +The +.IR /proc/ tid +subdirectories are +.I not +visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are +.I not +visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +However, the pathnames of these directories are visible to +(i.e., usable as arguments in) +system calls that operate on pathnames. +.TP +.IR /proc/thread\-self/ " (since Linux 3.17)" +.\" commit 0097875bd41528922fb3bb5f348c53f17e00e2fd +This directory refers to the thread accessing the +.I /proc +filesystem, +and is identical to the +.IR /proc/self/task/ tid +directory named by the process thread ID +.RI ( tid ) +of the same thread. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_timers.5 b/upstream/fedora-40/man5/proc_pid_timers.5 new file mode 100644 index 00000000..ebee7769 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_timers.5 @@ -0,0 +1,82 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_timers 5 2023-09-07 "Linux man-pages 6.06" +.SH NAME +/proc/pid/timers \- POSIX timers +.SH DESCRIPTION +.TP +.IR /proc/ pid /timers " (since Linux 3.10)" +.\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5 +.\" commit 48f6a7a511ef8823fdff39afee0320092d43a8a0 +A list of the POSIX timers for this process. +Each timer is listed with a line that starts with the string "ID:". +For example: +.IP +.in +4n +.EX +ID: 1 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 0 +ID: 0 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 1 +.EE +.in +.IP +The lines shown for each timer have the following meanings: +.RS +.TP +.I ID +The ID for this timer. +This is not the same as the timer ID returned by +.BR timer_create (2); +rather, it is the same kernel-internal ID that is available via the +.I si_timerid +field of the +.I siginfo_t +structure (see +.BR sigaction (2)). +.TP +.I signal +This is the signal number that this timer uses to deliver notifications +followed by a slash, and then the +.I sigev_value +value supplied to the signal handler. +Valid only for timers that notify via a signal. +.TP +.I notify +The part before the slash specifies the mechanism +that this timer uses to deliver notifications, +and is one of "thread", "signal", or "none". +Immediately following the slash is either the string "tid" for timers +with +.B SIGEV_THREAD_ID +notification, or "pid" for timers that notify by other mechanisms. +Following the "." is the PID of the process +(or the kernel thread ID of the thread) that will be delivered +a signal if the timer delivers notifications via a signal. +.TP +.I ClockID +This field identifies the clock that the timer uses for measuring time. +For most clocks, this is a number that matches one of the user-space +.B CLOCK_* +constants exposed via +.IR . +.B CLOCK_PROCESS_CPUTIME_ID +timers display with a value of \-6 +in this field. +.B CLOCK_THREAD_CPUTIME_ID +timers display with a value of \-2 +in this field. +.RE +.IP +This file is available only when the kernel was configured with +.BR CONFIG_CHECKPOINT_RESTORE . +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_timerslack_ns.5 b/upstream/fedora-40/man5/proc_pid_timerslack_ns.5 new file mode 100644 index 00000000..60a51f57 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_timerslack_ns.5 @@ -0,0 +1,41 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_timerslack_ns 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/timerslack_ns \- timer slack in nanoseconds +.SH DESCRIPTION +.TP +.IR /proc/ pid /timerslack_ns " (since Linux 4.6)" +.\" commit da8b44d5a9f8bf26da637b7336508ca534d6b319 +.\" commit 5de23d435e88996b1efe0e2cebe242074ce67c9e +This file exposes the process's "current" timer slack value, +expressed in nanoseconds. +The file is writable, +allowing the process's timer slack value to be changed. +Writing 0 to this file resets the "current" timer slack to the +"default" timer slack value. +For further details, see the discussion of +.B PR_SET_TIMERSLACK +in +.BR prctl (2). +.IP +Initially, +permission to access this file was governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check (see +.BR ptrace (2)). +However, this was subsequently deemed too strict a requirement +(and had the side effect that requiring a process to have the +.B CAP_SYS_PTRACE +capability would also allow it to view and change any process's memory). +Therefore, since Linux 4.9, +.\" commit 7abbaf94049914f074306d960b0f968ffe52e59f +only the (weaker) +.B CAP_SYS_NICE +capability is required to access this file. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_uid_map.5 b/upstream/fedora-40/man5/proc_pid_uid_map.5 new file mode 100644 index 00000000..14cfdf3e --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_uid_map.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_uid_map 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/gid_map, /proc/pid/uid_map \- user and group ID mappings +.SH DESCRIPTION +.TP +.IR /proc/ pid /gid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.TP +.IR /proc/ pid /uid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_pid_wchan.5 b/upstream/fedora-40/man5/proc_pid_wchan.5 new file mode 100644 index 00000000..c9e018a6 --- /dev/null +++ b/upstream/fedora-40/man5/proc_pid_wchan.5 @@ -0,0 +1,21 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_wchan 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/pid/wchan \- wait channel +.SH DESCRIPTION +.TP +.IR /proc/ pid /wchan " (since Linux 2.6.0)" +The symbolic name corresponding to the location +in the kernel where the process is sleeping. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_profile.5 b/upstream/fedora-40/man5/proc_profile.5 new file mode 100644 index 00000000..0a97484a --- /dev/null +++ b/upstream/fedora-40/man5/proc_profile.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_profile 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/profile \- kernel profiling +.SH DESCRIPTION +.TP +.IR /proc/profile " (since Linux 2.4)" +This file is present only if the kernel was booted with the +.I profile=1 +command-line option. +It exposes kernel profiling information in a binary format for use by +.BR readprofile (1). +Writing (e.g., an empty string) to this file resets the profiling counters; +on some architectures, +writing a binary integer "profiling multiplier" of size +.I sizeof(int) +sets the profiling interrupt frequency. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_scsi.5 b/upstream/fedora-40/man5/proc_scsi.5 new file mode 100644 index 00000000..753d0ff0 --- /dev/null +++ b/upstream/fedora-40/man5/proc_scsi.5 @@ -0,0 +1,66 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Michael Neuffer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_scsi 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/scsi/ \- SCSI +.SH DESCRIPTION +.TP +.I /proc/scsi/ +A directory with the +.I scsi +mid-level pseudo-file and various SCSI low-level +driver directories, +which contain a file for each SCSI host in this system, all of +which give the status of some part of the SCSI IO subsystem. +These files contain ASCII structures and are, therefore, readable with +.BR cat (1). +.IP +You can also write to some of the files to reconfigure the subsystem or +switch certain features on or off. +.TP +.I /proc/scsi/scsi +This is a listing of all SCSI devices known to the kernel. +The listing is similar to the one seen during bootup. +scsi currently supports only the \fIadd\-single\-device\fP command which +allows root to add a hotplugged device to the list of known devices. +.IP +The command +.IP +.in +4n +.EX +echo \[aq]scsi add\-single\-device 1 0 5 0\[aq] > /proc/scsi/scsi +.EE +.in +.IP +will cause +host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. +If there +is already a device known on this address or the address is invalid, an +error will be returned. +.TP +.IR /proc/scsi/ drivername / +\fIdrivername\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, +aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, +scsi_debug, seagate, t128, u15\-24f, ultrastore, or wd7000. +These directories show up for all drivers that registered at least one +SCSI HBA. +Every directory contains one file per registered host. +Every host-file is named after the number the host was assigned during +initialization. +.IP +Reading these files will usually show driver and host configuration, +statistics, and so on. +.IP +Writing to these files allows different things on different hosts. +For example, with the \fIlatency\fP and \fInolatency\fP commands, +root can switch on and off command latency measurement code in the +eata_dma driver. +With the \fIlockup\fP and \fIunlock\fP commands, +root can control bus lockups simulated by the scsi_debug driver. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_slabinfo.5 b/upstream/fedora-40/man5/proc_slabinfo.5 new file mode 100644 index 00000000..d551a431 --- /dev/null +++ b/upstream/fedora-40/man5/proc_slabinfo.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_slabinfo 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/slabinfo \- kernel caches +.SH DESCRIPTION +.TP +.I /proc/slabinfo +Information about kernel caches. +See +.BR slabinfo (5) +for details. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_stat.5 b/upstream/fedora-40/man5/proc_stat.5 new file mode 100644 index 00000000..52a14b4f --- /dev/null +++ b/upstream/fedora-40/man5/proc_stat.5 @@ -0,0 +1,140 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_stat 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/stat \- kernel system statistics +.SH DESCRIPTION +.TP +.I /proc/stat +kernel/system statistics. +Varies with architecture. +Common +entries include: +.RS +.TP +.I cpu 10132153 290696 3084719 46828483 16683 0 25195 0 175628 0 +.TQ +.I cpu0 1393280 32966 572056 13343292 6130 0 17875 0 23933 0 +The amount of time, measured in units of +USER_HZ (1/100ths of a second on most architectures, use +.I sysconf(_SC_CLK_TCK) +to obtain the right value), +.\" 1024 on Alpha and ia64 +that the system ("cpu" line) or the specific CPU ("cpu\fIN\fR" line) +spent in various states: +.RS +.TP +.I user +(1) Time spent in user mode. +.TP +.I nice +(2) Time spent in user mode with low priority (nice). +.TP +.I system +(3) Time spent in system mode. +.TP +.I idle +(4) Time spent in the idle task. +.\" FIXME . Actually, the following info about the /proc/stat 'cpu' field +.\" does not seem to be quite right (at least in Linux 2.6.12 or Linux 3.6): +.\" the idle time in /proc/uptime does not quite match this value +This value should be USER_HZ times the +second entry in the +.I /proc/uptime +pseudo-file. +.TP +.IR iowait " (since Linux 2.5.41)" +(5) Time waiting for I/O to complete. +This value is not reliable, for the following reasons: +.\" See kernel commit 9c240d757658a3ae9968dd309e674c61f07c7f48 +.RS +.IP \[bu] 3 +The CPU will not wait for I/O to complete; +iowait is the time that a task is waiting for I/O to complete. +When a CPU goes into idle state for outstanding task I/O, +another task will be scheduled on this CPU. +.IP \[bu] +On a multi-core CPU, +the task waiting for I/O to complete is not running on any CPU, +so the iowait of each CPU is difficult to calculate. +.IP \[bu] +The value in this field may +.I decrease +in certain conditions. +.RE +.TP +.IR irq " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +(6) Time servicing interrupts. +.TP +.IR softirq " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +(7) Time servicing softirqs. +.TP +.IR steal " (since Linux 2.6.11)" +(8) Stolen time, which is the time spent in other operating systems when +running in a virtualized environment +.TP +.IR guest " (since Linux 2.6.24)" +(9) Time spent running a virtual CPU for guest +operating systems under the control of the Linux kernel. +.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de +.TP +.IR guest_nice " (since Linux 2.6.33)" +.\" commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797 +(10) Time spent running a niced guest (virtual CPU for guest +operating systems under the control of the Linux kernel). +.RE +.TP +\fIpage 5741 1808\fP +The number of pages the system paged in and the number that were paged +out (from disk). +.TP +\fIswap 1 0\fP +The number of swap pages that have been brought in and out. +.TP +.\" FIXME . The following is not the full picture for the 'intr' of +.\" /proc/stat on 2.6: +\fIintr 1462898\fP +This line shows counts of interrupts serviced since boot time, +for each of the possible system interrupts. +The first column is the total of all interrupts serviced +including unnumbered architecture specific interrupts; +each subsequent column is the total for that particular numbered interrupt. +Unnumbered interrupts are not shown, only summed into the total. +.TP +\fIdisk_io: (2,0):(31,30,5764,1,2) (3,0):\fP... +(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, blks_written) +.br +(Linux 2.4 only) +.TP +\fIctxt 115315\fP +The number of context switches that the system underwent. +.TP +\fIbtime 769041601\fP +boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.TP +\fIprocesses 86031\fP +Number of forks since boot. +.TP +\fIprocs_running 6\fP +Number of processes in runnable state. +(Linux 2.5.45 onward.) +.TP +\fIprocs_blocked 2\fP +Number of processes blocked waiting for I/O to complete. +(Linux 2.5.45 onward.) +.TP +.I softirq 229245889 94 60001584 13619 5175704 2471304 28 51212741 59130143 0 51240672 +.\" commit d3d64df21d3d0de675a0d3ffa7c10514f3644b30 +This line shows the number of softirq for all CPUs. +The first column is the total of all softirqs and +each subsequent column is the total for particular softirq. +(Linux 2.6.31 onward.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_swaps.5 b/upstream/fedora-40/man5/proc_swaps.5 new file mode 100644 index 00000000..cb411aac --- /dev/null +++ b/upstream/fedora-40/man5/proc_swaps.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_swaps 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/swaps \- swap areas +.SH DESCRIPTION +.TP +.I /proc/swaps +Swap areas in use. +See also +.BR swapon (8). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_sys.5 b/upstream/fedora-40/man5/proc_sys.5 new file mode 100644 index 00000000..130ec5bf --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys.5 @@ -0,0 +1,31 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/ \- system information, and sysctl pseudo-filesystem +.SH DESCRIPTION +.TP +.I /proc/sys/ +This directory (present since Linux 1.3.57) contains a number of files +and subdirectories corresponding to kernel variables. +These variables can be read and in some cases modified using +the \fI/proc\fP filesystem, and the (deprecated) +.BR sysctl (2) +system call. +.IP +String values may be terminated by either \[aq]\e0\[aq] or \[aq]\en\[aq]. +.IP +Integer and long values may be written either in decimal or in +hexadecimal notation (e.g., 0x3FFF). +When writing multiple integer or long values, these may be separated +by any of the following whitespace characters: +\[aq]\ \[aq], \[aq]\et\[aq], or \[aq]\en\[aq]. +Using other separators leads to the error +.BR EINVAL . +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_sys_abi.5 b/upstream/fedora-40/man5/proc_sys_abi.5 new file mode 100644 index 00000000..161413bf --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_abi.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_abi 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/abi/ \- application binary information +.SH DESCRIPTION +.TP +.IR /proc/sys/abi/ " (since Linux 2.4.10)" +This directory may contain files with application binary information. +.\" On some systems, it is not present. +See the Linux kernel source file +.I Documentation/sysctl/abi.rst +(or +.I Documentation/sysctl/abi.txt +before Linux 5.3) +for more information. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_debug.5 b/upstream/fedora-40/man5/proc_sys_debug.5 new file mode 100644 index 00000000..cf2f458d --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_debug.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_debug 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/debug/ \- debug +.SH DESCRIPTION +.TP +.I /proc/sys/debug/ +This directory may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_dev.5 b/upstream/fedora-40/man5/proc_sys_dev.5 new file mode 100644 index 00000000..0f6c11f5 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_dev.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_dev 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/dev/ \- device-specific information +.SH DESCRIPTION +.TP +.I /proc/sys/dev/ +This directory contains device-specific information (e.g., +.IR dev/cdrom/info ). +On +some systems, it may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_fs.5 b/upstream/fedora-40/man5/proc_sys_fs.5 new file mode 100644 index 00000000..9196d399 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_fs.5 @@ -0,0 +1,471 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_fs 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/fs/ \- kernel variables related to filesystems +.SH DESCRIPTION +.TP +.I /proc/sys/fs/ +This directory contains the files and subdirectories for kernel variables +related to filesystems. +.TP +.IR /proc/sys/fs/aio\-max\-nr " and " /proc/sys/fs/aio\-nr " (since Linux 2.6.4)" +.I aio\-nr +is the running total of the number of events specified by +.BR io_setup (2) +calls for all currently active AIO contexts. +If +.I aio\-nr +reaches +.IR aio\-max\-nr , +then +.BR io_setup (2) +will fail with the error +.BR EAGAIN . +Raising +.I aio\-max\-nr +does not result in the preallocation or resizing +of any kernel data structures. +.TP +.I /proc/sys/fs/binfmt_misc +Documentation for files in this directory can be found +in the Linux kernel source in the file +.I Documentation/admin\-guide/binfmt\-misc.rst +(or in +.I Documentation/binfmt_misc.txt +on older kernels). +.TP +.IR /proc/sys/fs/dentry\-state " (since Linux 2.2)" +This file contains information about the status of the +directory cache (dcache). +The file contains six numbers, +.IR nr_dentry , +.IR nr_unused , +.I age_limit +(age in seconds), +.I want_pages +(pages requested by system) and two dummy values. +.RS +.IP \[bu] 3 +.I nr_dentry +is the number of allocated dentries (dcache entries). +This field is unused in Linux 2.2. +.IP \[bu] +.I nr_unused +is the number of unused dentries. +.IP \[bu] +.I age_limit +.\" looks like this is unused in Linux 2.2 to Linux 2.6 +is the age in seconds after which dcache entries +can be reclaimed when memory is short. +.IP \[bu] +.I want_pages +.\" looks like this is unused in Linux 2.2 to Linux 2.6 +is nonzero when the kernel has called shrink_dcache_pages() and the +dcache isn't pruned yet. +.RE +.TP +.I /proc/sys/fs/dir\-notify\-enable +This file can be used to disable or enable the +.I dnotify +interface described in +.BR fcntl (2) +on a system-wide basis. +A value of 0 in this file disables the interface, +and a value of 1 enables it. +.TP +.I /proc/sys/fs/dquot\-max +This file shows the maximum number of cached disk quota entries. +On some (2.4) systems, it is not present. +If the number of free cached disk quota entries is very low and +you have some awesome number of simultaneous system users, +you might want to raise the limit. +.TP +.I /proc/sys/fs/dquot\-nr +This file shows the number of allocated disk quota +entries and the number of free disk quota entries. +.TP +.IR /proc/sys/fs/epoll/ " (since Linux 2.6.28)" +This directory contains the file +.IR max_user_watches , +which can be used to limit the amount of kernel memory consumed by the +.I epoll +interface. +For further details, see +.BR epoll (7). +.TP +.I /proc/sys/fs/file\-max +This file defines +a system-wide limit on the number of open files for all processes. +System calls that fail when encountering this limit fail with the error +.BR ENFILE . +(See also +.BR setrlimit (2), +which can be used by a process to set the per-process limit, +.BR RLIMIT_NOFILE , +on the number of files it may open.) +If you get lots +of error messages in the kernel log about running out of file handles +(open file descriptions) +(look for "VFS: file\-max limit reached"), +try increasing this value: +.IP +.in +4n +.EX +echo 100000 > /proc/sys/fs/file\-max +.EE +.in +.IP +Privileged processes +.RB ( CAP_SYS_ADMIN ) +can override the +.I file\-max +limit. +.TP +.I /proc/sys/fs/file\-nr +This (read-only) file contains three numbers: +the number of allocated file handles +(i.e., the number of open file descriptions; see +.BR open (2)); +the number of free file handles; +and the maximum number of file handles (i.e., the same value as +.IR /proc/sys/fs/file\-max ). +If the number of allocated file handles is close to the +maximum, you should consider increasing the maximum. +Before Linux 2.6, +the kernel allocated file handles dynamically, +but it didn't free them again. +Instead the free file handles were kept in a list for reallocation; +the "free file handles" value indicates the size of that list. +A large number of free file handles indicates that there was +a past peak in the usage of open file handles. +Since Linux 2.6, the kernel does deallocate freed file handles, +and the "free file handles" value is always zero. +.TP +.IR /proc/sys/fs/inode\-max " (only present until Linux 2.2)" +This file contains the maximum number of in-memory inodes. +This value should be 3\[en]4 times larger +than the value in +.IR file\-max , +since \fIstdin\fP, \fIstdout\fP +and network sockets also need an inode to handle them. +When you regularly run out of inodes, you need to increase this value. +.IP +Starting with Linux 2.4, +there is no longer a static limit on the number of inodes, +and this file is removed. +.TP +.I /proc/sys/fs/inode\-nr +This file contains the first two values from +.IR inode\-state . +.TP +.I /proc/sys/fs/inode\-state +This file +contains seven numbers: +.IR nr_inodes , +.IR nr_free_inodes , +.IR preshrink , +and four dummy values (always zero). +.IP +.I nr_inodes +is the number of inodes the system has allocated. +.\" This can be slightly more than +.\" .I inode\-max +.\" because Linux allocates them one page full at a time. +.I nr_free_inodes +represents the number of free inodes. +.IP +.I preshrink +is nonzero when the +.I nr_inodes +> +.I inode\-max +and the system needs to prune the inode list instead of allocating more; +since Linux 2.4, this field is a dummy value (always zero). +.TP +.IR /proc/sys/fs/inotify/ " (since Linux 2.6.13)" +This directory contains files +.IR max_queued_events ", " max_user_instances ", and " max_user_watches , +that can be used to limit the amount of kernel memory consumed by the +.I inotify +interface. +For further details, see +.BR inotify (7). +.TP +.I /proc/sys/fs/lease\-break\-time +This file specifies the grace period that the kernel grants to a process +holding a file lease +.RB ( fcntl (2)) +after it has sent a signal to that process notifying it +that another process is waiting to open the file. +If the lease holder does not remove or downgrade the lease within +this grace period, the kernel forcibly breaks the lease. +.TP +.I /proc/sys/fs/leases\-enable +This file can be used to enable or disable file leases +.RB ( fcntl (2)) +on a system-wide basis. +If this file contains the value 0, leases are disabled. +A nonzero value enables leases. +.TP +.IR /proc/sys/fs/mount\-max " (since Linux 4.9)" +.\" commit d29216842a85c7970c536108e093963f02714498 +The value in this file specifies the maximum number of mounts that may exist +in a mount namespace. +The default value in this file is 100,000. +.TP +.IR /proc/sys/fs/mqueue/ " (since Linux 2.6.6)" +This directory contains files +.IR msg_max ", " msgsize_max ", and " queues_max , +controlling the resources used by POSIX message queues. +See +.BR mq_overview (7) +for details. +.TP +.IR /proc/sys/fs/nr_open " (since Linux 2.6.25)" +.\" commit 9cfe015aa424b3c003baba3841a60dd9b5ad319b +This file imposes a ceiling on the value to which the +.B RLIMIT_NOFILE +resource limit can be raised (see +.BR getrlimit (2)). +This ceiling is enforced for both unprivileged and privileged process. +The default value in this file is 1048576. +(Before Linux 2.6.25, the ceiling for +.B RLIMIT_NOFILE +was hard-coded to the same value.) +.TP +.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid +These files +allow you to change the value of the fixed UID and GID. +The default is 65534. +Some filesystems support only 16-bit UIDs and GIDs, although in Linux +UIDs and GIDs are 32 bits. +When one of these filesystems is mounted +with writes enabled, any UID or GID that would exceed 65535 is translated +to the overflow value before being written to disk. +.TP +.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/protected_fifos " (since Linux 4.19)" +The value in this file is/can be set to one of the following: +.RS +.TP 4 +0 +Writing to FIFOs is unrestricted. +.TP +1 +Don't allow +.B O_CREAT +.BR open (2) +on FIFOs that the caller doesn't own in world-writable sticky directories, +unless the FIFO is owned by the owner of the directory. +.TP +2 +As for the value 1, +but the restriction also applies to group-writable sticky directories. +.RE +.IP +The intent of the above protections is to avoid unintentional writes to an +attacker-controlled FIFO when a program expected to create a regular file. +.TP +.IR /proc/sys/fs/protected_hardlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on the creation of hard links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, +a hard link can be created to a target file +only if one of the following conditions is true: +.RS +.IP \[bu] 3 +The calling process has the +.B CAP_FOWNER +capability in its user namespace +and the file UID has a mapping in the namespace. +.IP \[bu] +The filesystem UID of the process creating the link matches +the owner (UID) of the target file +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID). +.IP \[bu] +All of the following conditions are true: +.RS 4 +.IP \[bu] 3 +the target is a regular file; +.IP \[bu] +the target file does not have its set-user-ID mode bit enabled; +.IP \[bu] +the target file does not have both its set-group-ID and +group-executable mode bits enabled; and +.IP \[bu] +the caller has permission to read and write the target file +(either via the file's permissions mask or because it has +suitable capabilities). +.RE +.RE +.IP +The default value in this file is 0. +Setting the value to 1 +prevents a longstanding class of security issues caused by +hard-link-based time-of-check, time-of-use races, +most commonly seen in world-writable directories such as +.IR /tmp . +The common method of exploiting this flaw +is to cross privilege boundaries when following a given hard link +(i.e., a root process follows a hard link created by another user). +Additionally, on systems without separated partitions, +this stops unauthorized users from "pinning" vulnerable set-user-ID and +set-group-ID files against being upgraded by +the administrator, or linking to special files. +.TP +.IR /proc/sys/fs/protected_regular " (since Linux 4.19)" +The value in this file is/can be set to one of the following: +.RS +.TP 4 +0 +Writing to regular files is unrestricted. +.TP +1 +Don't allow +.B O_CREAT +.BR open (2) +on regular files that the caller doesn't own in +world-writable sticky directories, +unless the regular file is owned by the owner of the directory. +.TP +2 +As for the value 1, +but the restriction also applies to group-writable sticky directories. +.RE +.IP +The intent of the above protections is similar to +.IR protected_fifos , +but allows an application to +avoid writes to an attacker-controlled regular file, +where the application expected to create one. +.TP +.IR /proc/sys/fs/protected_symlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on following symbolic links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, symbolic links are followed only +in the following circumstances: +.RS +.IP \[bu] 3 +the filesystem UID of the process following the link matches +the owner (UID) of the symbolic link +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID); +.IP \[bu] +the link is not in a sticky world-writable directory; or +.IP \[bu] +the symbolic link and its parent directory have the same owner (UID) +.RE +.IP +A system call that fails to follow a symbolic link +because of the above restrictions returns the error +.B EACCES +in +.IR errno . +.IP +The default value in this file is 0. +Setting the value to 1 avoids a longstanding class of security issues +based on time-of-check, time-of-use races when accessing symbolic links. +.TP +.IR /proc/sys/fs/suid_dumpable " (since Linux 2.6.13)" +.\" The following is based on text from Documentation/sysctl/kernel.txt +The value in this file is assigned to a process's "dumpable" flag +in the circumstances described in +.BR prctl (2). +In effect, +the value in this file determines whether core dump files are +produced for set-user-ID or otherwise protected/tainted binaries. +The "dumpable" setting also affects the ownership of files in a process's +.IR /proc/ pid +directory, as described above. +.IP +Three different integer values can be specified: +.RS +.TP +\fI0\ (default)\fP +.\" In kernel source: SUID_DUMP_DISABLE +This provides the traditional (pre-Linux 2.6.13) behavior. +A core dump will not be produced for a process which has +changed credentials (by calling +.BR seteuid (2), +.BR setgid (2), +or similar, or by executing a set-user-ID or set-group-ID program) +or whose binary does not have read permission enabled. +.TP +\fI1\ ("debug")\fP +.\" In kernel source: SUID_DUMP_USER +All processes dump core when possible. +(Reasons why a process might nevertheless not dump core are described in +.BR core (5).) +The core dump is owned by the filesystem user ID of the dumping process +and no security is applied. +This is intended for system debugging situations only: +this mode is insecure because it allows unprivileged users to +examine the memory contents of privileged processes. +.TP +\fI2\ ("suidsafe")\fP +.\" In kernel source: SUID_DUMP_ROOT +Any binary which normally would not be dumped (see "0" above) +is dumped readable by root only. +This allows the user to remove the core dump file but not to read it. +For security reasons core dumps in this mode will not overwrite one +another or other files. +This mode is appropriate when administrators are +attempting to debug problems in a normal environment. +.IP +Additionally, since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +.I /proc/sys/kernel/core_pattern +must either be an absolute pathname +or a pipe command, as detailed in +.BR core (5). +Warnings will be written to the kernel log if +.I core_pattern +does not follow these rules, and no core dump will be produced. +.\" 54b501992dd2a839e94e76aa392c392b55080ce8 +.RE +.IP +For details of the effect of a process's "dumpable" setting +on ptrace access mode checking, see +.BR ptrace (2). +.TP +.I /proc/sys/fs/super\-max +This file +controls the maximum number of superblocks, and +thus the maximum number of mounted filesystems the kernel +can have. +You need increase only +.I super\-max +if you need to mount more filesystems than the current value in +.I super\-max +allows you to. +.TP +.I /proc/sys/fs/super\-nr +This file +contains the number of filesystems currently mounted. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_kernel.5 b/upstream/fedora-40/man5/proc_sys_kernel.5 new file mode 100644 index 00000000..8563a761 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_kernel.5 @@ -0,0 +1,691 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_kernel 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/kernel/ \- control a range of kernel parameters +.SH DESCRIPTION +.TP +.I /proc/sys/kernel/ +This directory contains files controlling a range of kernel parameters, +as described below. +.TP +.I /proc/sys/kernel/acct +This file +contains three numbers: +.IR highwater , +.IR lowwater , +and +.IR frequency . +If BSD-style process accounting is enabled, these values control +its behavior. +If free space on filesystem where the log lives goes below +.I lowwater +percent, accounting suspends. +If free space gets above +.I highwater +percent, accounting resumes. +.I frequency +determines +how often the kernel checks the amount of free space (value is in +seconds). +Default values are 4, 2, and 30. +That is, suspend accounting if 2% or less space is free; resume it +if 4% or more space is free; consider information about amount of free space +valid for 30 seconds. +.TP +.IR /proc/sys/kernel/auto_msgmni " (Linux 2.6.27 to Linux 3.18)" +.\" commit 9eefe520c814f6f62c5d36a2ddcd3fb99dfdb30e (introduces feature) +.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 (rendered redundant) +From Linux 2.6.27 to Linux 3.18, +this file was used to control recomputing of the value in +.I /proc/sys/kernel/msgmni +upon the addition or removal of memory or upon IPC namespace creation/removal. +Echoing "1" into this file enabled +.I msgmni +automatic recomputing (and triggered a recomputation of +.I msgmni +based on the current amount of available memory and number of IPC namespaces). +Echoing "0" disabled automatic recomputing. +(Automatic recomputing was also disabled if a value was explicitly assigned to +.IR /proc/sys/kernel/msgmni .) +The default value in +.I auto_msgmni +was 1. +.IP +Since Linux 3.19, the content of this file has no effect (because +.I msgmni +.\" FIXME Must document the 3.19 'msgmni' changes. +defaults to near the maximum value possible), +and reads from this file always return the value "0". +.TP +.IR /proc/sys/kernel/cap_last_cap " (since Linux 3.2)" +See +.BR capabilities (7). +.TP +.IR /proc/sys/kernel/cap\-bound " (from Linux 2.2 to Linux 2.6.24)" +This file holds the value of the kernel +.I "capability bounding set" +(expressed as a signed decimal number). +This set is ANDed against the capabilities permitted to a process +during +.BR execve (2). +Starting with Linux 2.6.25, +the system-wide capability bounding set disappeared, +and was replaced by a per-thread bounding set; see +.BR capabilities (7). +.TP +.I /proc/sys/kernel/core_pattern +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_pipe_limit +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_uses_pid +See +.BR core (5). +.TP +.I /proc/sys/kernel/ctrl\-alt\-del +This file +controls the handling of Ctrl-Alt-Del from the keyboard. +When the value in this file is 0, Ctrl-Alt-Del is trapped and +sent to the +.BR init (1) +program to handle a graceful restart. +When the value is greater than zero, Linux's reaction to a Vulcan +Nerve Pinch (tm) will be an immediate reboot, without even +syncing its dirty buffers. +Note: when a program (like dosemu) has the keyboard in "raw" +mode, the Ctrl-Alt-Del is intercepted by the program before it +ever reaches the kernel tty layer, and it's up to the program +to decide what to do with it. +.TP +.IR /proc/sys/kernel/dmesg_restrict " (since Linux 2.6.37)" +The value in this file determines who can see kernel syslog contents. +A value of 0 in this file imposes no restrictions. +If the value is 1, only privileged users can read the kernel syslog. +(See +.BR syslog (2) +for more details.) +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.B CAP_SYS_ADMIN +capability may change the value in this file. +.TP +.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname +can be used to set the NIS/YP domainname and the +hostname of your box in exactly the same way as the commands +.BR domainname (1) +and +.BR hostname (1), +that is: +.IP +.in +4n +.EX +.RB "#" " echo \[aq]darkstar\[aq] > /proc/sys/kernel/hostname" +.RB "#" " echo \[aq]mydomain\[aq] > /proc/sys/kernel/domainname" +.EE +.in +.IP +has the same effect as +.IP +.in +4n +.EX +.RB "#" " hostname \[aq]darkstar\[aq]" +.RB "#" " domainname \[aq]mydomain\[aq]" +.EE +.in +.IP +Note, however, that the classic darkstar.frop.org has the +hostname "darkstar" and DNS (Internet Domain Name Server) +domainname "frop.org", not to be confused with the NIS (Network +Information Service) or YP (Yellow Pages) domainname. +These two +domain names are in general different. +For a detailed discussion +see the +.BR hostname (1) +man page. +.TP +.I /proc/sys/kernel/hotplug +This file +contains the pathname for the hotplug policy agent. +The default value in this file is +.IR /sbin/hotplug . +.TP +.\" Removed in commit 87f504e5c78b910b0c1d6ffb89bc95e492322c84 (tglx/history.git) +.IR /proc/sys/kernel/htab\-reclaim " (before Linux 2.4.9.2)" +(PowerPC only) If this file is set to a nonzero value, +the PowerPC htab +.\" removed in commit 1b483a6a7b2998e9c98ad985d7494b9b725bd228, before Linux 2.6.28 +(see kernel file +.IR Documentation/powerpc/ppc_htab.txt ) +is pruned +each time the system hits the idle loop. +.TP +.I /proc/sys/kernel/keys/ +This directory contains various files that define parameters and limits +for the key-management facility. +These files are described in +.BR keyrings (7). +.TP +.IR /proc/sys/kernel/kptr_restrict " (since Linux 2.6.38)" +.\" 455cd5ab305c90ffc422dd2e0fb634730942b257 +The value in this file determines whether kernel addresses are exposed via +.I /proc +files and other interfaces. +A value of 0 in this file imposes no restrictions. +If the value is 1, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros unless the user has the +.B CAP_SYSLOG +capability. +If the value is 2, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros regardless +of the user's capabilities. +The initial default value for this file was 1, +but the default was changed +.\" commit 411f05f123cbd7f8aa1edcae86970755a6e2a9d9 +to 0 in Linux 2.6.39. +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.B CAP_SYS_ADMIN +capability can change the value in this file. +.TP +.I /proc/sys/kernel/l2cr +(PowerPC only) This file +contains a flag that controls the L2 cache of G3 processor +boards. +If 0, the cache is disabled. +Enabled if nonzero. +.TP +.I /proc/sys/kernel/modprobe +This file contains the pathname for the kernel module loader. +The default value is +.IR /sbin/modprobe . +The file is present only if the kernel is built with the +.B CONFIG_MODULES +.RB ( CONFIG_KMOD +in Linux 2.6.26 and earlier) +option enabled. +It is described by the Linux kernel source file +.I Documentation/kmod.txt +(present only in Linux 2.4 and earlier). +.TP +.IR /proc/sys/kernel/modules_disabled " (since Linux 2.6.31)" +.\" 3d43321b7015387cfebbe26436d0e9d299162ea1 +.\" From Documentation/sysctl/kernel.txt +A toggle value indicating if modules are allowed to be loaded +in an otherwise modular kernel. +This toggle defaults to off (0), but can be set true (1). +Once true, modules can be neither loaded nor unloaded, +and the toggle cannot be set back to false. +The file is present only if the kernel is built with the +.B CONFIG_MODULES +option enabled. +.TP +.IR /proc/sys/kernel/msgmax " (since Linux 2.2)" +This file defines +a system-wide limit specifying the maximum number of bytes in +a single message written on a System V message queue. +.TP +.IR /proc/sys/kernel/msgmni " (since Linux 2.4)" +This file defines the system-wide limit on the number of +message queue identifiers. +See also +.IR /proc/sys/kernel/auto_msgmni . +.TP +.IR /proc/sys/kernel/msgmnb " (since Linux 2.2)" +This file defines a system-wide parameter used to initialize the +.I msg_qbytes +setting for subsequently created message queues. +The +.I msg_qbytes +setting specifies the maximum number of bytes that may be written to the +message queue. +.TP +.IR /proc/sys/kernel/ngroups_max " (since Linux 2.6.4)" +This is a read-only file that displays the upper limit on the +number of a process's group memberships. +.TP +.IR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" +See +.BR pid_namespaces (7). +.TP +.IR /proc/sys/kernel/ostype " and " /proc/sys/kernel/osrelease +These files +give substrings of +.IR /proc/version . +.TP +.IR /proc/sys/kernel/overflowgid " and " /proc/sys/kernel/overflowuid +These files duplicate the files +.I /proc/sys/fs/overflowgid +and +.IR /proc/sys/fs/overflowuid . +.TP +.I /proc/sys/kernel/panic +This file gives read/write access to the kernel variable +.IR panic_timeout . +If this is zero, the kernel will loop on a panic; if nonzero, +it indicates that the kernel should autoreboot after this number +of seconds. +When you use the +software watchdog device driver, the recommended setting is 60. +.TP +.IR /proc/sys/kernel/panic_on_oops " (since Linux 2.5.68)" +This file controls the kernel's behavior when an oops +or BUG is encountered. +If this file contains 0, then the system +tries to continue operation. +If it contains 1, then the system +delays a few seconds (to give klogd time to record the oops output) +and then panics. +If the +.I /proc/sys/kernel/panic +file is also nonzero, then the machine will be rebooted. +.TP +.IR /proc/sys/kernel/pid_max " (since Linux 2.5.34)" +This file specifies the value at which PIDs wrap around +(i.e., the value in this file is one greater than the maximum PID). +PIDs greater than this value are not allocated; +thus, the value in this file also acts as a system-wide limit +on the total number of processes and threads. +The default value for this file, 32768, +results in the same range of PIDs as on earlier kernels. +On 32-bit platforms, 32768 is the maximum value for +.IR pid_max . +On 64-bit systems, +.I pid_max +can be set to any value up to 2\[ha]22 +.RB ( PID_MAX_LIMIT , +approximately 4 million). +.\" Prior to Linux 2.6.10, pid_max could also be raised above 32768 on 32-bit +.\" platforms, but this broke /proc/[pid] +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2 +.TP +.IR /proc/sys/kernel/powersave\-nap " (PowerPC only)" +This file contains a flag. +If set, Linux-PPC will use the "nap" mode of +powersaving, +otherwise the "doze" mode will be used. +.TP +.I /proc/sys/kernel/printk +See +.BR syslog (2). +.TP +.IR /proc/sys/kernel/pty " (since Linux 2.6.4)" +This directory contains two files relating to the number of UNIX 98 +pseudoterminals (see +.BR pts (4)) +on the system. +.TP +.I /proc/sys/kernel/pty/max +This file defines the maximum number of pseudoterminals. +.\" FIXME Document /proc/sys/kernel/pty/reserve +.\" New in Linux 3.3 +.\" commit e9aba5158a80098447ff207a452a3418ae7ee386 +.TP +.I /proc/sys/kernel/pty/nr +This read-only file +indicates how many pseudoterminals are currently in use. +.TP +.I /proc/sys/kernel/random/ +This directory +contains various parameters controlling the operation of the file +.IR /dev/random . +See +.BR random (4) +for further information. +.TP +.IR /proc/sys/kernel/random/uuid " (since Linux 2.4)" +Each read from this read-only file returns a randomly generated 128-bit UUID, +as a string in the standard UUID format. +.TP +.IR /proc/sys/kernel/randomize_va_space " (since Linux 2.6.12)" +.\" Some further details can be found in Documentation/sysctl/kernel.txt +Select the address space layout randomization (ASLR) policy for the system +(on architectures that support ASLR). +Three values are supported for this file: +.RS +.TP +.B 0 +Turn ASLR off. +This is the default for architectures that don't support ASLR, +and when the kernel is booted with the +.I norandmaps +parameter. +.TP +.B 1 +Make the addresses of +.BR mmap (2) +allocations, the stack, and the VDSO page randomized. +Among other things, this means that shared libraries will be +loaded at randomized addresses. +The text segment of PIE-linked binaries will also be loaded +at a randomized address. +This value is the default if the kernel was configured with +.BR CONFIG_COMPAT_BRK . +.TP +.B 2 +(Since Linux 2.6.25) +.\" commit c1d171a002942ea2d93b4fbd0c9583c56fce0772 +Also support heap randomization. +This value is the default if the kernel was not configured with +.BR CONFIG_COMPAT_BRK . +.RE +.TP +.I /proc/sys/kernel/real\-root\-dev +This file is documented in the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10). +.TP +.IR /proc/sys/kernel/reboot\-cmd " (Sparc only)" +This file seems to be a way to give an argument to the SPARC +ROM/Flash boot loader. +Maybe to tell it what to do after +rebooting? +.TP +.I /proc/sys/kernel/rtsig\-max +(Up to and including Linux 2.6.7; see +.BR setrlimit (2)) +This file can be used to tune the maximum number +of POSIX real-time (queued) signals that can be outstanding +in the system. +.TP +.I /proc/sys/kernel/rtsig\-nr +(Up to and including Linux 2.6.7.) +This file shows the number of POSIX real-time signals currently queued. +.TP +.IR /proc/ pid /sched_autogroup_enabled " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_child_runs_first " (since Linux 2.6.23)" +If this file contains the value zero, then, after a +.BR fork (2), +the parent is first scheduled on the CPU. +If the file contains a nonzero value, +then the child is scheduled first on the CPU. +(Of course, on a multiprocessor system, +the parent and the child might both immediately be scheduled on a CPU.) +.TP +.IR /proc/sys/kernel/sched_rr_timeslice_ms " (since Linux 3.9)" +See +.BR sched_rr_get_interval (2). +.TP +.IR /proc/sys/kernel/sched_rt_period_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_rt_runtime_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/seccomp/ " (since Linux 4.14)" +.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af +This directory provides additional seccomp information and +configuration. +See +.BR seccomp (2) +for further details. +.TP +.IR /proc/sys/kernel/sem " (since Linux 2.4)" +This file contains 4 numbers defining limits for System V IPC semaphores. +These fields are, in order: +.RS +.TP +SEMMSL +The maximum semaphores per semaphore set. +.TP +SEMMNS +A system-wide limit on the number of semaphores in all semaphore sets. +.TP +SEMOPM +The maximum number of operations that may be specified in a +.BR semop (2) +call. +.TP +SEMMNI +A system-wide limit on the maximum number of semaphore identifiers. +.RE +.TP +.I /proc/sys/kernel/sg\-big\-buff +This file +shows the size of the generic SCSI device (sg) buffer. +You can't tune it just yet, but you could change it at +compile time by editing +.I include/scsi/sg.h +and changing +the value of +.BR SG_BIG_BUFF . +However, there shouldn't be any reason to change this value. +.TP +.IR /proc/sys/kernel/shm_rmid_forced " (since Linux 3.1)" +.\" commit b34a6b1da371ed8af1221459a18c67970f7e3d53 +.\" See also Documentation/sysctl/kernel.txt +If this file is set to 1, all System V shared memory segments will +be marked for destruction as soon as the number of attached processes +falls to zero; +in other words, it is no longer possible to create shared memory segments +that exist independently of any attached process. +.IP +The effect is as though a +.BR shmctl (2) +.B IPC_RMID +is performed on all existing segments as well as all segments +created in the future (until this file is reset to 0). +Note that existing segments that are attached to no process will be +immediately destroyed when this file is set to 1. +Setting this option will also destroy segments that were created, +but never attached, +upon termination of the process that created the segment with +.BR shmget (2). +.IP +Setting this file to 1 provides a way of ensuring that +all System V shared memory segments are counted against the +resource usage and resource limits (see the description of +.B RLIMIT_AS +in +.BR getrlimit (2)) +of at least one process. +.IP +Because setting this file to 1 produces behavior that is nonstandard +and could also break existing applications, +the default value in this file is 0. +Set this file to 1 only if you have a good understanding +of the semantics of the applications using +System V shared memory on your system. +.TP +.IR /proc/sys/kernel/shmall " (since Linux 2.2)" +This file +contains the system-wide limit on the total number of pages of +System V shared memory. +.TP +.IR /proc/sys/kernel/shmmax " (since Linux 2.2)" +This file +can be used to query and set the run-time limit +on the maximum (System V IPC) shared memory segment size that can be +created. +Shared memory segments up to 1 GB are now supported in the +kernel. +This value defaults to +.BR SHMMAX . +.TP +.IR /proc/sys/kernel/shmmni " (since Linux 2.4)" +This file +specifies the system-wide maximum number of System V shared memory +segments that can be created. +.TP +.IR /proc/sys/kernel/sysctl_writes_strict " (since Linux 3.16)" +.\" commit f88083005ab319abba5d0b2e4e997558245493c8 +.\" commit 2ca9bb456ada8bcbdc8f77f8fc78207653bbaa92 +.\" commit f4aacea2f5d1a5f7e3154e967d70cf3f711bcd61 +.\" commit 24fe831c17ab8149413874f2fd4e5c8a41fcd294 +The value in this file determines how the file offset affects +the behavior of updating entries in files under +.IR /proc/sys . +The file has three possible values: +.RS +.TP 4 +\-1 +This provides legacy handling, with no printk warnings. +Each +.BR write (2) +must fully contain the value to be written, +and multiple writes on the same file descriptor +will overwrite the entire value, regardless of the file position. +.TP +0 +(default) This provides the same behavior as for \-1, +but printk warnings are written for processes that +perform writes when the file offset is not 0. +.TP +1 +Respect the file offset when writing strings into +.I /proc/sys +files. +Multiple writes will +.I append +to the value buffer. +Anything written beyond the maximum length +of the value buffer will be ignored. +Writes to numeric +.I /proc/sys +entries must always be at file offset 0 and the value must be +fully contained in the buffer provided to +.BR write (2). +.\" FIXME . +.\" With /proc/sys/kernel/sysctl_writes_strict==1, writes at an +.\" offset other than 0 do not generate an error. Instead, the +.\" write() succeeds, but the file is left unmodified. +.\" This is surprising. The behavior may change in the future. +.\" See thread.gmane.org/gmane.linux.man/9197 +.\" From: Michael Kerrisk (man-pages +.\" Subject: sysctl_writes_strict documentation + an oddity? +.\" Newsgroups: gmane.linux.man, gmane.linux.kernel +.\" Date: 2015-05-09 08:54:11 GMT +.RE +.TP +.I /proc/sys/kernel/sysrq +This file controls the functions allowed to be invoked by the SysRq key. +By default, +the file contains 1 meaning that every possible SysRq request is allowed +(in older kernel versions, SysRq was disabled by default, +and you were required to specifically enable it at run-time, +but this is not the case any more). +Possible values in this file are: +.RS +.TP 5 +0 +Disable sysrq completely +.TP +1 +Enable all functions of sysrq +.TP +> 1 +Bit mask of allowed sysrq functions, as follows: +.PD 0 +.RS +.TP 5 +\ \ 2 +Enable control of console logging level +.TP +\ \ 4 +Enable control of keyboard (SAK, unraw) +.TP +\ \ 8 +Enable debugging dumps of processes etc. +.TP +\ 16 +Enable sync command +.TP +\ 32 +Enable remount read-only +.TP +\ 64 +Enable signaling of processes (term, kill, oom-kill) +.TP +128 +Allow reboot/poweroff +.TP +256 +Allow nicing of all real-time tasks +.RE +.PD +.RE +.IP +This file is present only if the +.B CONFIG_MAGIC_SYSRQ +kernel configuration option is enabled. +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.TP +.I /proc/sys/kernel/version +This file contains a string such as: +.IP +.in +4n +.EX +#5 Wed Feb 25 21:49:24 MET 1998 +.EE +.in +.IP +The "#5" means that +this is the fifth kernel built from this source base and the +date following it indicates the time the kernel was built. +.TP +.IR /proc/sys/kernel/threads\-max " (since Linux 2.3.11)" +.\" The following is based on Documentation/sysctl/kernel.txt +This file specifies the system-wide limit on the number of +threads (tasks) that can be created on the system. +.IP +Since Linux 4.1, +.\" commit 230633d109e35b0a24277498e773edeb79b4a331 +the value that can be written to +.I threads\-max +is bounded. +The minimum value that can be written is 20. +The maximum value that can be written is given by the +constant +.B FUTEX_TID_MASK +(0x3fffffff). +If a value outside of this range is written to +.IR threads\-max , +the error +.B EINVAL +occurs. +.IP +The value written is checked against the available RAM pages. +If the thread structures would occupy too much (more than 1/8th) +of the available RAM pages, +.I threads\-max +is reduced accordingly. +.TP +.IR /proc/sys/kernel/yama/ptrace_scope " (since Linux 3.5)" +See +.BR ptrace (2). +.TP +.IR /proc/sys/kernel/zero\-paged " (PowerPC only)" +This file +contains a flag. +When enabled (nonzero), Linux-PPC will pre-zero pages in +the idle loop, possibly speeding up get_free_pages. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_net.5 b/upstream/fedora-40/man5/proc_sys_net.5 new file mode 100644 index 00000000..ba5b8956 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_net.5 @@ -0,0 +1,34 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_net 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/net/ \- networking +.SH DESCRIPTION +.TP +.I /proc/sys/net/ +This directory contains networking stuff. +Explanations for some of the files under this directory can be found in +.BR tcp (7) +and +.BR ip (7). +.TP +.I /proc/sys/net/core/bpf_jit_enable +See +.BR bpf (2). +.TP +.I /proc/sys/net/core/somaxconn +This file defines a ceiling value for the +.I backlog +argument of +.BR listen (2); +see the +.BR listen (2) +manual page for details. +.SH SEE ALSO +.BR proc (5), +.BR proc_net (5) diff --git a/upstream/fedora-40/man5/proc_sys_proc.5 b/upstream/fedora-40/man5/proc_sys_proc.5 new file mode 100644 index 00000000..758ace67 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_proc.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_proc 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/proc/ \- ??? +.SH DESCRIPTION +.TP +.I /proc/sys/proc/ +This directory may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_sunrpc.5 b/upstream/fedora-40/man5/proc_sys_sunrpc.5 new file mode 100644 index 00000000..b6b207be --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_sunrpc.5 @@ -0,0 +1,19 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_sunrpc 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/sunrpc/ \- Sun remote procedure call for NFS +.SH DESCRIPTION +.TP +.I /proc/sys/sunrpc/ +This directory supports Sun remote procedure call for network filesystem +(NFS). +On some systems, it is not present. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_user.5 b/upstream/fedora-40/man5/proc_sys_user.5 new file mode 100644 index 00000000..3fe4e6ea --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_user.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_user 5 2023-11-24 "Linux man-pages 6.06" +.SH NAME +/proc/sys/user/ \- limits on the number of namespaces of various types +.SH DESCRIPTION +.TP +.IR /proc/sys/user/ " (since Linux 4.9)" +See +.BR namespaces (7). +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sys_vm.5 b/upstream/fedora-40/man5/proc_sys_vm.5 new file mode 100644 index 00000000..4f978478 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sys_vm.5 @@ -0,0 +1,420 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_vm 5 2023-09-30 "Linux man-pages 6.06" +.SH NAME +/proc/sys/vm/ \- virtual memory subsystem +.SH DESCRIPTION +.TP +.I /proc/sys/vm/ +This directory contains files for memory management tuning, buffer, and +cache management. +.TP +.IR /proc/sys/vm/admin_reserve_kbytes " (since Linux 3.10)" +.\" commit 4eeab4f5580d11bffedc697684b91b0bca0d5009 +This file defines the amount of free memory (in KiB) on the system that +should be reserved for users with the capability +.BR CAP_SYS_ADMIN . +.IP +The default value in this file is the minimum of [3% of free pages, 8MiB] +expressed as KiB. +The default is intended to provide enough for the superuser +to log in and kill a process, if necessary, +under the default overcommit 'guess' mode (i.e., 0 in +.IR /proc/sys/vm/overcommit_memory ). +.IP +Systems running in "overcommit never" mode (i.e., 2 in +.IR /proc/sys/vm/overcommit_memory ) +should increase the value in this file to account +for the full virtual memory size of the programs used to recover (e.g., +.BR login (1) +.BR ssh (1), +and +.BR top (1)) +Otherwise, the superuser may not be able to log in to recover the system. +For example, on x86-64 a suitable value is 131072 (128MiB reserved). +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/compact_memory " (since Linux 2.6.35)" +When 1 is written to this file, all zones are compacted such that free +memory is available in contiguous blocks where possible. +The effect of this action can be seen by examining +.IR /proc/buddyinfo . +.IP +Present only if the kernel was configured with +.BR CONFIG_COMPACTION . +.TP +.IR /proc/sys/vm/drop_caches " (since Linux 2.6.16)" +Writing to this file causes the kernel to drop clean caches, dentries, and +inodes from memory, causing that memory to become free. +This can be useful for memory management testing and +performing reproducible filesystem benchmarks. +Because writing to this file causes the benefits of caching to be lost, +it can degrade overall system performance. +.IP +To free pagecache, use: +.IP +.in +4n +.EX +echo 1 > /proc/sys/vm/drop_caches +.EE +.in +.IP +To free dentries and inodes, use: +.IP +.in +4n +.EX +echo 2 > /proc/sys/vm/drop_caches +.EE +.in +.IP +To free pagecache, dentries, and inodes, use: +.IP +.in +4n +.EX +echo 3 > /proc/sys/vm/drop_caches +.EE +.in +.IP +Because writing to this file is a nondestructive operation and dirty objects +are not freeable, the +user should run +.BR sync (1) +first. +.TP +.IR /proc/sys/vm/sysctl_hugetlb_shm_group " (since Linux 2.6.7)" +This writable file contains a group ID that is allowed +to allocate memory using huge pages. +If a process has a filesystem group ID or any supplementary group ID that +matches this group ID, +then it can make huge-page allocations without holding the +.B CAP_IPC_LOCK +capability; see +.BR memfd_create (2), +.BR mmap (2), +and +.BR shmget (2). +.TP +.IR /proc/sys/vm/legacy_va_layout " (since Linux 2.6.9)" +.\" The following is from Documentation/filesystems/proc.txt +If nonzero, this disables the new 32-bit memory-mapping layout; +the kernel will use the legacy (2.4) layout for all processes. +.TP +.IR /proc/sys/vm/memory_failure_early_kill " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Control how to kill processes when an uncorrected memory error +(typically a 2-bit error in a memory module) +that cannot be handled by the kernel +is detected in the background by hardware. +In some cases (like the page still having a valid copy on disk), +the kernel will handle the failure +transparently without affecting any applications. +But if there is no other up-to-date copy of the data, +it will kill processes to prevent any data corruptions from propagating. +.IP +The file has one of the following values: +.RS +.TP +.B 1 +Kill all processes that have the corrupted-and-not-reloadable page mapped +as soon as the corruption is detected. +Note that this is not supported for a few types of pages, +such as kernel internally +allocated data or the swap cache, but works for the majority of user pages. +.TP +.B 0 +Unmap the corrupted page from all processes and kill a process +only if it tries to access the page. +.RE +.IP +The kill is performed using a +.B SIGBUS +signal with +.I si_code +set to +.BR BUS_MCEERR_AO . +Processes can handle this if they want to; see +.BR sigaction (2) +for more details. +.IP +This feature is active only on architectures/platforms with advanced machine +check handling and depends on the hardware capabilities. +.IP +Applications can override the +.I memory_failure_early_kill +setting individually with the +.BR prctl (2) +.B PR_MCE_KILL +operation. +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/memory_failure_recovery " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Enable memory failure recovery (when supported by the platform). +.RS +.TP +.B 1 +Attempt recovery. +.TP +.B 0 +Always panic on a memory failure. +.RE +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/oom_dump_tasks " (since Linux 2.6.25)" +.\" The following is from Documentation/sysctl/vm.txt +Enables a system-wide task dump (excluding kernel threads) to be +produced when the kernel performs an OOM-killing. +The dump includes the following information +for each task (thread, process): +thread ID, real user ID, thread group ID (process ID), +virtual memory size, resident set size, +the CPU that the task is scheduled on, +oom_adj score (see the description of +.IR /proc/ pid /oom_adj ), +and command name. +This is helpful to determine why the OOM-killer was invoked +and to identify the rogue task that caused it. +.IP +If this contains the value zero, this information is suppressed. +On very large systems with thousands of tasks, +it may not be feasible to dump the memory state information for each one. +Such systems should not be forced to incur a performance penalty in +OOM situations when the information may not be desired. +.IP +If this is set to nonzero, this information is shown whenever the +OOM-killer actually kills a memory-hogging task. +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/oom_kill_allocating_task " (since Linux 2.6.24)" +.\" The following is from Documentation/sysctl/vm.txt +This enables or disables killing the OOM-triggering task in +out-of-memory situations. +.IP +If this is set to zero, the OOM-killer will scan through the entire +tasklist and select a task based on heuristics to kill. +This normally selects a rogue memory-hogging task that +frees up a large amount of memory when killed. +.IP +If this is set to nonzero, the OOM-killer simply kills the task that +triggered the out-of-memory condition. +This avoids a possibly expensive tasklist scan. +.IP +If +.I /proc/sys/vm/panic_on_oom +is nonzero, it takes precedence over whatever value is used in +.IR /proc/sys/vm/oom_kill_allocating_task . +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/overcommit_kbytes " (since Linux 3.14)" +.\" commit 49f0ce5f92321cdcf741e35f385669a421013cb7 +This writable file provides an alternative to +.I /proc/sys/vm/overcommit_ratio +for controlling the +.I CommitLimit +when +.I /proc/sys/vm/overcommit_memory +has the value 2. +It allows the amount of memory overcommitting to be specified as +an absolute value (in kB), +rather than as a percentage, as is done with +.IR overcommit_ratio . +This allows for finer-grained control of +.I CommitLimit +on systems with extremely large memory sizes. +.IP +Only one of +.I overcommit_kbytes +or +.I overcommit_ratio +can have an effect: +if +.I overcommit_kbytes +has a nonzero value, then it is used to calculate +.IR CommitLimit , +otherwise +.I overcommit_ratio +is used. +Writing a value to either of these files causes the +value in the other file to be set to zero. +.TP +.I /proc/sys/vm/overcommit_memory +This file contains the kernel virtual memory accounting mode. +Values are: +.RS +.IP +0: heuristic overcommit (this is the default) +.br +1: always overcommit, never check +.br +2: always check, never overcommit +.RE +.IP +In mode 0, calls of +.BR mmap (2) +with +.B MAP_NORESERVE +are not checked, and the default check is very weak, +leading to the risk of getting a process "OOM-killed". +.IP +In mode 1, the kernel pretends there is always enough memory, +until memory actually runs out. +One use case for this mode is scientific computing applications +that employ large sparse arrays. +Before Linux 2.6.0, any nonzero value implies mode 1. +.IP +In mode 2 (available since Linux 2.6), the total virtual address space +that can be allocated +.RI ( CommitLimit +in +.IR /proc/meminfo ) +is calculated as +.IP +.in +4n +.EX +CommitLimit = (total_RAM \- total_huge_TLB) * + overcommit_ratio / 100 + total_swap +.EE +.in +.IP +where: +.RS +.IP \[bu] 3 +.I total_RAM +is the total amount of RAM on the system; +.IP \[bu] +.I total_huge_TLB +is the amount of memory set aside for huge pages; +.IP \[bu] +.I overcommit_ratio +is the value in +.IR /proc/sys/vm/overcommit_ratio ; +and +.IP \[bu] +.I total_swap +is the amount of swap space. +.RE +.IP +For example, on a system with 16 GB of physical RAM, 16 GB +of swap, no space dedicated to huge pages, and an +.I overcommit_ratio +of 50, this formula yields a +.I CommitLimit +of 24 GB. +.IP +Since Linux 3.14, if the value in +.I /proc/sys/vm/overcommit_kbytes +is nonzero, then +.I CommitLimit +is instead calculated as: +.IP +.in +4n +.EX +CommitLimit = overcommit_kbytes + total_swap +.EE +.in +.IP +See also the description of +.I /proc/sys/vm/admin_reserve_kbytes +and +.IR /proc/sys/vm/user_reserve_kbytes . +.TP +.IR /proc/sys/vm/overcommit_ratio " (since Linux 2.6.0)" +This writable file defines a percentage by which memory +can be overcommitted. +The default value in the file is 50. +See the description of +.IR /proc/sys/vm/overcommit_memory . +.TP +.IR /proc/sys/vm/panic_on_oom " (since Linux 2.6.18)" +.\" The following is adapted from Documentation/sysctl/vm.txt +This enables or disables a kernel panic in +an out-of-memory situation. +.IP +If this file is set to the value 0, +the kernel's OOM-killer will kill some rogue process. +Usually, the OOM-killer is able to kill a rogue process and the +system will survive. +.IP +If this file is set to the value 1, +then the kernel normally panics when out-of-memory happens. +However, if a process limits allocations to certain nodes +using memory policies +.RB ( mbind (2) +.BR MPOL_BIND ) +or cpusets +.RB ( cpuset (7)) +and those nodes reach memory exhaustion status, +one process may be killed by the OOM-killer. +No panic occurs in this case: +because other nodes' memory may be free, +this means the system as a whole may not have reached +an out-of-memory situation yet. +.IP +If this file is set to the value 2, +the kernel always panics when an out-of-memory condition occurs. +.IP +The default value is 0. +1 and 2 are for failover of clustering. +Select either according to your policy of failover. +.TP +.I /proc/sys/vm/swappiness +.\" The following is from Documentation/sysctl/vm.txt +The value in this file controls how aggressively the kernel will swap +memory pages. +Higher values increase aggressiveness, lower values +decrease aggressiveness. +The default value is 60. +.TP +.IR /proc/sys/vm/user_reserve_kbytes " (since Linux 3.10)" +.\" commit c9b1d0981fcce3d9976d7b7a56e4e0503bc610dd +Specifies an amount of memory (in KiB) to reserve for user processes. +This is intended to prevent a user from starting a single memory hogging +process, such that they cannot recover (kill the hog). +The value in this file has an effect only when +.I /proc/sys/vm/overcommit_memory +is set to 2 ("overcommit never" mode). +In this case, the system reserves an amount of memory that is the minimum +of [3% of current process size, +.IR user_reserve_kbytes ]. +.IP +The default value in this file is the minimum of [3% of free pages, 128MiB] +expressed as KiB. +.IP +If the value in this file is set to zero, +then a user will be allowed to allocate all free memory with a single process +(minus the amount reserved by +.IR /proc/sys/vm/admin_reserve_kbytes ). +Any subsequent attempts to execute a command will result in +"fork: Cannot allocate memory". +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/unprivileged_userfaultfd " (since Linux 5.2)" +.\" cefdca0a86be517bc390fc4541e3674b8e7803b0 +This (writable) file exposes a flag that controls whether +unprivileged processes are allowed to employ +.BR userfaultfd (2). +If this file has the value 1, then unprivileged processes may use +.BR userfaultfd (2). +If this file has the value 0, then only processes that have the +.B CAP_SYS_PTRACE +capability may employ +.BR userfaultfd (2). +The default value in this file is 1. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/upstream/fedora-40/man5/proc_sysrq-trigger.5 b/upstream/fedora-40/man5/proc_sysrq-trigger.5 new file mode 100644 index 00000000..89c488c5 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sysrq-trigger.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sysrq-trigger 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/sysrq\-trigger \- SysRq function +.SH DESCRIPTION +.TP +.IR /proc/sysrq\-trigger " (since Linux 2.4.21)" +Writing a character to this file triggers the same SysRq function as +typing ALT-SysRq- (see the description of +.IR /proc/sys/kernel/sysrq ). +This file is normally writable only by +.IR root . +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_sysvipc.5 b/upstream/fedora-40/man5/proc_sysvipc.5 new file mode 100644 index 00000000..5fdf75f8 --- /dev/null +++ b/upstream/fedora-40/man5/proc_sysvipc.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sysvipc 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/sysvipc/ \- System V IPC +.SH DESCRIPTION +.TP +.I /proc/sysvipc/ +Subdirectory containing the pseudo-files +.IR msg ", " sem " and " shm "." +These files list the System V Interprocess Communication (IPC) objects +(respectively: message queues, semaphores, and shared memory) +that currently exist on the system, +providing similar information to that available via +.BR ipcs (1). +These files have headers and are formatted (one IPC object per line) +for easy understanding. +.BR sysvipc (7) +provides further background on the information shown by these files. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_tid_children.5 b/upstream/fedora-40/man5/proc_tid_children.5 new file mode 100644 index 00000000..67f984b9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_tid_children.5 @@ -0,0 +1,37 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_tid_children 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/tid/children \- child tasks +.SH DESCRIPTION +.TP +.IR /proc/ tid /children " (since Linux 3.5)" +.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7 +A space-separated list of child tasks of this task. +Each child task is represented by its TID. +.IP +.\" see comments in get_children_pid() in fs/proc/array.c +This option is intended for use by the checkpoint-restore (CRIU) system, +and reliably provides a list of children only if all of the child processes +are stopped or frozen. +It does not work properly if children of the target task exit while +the file is being read! +Exiting children may cause non-exiting children to be omitted from the list. +This makes this interface even more unreliable than classic PID-based +approaches if the inspected task and its children aren't frozen, +and most code should probably not use this interface. +.IP +Until Linux 4.2, the presence of this file was governed by the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option. +Since Linux 4.2, +.\" commit 2e13ba54a2682eea24918b87ad3edf70c2cf085b +it is governed by the +.B CONFIG_PROC_CHILDREN +option. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_timer_list.5 b/upstream/fedora-40/man5/proc_timer_list.5 new file mode 100644 index 00000000..51b9575b --- /dev/null +++ b/upstream/fedora-40/man5/proc_timer_list.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_timer_list 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/timer_list \- pending timers +.SH DESCRIPTION +.TP +.IR /proc/timer_list " (since Linux 2.6.21)" +.\" commit 289f480af87e45f7a6de6ba9b4c061c2e259fe98 +This read-only file exposes a list of all currently pending +(high-resolution) timers, +all clock-event sources, and their parameters in a human-readable form. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_timer_stats.5 b/upstream/fedora-40/man5/proc_timer_stats.5 new file mode 100644 index 00000000..caf83856 --- /dev/null +++ b/upstream/fedora-40/man5/proc_timer_stats.5 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_timer_stats 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/timer_stats \- timer statistics +.SH DESCRIPTION +.TP +.IR /proc/timer_stats " (from Linux 2.6.21 until Linux 4.10)" +.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221 +.\" Date: Fri Feb 16 01:28:13 2007 -0800 +.\" Text largely derived from Documentation/timers/timer_stats.txt +.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1 +.\" Date: Wed Feb 8 11:26:59 2017 -0800 +This is a debugging facility to make timer (ab)use in a Linux +system visible to kernel and user-space developers. +It can be used by kernel and user-space developers to verify that +their code does not make undue use of timers. +The goal is to avoid unnecessary wakeups, +thereby optimizing power consumption. +.IP +If enabled in the kernel +.RB ( CONFIG_TIMER_STATS ), +but not used, +it has almost zero run-time overhead and a relatively small +data-structure overhead. +Even if collection is enabled at run time, overhead is low: +all the locking is per-CPU and lookup is hashed. +.IP +The +.I /proc/timer_stats +file is used both to control sampling facility and to read out the +sampled information. +.IP +The +.I timer_stats +functionality is inactive on bootup. +A sampling period can be started using the following command: +.IP +.in +4n +.EX +# echo 1 > /proc/timer_stats +.EE +.in +.IP +The following command stops a sampling period: +.IP +.in +4n +.EX +# echo 0 > /proc/timer_stats +.EE +.in +.IP +The statistics can be retrieved by: +.IP +.in +4n +.EX +$ cat /proc/timer_stats +.EE +.in +.IP +While sampling is enabled, each readout from +.I /proc/timer_stats +will see +newly updated statistics. +Once sampling is disabled, the sampled information +is kept until a new sample period is started. +This allows multiple readouts. +.IP +Sample output from +.IR /proc/timer_stats : +.IP +.in +4n +.EX +.RB $ " cat /proc/timer_stats" +Timer Stats Version: v0.3 +Sample period: 1.764 s +Collection: active + 255, 0 swapper/3 hrtimer_start_range_ns (tick_sched_timer) + 71, 0 swapper/1 hrtimer_start_range_ns (tick_sched_timer) + 58, 0 swapper/0 hrtimer_start_range_ns (tick_sched_timer) + 4, 1694 gnome\-shell mod_delayed_work_on (delayed_work_timer_fn) + 17, 7 rcu_sched rcu_gp_kthread (process_timeout) +\&... + 1, 4911 kworker/u16:0 mod_delayed_work_on (delayed_work_timer_fn) + 1D, 2522 kworker/0:0 queue_delayed_work_on (delayed_work_timer_fn) +1029 total events, 583.333 events/sec +.EE +.in +.IP +The output columns are: +.RS +.IP [1] 5 +a count of the number of events, +optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq] +.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers +if this is a deferrable timer; +.IP [2] +the PID of the process that initialized the timer; +.IP [3] +the name of the process that initialized the timer; +.IP [4] +the function where the timer was initialized; and +(in parentheses) +the callback function that is associated with the timer. +.RE +.IP +During the Linux 4.11 development cycle, +this file was removed because of security concerns, +as it exposes information across namespaces. +Furthermore, it is possible to obtain +the same information via in-kernel tracing facilities such as ftrace. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_tty.5 b/upstream/fedora-40/man5/proc_tty.5 new file mode 100644 index 00000000..e554541f --- /dev/null +++ b/upstream/fedora-40/man5/proc_tty.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_tty 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/tty/ \- tty +.SH DESCRIPTION +.TP +.I /proc/tty/ +Subdirectory containing the pseudo-files and subdirectories for +tty drivers and line disciplines. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_uptime.5 b/upstream/fedora-40/man5/proc_uptime.5 new file mode 100644 index 00000000..7268029d --- /dev/null +++ b/upstream/fedora-40/man5/proc_uptime.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_uptime 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/uptime \- system uptime +.SH DESCRIPTION +.TP +.I /proc/uptime +This file contains two numbers (values in seconds): the uptime of the +system (including time spent in suspend) and the amount of time spent +in the idle process. +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_version.5 b/upstream/fedora-40/man5/proc_version.5 new file mode 100644 index 00000000..5a4a703c --- /dev/null +++ b/upstream/fedora-40/man5/proc_version.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_version 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/version \- kernel version +.SH DESCRIPTION +.TP +.I /proc/version +This string identifies the kernel version that is currently running. +It includes the contents of +.IR /proc/sys/kernel/ostype , +.IR /proc/sys/kernel/osrelease , +and +.IR /proc/sys/kernel/version . +For example: +.IP +.in +4n +.EX +Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 +.EE +.in +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_vmstat.5 b/upstream/fedora-40/man5/proc_vmstat.5 new file mode 100644 index 00000000..fe7dccdc --- /dev/null +++ b/upstream/fedora-40/man5/proc_vmstat.5 @@ -0,0 +1,702 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_vmstat 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/vmstat \- virtual memory statistics +.SH DESCRIPTION +.TP +.IR /proc/vmstat " (since Linux 2.6.0)" +This file displays various virtual memory statistics. +Each line of this file contains a single name-value pair, +delimited by white space. +Some lines are present only if the kernel was configured with +suitable options. +(In some cases, the options required for particular files have changed +across kernel versions, so they are not listed here. +Details can be found by consulting the kernel source code.) +The following fields may be present: +.\" FIXME We need explanations for each of the following fields... +.RS +.TP +.IR nr_free_pages " (since Linux 2.6.31)" +.\" commit d23ad42324cc4378132e51f2fc5c9ba6cbe75182 +.TP +.IR nr_alloc_batch " (since Linux 3.12)" +.\" commit 81c0a2bb515fd4daae8cab64352877480792b515 +.TP +.IR nr_inactive_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_inactive_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_unevictable " (since Linux 2.6.28)" +.\" commit 7b854121eb3e5ba0241882ff939e2c485228c9c5 +.TP +.IR nr_mlock " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.TP +.IR nr_anon_pages " (since Linux 2.6.18)" +.\" commit f3dbd34460ff54962d3e3244b6bcb7f5295356e6 +.TP +.IR nr_mapped " (since Linux 2.6.0)" +.TP +.IR nr_file_pages " (since Linux 2.6.18)" +.\" commit 347ce434d57da80fd5809c0c836f206a50999c26 +.TP +.IR nr_dirty " (since Linux 2.6.0)" +.TP +.IR nr_writeback " (since Linux 2.6.0)" +.TP +.IR nr_slab_reclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.\" Linux 2.6.0 had nr_slab +.TP +.IR nr_slab_unreclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.TP +.IR nr_page_table_pages " (since Linux 2.6.0)" +.TP +.IR nr_kernel_stack " (since Linux 2.6.32)" +.\" commit c6a7f5728a1db45d30df55a01adc130b4ab0327c +Amount of memory allocated to kernel stacks. +.TP +.IR nr_unstable " (since Linux 2.6.0)" +.TP +.IR nr_bounce " (since Linux 2.6.12)" +.\" commit edfbe2b0038723e5699ab22695ccd62b5542a5c1 +.TP +.IR nr_vmscan_write " (since Linux 2.6.19)" +.\" commit e129b5c23c2b471d47f1c5d2b8b193fc2034af43 +.TP +.IR nr_vmscan_immediate_reclaim " (since Linux 3.2)" +.\" commit 49ea7eb65e7c5060807fb9312b1ad4c3eab82e2c +.TP +.IR nr_writeback_temp " (since Linux 2.6.26)" +.\" commit fc3ba692a4d19019387c5acaea63131f9eab05dd +.TP +.IR nr_isolated_anon " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_isolated_file " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_shmem " (since Linux 2.6.32)" +.\" commit 4b02108ac1b3354a22b0d83c684797692efdc395 +Pages used by shmem and +.BR tmpfs (5). +.TP +.IR nr_dirtied " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_written " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_pages_scanned " (since Linux 3.17)" +.\" commit 0d5d823ab4e608ec7b52ac4410de4cb74bbe0edd +.TP +.IR numa_hit " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_miss " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_foreign " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_interleave " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_local " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_other " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR workingset_refault " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_activate " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_nodereclaim " (since Linux 3.15)" +.\" commit 449dd6984d0e47643c04c807f609dd56d48d5bcc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_anon_transparent_hugepages " (since Linux 2.6.38)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_free_cma " (since Linux 3.7)" +.\" commit d1ce749a0db12202b711d1aba1d29e823034648d +Number of free CMA (Contiguous Memory Allocator) pages. +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_background_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgalloc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgalloc_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfree " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgdeactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgmajfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgrefill +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgrefill_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Formerly there were +.\" pgsteal_high +.\" pgsteal_normal +.\" pgsteal_dma32 +.\" pgsteal_dma +.\" These were split out into pgsteal_kswapd* and pgsteal_direct* +.\" in commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.TP +.IR pgsteal_kswapd_dma " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Linux 2.6.0 had pgsteal +.\" Present only if the kernel was configured with +.\" .\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_kswapd_movable " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgsteal_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_kswapd_dma +.\" Linux 2.6.0 had pgscan +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_kswapd_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_kswapd_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_normal +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_throttle " (since Linux 3.6)" +.\" commit 68243e76ee343d63c6cf76978588a885951e2818 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR zone_reclaim_failed " (since linux 2.6.31)" +.\" commit 24cf72518c79cdcda486ed26074ff8151291cf65 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA . +.TP +.IR pginodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR slabs_scanned " (since linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_inodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_low_wmark_hit_quickly " (since Linux 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_high_wmark_hit_quickly " (since Linux 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pageoutrun " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR allocstall " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrotated " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_pagecache " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_slab " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR numa_pte_updates " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_huge_pte_updates " (since Linux 3.13)" +.\" commit 72403b4a0fbdf433c1fe0127e49864658f6f6468 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults_local " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_pages_migrated " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR pgmigrate_success " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR pgmigrate_fail " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR compact_migrate_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Linux 3.8 dropped compact_blocks_moved, compact_pages_moved, and +.\" compact_pagemigrate_failed +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_free_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_isolated " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_stall " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_fail " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_success " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR htlb_buddy_alloc_success " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR htlb_buddy_alloc_fail " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR unevictable_pgs_culled " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_scanned " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_rescued " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_mlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_munlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_cleared " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_stranded " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Linux 3.7 removed unevictable_pgs_mlockfreed +.TP +.IR thp_fault_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_fault_fallback " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc_failed " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_split " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc_failed " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR balloon_inflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_deflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_migrate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS , +.\" .BR CONFIG_MEMORY_BALLOON , +.\" and +.\" .BR CONFIG_BALLOON_COMPACTION . +.TP +.IR nr_tlb_remote_flush " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_remote_flush_received " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_local_flush_all " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR nr_tlb_local_flush_one " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR vmacache_find_calls " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_find_hits " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_full_flushes " (since Linux 3.19)" +.\" commit f5f302e21257ebb0c074bbafc37606c26d28cc3d +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/proc_zoneinfo.5 b/upstream/fedora-40/man5/proc_zoneinfo.5 new file mode 100644 index 00000000..ad3341d9 --- /dev/null +++ b/upstream/fedora-40/man5/proc_zoneinfo.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_zoneinfo 5 2023-08-15 "Linux man-pages 6.06" +.SH NAME +/proc/zoneinfo \- memory zones +.SH DESCRIPTION +.TP +.IR /proc/zoneinfo " (since Linux 2.6.13)" +This file displays information about memory zones. +This is useful for analyzing virtual memory behavior. +.\" FIXME more should be said about /proc/zoneinfo +.SH SEE ALSO +.BR proc (5) diff --git a/upstream/fedora-40/man5/procmailex.5 b/upstream/fedora-40/man5/procmailex.5 new file mode 100644 index 00000000..0107668e --- /dev/null +++ b/upstream/fedora-40/man5/procmailex.5 @@ -0,0 +1,568 @@ +.\"if n .pl +(135i-\n(.pu) +.de Id +.ds Rv \\$3 +.ds Dt \\$4 +.. +.Id $Id$ +.TH PROCMAILEX 5 \*(Dt BuGless +.rn SH Sh +.de SH +.br +.ne 11 +.Sh "\\$1" +.. +.rn SS Ss +.de SS +.br +.ne 10 +.Ss "\\$1" +.. +.rn TP Tp +.de TP +.br +.ne 9 +.Tp \\$1 +.. +.rn RS Rs +.de RS +.na +.nf +.Rs +.. +.rn RE Re +.de RE +.Re +.fi +.ad +.. +.de Sx +.PP +.ne \\$1 +.RS +.. +.de Ex +.RE +.PP +.. +.na +.SH NAME +procmailex \- procmail rcfile examples +.SH SYNOPSIS +.B $HOME/.procmailrc examples +.ad +.SH DESCRIPTION +For a description of the rcfile format see +.BR procmailrc (5). +.PP +The weighted scoring technique is described in detail in the +.BR procmailsc (5) +man page. +.PP +This man page shows several example recipes. For examples of complete rcfiles +you can check the NOTES section in +.BR procmail (1), +or look at the example rcfiles in /usr/share/doc/procmail/examples. +.SH EXAMPLES +Sort out all mail coming from the scuba-dive mailing list into the mailfolder +scubafile (uses the locallockfile scubafile.lock). +.Sx 3 +:0: +* ^TOscuba +scubafile +.Ex +Forward all mail from peter about compilers to william (and keep a copy +of it here in petcompil). +.Sx 10 +:0 +* ^From.*peter +* ^Subject:.*compilers +{ + :0 c + ! william@somewhere.edu + + :0 + petcompil +} +.Ex +An equivalent solution that accomplishes the same: +.Sx 7 +:0 c +* ^From.*peter +* ^Subject:.*compilers +! william@somewhere.edu + + :0 A + petcompil +.Ex +An equivalent, but slightly slower solution that accomplishes the same: +.Sx 9 +:0 c +* ^From.*peter +* ^Subject:.*compilers +! william@somewhere.edu + +:0 +* ^From.*peter +* ^Subject:.*compilers +petcompil +.Ex +If you are fairly new to procmail and plan to experiment a little bit +it often helps to have a +.I safety net +of some sort. Inserting the following two recipes above all other recipes +will make sure that of all arriving mail always the last 32 messages will +be preserved. In order for it to work as intended, you have to create +a directory named `backup' in $MAILDIR prior to inserting these two recipes. +.Sx 5 +:0 c +backup + +:0 ic +| cd backup && rm \-f dummy `ls \-t msg.* | sed \-e 1,32d` +.Ex +If your system doesn't generate or generates incorrect leading `From ' +lines on every mail, you can fix this by calling up procmail with +the \-f- option. To fix the same problem by +different means, you could have inserted the following +recipe above all other recipes in your rcfile. They will filter the header +of any mail through formail which will strip any leading `From ', and +automatically regenerates it subsequently. +.Sx 2 +:0 fhw +| formail \-I "From " \-a "From " +.Ex +Add the headers of all messages that didn't come from the postmaster +to your private header collection (for +statistics or mail debugging); and use the lockfile `headc.lock'. In order +to make sure the lockfile is not removed until the pipe has finished, +you have to specify option `w'; otherwise the lockfile would be +removed as soon as the pipe has accepted the mail. +.Sx 3 +:0 hwc: +* !^FROM_MAILER +| uncompress headc.Z; cat >>headc; compress headc +.Ex +Or, if you would use the more efficient gzip instead of compress: +.Sx 3 +:0 hwc: +* !^FROM_MAILER +| gzip >>headc.gz +.Ex +Forward all mails shorter than 1000 bytes to my home address (no lockfile +needed on this recipe). +.Sx 3 +:0 +* < 1000 +! myname@home +.Ex +Split up incoming digests from the surfing mailing list into their individual +messages, and store them into surfing, using surfing.lock as the locallockfile. +.Sx 3 +:0: +* ^Subject:.*surfing.*Digest +| formail +1 \-ds >>surfing +.Ex +Store everything coming from the postmaster or mailer-daemon (like bounced +mail) into the file postm, using postm.lock as the locallockfile. +.Sx 3 +:0: +* ^FROM_MAILER +postm +.Ex +A simple autoreply recipe. It makes sure that neither mail from any daemon +(like bouncing mail or mail from mailing-lists), nor autoreplies coming from +yourself will be autoreplied to. If this precaution would not be taken, +disaster could result (`ringing' mail). In order for this recipe to autoreply +to all the incoming mail, you should of course insert it before all other +recipes in your rcfile. However, it is advisable to put it +.I after +any recipes that process the mails from subscribed mailinglists; it generally +is not a good idea to generate autoreplies to mailinglists (yes, the +!^FROM_DAEMON regexp should already catch those, but if the mailinglist +doesn't follow accepted conventions, this might +.I not +be +.IR enough ). +.Sx 6 +:0 h c +* !^FROM_DAEMON +* !^X-Loop: your@own.mail.address +| (formail \-r \-I"Precedence: junk" \e + \-A"X-Loop: your@own.mail.address" ; \e + echo "Mail received.") | $SENDMAIL \-t +.Ex +A more complicated autoreply recipe that implements the functional equivalent +of the well known +.BR vacation (1) +program. This recipe is based on the same principles as the last one (prevent +`ringing' mail). In addition to that however, it maintains a vacation database +by extracting the name of the sender and inserting it in the vacation.cache +file if the name was new (the vacation.cache file is maintained by formail +which will make sure that it always contains the most recent names, the size +of the file is limited to a maximum of approximately 8192 bytes). If the name +was new, an autoreply will be sent. +.PP +As you can see, the following recipe has comments +.B between +the conditions. +This is allowed. Do +.B not +put comments on the same line as a condition though. +.Sx 18 +SHELL=/bin/sh # only needed for older versions of procmail + +:0 Whc: vacation.lock + # Perform a quick check to see if the mail was addressed to us +* $^To:.*\e<$\eLOGNAME\e> + # Don't reply to daemons and mailinglists +* !^FROM_DAEMON + # Mail loops are evil +* !^X-Loop: your@own.mail.address +| formail \-rD 8192 vacation.cache + + :0 ehc # if the name was not in the cache + | (formail \-rI"Precedence: junk" \e + \-A"X-Loop: your@own.mail.address" ; \e + echo "I received your mail,"; \e + echo "but I won't be back until Monday."; \e + echo "-- "; cat $HOME/.signature \e + ) | $SENDMAIL \-oi \-t +.Ex +Store all messages concerning TeX in separate, unique filenames, in a directory +named texmail (this directory has to exist); there is no need to use lockfiles +in this case, so we won't. +.Sx 3 +:0 +* (^TO|^Subject:.*)TeX[^t] +texmail +.Ex +The same as above, except now we store the mails in numbered files (MH mail +folder). +.Sx 3 +:0 +* (^TO|^Subject:.*)TeX[^t] +texmail/. +.Ex +Or you could file the mail in several directory folders at the same time. +The following recipe will deliver the mail to two MH-folders and one +directory folder. It is actually only one file with two extra hardlinks. +.Sx 3 +:0 +* (^TO|^Subject:.*)TeX[^t] +texmail/. wordprocessing dtp/. +.Ex +Store all the messages about meetings in a folder that is in a directory +that changes every month. E.g. if it were January 1994, the folder +would have the name `94-01/meeting' and the locallockfile would be +`94-01/meeting.lock'. +.Sx 3 +:0: +* meeting +`date +%y-%m`/meeting +.Ex +The same as above, but, if the `94-01' directory wouldn't have existed, it +is created automatically: +.Sx 9 +MONTHFOLDER=`date +%y-%m` + +:0 Wic +* ? test ! \-d $MONTHFOLDER +| mkdir $MONTHFOLDER + +:0: +* meeting +${MONTHFOLDER}/meeting +.Ex +The same as above, but now by slightly different means: +.Sx 6 +MONTHFOLDER=`date +%y-%m` +DUMMY=`test \-d $MONTHFOLDER || mkdir $MONTHFOLDER` + +:0: +* meeting +${MONTHFOLDER}/meeting +.Ex +If you are subscribed to several mailinglists and people cross-post to +some of them, you usually receive several duplicate mails (one from every +list). The following simple recipe eliminates duplicate mails. It tells +formail to keep an 8KB cache file in which it will store the Message-IDs of +the most recent mails you received. Since Message-IDs are guaranteed to +be unique for every new mail, they are ideally suited to weed out duplicate +mails. Simply put the following recipe at the top of your rcfile, and +no duplicate mail will get past it. +.Sx 2 +:0 Wh: msgid.lock +| formail \-D 8192 msgid.cache +.Ex +.B Beware +if you have delivery problems in recipes below this one and procmail tries +to requeue the mail, then on the next queue run, this mail will be considered +a duplicate and will be thrown away. For those not quite so confident in +their own scripting capabilities, you can use the following recipe instead. +It puts duplicates in a separate folder instead of throwing them away. +It is up to you to periodically empty the folder of course. +.Sx 5 +:0 Whc: msgid.lock +| formail \-D 8192 msgid.cache + +:0 a: +duplicates +.Ex +Procmail can deliver to MH folders directly, but, it does not update +the unseen sequences the real MH manages. If you want procmail to +update those as well, use a recipe like the following which will file +everything that contains the word spam in the body of the mail into an +MH folder called spamfold. Note the local lockfile, which is needed +because MH programs do not lock the sequences file. Asynchronous +invocations of MH programs that change the sequences file may therefore +corrupt it or silently lose changes. Unfortunately, the lockfile +doesn't completely solve the problem as rcvstore could be invoked while +`show' or `mark' or some other MH program is running. This problem is +expected to be fixed in some future version of MH, but until then, +you'll have to balance the risk of lost or corrupt sequences against +the benefits of the unseen sequence. +.Sx 3 +:0 :spamfold/$LOCKEXT +* B ?? spam +| rcvstore +spamfold +.Ex +When delivering to emacs folders (i.e., mailfolders managed by any emacs +mail package, e.g., RMAIL or VM) directly, you should use emacs-compatible +lockfiles. The emacs mailers are a bit braindamaged in that respect, they get +very upset if someone delivers to mailfolders which they already have in their +internal buffers. The following recipe assumes that $HOME equals /home/john. +.Sx 5 +MAILDIR=Mail + +:0:/usr/local/lib/emacs/lock/!home!john!Mail!mailbox +* ^Subject:.*whatever +mailbox +.Ex +Alternatively, you can have procmail deliver into its own set of mailboxes, +which you then periodically empty and copy over to your emacs files using +.BR movemail . +Movemail uses mailbox.lock local lockfiles per mailbox. This actually is +the preferred mode of operation in conjunction with procmail. +.PP +To extract certain headers from a mail and put them into environment +variables you can use any of the following constructs: +.Sx 5 +SUBJECT=`formail \-xSubject:` # regular field +FROM=`formail \-rt \-xTo:` # special case + +:0 h # alternate method +KEYWORDS=| formail \-xKeywords: +.Ex +If you are using temporary files in a procmailrc file, and want to make +sure that they are removed just before procmail exits, you could use +something along the lines of: +.Sx 2 +TEMPORARY=$HOME/tmp/pmail.$$ +TRAP="/bin/rm \-f $TEMPORARY" +.Ex +The TRAP keyword can also be used to change the exitcode of procmail. +I.e. if you want procmail to return an exitcode of `1' instead of its +regular exitcodes, you could use: +.Sx 3 +EXITCODE="" +TRAP="exit 1;" # The trailing semi-colon is important + # since exit is not a standalone program +.Ex +Or, if the exitcode does not need to depend on the programs run from +the TRAP, you can use a mere: +.Sx 1 +EXITCODE=1 +.Ex +The following recipe prints every incoming mail that looks like a postscript +file. +.Sx 3 +:0 Bb +* ^^%! +| lpr +.Ex +The following recipe does the same, but is a bit more selective. It only +prints the postscript file if it comes from the print-server. The first +condition matches only if it is found in the header. The second condition +only matches at the start of the body. +.Sx 4 +:0 b +* ^From[ :].*print-server +* B ?? ^^%! +| lpr +.Ex +The same as above, but now by slightly different means: +.Sx 7 +:0 +* ^From[ :].*print-server +{ + :0 B b + * ^^%! + | lpr +} +.Ex +Likewise: +.Sx 4 +:0 HB b +* ^^(.+$)*From[ :].*print-server +* ^^(.+$)*^%! +| lpr +.Ex +Suppose you have two accounts, you use both accounts regularly, but they are +in very distinct places (i.e., you can only read mail that arrived at either one +of the accounts). You would like to forward mail arriving at account one to +account two, and the other way around. The first thing that comes to mind is +using .forward files at both sites; this won't work of course, since you will +be creating a mail loop. This mail loop can be avoided by inserting the +following recipe in front of all other recipes in the $HOME/.procmailrc files on +both sites. If you make sure that you add the same X-Loop: field at both +sites, mail can now safely be forwarded to the other account from either of +them. +.Sx 4 +:0 c +* !^X-Loop: yourname@your.main.mail.address +| formail \-A "X-Loop: yourname@your.main.mail.address" | \e + $SENDMAIL \-oi yourname@the.other.account +.Ex +If someone sends you a mail with the word `retrieve' in the subject, the +following will automatically send back the contents of info_file to the +sender. Like in all recipes where we send mail, we watch out for mail +loops. +.Sx 6 +:0 +* !^From +YOUR_USERNAME +* !^Subject:.*Re: +* !^FROM_DAEMON +* ^Subject:.*retrieve +| (formail \-r ; cat info_file) | $SENDMAIL \-oi \-t +.Ex +Now follows an example for a very simple fileserver accessible by mail. +For more demanding applications, I suggest you take a look at +.B SmartList +(available from the same place as the procmail distribution). +As listed, this fileserver sends back at most one file per request, it +ignores the body of incoming mails, the Subject: line has to look +like "Subject: send file the_file_you_want" (the blanks are significant), +it does not return files that have names starting with a dot, nor does +it allow files to be retrieved that are outside the fileserver directory +tree (if you decide to munge this example, make sure you do not inadvertently +loosen this last restriction). +.Sx 18 +:0 +* ^Subject: send file [0-9a-z] +* !^X-Loop: yourname@your.main.mail.address +* !^Subject:.*Re: +* !^FROM_DAEMON +* !^Subject: send file .*[/.]\e. +{ + MAILDIR=$HOME/fileserver # chdir to the fileserver directory + + :0 fhw # reverse mailheader and extract name + * ^Subject: send file \e/[^ ]* + | formail \-rA "X-Loop: yourname@your.main.mail.address" + + FILE="$MATCH" # the requested filename + + :0 ah + | cat \- ./$FILE 2>&1 | $SENDMAIL \-oi \-t +} +.Ex +The following example preconverts all plain-text mail arriving in certain +encoded MIME formats into a more compact 8-bit format which can be used +and displayed more easily by most programs. The +.BR mimencode (1) +program is part of Nathaniel Borenstein's metamail package. +.Sx 17 +:0 +* ^Content-Type: *text/plain +{ + :0 fbw + * ^Content-Transfer-Encoding: *quoted-printable + | mimencode \-u \-q + + :0 Afhw + | formail \-I "Content-Transfer-Encoding: 8bit" + + :0 fbw + * ^Content-Transfer-Encoding: *base64 + | mimencode \-u \-b + + :0 Afhw + | formail \-I "Content-Transfer-Encoding: 8bit" +} +.Ex +The following one is rather exotic, but it only serves to demonstrate a +feature. Suppose you have a file in your HOME directory called ".urgent", +and the (one) person named in that file is the sender of an incoming mail, +you'd like that mail to be stored in $MAILDIR/urgent instead of in any of the +normal mailfolders it would have been sorted in. Then this is what you could +do (beware, the filelength of $HOME/.urgent should be well below $LINEBUF, +increase LINEBUF if necessary): +.Sx 5 +URGMATCH=`cat $HOME/.urgent` + +:0: +* $^From.*${URGMATCH} +urgent +.Ex +An entirely different application for procmail would be to conditionally +apply filters to a certain (outgoing) text or mail. A typical example +would be a filter through which you pipe all outgoing mail, in order +to make sure that it will be MIME encoded only if it needs to be. +I.e. in this case you could start procmail in the middle of a pipe like: +.Sx 1 +cat newtext | procmail ./mimeconvert | mail chris@where.ever +.Ex +The +.B mimeconvert +rcfile could contain something like (the =0x80= and =0xff= should +be substituted with the real 8-bit characters): +.Sx 10 +DEFAULT=| # pipe to stdout instead of + # delivering mail as usual +:0 Bfbw +* [=0x80=-=0xff=] +| mimencode \-q + + :0 Afhw + | formail \-I 'MIME-Version: 1.0' \e + \-I 'Content-Type: text/plain; charset=ISO-8859-1' \e + \-I 'Content-Transfer-Encoding: quoted-printable' +.Ex +.SH "SEE ALSO" +.na +.nh +.BR procmail (1), +.BR procmailrc (5), +.BR procmailsc (5), +.BR sh (1), +.BR csh (1), +.BR mail (1), +.BR mailx (1), +.BR uucp (1), +.BR aliases (5), +.BR sendmail (8), +.BR egrep (1), +.BR grep (1), +.BR biff (1), +.BR comsat (8), +.BR mimencode (1), +.BR lockfile (1), +.BR formail (1) +.hy +.ad +.SH AUTHORS +Stephen R. van den Berg +.RS + +.RE +.\".if n .pl -(\n(.tu-1i) +.rm SH +.rn Sh SH +.rm SS +.rn Ss SS +.rm TP +.rn Tp TP +.rm RS +.rn Rs RS +.rm RE +.rn Re RE diff --git a/upstream/fedora-40/man5/procmailrc.5 b/upstream/fedora-40/man5/procmailrc.5 new file mode 100644 index 00000000..0c745215 --- /dev/null +++ b/upstream/fedora-40/man5/procmailrc.5 @@ -0,0 +1,929 @@ +.\"if n .pl +(135i-\n(.pu) +.de Id +.ds Rv \\$3 +.ds Dt \\$4 +.. +.Id $Id$ +.TH PROCMAILRC 5 \*(Dt BuGless +.rn SH Sh +.de SH +.br +.ne 11 +.Sh "\\$1" +.. +.rn SS Ss +.de SS +.br +.ne 10 +.Ss "\\$1" +.. +.rn TP Tp +.de TP +.br +.ne 9 +.Tp \\$1 +.. +.rn RS Rs +.de RS +.na +.nf +.Rs +.. +.rn RE Re +.de RE +.Re +.fi +.ad +.. +.de Sx +.PP +.ne \\$1 +.RS +.. +.de Ex +.RE +.PP +.. +.na +.SH NAME +procmailrc \- procmail rcfile +.SH SYNOPSIS +.B $HOME/.procmailrc +.ad +.SH DESCRIPTION +For a quick start, see +.B NOTES +at the end of the +.BR procmail (1) +man page. +.PP +The rcfile can contain a mixture of environment variable assignments (some +of which have special meanings to procmail), and recipes. In their most +simple appearance, the recipes are simply one line regular expressions +that are searched for in the header of the arriving mail. The first recipe +that matches is used to determine where the mail has to go (usually a file). +If processing falls off the end of the rcfile, procmail will deliver the mail +to +.BR $DEFAULT . +.PP +There are two kinds of recipes: delivering and non-delivering recipes. +If a +.I delivering recipe +is found to match, procmail considers the mail (you guessed it) delivered and +will +.I cease processing +the rcfile after having successfully executed the action line of the recipe. +If a +.I non-delivering recipe +is found to match, processing of the rcfile will +.I continue +after the action line of this recipe has been executed. +.PP +Delivering recipes are those that cause header and/or body of the mail to +be: written into a file, absorbed by a program or forwarded to a mailaddress. +.PP +Non-delivering recipes are: those that cause the output of a program or +filter to be captured back by procmail or those that start a nesting block. +.PP +You can tell procmail to treat a +.I delivering recipe +as if it were a non-delivering recipe by specifying the `c' flag on +such a recipe. This will make procmail generate a +.I carbon copy +of the mail by delivering it to this recipe, yet continue processing the +rcfile. +.PP +By using any number of recipes you can presort your mail extremely +straightforward into several mailfolders. Bear in mind though that the mail +can arrive concurrently in these mailfolders (if several procmail programs +happen to run at the same time, not unlikely if a lot of mail arrives). To +make sure this does not result in a mess, proper use of lockfiles is highly +recommended. +.PP +The environment variable +.B assignments +and +.B recipes +can be freely intermixed in the rcfile. If any environment variable has +a special meaning to procmail, it will be used appropriately the moment +it is parsed (i.e., you can change the current directory whenever you +want by specifying a new +.BR MAILDIR , +switch lockfiles by specifying a new +.BR LOCKFILE , +change the umask at any time, etc., the possibilities are endless :\-). +.PP +The assignments and substitutions of these environment variables are handled +exactly like in +.BR sh (1) +(that includes all possible quotes and escapes), +with the added bonus that blanks around the '=' sign are ignored and that, +if an environment variable appears without a trailing '=', it will be +removed from the environment. Any program in backquotes started by procmail +will have the entire mail at its stdin. +.PP +.SS Comments +A word beginning with # and all the following characters up to a NEWLINE +are ignored. This does not apply to condition lines, which cannot be +commented. +.SS Recipes +.PP +A line starting with ':' marks the beginning of a recipe. It has the +following format: +.Sx 3 +:0 [\fIflags\fP] [ : [\fIlocallockfile\fP] ] + + +.Ex +Conditions start with a leading `*', everything after that character +is passed on to the internal egrep +.BR literally , +except for leading and trailing whitespace. +These regular expressions are +.B completely +compatible to the normal +.BR egrep (1) +extended regular expressions. See also +.BR "Extended regular expressions" . +.PP +Conditions are anded; if there are no conditions the result will be true +by default. +.PP +.I Flags +can be any of the following: +.TP 0.5i +.B H +Egrep the header (default). +.TP +.B B +Egrep the body. +.TP +.B D +Tell the internal egrep to distinguish between upper and lower case (contrary +to the default which is to ignore case). +.TP +.B A +This recipe will not be executed unless the conditions on the last preceding +recipe (on the current block-nesting level) without the `A' or +`a' flag matched as well. This allows you to chain actions +that depend on a common condition. +.TP +.B a +Has the same meaning as the `A' flag, with the additional +condition that the immediately preceding recipe must have been +.I successfully +completed before this recipe is executed. +.TP +.B E +This recipe only executes if the immediately preceding recipe was not +executed. Execution of this recipe also disables any immediately +following recipes with the 'E' flag. This allows you to specify +`else if' actions. +.TP +.B e +This recipe only executes if the immediately preceding recipe +.IR failed +(i.e., the action line was attempted, but resulted in an error). +.TP +.B h +Feed the header to the pipe, file or mail destination (default). +.TP +.B b +Feed the body to the pipe, file or mail destination (default). +.TP +.B f +Consider the pipe as a filter. +.TP +.B c +Generate a +.B carbon copy +of this mail. This only makes sense on +.I delivering +recipes. The only non-delivering recipe this flag has an effect on is +on a nesting block, in order to generate a carbon copy this will +.B clone +the running procmail process (lockfiles will not be inherited), whereby +the clone will proceed as usual and the parent will jump across the block. +.TP +.B w +Wait for the filter or program to finish and check its exitcode (normally +ignored); if the filter is unsuccessful, then the text will not have been +filtered. +.TP +.B W +Has the same meaning as the `w' flag, but will suppress any +`Program failure' message. +.TP +.B i +Ignore any write errors on this recipe (i.e., usually due to an early closed +pipe). +.TP +.B r +Raw mode, do not try to ensure the mail ends with an empty line, write +it out as is. +.PP +There are some special conditions you can use that are not straight regular +expressions. To select them, the condition must start with: +.TP 0.5i +.B ! +Invert the condition. +.TP +.B $ +Evaluate the remainder of this condition according to +.BR sh (1) +substitution rules inside double quotes, skip leading whitespace, +then reparse it. +.TP +.B ? +Use the exitcode of the specified program. +.TP +.B < +Check if the total length of the mail is shorter than the specified (in +decimal) number of bytes. +.TP +.B > +Analogous to '<'. +.TP +.B "variablename \fI??\fP" +Match the remainder of this condition against the value of this environment +variable (which cannot be a pseudo variable). A special case is if +variablename is equal to `B', `H', `HB' or `BH'; this merely overrides the +default header/body search area defined by the initial flags on this recipe. +.TP +.B \e +To quote any of the above at the start of the line. +.SS "Local lockfile" +.PP +If you put a second (trailing) ':' on the first recipe line, then procmail +will use a +.I locallockfile +(for this recipe only). You can optionally specify the locallockfile +to use; if you don't however, procmail will use the destination filename +(or the filename following the first '>>') and will append $LOCKEXT to it. +.SS "Recipe action line" +.PP +The action line can start with the following characters: +.TP +.B ! +Forwards to all the specified mail addresses. +.TP +.B | +Starts the specified program, possibly in $SHELL if any +of the characters $SHELLMETAS are spotted. You can optionally prepend this +pipe symbol with +.IR variable= , +which will cause stdout of the program to be captured in the environment +.I variable +(procmail will +.B not +terminate processing the rcfile at this point). +If you specify just this pipe symbol, without any program, then procmail will +pipe the mail to stdout. +.TP +.B { +Followed by at least one space, tab or newline will mark the start of a +nesting block. Everything up till the next closing brace will depend on +the conditions specified for this recipe. Unlimited nesting is permitted. +The closing brace exists merely to delimit the block, it will +.I not +cause procmail to terminate in any way. If the end of a block is reached +processing will continue as usual after the block. +On a nesting block, the flags `H' and `B' only affect +the conditions leading up to the block, the flags `h' and +`b' have no effect whatsoever. +.PP +Anything else will be taken as a mailbox name (either a filename or a +directory, absolute or relative to the current directory (see MAILDIR)). +If it is a (possibly yet nonexistent) filename, the mail will be appended to +it. +.PP +If it is a directory, the mail will be delivered to a newly created, +guaranteed to be unique file named $MSGPREFIX* in the specified directory. +If the mailbox name ends in "/.", then this directory is +presumed to be an MH folder; i.e., procmail will use the next number it +finds available. If the mailbox name ends in "/", then this +directory is presumed to be a maildir folder; i.e., procmail will deliver +the message to a file in a subdirectory named "tmp" and rename it to be +inside a subdirectory named "new". If the mailbox is specified to be an MH +folder or maildir folder, procmail will create the necessary directories if +they don't exist, rather than treat the mailbox as a non-existent +filename. When procmail is delivering to directories, you can specify +multiple directories to deliver to (procmail will do so utilising +hardlinks). +.SS "Environment variable defaults" +.TP 2.2i +.B "LOGNAME, HOME and USER_SHELL" +Your (the recipient's) defaults +.TP +.B SHELL +\&/bin/sh +.TP +.B PATH +.na +\&$HOME/bin\h'-\w' 'u' :/bin\h'-\w' 'u' :/usr/bin\h'-\w' 'u' :/sbin\h'-\w' 'u' :/usr/sbin\h'-\w' 'u' :/usr/local/bin\h'-\w' 'u' :/usr/X11R6/bin +(Except +.ad +during the processing of an /etc/procmailrc file, when it will be set +to +.na +`\&/usr/local/bin\h'-\w' 'u' :/bin'.) +.ad +.TP +.B SHELLMETAS +\&&\h'-\w' 'u' |<>~;?*[ +.TP +.B SHELLFLAGS +\&-c +.TP +.BR ORGMAIL +\&/var/spool/mail/$LOGNAME +.br +(Unless +.B \-m +has been specified, in which case it is unset) +.TP +.B MAILDIR +\&$HOME +.br +(Unless the name of the first successfully opened rcfile starts with +`./' or if +.B \-m +has been specified, in which case it defaults to `.') +.TP +.B DEFAULT +\&$ORGMAIL +.TP +.B MSGPREFIX +\&msg. +.TP +.B SENDMAIL +\&/usr/sbin/sendmail +.TP +.B SENDMAILFLAGS +\&-oi +.TP +.B HOST +The current hostname +.TP +.B COMSAT +\&no +.br +(If an rcfile is specified on the command line) +.TP +.B PROCMAIL_VERSION +\&3.24 +.TP +.B LOCKEXT +\&.lock +.na +.PP +Other cleared or preset environment variables are IFS, ENV and PWD. +.ad +.PP +For security reasons, upon startup procmail will wipe out all environment variables that are suspected of modifying the behavior of the runtime linker. +.SS Environment +.PP +Before you get lost in the multitude of environment variables, keep in mind +that all of them have reasonable defaults. +.TP 1.2i +.B MAILDIR +Current directory while procmail is executing (that means that all paths +are relative to $MAILDIR). +.TP +.B DEFAULT +Default +.B mailbox +file (if not told otherwise, procmail will dump mail in this mailbox). +Procmail will automatically use $DEFAULT$LOCKEXT as lockfile prior to writing +to this mailbox. You do not need to set this variable, since it already +points to the standard system mailbox. +.TP +.B LOGFILE +This file will also contain any error or diagnostic messages from procmail +(normally none :\-) or any other programs started by procmail. If this file +is not specified, any diagnostics or error messages will +be mailed back to the sender. +See also +.BR LOGABSTRACT . +.TP +.B VERBOSE +You can turn on +.I extended diagnostics +by setting this variable to `yes' or `on', to turn it off again set it to `no' +or `off'. +.TP +.B LOGABSTRACT +Just before procmail exits it logs an abstract of the delivered message in +$LOGFILE showing the `From ' and `Subject:' fields of the header, what folder +it finally went to and how long (in bytes) the message was. By setting this +variable to `no', generation of this abstract is suppressed. If you set +it to `all', procmail will log an abstract for every successful +.I delivering recipe +it processes. +.TP +.B LOG +Anything assigned to this variable will be appended to $LOGFILE. +.TP +.B ORGMAIL +Usually the system mailbox (\fBOR\fPi\fBG\fPinal \fBMAIL\fPbox). If, for +some obscure reason (like `\fBfilesystem full\fP') the mail could not be +delivered, then this mailbox will be the last resort. If procmail +fails to save the mail in here (deep, deep trouble :\-), then the mail +will bounce back to the sender. +.TP +.B LOCKFILE +Global semaphore file. If this file already exists, procmail +will wait until it has gone before proceeding, and will create it itself +(cleaning it up when ready, of course). If more than one +.I lockfile +are specified, then the previous one will be removed before trying to create +the new one. The use of a global lockfile is discouraged, whenever possible +use locallockfiles (on a per recipe basis) instead. +.TP +.B LOCKEXT +Default extension that is appended to a destination file to determine +what local +.I lockfile +to use (only if turned on, on a per-recipe basis). +.TP +.B LOCKSLEEP +Number of seconds procmail will sleep before retrying on a +.I lockfile +(if it already existed); if not specified, it defaults to 8 +seconds. +.TP +.B LOCKTIMEOUT +Number of seconds that have to have passed since a +.I lockfile +was last modified/created before procmail decides that this must be an +erroneously leftover lockfile that can be removed by force now. If zero, +then no timeout will be used and procmail will wait forever until the +lockfile is removed; if not specified, it defaults to 1024 seconds. +This variable is useful to prevent indefinite hangups of +.BR sendmail /procmail. +Procmail is immune to clock skew across machines. +.TP +.B TIMEOUT +Number of seconds that have to have passed before procmail decides that +some child it started must be hanging. The offending program will receive +a TERMINATE signal from procmail, and processing of the rcfile will continue. +If zero, then no timeout will be used and procmail will wait forever until the +child has terminated; if not specified, it defaults to 960 seconds. +.TP +.B MSGPREFIX +Filename prefix that is used when delivering to a directory (not used when +delivering to a maildir or an MH directory). +.TP +.B HOST +If this is not the +.I hostname +of the machine, processing of the current +.I rcfile +will immediately cease. If other rcfiles were specified on the +command line, processing will continue with the next one. If all rcfiles +are exhausted, the program will terminate, but will not generate an error +(i.e., to the mailer it will seem that the mail has been delivered). +.TP +.B UMASK +The name says it all (if it doesn't, then forget about this one :\-). +Anything assigned to UMASK is taken as an +.B octal +number. If not specified, the umask defaults to 077. If the umask +permits o+x, all the mailboxes procmail delivers to directly will receive +an o+x mode change. This can be used to check if new mail arrived. +.TP +.B SHELLMETAS +If any of the characters in SHELLMETAS appears in the line specifying +a filter or program, the line will be fed to $SHELL +instead of being executed directly. +.TP +.B SHELLFLAGS +Any invocation of $SHELL will be like: +.br +"$SHELL" "$SHELLFLAGS" "$*"; +.TP +.B SENDMAIL +If you're not using the +.I forwarding +facility don't worry about this one. It specifies the program being +called to forward any mail. +.br +It gets invoked as: "$SENDMAIL" $SENDMAILFLAGS "$@"; +.TP +.B NORESRETRY +Number of retries that are to be made if any `\fBprocess table full\fP', +`\fBfile table full\fP', `\fBout of memory\fP' or +`\fBout of swap space\fP' error should occur. If this number is negative, +then procmail will retry indefinitely; if not specified, it defaults to +4 times. The retries occur with a $SUSPEND second interval. The +idea behind this is that if, e.g., the +.I swap +.I space +has been exhausted or the +.I process +.I table +is full, usually several other programs will either detect this as well +and abort or crash 8\-), thereby freeing valuable +.I resources +for procmail. +.TP +.B SUSPEND +Number of seconds that procmail will pause if it has to wait for something +that is currently unavailable (memory, fork, etc.); if not specified, it will +default to 16 seconds. See also: +.BR LOCKSLEEP . +.TP +.B LINEBUF +Length of the internal line buffers, cannot be set smaller than 128. +All lines read from the +.I rcfile +should not exceed $LINEBUF characters before and after expansion. If not +specified, it defaults to 2048. This limit, of course, does +.I not +apply to the mail itself, which can have arbitrary line lengths, or could +be a binary file for that matter. See also PROCMAIL_OVERFLOW. +.TP +.B DELIVERED +If set to `yes' procmail will pretend (to the mail agent) the mail +has been delivered. If mail cannot be delivered after having met this +assignment (set to `yes'), the mail will be lost (i.e., it will not bounce). +.TP +.B TRAP +When procmail terminates of its own accord and not because it +received a signal, it will execute the contents of this variable. +A copy of the mail can be read from stdin. Any output produced by this +command will be appended to $LOGFILE. Possible uses for TRAP are: removal +of temporary files, logging customised abstracts, etc. See also +.B EXITCODE +and +.BR LOGABSTRACT . +.TP +.B EXITCODE +By default, procmail returns an exitcode of zero (success) if it +successfully delivered the message or if the +.B HOST +variable was misset and there were no more rcfiles on the command +line; otherwise it returns failure. Before doing so, procmail +examines the value of this variable. If it is set to a positive +numeric value, procmail will instead use that value as its exitcode. +If this variable is set but empty and +.B TRAP +is set, procmail will set the exitcode to whatever the +.B TRAP +program returns. If this variable is not set, procmail will set +it shortly before calling up the +.B TRAP +program. +.TP +.B LASTFOLDER +This variable is assigned to by procmail whenever it is delivering +to a folder or program. It always contains the name of the last file +(or program) procmail delivered to. If the last delivery was to +several directory folders together then $LASTFOLDER will contain +the hardlinked filenames as a space separated list. +.TP +.B MATCH +This variable is assigned to by procmail whenever it is told to extract +text from a matching regular expression. It will contain all text +matching the regular expression past the `\fB\e/\fP' token. +.TP +.B SHIFT +Assigning a positive value to this variable has the same effect as +the `shift' command in +.BR sh (1). +This command is most useful to extract extra arguments passed to procmail +when acting as a generic mailfilter. +.TP +.B INCLUDERC +Names an rcfile (relative to the current directory) which will be +included here as if it were part of the current rcfile. Nesting is +permitted and only limited by systems resources (memory and file +descriptors). As no checking is done on the permissions or ownership +of the rcfile, users of +.B INCLUDERC +should make sure that only trusted users have write access to the included +rcfile or the directory it is in. Command line assignments to +.B INCLUDERC +have no effect. +.TP +.B SWITCHRC +Names an rcfile (relative to the current directory) to which processing +will be switched. If the named rcfile doesn't exist or is not a normal +file or /dev/null then an error will be logged and processing will +continue in the current rcfile. Otherwise, processing of the current +rcfile will be aborted and the named rcfile started. Unsetting +.B SWITCHRC +aborts processing of the current rcfile as if it had ended at the +assignment. As with +.BR INCLUDERC , +no checking is done on the permissions or ownership of the rcfile +and command line assignments have no effect. +.TP +.B PROCMAIL_VERSION +The version number of the running procmail binary. +.TP +.B PROCMAIL_OVERFLOW +This variable will be set to a non-empty value if procmail detects a +buffer overflow. See the +.B BUGS +section below for other details of operation when overflow occurs. +.TP +.B COMSAT +.BR Comsat (8)/ biff (1) +notification is on by default, it can be turned off by setting this variable +to `no'. Alternatively the biff-service can be customised by setting it to +either `service@', `@hostname', or +`service@hostname'. When not specified it defaults +to biff@localhost. +.TP +.B DROPPRIVS +If set to `yes' procmail will drop all privileges it might have had (suid or sgid). This is only useful if you want to guarantee that the bottom half of the /etc/procmailrc file is executed on behalf of the recipient. +.SS "Extended regular expressions" +The following tokens are known to both the procmail internal egrep and the +standard +.BR egrep (1) +(beware that some egrep implementations include other non-standard +extensions; in particular, the repetition operator +.B { +is not supported by procmail's egrep): +.TP 1.0i +.B ^ +Start of a line. +.TP +.B $ +End of a line. +.TP +.B . +Any character except a newline. +.TP +.B a* +Any sequence of zero or more a's. +.TP +.B a+ +Any sequence of one or more a's. +.TP +.B a? +Either zero or one a. +.TP +.B [^-a-d] +Any character which is +.B not +either a dash, a, b, c, d or newline. +.TP +.B de|abc +Either the sequence `de' or `abc'. +.TP +.B (abc)* +Zero or more times the sequence `abc'. +.TP +.B \e. +Matches a single dot; use \e to quote any of the magic characters to get +rid of their special meaning. See also $\e variable substitution. +.PP +These were only samples, of course, any more complex combination is valid +as well. +.PP +The following token meanings are special procmail extensions: +.TP 1.0i +\fB^\fP or \fB$\fP +Match a newline (for multiline matches). +.TP +.B ^^ +Anchor the expression at the very start of the search area, or if encountered +at the end of the expression, anchor it at the very end of the search area. +.TP +\fB\e<\fP or \fB\e>\fP +Match the character before or after a word. They are merely a shorthand +for `[^a-zA-Z0-9_]', but can also match newlines. +Since they match actual characters, they are only suitable to delimit +words, not to delimit inter-word space. +.TP +.B \e/ +Splits the expression in two parts. Everything matching the right part +will be assigned to the MATCH environment variable. +.SH EXAMPLES +Look in the +.BR procmailex (5) +man page. +.SH CAVEATS +Continued lines in an action line that specifies a program always have to end +in a backslash, even if the underlying shell would not need or want the +backslash to indicate continuation. This is due to the two pass parsing +process needed (first procmail, then the shell (or not, depending on +.BR SHELLMETAS )). +.PP +Don't put comments on the regular expression condition lines in a +recipe, these lines are fed to the internal egrep +.I literally +(except for continuation backslashes at the end of a line). +.PP +Leading whitespace on continued regular expression condition lines +is usually ignored (so that they can be indented), but +.B not +on continued condition lines that are evaluated according to the +.BR sh (1) +substitution rules inside double quotes. +.PP +Watch out for deadlocks when doing unhealthy things like forwarding mail +to your own account. Deadlocks can be broken by proper use of +.BR LOCKTIMEOUT . +.PP +Any default values that procmail has for some environment variables will +.B always +override the ones that were already defined. If you really want to +override the defaults, you either have to put them in the +.B rcfile +or on the command line as arguments. +.PP +The /etc/procmailrc file cannot change the PATH setting seen by user rcfiles +as the value is reset when procmail finishes the /etc/procmailrc file. While +future enhancements are expected in this area, recompiling procmail +with the desired value is currently the only correct solution. +.PP +Environment variables set +.B inside +the shell-interpreted-`|' action part of a recipe will +.B not +retain their value after the recipe has finished since they are set in a +subshell of procmail. To make sure the value of an environment variable is +retained you have to put the assignment to the variable before the leading `|' +of a recipe, so that it can capture stdout of the program. +.PP +If you specify only a `h' or a `b' flag on a delivering +recipe, and the recipe matches, then, unless the `c' flag is +present as well, the body respectively the header of the mail will be silently +lost. +.SH "SEE ALSO" +.na +.nh +.BR procmail (1), +.BR procmailsc (5), +.BR procmailex (5), +.BR sh (1), +.BR csh (1), +.BR mail (1), +.BR mailx (1), +.BR uucp (1), +.BR aliases (5), +.BR sendmail (8), +.BR egrep (1), +.BR regexp (5), +.BR grep (1), +.BR biff (1), +.BR comsat (8), +.BR lockfile (1), +.BR formail (1) +.hy +.ad +.SH BUGS +The only substitutions of environment variables that can be handled by +procmail itself are of the type $name, ${name}, ${name:-text}, ${name:+text}, +${name-text}, ${name+text}, $\ename, $#, $n, $$, $?, $_, $\- and $=; +whereby $\ename will be substituted by the +all-magic-regular-expression-characters-disarmed +equivalent of $name, $_ by the name of the current rcfile, $\- by +$LASTFOLDER and $= will contain the score of the last recipe. +Furthermore, the result of $\ename substitution will never be split on +whitespace. When the +.B \-a +or +.B \-m +options are used, $# will expand to the number of arguments so +specified and "$@" (the quotes are required) will expand to the +specified arguments. However, "$@" will only be expanded when +used in the argument list to a program, and +then only one such occurrence will be expanded. +.PP +Unquoted variable expansions performed by procmail are always split on +space, tab, and newline characters; the IFS variable is not used internally. +.PP +Procmail does not support the expansion of `~'. +.PP +A line buffer of length $LINEBUF is used when processing the +.IR rcfile , +any expansions that don't fit within this limit will be truncated and +PROCMAIL_OVERFLOW will be set. If the overflowing line is a condition +or an action line, then it will be considered failed and procmail will +continue processing. If it is a variable assignment or recipe start +line then procmail will abort the entire rcfile. +.PP +If the global lockfile has a +.I relative +path, and the current directory +is not the same as when the global lockfile was created, then the global +lockfile will not be removed if procmail exits at that point (remedy: +use +.I absolute +paths to specify global lockfiles). +.PP +If an rcfile has a +.I relative +path and when the rcfile is first opened +.B MAILDIR +contains a relative path, and if at one point procmail is instructed to +clone itself and the current directory has changed since the rcfile was +opened, then procmail will not be able to clone itself (remedy: use an +.I absolute +path to reference the rcfile or make sure MAILDIR contains an absolute +path as the rcfile is opened). +.PP +A locallockfile on the recipe that marks the start of a non-forking nested +block does not work as expected. +.PP +When capturing stdout from a recipe into an environment variable, exactly +one trailing newline will be stripped. +.PP +Some non-optimal and non-obvious regexps set MATCH to an incorrect +value. The regexp can be made to work by removing one or more unneeded +\&'*', '+', or '?' operators on the left-hand side of the \e/ token. +.SH MISCELLANEOUS +If the regular expression contains `\fB^TO_\fP' it will be substituted by +.na +.nh +`\fB(^((Original-)?(Resent-)?(To\h'-\w' 'u' |Cc\h'-\w' 'u' |Bcc)\h'-\w' 'u' |(X-Envelope\h'-\w' 'u' |Apparently(-Resent)?)-To)\h'-\w' 'u' :(.*[^-a-zA-Z0-9_.])?)\fP', +which should catch all destination specifications containing a specific +.IR address . +.hy +.ad +.PP +If the regular expression contains `\fB^TO\fP' it will be substituted by +.na +.nh +`\fB(^((Original-)?(Resent-)?(To\h'-\w' 'u' |Cc\h'-\w' 'u' |Bcc)\h'-\w' 'u' |(X-Envelope\h'-\w' 'u' |Apparently(-Resent)?)-To)\h'-\w' 'u' :(.*[^a-zA-Z])?)\fP', +which should catch all destination specifications containing a specific +.IR word . +.hy +.ad +.PP +If the regular expression contains `\fB^FROM_DAEMON\fP' it will be +substituted by +.na +.nh +`\fB(^(Mailing-List\h'-\w' 'u' :\h'-\w' 'u' |Precedence\h'-\w' 'u' :.*(junk\h'-\w' 'u' |bulk\h'-\w' 'u' |list)\h'-\w' 'u' |To\h'-\w' 'u' : Multiple recipients of |(((Resent-)?(From\h'-\w' 'u' |Sender)\h'-\w' 'u' |X-Envelope-From)\h'-\w' 'u' :\h'-\w' 'u' |>?From )([^>]*[^(.%@a-z0-9])?(Post(ma?(st(e?r)?\h'-\w' 'u' |n)\h'-\w' 'u' |office)\h'-\w' 'u' |(send)?Mail(er)?\h'-\w' 'u' |daemon\h'-\w' 'u' |m(mdf\h'-\w' 'u' |ajordomo)\h'-\w' 'u' |n?uucp\h'-\w' 'u' |LIST(SERV\h'-\w' 'u' |proc)\h'-\w' 'u' |NETSERV\h'-\w' 'u' |o(wner\h'-\w' 'u' |ps)\h'-\w' 'u' |r(e(quest\h'-\w' 'u' |sponse)\h'-\w' 'u' |oot)\h'-\w' 'u' |b(ounce\h'-\w' 'u' |bs\e.smtp)\h'-\w' 'u' |echo\h'-\w' 'u' |mirror\h'-\w' 'u' |s(erv(ices?\h'-\w' 'u' |er)\h'-\w' 'u' |mtp(error)?\h'-\w' 'u' |ystem)\h'-\w' 'u' |A(dmin(istrator)?\h'-\w' 'u' |MMGR\h'-\w' 'u' |utoanswer))(([^).!\h'-\w' 'u' :a-z0-9][-_a-z0-9]*)?[%@>\\t ][^<)]*(\e(.*\e).*)?)?$([^>]\h'-\w' 'u' |$)))\fP', +which should catch mails coming from most daemons (how's that for a regular +expression :\-). +.hy +.ad +.PP +If the regular expression contains `\fB^FROM_MAILER\fP' it will be +substituted by +.na +.nh +`\fB(^(((Resent-)?(From\h'-\w' 'u' |Sender)\h'-\w' 'u' |X-Envelope-From)\h'-\w' 'u' :\h'-\w' 'u' |>?From )([^>]*[^(.%@a-z0-9])?(Post(ma(st(er)?\h'-\w' 'u' |n)\h'-\w' 'u' |office)\h'-\w' 'u' |(send)?Mail(er)?\h'-\w' 'u' |daemon\h'-\w' 'u' |mmdf\h'-\w' 'u' |n?uucp\h'-\w' 'u' |ops\h'-\w' 'u' |r(esponse\h'-\w' 'u' |oot)\h'-\w' 'u' |(bbs\e.)?smtp(error)?\h'-\w' 'u' |s(erv(ices?\h'-\w' 'u' |er)\h'-\w' 'u' |ystem)\h'-\w' 'u' |A(dmin(istrator)?\h'-\w' 'u' |MMGR))(([^).!\h'-\w' 'u' :a-z0-9][-_a-z0-9]*)?[%@>\\t ][^<)]*(\e(.*\e).*)?)?$([^>]\h'-\w' 'u' |$))\fP' +(a stripped down version of `\fB^FROM_DAEMON\fP'), +which should catch mails coming from most mailer-daemons. +.hy +.ad +.PP +When assigning boolean values to variables like VERBOSE, DELIVERED or COMSAT, +procmail accepts as true every string starting with: a non-zero value, `on', +`y', `t' or `e'. False is every string starting with: a zero value, `off', +`n', `f' or `d'. +.PP +If the action line of a recipe specifies a program, a sole backslash-newline +pair in it on an otherwise empty line will be converted into a newline. +.PP +The regular expression engine built into procmail does not support named +character classes. +.SH NOTES +Since unquoted leading whitespace is generally ignored in the rcfile you can +indent everything to taste. +.PP +The leading `|' on the action line to specify a program or filter is stripped +before checking for $SHELLMETAS. +.PP +Files included with the INCLUDERC directive containing only environment +variable assignments can be shared with sh. +.PP +The current behavior of assignments on the command line to +.B INCLUDERC +and +.B SWITCHRC +is not guaranteed, has been changed once already, and may be changed +again or removed in future releases. +.PP +For +.I really +complicated processing you can even consider calling +.B procmail +recursively. +.PP +In the old days, the `:0' that marks the beginning of a recipe, had to +be changed to `:n', whereby `n' denotes the number of conditions that +follow. +.SH AUTHORS +Stephen R. van den Berg +.RS + +.RE +.\".if n .pl -(\n(.tu-1i) +.rm SH +.rn Sh SH +.rm SS +.rn Ss SS +.rm TP +.rn Tp TP +.rm RS +.rn Rs RS +.rm RE +.rn Re RE diff --git a/upstream/fedora-40/man5/procmailsc.5 b/upstream/fedora-40/man5/procmailsc.5 new file mode 100644 index 00000000..b3127609 --- /dev/null +++ b/upstream/fedora-40/man5/procmailsc.5 @@ -0,0 +1,324 @@ +.\"if n .pl +(135i-\n(.pu) +.de Id +.ds Rv \\$3 +.ds Dt \\$4 +.. +.Id $Id$ +.TH PROCMAILSC 5 \*(Dt BuGless +.rn SH Sh +.de SH +.br +.ne 11 +.Sh "\\$1" +.. +.rn SS Ss +.de SS +.br +.ne 10 +.Ss "\\$1" +.. +.rn TP Tp +.de TP +.br +.ne 9 +.Tp \\$1 +.. +.rn RS Rs +.de RS +.na +.nf +.Rs +.. +.rn RE Re +.de RE +.Re +.fi +.ad +.. +.de Sx +.PP +.ne \\$1 +.RS +.. +.de Ex +.RE +.PP +.. +.na +.SH NAME +procmailsc \- procmail weighted scoring technique +.SH SYNOPSIS +.RB [ * ] +.B "w^x condition" +.ad +.SH DESCRIPTION +In addition to the traditional true or false conditions you can specify +on a recipe, you can use a weighted scoring technique to decide if +a certain recipe matches or not. When weighted scoring is used in a +recipe, then the final score for that recipe must be positive for it +to match. + +A certain condition can contribute to the score if you allocate it +a `weight' +.RB ( w ) +and an `exponent' +.RB ( x ). +You do this by preceding the condition (on the same line) with: +.RS +.B w^x +.RE +Whereas both +.B w +and +.B x +are real numbers between -2147483647.0 and 2147483647.0 inclusive. + +.SH "Weighted regular expression conditions" +The first time the regular expression is found, it will add +.I w +to the score. The second time it is found, +.I w*x +will be added. The third time it is found, +.I w*x*x +will be added. The fourth time +.I w*x*x*x +will be added. And so forth. + +This can be described by the following concise formula: +.Sx 4 + n + n k\-1 x \- 1 +w * Sum x = w * \-\-\-\-\-\-\- + k=1 x \- 1 +.Ex +It represents the total added score for this condition if +.B n +matches are found. + +Note that the following case distinctions can be made: +.TP 8 +x=0 +Only the first match will contribute w to the score. Any subsequent +matches are ignored. +.TP +x=1 +Every match will contribute the same w to the score. The score grows +linearly with the number of matches found. +.TP +0 L +.Ex +will generate an additional score of: +.Sx 4 + x + / M \e +w * | \-\-\- | + \e L / +.Ex +And: +.Sx 1 +* w^x < L +.Ex +will generate an additional score of: +.Sx 4 + x + / L \e +w * | \-\-\- | + \e M / +.Ex +.PP +In both cases, if L=M, this will add w to the score. In the former case +however, larger mails will be favoured, in the latter case, smaller +mails will be favoured. Although x can be varied to fine-tune the +steepness of the function, typical usage sets x=1. +.SH MISCELLANEOUS +You can query the final score of all the conditions on a recipe from the +environment variable +.BR $= . +This variable is set +.I every +time just after procmail has parsed all conditions on a recipe (even if the +recipe is not being executed). +.SH EXAMPLES +The following recipe will ditch all mails having more than 150 lines in the +body. +The first condition contains an empty regular expression which, because +it always matches, is used to give our score a negative offset. +The second condition then matches every line in the mail, and consumes +up the previous negative offset we gave (one point per line). In the end, +the score will only be positive if the mail contained more than 150 lines. +.Sx 5 +:0 Bh +* \-150^0 +* 1^1 ^.*$ +/dev/null +.Ex +Suppose you have a priority folder which you always read first. The next +recipe picks out the priority mail and files them in this special folder. +The first condition is a regular one, i.e., it doesn't contribute to the +score, but simply has to be satisfied. The other conditions describe things +like: john and claire usually have something important to say, meetings +are usually important, replies are favoured a bit, mails about Elvis +(this is merely an example :\-) are favoured (the more he is mentioned, the +more the mail is favoured, but the maximum extra score due to Elvis will +be 4000, no matter how often he is mentioned), lots of quoted lines are +disliked, smileys are appreciated (the score for those will reach a maximum +of 3500), those three people usually don't send +interesting mails, the mails should preferably be small (e.g., 2000 bytes long +mails will score \-100, 4000 bytes long mails do \-800). +As you see, if some of the uninteresting people send mail, then the mail +still has a chance of landing in the priority folder, e.g., if it is about +a meeting, or if it contains at least two smileys. +.Sx 11 +:0 HB +* !^Precedence:.*(junk|bulk) +* 2000^0 ^From:.*(john@home|claire@work) +* 2000^0 ^Subject:.*meeting +* 300^0 ^Subject:.*Re: +* 1000^.75 elvis|presley +* \-100^1 ^> +* 350^.9 :\-\e) +* \-500^0 ^From:.*(boss|jane|henry)@work +* \-100^3 > 2000 +priority_folder +.Ex +If you are subscribed to a mailinglist, and just would like to read +the quality mails, then the following recipes could do the trick. +First we make sure that the mail is coming from the mailinglist. +Then we check if it is from certain persons of whom we value +the opinion, or about a subject we absolutely want to know everything +about. If it is, file it. Otherwise, check if the ratio of quoted lines +to original lines is at most 1:2. If it exceeds that, ditch the mail. +Everything that survived the previous test, is filed. +.Sx 15 +:0 +^From mailinglist-request@some.where +{ + :0: + * ^(From:.*(paula|bill)|Subject:.*skiing) + mailinglist + + :0 Bh + * 20^1 ^> + * \-10^1 ^[^>] + /dev/null + + :0: + mailinglist +} +.Ex +For further examples you should look in the +.BR procmailex (5) +man page. +.SH CAVEATS +Because this speeds up the search by an order of magnitude, +the procmail internal egrep will always search for the leftmost +.I shortest +match, unless it is determining what to assign to +.BR MATCH , +in which case it searches the leftmost +.I longest +match. +E.g. for the leftmost +.I shortest +match, by itself, the regular expression: +.TP +.B .* +will always match a zero length string at the same spot. +.TP +.B .+ +will always match one character (except newlines of course). +.SH "SEE ALSO" +.na +.nh +.BR procmail (1), +.BR procmailrc (5), +.BR procmailex (5), +.BR sh (1), +.BR csh (1), +.BR egrep (1), +.BR grep (1), +.hy +.ad +.SH BUGS +If, in a length condition, you specify an +.B x +that causes an overflow, procmail is at the mercy of the +.BR pow (3) +function in your mathematical library. +.PP +Floating point numbers in `engineering' format (e.g., 12e5) are not accepted. +.SH MISCELLANEOUS +As soon as `plus infinity' (2147483647) is reached, any subsequent +.I weighted +conditions will simply be skipped. +.PP +As soon as `minus infinity' (-2147483647) is reached, the condition will +be considered as `no match' and the recipe will terminate early. +.SH NOTES +If in a regular expression weighted formula +.BR 0 +.RE +.\".if n .pl -(\n(.tu-1i) +.rm SH +.rn Sh SH +.rm SS +.rn Ss SS +.rm TP +.rn Tp TP +.rm RS +.rn Rs RS +.rm RE +.rn Re RE diff --git a/upstream/fedora-40/man5/projects.5 b/upstream/fedora-40/man5/projects.5 new file mode 100644 index 00000000..68455403 --- /dev/null +++ b/upstream/fedora-40/man5/projects.5 @@ -0,0 +1,31 @@ +.TH projects 5 +.SH NAME +projects \- persistent project root definition +.SH DESCRIPTION +The +.I /etc/projects +file provides a mapping between numeric project identifiers and those directories +which are the roots of the quota tree. Its format is simply: + +.nf +.sp +.in +5 +# comments are hash-prefixed +# ... +10:/export/cage +42:/var/log +.in -5 +.fi +.PP +The +.I /etc/projects +file is optional, instead +.BR xfs_quota (8) +can be used with the +.B \-p +argument to specify a project root directly for each operation. + +.SH SEE ALSO +.BR xfs_quota (8), +.BR xfsctl (3), +.BR projid (5). diff --git a/upstream/fedora-40/man5/projid.5 b/upstream/fedora-40/man5/projid.5 new file mode 100644 index 00000000..c8ef71eb --- /dev/null +++ b/upstream/fedora-40/man5/projid.5 @@ -0,0 +1,29 @@ +.TH projid 5 +.SH NAME +projid \- the project name mapping file +.SH DESCRIPTION +The +.I /etc/projid +file provides a mapping between numeric project identifiers and a +simple human readable name (similar relationship to the one that +exists between usernames and uids). +Its format is simply: +.nf +.sp +.in +5 +# comments are hash-prefixed +# ... +cage:10 +logfiles:42 + +.in -5 +.fi +.PP + +This file is optional, if a project identifier cannot be mapped to +a name, it will be parsed and displayed as a numeric value. + +.SH SEE ALSO +.BR xfs_quota (8), +.BR xfsctl (3), +.BR projects (5). diff --git a/upstream/fedora-40/man5/protocols.5 b/upstream/fedora-40/man5/protocols.5 new file mode 100644 index 00000000..c30d0527 --- /dev/null +++ b/upstream/fedora-40/man5/protocols.5 @@ -0,0 +1,66 @@ +.\" Copyright (c) 1995 Martin Schulze +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1995-10-18 Martin Schulze +.\" * first released +.\" 2002-09-22 Seth W. Klein +.\" * protocol numbers are now assigned by the IANA +.\" +.TH protocols 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +protocols \- protocols definition file +.SH DESCRIPTION +This file is a plain ASCII file, describing the various DARPA internet +protocols that are available from the TCP/IP subsystem. +It should be +consulted instead of using the numbers in the ARPA include files, or, +even worse, just guessing them. +These numbers will occur in the +protocol field of any IP header. +.P +Keep this file untouched since changes would result in incorrect IP +packages. +Protocol numbers and names are specified by the IANA +(Internet Assigned Numbers Authority). +.\" .. by the DDN Network Information Center. +.P +Each line is of the following format: +.P +.RS +.I protocol number aliases ... +.RE +.P +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +If a line contains a hash mark (#), the hash mark and the part +of the line following it are ignored. +.P +The field descriptions are: +.TP +.I protocol +the native name for the protocol. +For example +.IR ip , +.IR tcp , +or +.IR udp . +.TP +.I number +the official number for this protocol as it will appear within the IP +header. +.TP +.I aliases +optional aliases for the protocol. +.P +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. +.SH FILES +.TP +.I /etc/protocols +The protocols definition file. +.SH SEE ALSO +.BR getprotoent (3) +.P +.UR http://www.iana.org\:/assignments\:/protocol\-numbers +.UE diff --git a/upstream/fedora-40/man5/pstore.conf.5 b/upstream/fedora-40/man5/pstore.conf.5 new file mode 100644 index 00000000..247722c9 --- /dev/null +++ b/upstream/fedora-40/man5/pstore.conf.5 @@ -0,0 +1,97 @@ +'\" t +.TH "PSTORE\&.CONF" "5" "" "systemd 255" "pstore.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pstore.conf, pstore.conf.d \- PStore configuration file +.SH "SYNOPSIS" +.PP +/etc/systemd/pstore\&.conf +/etc/systemd/pstore\&.conf\&.d/* +.SH "DESCRIPTION" +.PP +This file configures the behavior of +\fBsystemd-pstore\fR(8), a tool for archiving the contents of the persistent storage filesystem, +\m[blue]\fBpstore\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [PStore] section: +.PP +\fIStorage=\fR +.RS 4 +Controls where to archive (i\&.e\&. copy) files from the pstore filesystem\&. One of +"none", +"external", and +"journal"\&. When +"none", the tool exits without processing files in the pstore filesystem\&. When +"external" +(the default), files are archived into +/var/lib/systemd/pstore/, and logged into the journal\&. When +"journal", pstore file contents are logged only in the journal\&. +.sp +Added in version 243\&. +.RE +.PP +\fIUnlink=\fR +.RS 4 +Controls whether or not files are removed from pstore after processing\&. Takes a boolean value\&. When true, a pstore file is removed from the pstore once it has been archived (either to disk or into the journal)\&. When false, processing of pstore files occurs normally, but the files remain in the pstore\&. The default is true in order to maintain the pstore in a nearly empty state, so that the pstore has storage available for the next kernel error event\&. +.sp +Added in version 243\&. +.RE +.PP +The defaults for all values are listed as comments in the template +/etc/systemd/pstore\&.conf +file that is installed by default\&. +.SH "SEE ALSO" +.PP +\fBsystemd-journald.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +pstore +.RS 4 +\%https://docs.kernel.org/admin-guide/abi-testing.html#abi-sys-fs-pstore +.RE diff --git a/upstream/fedora-40/man5/rcsfile.5 b/upstream/fedora-40/man5/rcsfile.5 new file mode 100644 index 00000000..cea81913 --- /dev/null +++ b/upstream/fedora-40/man5/rcsfile.5 @@ -0,0 +1,459 @@ +.do if !dPS .ds PS +.do if !dPE .ds PE +.do if !dPF .ds PF +.do if !dPY .ds PY +.ds Rv 5.10.1 +.ds Dt 2024-01-26 +.ds i \&\s-1ISO\s0 +.ds r \&\s-1RCS\s0 +.ds u \&\s-1UTC\s0 +.ds o \*r file +.\" Set p to 1 if your formatter can handle pic output. +.if t .nr p 1 +.if n .ds - \%-- +.if t .ds - \(em +.TH RCSFILE 5 "\*(Dt" "GNU RCS \*(Rv" +.SH NAME +rcsfile \- \*o format +.SH DESCRIPTION +An \*o's +contents are described by the grammar +below. +.PP +The text is free format: space, backspace, tab, newline, vertical +tab, form feed, and carriage return (collectively, +.IR "white space") +have no significance except in strings. +However, white space cannot appear within an id, num, or sym, +and an \*o must end with a newline. +.PP +Strings are enclosed by +.BR @ . +If a string contains a +.BR @ , +it must be doubled; +otherwise, strings can contain arbitrary binary data. +.PP +The meta syntax uses the following conventions: `|' (bar) separates +alternatives; `{' and `}' enclose optional phrases; `{' and `}*' enclose +phrases that can be repeated zero or more times; +`{' and '}+' enclose phrases that must appear at least once and can be +repeated; +Terminal symbols are in +.BR boldface ; +nonterminal symbols are in +.IR italics . +.LP +.nr w \w'\f3deltatext\fP ' +.if \nw<\ny .nr w \ny +.nr x \w'\f3branches\fP' +.nr y \w'{ \f3comment\fP' +.if \nx<\ny .nr x \ny +.nr y \w'\f3{ branch\fP' +.if \nx<\ny .nr x \ny +.ta \nwu +\w'::= 'u +\nxu+\w' 'u +.fc # +.nf +\f2rcstext\fP ::= \f2admin\fP {\f2delta\fP}* \f2desc\fP {\f2deltatext\fP}* +.LP +\f2admin\fP ::= \f3head\fP {\f2num\fP}\f3;\fP + { \f3branch\fP {\f2num\fP}\f3;\fP } + \f3access\fP {\f2id\fP}*\f3;\fP + \f3symbols\fP {\f2sym\fP \f3:\fP \f2num\fP}*\f3;\fP + \f3locks\fP {\f2id\fP \f3:\fP \f2num\fP}*\f3;\fP {\f3strict ;\fP} + { \f3integrity\fP {\f2intstring\fP}\f3;\fP } + { \f3comment\fP {\f2string\fP}\f3;\fP } + { \f3expand\fP {\f2string\fP}\f3;\fP } +.LP +\f2delta\fP ::= \f2num\fP + \f3date\fP \f2num\fP\f3;\fP + \f3author\fP \f2id\fP\f3;\fP + \f3state\fP {\f2id\fP}\f3;\fP + \f3branches\fP {\f2num\fP}*\f3;\fP + \f3next\fP {\f2num\fP}\f3;\fP + { \f3commitid\fP \f2sym\fP\f3;\fP } +.LP +\f2desc\fP ::= \f3desc\fP \f2string\fP +.LP +\f2deltatext\fP ::= \f2num\fP + \f3log\fP \f2string\fP + \f3text\fP \f2string\fP +.LP +\f2num\fP ::= {\f2digit\fP | \f3.\fP}+ +.LP +\f2digit\fP ::= \f30\fP | \f31\fP | \f32\fP | \f33\fP | \f34\fP | \f35\fP | \f36\fP | \f37\fP | \f38\fP | \f39\fP +.LP +\f2id\fP ::= {\f2idchar\fP | \f3.\fP}+ +.LP +\f2sym\fP ::= {\f2idchar\fP}+ +.LP +\f2idchar\fP ::= any visible graphic character except \f2special\fP +.LP +\f2special\fP ::= \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP +.LP +\f2string\fP ::= \f3@\fP{any character, with \f3@\fP doubled}*\f3@\fP +.LP +\f2word\fP ::= \f2id\fP | \f2num\fP | \f2string\fP | \f3:\fP +.LP +\f2intchar\fP ::= any character, except \f3@\fP +.LP +\f2thirdp\fP ::= \f3^L\fP {\f2intchar\fP}* +.LP +\f2intstring\fP ::= \f3@\fP {\f2intchar\fP}* {\f2thirdp\fP}* \f3@\fP +.fi +.PP +In releases prior to 5.8 (2011-08-30), the grammar included the +.I newphrase +production and used it in the +.IR admin , +.I delta +and +.I deltatext +productions. +This allowed third-party programs to interoperate with \*r +by storing opaque (to \*r) data in the file. +As of 5.8, in the name of progress (towards more systematic file +integrity support), the only area reserved for third-party interop is in +the (string) value of the +.I integrity +field, specifically after the first +.B ^L +(formfeed). +A further restriction (for all programs) is that the +.I integrity +value must not contain +.BR @ . +.PP +Identifiers are case sensitive. Keywords are in lower case only. +The sets of keywords and identifiers can overlap. +In most environments \*r uses the \s-1ISO\s0 8859/1 encoding: +visible graphic characters are codes 041\-176 and 240\-377, +and white space characters are codes 010\-015 and 040. +.PP +Dates, which appear after the +.B date +keyword, are of the form +\f2Y\fP\f3.\fP\f2mm\fP\f3.\fP\f2dd\fP\f3.\fP\f2hh\fP\f3.\fP\f2mm\fP\f3.\fP\f2ss\fP, +where +.I Y +is the year, +.I mm +the month (01\-12), +.I dd +the day (01\-31), +.I hh +the hour (00\-23), +.I mm +the minute (00\-59), +and +.I ss +the second (00\-60). +.I Y +contains just the last two digits of the year +for years from 1900 through 1999, +and all the digits of years thereafter. +Dates use the Gregorian calendar; times use UTC. +.PP +The +.I delta +nodes form a tree. All nodes whose numbers +consist of a single pair +(e.g., 2.3, 2.1, 1.3, etc.) +are on the trunk, and are linked through the +.B next +field in order of decreasing numbers. +The +.B head +field in the +.I admin +node points to the head of that sequence (i.e., contains +the highest pair). +The +.B branch +node in the admin node indicates the default +branch (or revision) for most \*r operations. +If empty, the default +branch is the highest branch on the trunk. +.PP +All +.I delta +nodes whose numbers consist of +.RI 2 n +fields +.RI ( n \(>=2) +(e.g., 3.1.1.1, 2.1.2.2, etc.) +are linked as follows. +All nodes whose first +.RI 2 n \-1 +number fields are identical are linked through the +.B next +field in order of increasing numbers. +For each such sequence, +the +.I delta +node whose number is identical to the first +.RI 2 n \-2 +number fields of the deltas on that sequence is called the branchpoint. +The +.B branches +field of a node contains a list of the +numbers of the first nodes of all sequences for which it is a branchpoint. +This list is ordered in increasing numbers. +.LP +The following diagram shows an example of an \*o's organization. +.if !\np \{\ +.nf +.vs 12 +.ne 36 +.cs 1 20 +.eo + + Head + | + | + v / \ + --------- / \ + / \ / \ | | / \ / \ + / \ / \ | 2.1 | / \ / \ + / \ / \ | | / \ / \ +/1.2.1.3\ /1.3.1.1\ | | /1.2.2.2\ /1.2.2.1.1.1\ +--------- --------- --------- --------- ------------- + ^ ^ | ^ ^ + | | | | | + | | v | | + / \ | --------- / \ | + / \ | \ 1.3 / / \ | + / \ ---------\ / / \----------- +/1.2.1.1\ 1.3.1 \ / /1.2.2.1\ 1.2.2.1.1 +--------- \ / --------- + ^ | ^ + | | | + | v | + | --------- | + | \ 1.2 / | + ----------------------\ /--------- + 1.2.1 \ / 1.2.2 + \ / + | + | + v + --------- + \ 1.1 / + \ / + \ / + \ / + +.ec +.cs 1 +.vs +.fi +.\} +.if \np \{\ +.PS 4.250i 3.812i +.\" -2.0625 -4.25 1.75 0 +.\" 0.000i 4.250i 3.812i 0.000i +.nr 00 \n(.u +.nf +.nr 0x 1 +\h'3.812i' +.sp -1 +\h'2.062i-(\w'Head'u/2u)'\v'0.125i-(0v/2u)+0v+0.22m'Head +.sp -1 +\h'2.087i'\v'0.647i'\D'l -0.025i 0.100i' +.sp -1 +\h'2.038i'\v'0.647i'\D'l 0.025i 0.100i' +.sp -1 +\h'2.062i'\v'0.250i'\D'l 0.000i 0.497i' +.sp -1 +\h'1.688i'\v'1.250i'\D'l 0.750i 0.000i' +.sp -1 +\h'2.438i'\v'1.250i'\D'l 0.000i -0.500i' +.sp -1 +\h'2.438i'\v'0.750i'\D'l -0.750i 0.000i' +.sp -1 +\h'1.688i'\v'0.750i'\D'l 0.000i 0.500i' +.sp -1 +\h'2.062i-(\w'2.1'u/2u)'\v'1.000i-(0v/2u)+0v+0.22m'2.1 +.sp -1 +\h'2.087i'\v'1.647i'\D'l -0.025i 0.100i' +.sp -1 +\h'2.038i'\v'1.647i'\D'l 0.025i 0.100i' +.sp -1 +\h'2.062i'\v'1.250i'\D'l 0.000i 0.497i' +.sp -1 +\h'2.062i-(\w'1.3'u/2u)'\v'1.950i-(0v/2u)+0v+0.22m'1.3 +.sp -1 +\h'2.062i'\v'2.250i'\D'l -0.375i -0.500i' +.sp -1 +\h'1.688i'\v'1.750i'\D'l 0.750i 0.000i' +.sp -1 +\h'2.438i'\v'1.750i'\D'l -0.375i 0.500i' +.sp -1 +\h'1.350i'\v'1.603i'\D'l 0.025i -0.100i' +.sp -1 +\h'1.400i'\v'1.603i'\D'l -0.025i -0.100i' +.sp -1 +\h'1.875i'\v'2.000i'\D'~ -0.500i 0.000i 0.000i -0.497i' +.sp -1 +\h'1.375i-(\w'1.3.1'u/2u)'\v'2.100i-(0v/2u)+0v+0.22m'1.3.1 +.sp -1 +\h'1.375i-(\w'1.3.1.1'u/2u)'\v'1.400i-(0v/2u)+0v+0.22m'1.3.1.1 +.sp -1 +\h'1.375i'\v'1.000i'\D'l -0.375i 0.500i' +.sp -1 +\h'1.000i'\v'1.500i'\D'l 0.750i 0.000i' +.sp -1 +\h'1.750i'\v'1.500i'\D'l -0.375i -0.500i' +.sp -1 +\h'2.087i'\v'2.647i'\D'l -0.025i 0.100i' +.sp -1 +\h'2.038i'\v'2.647i'\D'l 0.025i 0.100i' +.sp -1 +\h'2.062i'\v'2.250i'\D'l 0.000i 0.497i' +.sp -1 +\h'2.062i-(\w'1.2'u/2u)'\v'2.950i-(0v/2u)+0v+0.22m'1.2 +.sp -1 +\h'2.062i'\v'3.250i'\D'l -0.375i -0.500i' +.sp -1 +\h'1.688i'\v'2.750i'\D'l 0.750i 0.000i' +.sp -1 +\h'2.438i'\v'2.750i'\D'l -0.375i 0.500i' +.sp -1 +\h'0.350i'\v'2.603i'\D'l 0.025i -0.100i' +.sp -1 +\h'0.400i'\v'2.603i'\D'l -0.025i -0.100i' +.sp -1 +\h'1.875i'\v'3.000i'\D'~ -0.500i 0.000i -0.500i 0.000i -0.500i 0.000i 0.000i -0.497i' +.sp -1 +\h'0.375i-(\w'1.2.1'u/2u)'\v'3.100i-(0v/2u)+0v+0.22m'1.2.1 +.sp -1 +\h'0.375i-(\w'1.2.1.1'u/2u)'\v'2.400i-(0v/2u)+0v+0.22m'1.2.1.1 +.sp -1 +\h'0.375i'\v'2.000i'\D'l -0.375i 0.500i' +.sp -1 +\h'0.000i'\v'2.500i'\D'l 0.750i 0.000i' +.sp -1 +\h'0.750i'\v'2.500i'\D'l -0.375i -0.500i' +.sp -1 +\h'0.350i'\v'1.603i'\D'l 0.025i -0.100i' +.sp -1 +\h'0.400i'\v'1.603i'\D'l -0.025i -0.100i' +.sp -1 +\h'0.375i'\v'2.000i'\D'l 0.000i -0.497i' +.sp -1 +\h'0.375i-(\w'1.2.1.3'u/2u)'\v'1.400i-(0v/2u)+0v+0.22m'1.2.1.3 +.sp -1 +\h'0.375i'\v'1.000i'\D'l -0.375i 0.500i' +.sp -1 +\h'0.000i'\v'1.500i'\D'l 0.750i 0.000i' +.sp -1 +\h'0.750i'\v'1.500i'\D'l -0.375i -0.500i' +.sp -1 +\h'2.725i'\v'2.603i'\D'l 0.025i -0.100i' +.sp -1 +\h'2.775i'\v'2.603i'\D'l -0.025i -0.100i' +.sp -1 +\h'2.250i'\v'3.000i'\D'~ 0.500i 0.000i 0.000i -0.497i' +.sp -1 +\h'2.750i-(\w'1.2.2'u/2u)'\v'3.100i-(0v/2u)+0v+0.22m'1.2.2 +.sp -1 +\h'2.750i-(\w'1.2.2.1'u/2u)'\v'2.400i-(0v/2u)+0v+0.22m'1.2.2.1 +.sp -1 +\h'2.750i'\v'2.000i'\D'l -0.375i 0.500i' +.sp -1 +\h'2.375i'\v'2.500i'\D'l 0.750i 0.000i' +.sp -1 +\h'3.125i'\v'2.500i'\D'l -0.375i -0.500i' +.sp -1 +\h'3.413i'\v'1.353i'\D'l 0.025i -0.100i' +.sp -1 +\h'3.462i'\v'1.353i'\D'l -0.025i -0.100i' +.sp -1 +\h'2.938i'\v'2.250i'\D'~ 0.500i 0.000i 0.000i -0.500i 0.000i -0.497i' +.sp -1 +\h'3.438i-(\w'1.2.2.1.1'u/2u)'\v'2.350i-(0v/2u)+0v+0.22m'1.2.2.1.1 +.sp -1 +\h'3.438i-(\w'\s-21.2.2.1.1.1\s0'u/2u)'\v'1.150i-(0v/2u)+0v+0.22m'\s-21.2.2.1.1.1\s0 +.sp -1 +\h'3.438i'\v'0.750i'\D'l -0.375i 0.500i' +.sp -1 +\h'3.062i'\v'1.250i'\D'l 0.750i 0.000i' +.sp -1 +\h'3.812i'\v'1.250i'\D'l -0.375i -0.500i' +.sp -1 +\h'2.725i'\v'1.603i'\D'l 0.025i -0.100i' +.sp -1 +\h'2.775i'\v'1.603i'\D'l -0.025i -0.100i' +.sp -1 +\h'2.750i'\v'2.000i'\D'l 0.000i -0.497i' +.sp -1 +\h'2.750i-(\w'1.2.2.2'u/2u)'\v'1.400i-(0v/2u)+0v+0.22m'1.2.2.2 +.sp -1 +\h'2.750i'\v'1.000i'\D'l -0.375i 0.500i' +.sp -1 +\h'2.375i'\v'1.500i'\D'l 0.750i 0.000i' +.sp -1 +\h'3.125i'\v'1.500i'\D'l -0.375i -0.500i' +.sp -1 +\h'2.087i'\v'3.647i'\D'l -0.025i 0.100i' +.sp -1 +\h'2.038i'\v'3.647i'\D'l 0.025i 0.100i' +.sp -1 +\h'2.062i'\v'3.250i'\D'l 0.000i 0.497i' +.sp -1 +\h'2.062i-(\w'1.1'u/2u)'\v'3.950i-(0v/2u)+0v+0.22m'1.1 +.sp -1 +\h'2.062i'\v'4.250i'\D'l -0.375i -0.500i' +.sp -1 +\h'1.688i'\v'3.750i'\D'l 0.750i 0.000i' +.sp -1 +\h'2.438i'\v'3.750i'\D'l -0.375i 0.500i' +.sp -1 +.sp 4.250i+1 +.if \n(00 .fi +.br +.nr 0x 0 +.PE +.\} +.PP +.ds EY 1990, 1991, 1992, 1993, 1994, 1995 +.SH IDENTIFICATION +Author: Walter F. Tichy. +.br +Manual Page Revision: \*(Rv; Release Date: \*(Dt. +.br +Copyright \(co 2010-2022 Thien-Thi Nguyen. +.br +Copyright \(co \*(EY Paul Eggert. +.br +Copyright \(co 1982, 1988, 1989 Walter F. Tichy. +.br +.SH "SEE ALSO" +.BR ci (1), +.BR co (1), +.BR ident (1), +.BR rcs (1), +.BR rcsclean (1), +.BR rcsdiff (1), +.BR rcsmerge (1), +.BR rlog (1). +.PP +Walter F. Tichy, +\*r\*-A System for Version Control, +.I "Software\*-Practice & Experience" +.BR 15 , +7 (July 1985), 637-654. +.PP +The full documentation for \*r is maintained as a Texinfo manual. +If the +.BR info (1) +and \*r programs are properly installed at your site, the command +.IP +.B info rcs +.PP +should give you access to the complete manual. +Additionally, the \*r homepage: +.IP +.B http://www.gnu.org/software/rcs/ +.PP +has news and links to the latest release, development site, etc. diff --git a/upstream/fedora-40/man5/repart.d.5 b/upstream/fedora-40/man5/repart.d.5 new file mode 100644 index 00000000..17e247f9 --- /dev/null +++ b/upstream/fedora-40/man5/repart.d.5 @@ -0,0 +1,1113 @@ +'\" t +.TH "REPART\&.D" "5" "" "systemd 255" "repart.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +repart.d \- Partition Definition Files for Automatic Boot\-Time Repartitioning +.SH "SYNOPSIS" +.PP +.nf +/etc/repart\&.d/*\&.conf +/run/repart\&.d/*\&.conf +/usr/lib/repart\&.d/*\&.conf + +.fi +.SH "DESCRIPTION" +.PP +repart\&.d/*\&.conf +files describe basic properties of partitions of block devices of the local system\&. They may be used to declare types, names and sizes of partitions that shall exist\&. The +\fBsystemd-repart\fR(8) +service reads these files and attempts to add new partitions currently missing and enlarge existing partitions according to these definitions\&. Operation is generally incremental, i\&.e\&. when applied, what exists already is left intact, and partitions are never shrunk, moved or deleted\&. +.PP +These definition files are useful for implementing operating system images that are prepared and delivered with minimally sized images (for example lacking any state or swap partitions), and which on first boot automatically take possession of any remaining disk space following a few basic rules\&. +.PP +Currently, support for partition definition files is only implemented for GPT partition tables\&. +.PP +Partition files are generally matched against any partitions already existing on disk in a simple algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then compared in order against existing partitions matching the same partition type UUID\&. Specifically, the first existing partition with a specific partition type UUID is assigned the first definition file with the same partition type UUID, and the second existing partition with a specific type UUID the second partition file with the same type UUID, and so on\&. Any left\-over partition files that have no matching existing partition are assumed to define new partition that shall be created\&. Such partitions are appended to the end of the partition table, in the order defined by their names utilizing the first partition slot greater than the highest slot number currently in use\&. Any existing partitions that have no matching partition file are left as they are\&. +.PP +Note that these definitions may only be used to create and initialize new partitions or to grow existing ones\&. In the latter case it will not grow the contained files systems however; separate mechanisms, such as +\fBsystemd-growfs\fR(8) +may be used to grow the file systems inside of these partitions\&. Partitions may also be marked for automatic growing via the +\fIGrowFileSystem=\fR +setting, in which case the file system is grown on first mount by tools that respect this flag\&. See below for details\&. +.SH "[PARTITION] SECTION OPTIONS" +.PP +\fIType=\fR +.RS 4 +The GPT partition type UUID to match\&. This may be a GPT partition type UUID such as +\fB4f68bce3\-e8cd\-4db1\-96e7\-fbcaf984b709\fR, or an identifier\&. Architecture specific partition types can use one of these architecture identifiers: +\fBalpha\fR, +\fBarc\fR, +\fBarm\fR +(32\-bit), +\fBarm64\fR +(64\-bit, aka aarch64), +\fBia64\fR, +\fBloongarch64\fR, +\fBmips\-le\fR, +\fBmips64\-le\fR, +\fBparisc\fR, +\fBppc\fR, +\fBppc64\fR, +\fBppc64\-le\fR, +\fBriscv32\fR, +\fBriscv64\fR, +\fBs390\fR, +\fBs390x\fR, +\fBtilegx\fR, +\fBx86\fR +(32\-bit, aka i386) and +\fBx86\-64\fR +(64\-bit, aka amd64)\&. +.sp +The supported identifiers are: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&GPT partition type identifiers +.TS +allbox tab(:); +lB lB. +T{ +Identifier +T}:T{ +Explanation +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +\fBesp\fR +T}:T{ +EFI System Partition +T} +T{ +\fBxbootldr\fR +T}:T{ +Extended Boot Loader Partition +T} +T{ +\fBswap\fR +T}:T{ +Swap partition +T} +T{ +\fBhome\fR +T}:T{ +Home (/home/) partition +T} +T{ +\fBsrv\fR +T}:T{ +Server data (/srv/) partition +T} +T{ +\fBvar\fR +T}:T{ +Variable data (/var/) partition +T} +T{ +\fBtmp\fR +T}:T{ +Temporary data (/var/tmp/) partition +T} +T{ +\fBlinux\-generic\fR +T}:T{ +Generic Linux file system partition +T} +T{ +\fBroot\fR +T}:T{ +Root file system partition type appropriate for the local architecture (an alias for an architecture root file system partition type listed below, e\&.g\&. \fBroot\-x86\-64\fR) +T} +T{ +\fBroot\-verity\fR +T}:T{ +Verity data for the root file system partition for the local architecture +T} +T{ +\fBroot\-verity\-sig\fR +T}:T{ +Verity signature data for the root file system partition for the local architecture +T} +T{ +\fBroot\-secondary\fR +T}:T{ +Root file system partition of the secondary architecture of the local architecture (usually the matching 32\-bit architecture for the local 64\-bit architecture) +T} +T{ +\fBroot\-secondary\-verity\fR +T}:T{ +Verity data for the root file system partition of the secondary architecture +T} +T{ +\fBroot\-secondary\-verity\-sig\fR +T}:T{ +Verity signature data for the root file system partition of the secondary architecture +T} +T{ +\fBroot\-{arch}\fR +T}:T{ +Root file system partition of the given architecture (such as \fBroot\-x86\-64\fR or \fBroot\-riscv64\fR) +T} +T{ +\fBroot\-{arch}\-verity\fR +T}:T{ +Verity data for the root file system partition of the given architecture +T} +T{ +\fBroot\-{arch}\-verity\-sig\fR +T}:T{ +Verity signature data for the root file system partition of the given architecture +T} +T{ +\fBusr\fR +T}:T{ +/usr/ file system partition type appropriate for the local architecture (an alias for an architecture /usr/ file system partition type listed below, e\&.g\&. \fBusr\-x86\-64\fR) +T} +T{ +\fBusr\-verity\fR +T}:T{ +Verity data for the /usr/ file system partition for the local architecture +T} +T{ +\fBusr\-verity\-sig\fR +T}:T{ +Verity signature data for the /usr/ file system partition for the local architecture +T} +T{ +\fBusr\-secondary\fR +T}:T{ +/usr/ file system partition of the secondary architecture of the local architecture (usually the matching 32\-bit architecture for the local 64\-bit architecture) +T} +T{ +\fBusr\-secondary\-verity\fR +T}:T{ +Verity data for the /usr/ file system partition of the secondary architecture +T} +T{ +\fBusr\-secondary\-verity\-sig\fR +T}:T{ +Verity signature data for the /usr/ file system partition of the secondary architecture +T} +T{ +\fBusr\-{arch}\fR +T}:T{ +/usr/ file system partition of the given architecture +T} +T{ +\fBusr\-{arch}\-verity\fR +T}:T{ +Verity data for the /usr/ file system partition of the given architecture +T} +T{ +\fBusr\-{arch}\-verity\-sig\fR +T}:T{ +Verity signature data for the /usr/ file system partition of the given architecture +T} +.TE +.sp 1 +This setting defaults to +\fBlinux\-generic\fR\&. +.sp +Most of the partition type UUIDs listed above are defined in the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.sp +Added in version 245\&. +.RE +.PP +\fILabel=\fR +.RS 4 +The textual label to assign to the partition if none is assigned yet\&. Note that this setting is not used for matching\&. It is also not used when a label is already set for an existing partition\&. It is thus only used when a partition is newly created or when an existing one had a no label set (that is: an empty label)\&. If not specified a label derived from the partition type is automatically used\&. Simple specifier expansion is supported, see below\&. +.sp +Added in version 245\&. +.RE +.PP +\fIUUID=\fR +.RS 4 +The UUID to assign to the partition if none is assigned yet\&. Note that this setting is not used for matching\&. It is also not used when a UUID is already set for an existing partition\&. It is thus only used when a partition is newly created or when an existing one had a all\-zero UUID set\&. If set to +"null", the UUID is set to all zeroes\&. If not specified a UUID derived from the partition type is automatically used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +A numeric priority to assign to this partition, in the range \-2147483648\&...2147483647, with smaller values indicating higher priority, and higher values indicating smaller priority\&. This priority is used in case the configured size constraints on the defined partitions do not permit fitting all partitions onto the available disk space\&. If the partitions do not fit, the highest numeric partition priority of all defined partitions is determined, and all defined partitions with this priority are removed from the list of new partitions to create (which may be multiple, if the same priority is used for multiple partitions)\&. The fitting algorithm is then tried again\&. If the partitions still do not fit, the now highest numeric partition priority is determined, and the matching partitions removed too, and so on\&. Partitions of a priority of 0 or lower are never removed\&. If all partitions with a priority above 0 are removed and the partitions still do not fit on the device the operation fails\&. Note that this priority has no effect on ordering partitions, for that use the alphabetical order of the filenames of the partition definition files\&. Defaults to 0\&. +.sp +Added in version 245\&. +.RE +.PP +\fIWeight=\fR +.RS 4 +A numeric weight to assign to this partition in the range 0\&...1000000\&. Available disk space is assigned the defined partitions according to their relative weights (subject to the size constraints configured with +\fISizeMinBytes=\fR, +\fISizeMaxBytes=\fR), so that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with weight 333 a third of that\&. Defaults to 1000\&. +.sp +The +\fIWeight=\fR +setting is used to distribute available disk space in an "elastic" fashion, based on the disk size and existing partitions\&. If a partition shall have a fixed size use both +\fISizeMinBytes=\fR +and +\fISizeMaxBytes=\fR +with the same value in order to fixate the size to one value, in which case the weight has no effect\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPaddingWeight=\fR +.RS 4 +Similar to +\fIWeight=\fR, but sets a weight for the free space after the partition (the "padding")\&. When distributing available space the weights of all partitions and all defined padding is summed, and then each partition and padding gets the fraction defined by its weight\&. Defaults to 0, i\&.e\&. by default no padding is applied\&. +.sp +Padding is useful if empty space shall be left for later additions or a safety margin at the end of the device or between partitions\&. +.sp +Added in version 245\&. +.RE +.PP +\fISizeMinBytes=\fR, \fISizeMaxBytes=\fR +.RS 4 +Specifies minimum and maximum size constraints in bytes\&. Takes the usual K, M, G, T, \&... suffixes (to the base of 1024)\&. If +\fISizeMinBytes=\fR +is specified the partition is created at or grown to at least the specified size\&. If +\fISizeMaxBytes=\fR +is specified the partition is created at or grown to at most the specified size\&. The precise size is determined through the weight value configured with +\fIWeight=\fR, see above\&. When +\fISizeMinBytes=\fR +is set equal to +\fISizeMaxBytes=\fR +the configured weight has no effect as the partition is explicitly sized to the specified fixed value\&. Note that partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the previous size of the partition (in case the partition already exists) is also enforced as lower bound for the new size\&. The values should be specified as multiples of 4096 bytes, and are rounded upwards (in case of +\fISizeMinBytes=\fR) or downwards (in case of +\fISizeMaxBytes=\fR) otherwise\&. If the backing device does not provide enough space to fulfill the constraints placing the partition will fail\&. For partitions that shall be created, depending on the setting of +\fIPriority=\fR +(see above) the partition might be dropped and the placing algorithm restarted\&. By default a minimum size constraint of 10M and no maximum size constraint is set\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPaddingMinBytes=\fR, \fIPaddingMaxBytes=\fR +.RS 4 +Specifies minimum and maximum size constraints in bytes for the free space after the partition (the "padding")\&. Semantics are similar to +\fISizeMinBytes=\fR +and +\fISizeMaxBytes=\fR, except that unlike partition sizes free space can be shrunk and can be as small as zero\&. By default no size constraints on padding are set, so that only +\fIPaddingWeight=\fR +determines the size of the padding applied\&. +.sp +Added in version 245\&. +.RE +.PP +\fICopyBlocks=\fR +.RS 4 +Takes a path to a regular file, block device node or directory, or the special value +"auto"\&. If specified and the partition is newly created, the data from the specified path is written to the newly created partition, on the block level\&. If a directory is specified, the backing block device of the file system the directory is on is determined, and the data read directly from that\&. This option is useful to efficiently replicate existing file systems onto new partitions on the block level \(em for example to build a simple OS installer or an OS image builder\&. +.sp +If the special value +"auto" +is specified, the source to copy from is automatically picked up from the running system (or the image specified with +\fB\-\-image=\fR +\(em if used)\&. A partition that matches both the configured partition type (as declared with +\fIType=\fR +described above), and the currently mounted directory appropriate for that partition type is determined\&. For example, if the partition type is set to +"root" +the partition backing the root directory (/) is used as source to copy from \(em if its partition type is set to +"root" +as well\&. If the declared type is +"usr" +the partition backing +/usr/ +is used as source to copy blocks from \(em if its partition type is set to +"usr" +too\&. The logic is capable of automatically tracking down the backing partitions for encrypted and Verity\-enabled volumes\&. +"CopyBlocks=auto" +is useful for implementing "self\-replicating" systems, i\&.e\&. systems that are their own installer\&. +.sp +The file specified here must have a size that is a multiple of the basic block size 512 and not be empty\&. If this option is used, the size allocation algorithm is slightly altered: the partition is created as least as big as required to fit the data in, i\&.e\&. the data size is an additional minimum size value taken into consideration for the allocation algorithm, similar to and in addition to the +\fISizeMin=\fR +value configured above\&. +.sp +This option has no effect if the partition it is declared for already exists, i\&.e\&. existing data is never overwritten\&. Note that the data is copied in before the partition table is updated, i\&.e\&. before the partition actually is persistently created\&. This provides robustness: it is guaranteed that the partition either doesn\*(Aqt exist or exists fully populated; it is not possible that the partition exists but is not or only partially populated\&. +.sp +This option cannot be combined with +\fIFormat=\fR +or +\fICopyFiles=\fR\&. +.sp +Added in version 246\&. +.RE +.PP +\fIFormat=\fR +.RS 4 +Takes a file system name, such as +"ext4", +"btrfs", +"xfs", +"vfat", +"erofs", +"squashfs" +or the special value +"swap"\&. If specified and the partition is newly created it is formatted with the specified file system (or as swap device)\&. The file system UUID and label are automatically derived from the partition UUID and label\&. If this option is used, the size allocation algorithm is slightly altered: the partition is created as least as big as required for the minimal file system of the specified type (or 4KiB if the minimal size is not known)\&. +.sp +This option has no effect if the partition already exists\&. +.sp +Similarly to the behaviour of +\fICopyBlocks=\fR, the file system is formatted before the partition is created, ensuring that the partition only ever exists with a fully initialized file system\&. +.sp +This option cannot be combined with +\fICopyBlocks=\fR\&. +.sp +Added in version 247\&. +.RE +.PP +\fICopyFiles=\fR +.RS 4 +Takes a pair of colon separated absolute file system paths\&. The first path refers to a source file or directory on the host, the second path refers to a target in the file system of the newly created partition and formatted file system\&. This setting may be used to copy files or directories from the host into the file system that is created due to the +\fIFormat=\fR +option\&. If +\fICopyFiles=\fR +is used without +\fIFormat=\fR +specified explicitly, +"Format=" +with a suitable default is implied (currently +"vfat" +for +"ESP" +and +"XBOOTLDR" +partitions, and +"ext4" +otherwise, but this may change in the future)\&. This option may be used multiple times to copy multiple files or directories from host into the newly formatted file system\&. The colon and second path may be omitted in which case the source path is also used as the target path (relative to the root of the newly created file system)\&. If the source path refers to a directory it is copied recursively\&. +.sp +This option has no effect if the partition already exists: it cannot be used to copy additional files into an existing partition, it may only be used to populate a file system created anew\&. +.sp +The copy operation is executed before the file system is registered in the partition table, thus ensuring that a file system populated this way only ever exists fully initialized\&. +.sp +Note that +\fICopyFiles=\fR +will skip copying files that aren\*(Aqt supported by the target filesystem (e\&.g symlinks, fifos, sockets and devices on vfat)\&. When an unsupported file type is encountered, +\fBsystemd\-repart\fR +will skip copying this file and write a log message about it\&. +.sp +Note that +\fBsystemd\-repart\fR +does not change the UIDs/GIDs of any copied files and directories\&. When running +\fBsystemd\-repart\fR +as an unprivileged user to build an image of files and directories owned by the same user, you can run +\fBsystemd\-repart\fR +in a user namespace with the current user mapped to the root user to make sure the files and directories in the image are owned by the root user\&. +.sp +Note that when populating XFS filesystems with +\fBsystemd\-repart\fR +and loop devices are not available, populating XFS filesystems with files containing spaces, tabs or newlines might fail on old versions of +\fBmkfs.xfs\fR(8) +due to limitations of its protofile format\&. +.sp +Note that when populating XFS filesystems with +\fBsystemd\-repart\fR +and loop devices are not available, extended attributes will not be copied into generated XFS filesystems due to limitations +\fBmkfs.xfs\fR(8)\*(Aqs protofile format\&. +.sp +This option cannot be combined with +\fICopyBlocks=\fR\&. +.sp +When +\fBsystemd-repart\fR(8) +is invoked with the +\fB\-\-copy\-source=\fR +command line switch the file paths are taken relative to the specified directory\&. If +\fB\-\-copy\-source=\fR +is not used, but the +\fB\-\-image=\fR +or +\fB\-\-root=\fR +switches are used, the source paths are taken relative to the specified root directory or disk image root\&. +.sp +Added in version 247\&. +.RE +.PP +\fIExcludeFiles=\fR, \fIExcludeFilesTarget=\fR +.RS 4 +Takes an absolute file system path referring to a source file or directory on the host\&. This setting may be used to exclude files or directories from the host from being copied into the file system when +\fICopyFiles=\fR +is used\&. This option may be used multiple times to exclude multiple files or directories from host from being copied into the newly formatted file system\&. +.sp +If the path is a directory and ends with +"/", only the directory\*(Aqs contents are excluded but not the directory itself\&. If the path is a directory and does not end with +"/", both the directory and its contents are excluded\&. +.sp +\fIExcludeFilesTarget=\fR +is like +\fIExcludeFiles=\fR +except that instead of excluding the path on the host from being copied into the partition, we exclude any files and directories from being copied into the given path in the partition\&. +.sp +When +\fBsystemd-repart\fR(8) +is invoked with the +\fB\-\-image=\fR +or +\fB\-\-root=\fR +command line switches the paths specified are taken relative to the specified root directory or disk image root\&. +.sp +Added in version 254\&. +.RE +.PP +\fIMakeDirectories=\fR +.RS 4 +Takes one or more absolute paths, separated by whitespace, each declaring a directory to create within the new file system\&. Behaviour is similar to +\fICopyFiles=\fR, but instead of copying in a set of files this just creates the specified directories with the default mode of 0755 owned by the root user and group, plus all their parent directories (with the same ownership and access mode)\&. To configure directories with different ownership or access mode, use +\fICopyFiles=\fR +and specify a source tree to copy containing appropriately owned/configured directories\&. This option may be used more than once to create multiple directories\&. When +\fICopyFiles=\fR +and +\fIMakeDirectories=\fR +are used together the former is applied first\&. If a directory listed already exists no operation is executed (in particular, the ownership/access mode of the directories is left as is)\&. +.sp +The primary use case for this option is to create a minimal set of directories that may be mounted over by other partitions contained in the same disk image\&. For example, a disk image where the root file system is formatted at first boot might want to automatically pre\-create +/usr/ +in it this way, so that the +"usr" +partition may over\-mount it\&. +.sp +Consider using +\fBsystemd-tmpfiles\fR(8) +with its +\fB\-\-image=\fR +option to pre\-create other, more complex directory hierarchies (as well as other inodes) with fine\-grained control of ownership, access modes and other file attributes\&. +.sp +Added in version 249\&. +.RE +.PP +\fISubvolumes=\fR +.RS 4 +Takes one or more absolute paths, separated by whitespace, each declaring a directory that should be a subvolume within the new file system\&. This option may be used more than once to specify multiple directories\&. Note that this setting does not create the directories themselves, that can be configured with +\fIMakeDirectories=\fR +and +\fICopyFiles=\fR\&. +.sp +Note that this option only takes effect if the target filesystem supports subvolumes, such as +"btrfs"\&. +.sp +Note that due to limitations of +"mkfs\&.btrfs", this option is only supported when running with +\fB\-\-offline=no\fR\&. +.sp +Added in version 255\&. +.RE +.PP +\fIEncrypt=\fR +.RS 4 +Takes one of +"off", +"key\-file", +"tpm2" +and +"key\-file+tpm2" +(alternatively, also accepts a boolean value, which is mapped to +"off" +when false, and +"key\-file" +when true)\&. Defaults to +"off"\&. If not +"off" +the partition will be formatted with a LUKS2 superblock, before the blocks configured with +\fICopyBlocks=\fR +are copied in or the file system configured with +\fIFormat=\fR +is created\&. +.sp +The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion\&. If +"key\-file" +or +"key\-file+tpm2" +is used, a key is added to the LUKS2 superblock, configurable with the +\fB\-\-key\-file=\fR +option to +\fBsystemd\-repart\fR\&. If +"tpm2" +or +"key\-file+tpm2" +is used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured with the +\fB\-\-tpm2\-device=\fR +and +\fB\-\-tpm2\-pcrs=\fR +options to +\fBsystemd\-repart\fR\&. +.sp +When used this slightly alters the size allocation logic as the implicit, minimal size limits of +\fIFormat=\fR +and +\fICopyBlocks=\fR +are increased by the space necessary for the LUKS2 superblock (see above)\&. +.sp +This option has no effect if the partition already exists\&. +.sp +Added in version 247\&. +.RE +.PP +\fIVerity=\fR +.RS 4 +Takes one of +"off", +"data", +"hash" +or +"signature"\&. Defaults to +"off"\&. If set to +"off" +or +"data", the partition is populated with content as specified by +\fICopyBlocks=\fR +or +\fICopyFiles=\fR\&. If set to +"hash", the partition will be populated with verity hashes from the matching verity data partition\&. If set to +"signature", the partition will be populated with a JSON object containing a signature of the verity root hash of the matching verity hash partition\&. +.sp +A matching verity partition is a partition with the same verity match key (as configured with +\fIVerityMatchKey=\fR)\&. +.sp +If not explicitly configured, the data partition\*(Aqs UUID will be set to the first 128 bits of the verity root hash\&. Similarly, if not configured, the hash partition\*(Aqs UUID will be set to the final 128 bits of the verity root hash\&. The verity root hash itself will be included in the output of +\fBsystemd\-repart\fR\&. +.sp +This option has no effect if the partition already exists\&. +.sp +Usage of this option in combination with +\fIEncrypt=\fR +is not supported\&. +.sp +For each unique +\fIVerityMatchKey=\fR +value, a single verity data partition ("Verity=data") and a single verity hash partition ("Verity=hash") must be defined\&. +.sp +Added in version 252\&. +.RE +.PP +\fIVerityMatchKey=\fR +.RS 4 +Takes a short, user\-chosen identifier string\&. This setting is used to find sibling verity partitions for the current verity partition\&. See the description for +\fIVerity=\fR\&. +.sp +Added in version 252\&. +.RE +.PP +\fIVerityDataBlockSizeBytes=\fR +.RS 4 +Configures the data block size of the generated verity hash partition\&. Must be between 512 and 4096 bytes and must be a power of 2\&. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if systemd\-repart is not operating on a block device\&. +.sp +Added in version 255\&. +.RE +.PP +\fIVerityHashBlockSizeBytes=\fR +.RS 4 +Configures the hash block size of the generated verity hash partition\&. Must be between 512 and 4096 bytes and must be a power of 2\&. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if systemd\-repart is not operating on a block device\&. +.sp +Added in version 255\&. +.RE +.PP +\fIFactoryReset=\fR +.RS 4 +Takes a boolean argument\&. If specified the partition is marked for removal during a factory reset operation\&. This functionality is useful to implement schemes where images can be reset into their original state by removing partitions and creating them anew\&. Defaults to off\&. +.sp +Added in version 245\&. +.RE +.PP +\fIFlags=\fR +.RS 4 +Configures the 64\-bit GPT partition flags field to set for the partition when creating it\&. This option has no effect if the partition already exists\&. If not specified the flags values is set to all zeroes, except for the three bits that can also be configured via +\fINoAuto=\fR, +\fIReadOnly=\fR +and +\fIGrowFileSystem=\fR; see below for details on the defaults for these three flags\&. Specify the flags value in hexadecimal (by prefixing it with +"0x"), binary (prefix +"0b") or decimal (no prefix)\&. +.sp +Added in version 249\&. +.RE +.PP +\fINoAuto=\fR, \fIReadOnly=\fR, \fIGrowFileSystem=\fR +.RS 4 +Configures the No\-Auto, Read\-Only and Grow\-File\-System partition flags (bit 63, 60 and 59) of the partition table entry, as defined by the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. Only available for partition types supported by the specification\&. This option is a friendly way to set bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set via +\fIFlags=\fR +too, see above\&. +.sp +If +\fIFlags=\fR +is used in conjunction with one or more of +\fINoAuto=\fR/\fIReadOnly=\fR/\fIGrowFileSystem=\fR +the latter control the value of the relevant flags, i\&.e\&. the high\-level settings +\fINoAuto=\fR/\fIReadOnly=\fR/\fIGrowFileSystem=\fR +override the relevant bits of the low\-level setting +\fIFlags=\fR\&. +.sp +Note that the three flags affect only automatic partition mounting, as implemented by +\fBsystemd-gpt-auto-generator\fR(8) +or the +\fB\-\-image=\fR +option of various commands (such as +\fBsystemd-nspawn\fR(1))\&. It has no effect on explicit mounts, such as those done via +\fBmount\fR(8) +or +\fBfstab\fR(5)\&. +.sp +If both bit 50 and 59 are set for a partition (i\&.e\&. the partition is marked both read\-only and marked for file system growing) the latter is typically without effect: the read\-only flag takes precedence in most tools reading these flags, and since growing the file system involves writing to the partition it is consequently ignored\&. +.sp +\fINoAuto=\fR +defaults to off\&. +\fIReadOnly=\fR +defaults to on for Verity partition types, and off for all others\&. +\fIGrowFileSystem=\fR +defaults to on for all partition types that support it, except if the partition is marked read\-only (and thus effectively, defaults to off for Verity partitions)\&. +.sp +Added in version 249\&. +.RE +.PP +\fISplitName=\fR +.RS 4 +Configures the suffix to append to split artifacts when the +\fB\-\-split\fR +option of +\fBsystemd-repart\fR(8) +is used\&. Simple specifier expansion is supported, see below\&. Defaults to +"%t"\&. To disable split artifact generation for a partition, set +\fISplitName=\fR +to +"\-"\&. +.sp +Added in version 252\&. +.RE +.PP +\fIMinimize=\fR +.RS 4 +Takes one of +"off", +"best", and +"guess" +(alternatively, also accepts a boolean value, which is mapped to +"off" +when false, and +"best" +when true)\&. Defaults to +"off"\&. If set to +"best", the partition will have the minimal size required to store the sources configured with +\fICopyFiles=\fR\&. +"best" +is currently only supported for read\-only filesystems\&. If set to +"guess", the partition is created at least as big as required to store the sources configured with +\fICopyFiles=\fR\&. Note that unless the filesystem is a read\-only filesystem, +\fBsystemd\-repart\fR +will have to populate the filesystem twice to guess the minimal required size, so enabling this option might slow down repart when populating large partitions\&. +.sp +Added in version 253\&. +.RE +.SH "SPECIFIERS" +.PP +Specifiers may be used in the +\fILabel=\fR, +\fICopyBlocks=\fR, +\fICopyFiles=\fR, +\fIMakeDirectories=\fR, +\fISplitName=\fR +settings\&. The following expansions are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system\&. +T} +T{ +"%l" +T}:T{ +Short host name +T}:T{ +The hostname of the running system, truncated at the first dot to remove any domain component\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%T" +T}:T{ +Directory for temporary files +T}:T{ +This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%V" +T}:T{ +Directory for larger and persistent temporary files +T}:T{ +This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +.PP +Additionally, for the +\fISplitName=\fR +setting, the following specifiers are also understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&3.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l. +T{ +"%T" +T}:T{ +Partition Type UUID +T}:T{ +The partition type UUID, as configured with \fIType=\fR +T} +T{ +"%t" +T}:T{ +Partition Type Identifier +T}:T{ +The partition type identifier corresponding to the partition type UUID +T} +T{ +"%U" +T}:T{ +Partition UUID +T}:T{ +The partition UUID, as configured with \fIUUID=\fR +T} +T{ +"%n" +T}:T{ +Partition Number +T}:T{ +The partition number assigned to the partition +T} +.TE +.sp 1 +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Grow the root partition to the full disk size at first boot\fR +.PP +With the following file the root partition is automatically grown to the full disk if possible during boot\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/repart\&.d/50\-root\&.conf +[Partition] +Type=root +.fi +.if n \{\ +.RE +.\} + +.PP +\fBExample\ \&2.\ \&Create a swap and home partition automatically on boot, if missing\fR +.PP +The home partition gets all available disk space while the swap partition gets 1G at most and 64M at least\&. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not enough space is available\&. For every three bytes assigned to the home partition the swap partition gets assigned one\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/repart\&.d/60\-home\&.conf +[Partition] +Type=home +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/repart\&.d/70\-swap\&.conf +[Partition] +Type=swap +SizeMinBytes=64M +SizeMaxBytes=1G +Priority=1 +Weight=333 +.fi +.if n \{\ +.RE +.\} + +.PP +\fBExample\ \&3.\ \&Create B partitions in an A/B Verity setup, if missing\fR +.PP +Let\*(Aqs say the vendor intends to update OS images in an A/B setup, i\&.e\&. with two root partitions (and two matching Verity partitions) that shall be used alternatingly during upgrades\&. To minimize image sizes the original image is shipped only with one root and one Verity partition (the "A" set), and the second root and Verity partitions (the "B" set) shall be created on first boot on the free space on the medium\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/repart\&.d/50\-root\&.conf +[Partition] +Type=root +SizeMinBytes=512M +SizeMaxBytes=512M +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/repart\&.d/60\-root\-verity\&.conf +[Partition] +Type=root\-verity +SizeMinBytes=64M +SizeMaxBytes=64M +.fi +.if n \{\ +.RE +.\} +.PP +The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity partition for the root partition (of a fixed 64M size)\&. Let\*(Aqs use symlinks to create the "B" set of partitions, since after all they shall have the same properties and sizes as the "A" set\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# ln \-s 50\-root\&.conf /usr/lib/repart\&.d/70\-root\-b\&.conf +# ln \-s 60\-root\-verity\&.conf /usr/lib/repart\&.d/80\-root\-verity\-b\&.conf +.fi +.if n \{\ +.RE +.\} + +.PP +\fBExample\ \&4.\ \&Create a data partition and corresponding verity partitions from a OS tree\fR +.PP +Assuming we have an OS tree at +/var/tmp/os\-tree +that we want to package in a root partition together with matching verity partitions, we can do so as follows: +.PP +.if n \{\ +.RS 4 +.\} +.nf +# 50\-root\&.conf +[Partition] +Type=root +CopyFiles=/var/tmp/os\-tree +Verity=data +VerityMatchKey=root +Minimize=guess +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +# 60\-root\-verity\&.conf +[Partition] +Type=root\-verity +Verity=hash +VerityMatchKey=root +# Explicitly set the hash and data block size to 4K +VerityDataBlockSizeBytes=4096 +VerityHashBlockSizeBytes=4096 +Minimize=best +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +# 70\-root\-verity\-sig\&.conf +[Partition] +Type=root\-verity\-sig +Verity=signature +VerityMatchKey=root +.fi +.if n \{\ +.RE +.\} + +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-repart\fR(8), +\fBsfdisk\fR(8), +\fBsystemd-cryptenroll\fR(1) +.SH "NOTES" +.IP " 1." 4 +Discoverable Partitions Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification +.RE diff --git a/upstream/fedora-40/man5/repertoiremap.5 b/upstream/fedora-40/man5/repertoiremap.5 new file mode 100644 index 00000000..dd7781cb --- /dev/null +++ b/upstream/fedora-40/man5/repertoiremap.5 @@ -0,0 +1,58 @@ +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH repertoiremap 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +repertoiremap \- map symbolic character names to Unicode code points +.SH DESCRIPTION +A repertoire map defines mappings between symbolic character names +(mnemonics) and Unicode code points when compiling a locale with +.BR localedef (1). +Using a repertoire map is optional, it is needed only when symbolic +names are used instead of now preferred Unicode code points. +.SS Syntax +The repertoiremap file starts with a header that may consist of the +following keywords: +.TP +.I comment_char +is followed by a character that will be used as the +comment character for the rest of the file. +It defaults to the number sign (#). +.TP +.I escape_char +is followed by a character that should be used as the escape character +for the rest of the file to mark characters that should be interpreted +in a special way. +It defaults to the backslash (\e). +.P +The mapping section starts with the keyword +.I CHARIDS +in the first column. +.P +The mapping lines have the following form: +.TP +.I comment +This defines exactly one mapping, +.I comment +being optional. +.P +The mapping section ends with the string +.IR "END CHARIDS" . +.SH FILES +.TP +.I /usr/share/i18n/repertoiremaps +Usual default repertoire map path. +.SH STANDARDS +POSIX.2. +.SH NOTES +Repertoire maps are deprecated in favor of Unicode code points. +.SH EXAMPLES +A mnemonic for the Euro sign can be defined as follows: +.P +.nf + EURO SIGN +.fi +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR charmap (5), +.BR locale (5) diff --git a/upstream/fedora-40/man5/resolv.conf.5 b/upstream/fedora-40/man5/resolv.conf.5 new file mode 100644 index 00000000..149f06dc --- /dev/null +++ b/upstream/fedora-40/man5/resolv.conf.5 @@ -0,0 +1,406 @@ +.\" Copyright (c) 1986 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %%%LICENSE_END +.\" +.\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 +.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ +.\" +.\" Added ndots remark by Bernhard R. Link - debian bug #182886 +.\" +.TH resolv.conf 5 2023-10-31 "Linux man-pages 6.06" +.UC 4 +.SH NAME +resolv.conf \- resolver configuration file +.SH SYNOPSIS +.nf +.B /etc/resolv.conf +.fi +.SH DESCRIPTION +The +.I resolver +is a set of routines in the C library +that provide access to the Internet Domain Name System (DNS). +The resolver configuration file contains information that is read +by the resolver routines the first time they are invoked by a process. +The file is designed to be human readable and contains a list of +keywords with values that provide various types of resolver information. +The configuration file is considered a trusted source of DNS information; +see the +.B trust-ad +option below for details. +.P +If this file does not exist, only the name server on the local machine +will be queried, and the search list contains the local domain name +determined from the hostname. +.P +The different configuration options are: +.TP +\fBnameserver\fP Name server IP address +Internet address of a name server that the resolver should query, +either an IPv4 address (in dot notation), +or an IPv6 address in colon (and possibly dot) notation as per RFC 2373. +Up to +.B MAXNS +(currently 3, see \fI\fP) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. +If no \fBnameserver\fP entries are present, +the default is to use the name server on the local machine. +(The algorithm used is to try a name server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made.) +.TP +\fBsearch\fP Search list for host-name lookup. +By default, the search list contains one entry, the local domain name. +It is determined from the local hostname returned by +.BR gethostname (2); +the local domain name is taken to be everything after the first +\[aq].\[aq]. +Finally, if the hostname does not contain a \[aq].\[aq], the +root domain is assumed as the local domain name. +.IP +This may be changed by listing the desired domain search path +following the \fIsearch\fP keyword with spaces or tabs separating +the names. +Resolver queries having fewer than +.I ndots +dots (default is 1) in them will be attempted using each component +of the search path in turn until a match is found. +For environments with multiple subdomains please read +.BI "options ndots:" n +below to avoid man-in-the-middle attacks and unnecessary +traffic for the root-dns-servers. +.\" When having a resolv.conv with a line +.\" search subdomain.domain.tld domain.tld +.\" and doing a hostlookup, for example by +.\" ping host.anothersubdomain +.\" it sends dns-requests for +.\" host.anothersubdomain. +.\" host.anothersubdomain.subdomain.domain.tld. +.\" host.anothersubdomain.domain.tld. +.\" thus not only causing unnecessary traffic for the root-dns-servers +.\" but broadcasting information to the outside and making man-in-the-middle +.\" attacks possible. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.IP +If there are multiple +.B search +directives, only the search list from the last instance is used. +.IP +In glibc 2.25 and earlier, the search list is limited to six domains +with a total of 256 characters. +Since glibc 2.26, +.\" glibc commit 3f853f22c87f0b671c0366eb290919719fa56c0e +the search list is unlimited. +.IP +The +.B domain +directive is an obsolete name for the +.B search +directive that handles one search list entry only. +.TP +\fBsortlist\fP +This option allows addresses returned by +.BR gethostbyname (3) +to be sorted. +A sortlist is specified by IP-address-netmask pairs. +The netmask is +optional and defaults to the natural netmask of the net. +The IP address +and optional network pairs are separated by slashes. +Up to 10 pairs may +be specified. +Here is an example: +.IP +.in +4n +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.in +.TP +\fBoptions\fP +Options allows certain internal resolver variables to be modified. +The syntax is +.RS +.IP +\fBoptions\fP \fIoption\fP \fI...\fP +.P +where \fIoption\fP is one of the following: +.TP +\fBdebug\fP +.\" Since glibc 2.2? +Sets +.B RES_DEBUG +in +.I _res.options +(effective only if glibc was built with debug support; see +.BR resolver (3)). +.TP +.BI ndots: n +.\" Since glibc 2.2 +Sets a threshold for the number of dots which +must appear in a name given to +.BR res_query (3) +(see +.BR resolver (3)) +before an \fIinitial absolute query\fP will be made. +The default for +\fIn\fP is 1, meaning that if there are any dots in a name, the name +will be tried first as an absolute name before any \fIsearch list\fP +elements are appended to it. +The value for this option is silently capped to 15. +.TP +.BI timeout: n +.\" Since glibc 2.2 +Sets the amount of time the resolver will wait for a +response from a remote name server before retrying the +query via a different name server. +This may +.B not +be the total time taken by any resolver API call and there is no +guarantee that a single resolver API call maps to a single timeout. +Measured in seconds, +the default is +.B RES_TIMEOUT +(currently 5, see \fI\fP). +The value for this option is silently capped to 30. +.TP +.BI attempts: n +Sets the number of times the resolver will send a +query to its name servers before giving up and returning +an error to the calling application. +The default is +.B RES_DFLRETRY +(currently 2, see \fI\fP). +The value for this option is silently capped to 5. +.TP +.B rotate +.\" Since glibc 2.2 +Sets +.B RES_ROTATE +in +.IR _res.options , +which causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every time. +.TP +.B no\-aaaa (since glibc 2.36) +.\" f282cdbe7f436c75864e5640a409a10485e9abb2 +Sets +.B RES_NOAAAA +in +.IR _res.options , +which suppresses AAAA queries made by the stub resolver, +including AAAA lookups triggered by NSS-based interfaces such as +.BR getaddrinfo (3). +Only DNS lookups are affected: IPv6 data in +.BR hosts (5) +is still used, +.BR getaddrinfo (3) +with +.B AI_PASSIVE +will still produce IPv6 addresses, +and configured IPv6 name servers are still used. +To produce correct Name Error (NXDOMAIN) results, +AAAA queries are translated to A queries. +This option is intended preliminary for diagnostic purposes, +to rule out that AAAA DNS queries have adverse impact. +It is incompatible with EDNS0 usage and DNSSEC validation by applications. +.TP +.B no\-check\-names +.\" since glibc 2.2 +Sets +.B RES_NOCHECKNAME +in +.IR _res.options , +which disables the modern BIND checking of incoming hostnames and +mail names for invalid characters such as underscore (_), non-ASCII, +or control characters. +.TP +.B inet6 +.\" Since glibc 2.2 +Sets +.B RES_USE_INET6 +in +.IR _res.options . +This has the effect of trying an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and of mapping IPv4 responses in IPv6 "tunneled form" +if no AAAA records are found but an A record set exists. +Since glibc 2.25, +.\" b76e065991ec01299225d9da90a627ebe6c1ac97 +this option is deprecated; applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.BR ip6\-bytestring " (since glibc 2.3.4 to glibc 2.24)" +Sets +.B RES_USEBSTRING +in +.IR _res.options . +This causes reverse IPv6 lookups to be made using the bit-label format +described in RFC\ 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR ip6\-dotint / no\-ip6\-dotint " (glibc 2.3.4 to glibc 2.24)" +Clear/set +.B RES_NOIP6DOTINT +in +.IR _res.options . +When this option is clear +.RB ( ip6\-dotint ), +reverse IPv6 lookups are made in the (deprecated) +.I ip6.int +zone; +when this option is set +.RB ( no\-ip6\-dotint ), +reverse IPv6 lookups are made in the +.I ip6.arpa +zone by default. +These options are available up to glibc 2.24, where +.B no\-ip6\-dotint +is the default. +Since +.B ip6\-dotint +support long ago ceased to be available on the Internet, +these options were removed in glibc 2.25. +.TP +.BR edns0 " (since glibc 2.6)" +Sets +.B RES_USE_EDNS0 +in +.IR _res.options . +This enables support for the DNS extensions described in RFC\ 2671. +.TP +.BR single\-request " (since glibc 2.10)" +Sets +.B RES_SNGLKUP +in +.IR _res.options . +By default, glibc performs IPv4 and IPv6 lookups in parallel since +glibc 2.9. +Some appliance DNS servers +cannot handle these queries properly and make the requests time out. +This option disables the behavior and makes glibc perform the IPv6 +and IPv4 requests sequentially (at the cost of some slowdown of the +resolving process). +.TP +.BR single\-request\-reopen " (since glibc 2.9)" +Sets +.B RES_SNGLKUPREOP +in +.IR _res.options . +The resolver uses the same socket for the A and AAAA requests. +Some hardware mistakenly sends back only one reply. +When that happens the client system will sit and wait for the second reply. +Turning this option on changes this behavior +so that if two requests from the same port are not handled correctly it will +close the socket and open a new one before sending the second request. +.TP +.BR no\-tld\-query " (since glibc 2.14)" +Sets +.B RES_NOTLDQUERY +in +.IR _res.options . +This option causes +.BR res_nsearch () +to not attempt to resolve an unqualified name +as if it were a top level domain (TLD). +This option can cause problems if the site has ``localhost'' as a TLD +rather than having localhost on one or more elements of the search list. +This option has no effect if neither RES_DEFNAMES or RES_DNSRCH is set. +.TP +.BR use\-vc " (since glibc 2.14)" +Sets +.B RES_USEVC +in +.IR _res.options . +This option forces the use of TCP for DNS resolutions. +.\" aef16cc8a4c670036d45590877d411a97f01e0cd +.TP +.BR no\-reload " (since glibc 2.26)" +Sets +.B RES_NORELOAD +in +.IR _res.options . +This option disables automatic reloading of a changed configuration file. +.TP +.BR trust\-ad " (since glibc 2.31)" +.\" 446997ff1433d33452b81dfa9e626b8dccf101a4 +Sets +.B RES_TRUSTAD +in +.IR _res.options . +This option controls the AD bit behavior of the stub resolver. +If a validating resolver sets the AD bit in a response, +it indicates that the data in the response was verified according +to the DNSSEC protocol. +In order to rely on the AD bit, the local system has to +trust both the DNSSEC-validating resolver and the network path to it, +which is why an explicit opt-in is required. +If the +.B trust\-ad +option is active, the stub resolver sets the AD bit in outgoing DNS +queries (to enable AD bit support), and preserves the AD bit in responses. +Without this option, the AD bit is not set in queries, +and it is always removed from responses before they are returned to the +application. +This means that applications can trust the AD bit in responses if the +.B trust\-ad +option has been set correctly. +.IP +In glibc 2.30 and earlier, +the AD is not set automatically in queries, +and is passed through unchanged to applications in responses. +.RE +.P +The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be +overridden on a per-process basis by setting the environment variable +.B LOCALDOMAIN +to a space-separated list of search domains. +.P +The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be +amended on a per-process basis by setting the environment variable +.B RES_OPTIONS +to a space-separated list of resolver options +as explained above under \fBoptions\fP. +.P +The keyword and value must appear on a single line, and the keyword +(e.g., \fBnameserver\fP) must start the line. +The value follows the keyword, separated by white space. +.P +Lines that contain a semicolon (;) or hash character (#) +in the first column are treated as comments. +.SH FILES +.IR /etc/resolv.conf , +.I +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolver (3), +.BR host.conf (5), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.P +Name Server Operations Guide for BIND diff --git a/upstream/fedora-40/man5/resolved.conf.5 b/upstream/fedora-40/man5/resolved.conf.5 new file mode 100644 index 00000000..cd0d5721 --- /dev/null +++ b/upstream/fedora-40/man5/resolved.conf.5 @@ -0,0 +1,389 @@ +'\" t +.TH "RESOLVED\&.CONF" "5" "" "systemd 255" "resolved.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +resolved.conf, resolved.conf.d \- Network Name Resolution configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/resolved\&.conf +.PP +/etc/systemd/resolved\&.conf\&.d/*\&.conf +.PP +/run/systemd/resolved\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/resolved\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These configuration files control local DNS and LLMNR name resolution\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +The following options are available in the [Resolve] section: +.PP +\fIDNS=\fR +.RS 4 +A space\-separated list of IPv4 and IPv6 addresses to use as system DNS servers\&. Each address can optionally take a port number separated with +":", a network interface name or index separated with +"%", and a Server Name Indication (SNI) separated with +"#"\&. When IPv6 address is specified with a port number, then the address must be in the square brackets\&. That is, the acceptable full formats are +"111\&.222\&.333\&.444:9953%ifname#example\&.com" +for IPv4 and +"[1111:2222::3333]:9953%ifname#example\&.com" +for IPv6\&. DNS requests are sent to one of the listed DNS servers in parallel to suitable per\-link DNS servers acquired from +\fBsystemd-networkd.service\fR(8) +or set at runtime by external applications\&. For compatibility reasons, if this setting is not specified, the DNS servers listed in +/etc/resolv\&.conf +are used instead, if that file exists and any servers are configured in it\&. This setting defaults to the empty list\&. +.sp +Added in version 213\&. +.RE +.PP +\fIFallbackDNS=\fR +.RS 4 +A space\-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers\&. Please see +\fIDNS=\fR +for acceptable format of addresses\&. Any per\-link DNS servers obtained from +\fBsystemd-networkd.service\fR(8) +take precedence over this setting, as do any servers set via +\fIDNS=\fR +above or +/etc/resolv\&.conf\&. This setting is hence only used if no other DNS server information is known\&. If this option is not given, a compiled\-in list of DNS servers is used instead\&. +.sp +Added in version 216\&. +.RE +.PP +\fIDomains=\fR +.RS 4 +A space\-separated list of domains, optionally prefixed with +"~", used for two distinct purposes described below\&. Defaults to the empty list\&. +.sp +Any domains +\fInot\fR +prefixed with +"~" +are used as search suffixes when resolving single\-label hostnames (domain names which contain no dot), in order to qualify them into fully\-qualified domain names (FQDNs)\&. These "search domains" are strictly processed in the order they are specified in, until the name with the suffix appended is found\&. For compatibility reasons, if this setting is not specified, the search domains listed in +/etc/resolv\&.conf +with the +\fIsearch\fR +keyword are used instead, if that file exists and any domains are configured in it\&. +.sp +The domains prefixed with +"~" +are called "route\-only domains"\&. All domains listed here (\fIboth search domains and route\-only domains\fR +after removing the +"~" +prefix) define a search path that preferably directs DNS queries to this interface\&. This search path has an effect only when suitable per\-link DNS servers are known\&. Such servers may be defined through the +\fIDNS=\fR +setting (see above) and dynamically at run time, for example from DHCP leases\&. If no per\-link DNS servers are known, route\-only domains have no effect\&. +.sp +Use the construct +"~\&." +(which is composed from +"~" +to indicate a route\-only domain and +"\&." +to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the DNS servers defined for this link preferably for all domains\&. +.sp +See "Protocols and Routing" in +\fBsystemd-resolved.service\fR(8) +for details of how search and route\-only domains are used\&. +.sp +Note that configuring the MulticastDNS domain +"local" +as search or routing domain has the effect of routing lookups for this domain to classic unicast DNS\&. This may be used to provide compatibility with legacy installations that use this domain in a unicast DNS context, against the IANA assignment of this domain to pure MulticastDNS purposes\&. Search and routing domains are a unicast DNS concept, they +\fIcannot\fR +be used to resolve single\-label lookups via MulticastDNS\&. +.sp +Added in version 229\&. +.RE +.PP +\fILLMNR=\fR +.RS 4 +Takes a boolean argument or +"resolve"\&. Controls Link\-Local Multicast Name Resolution support (\m[blue]\fBRFC 4795\fR\m[]\&\s-2\u[1]\d\s+2) on the local host\&. If true, enables full LLMNR responder and resolver support\&. If false, disables both\&. If set to +"resolve", only resolution support is enabled, but responding is disabled\&. Note that +\fBsystemd-networkd.service\fR(8) +also maintains per\-link LLMNR settings\&. LLMNR will be enabled on a link only if the per\-link and the global setting is on\&. +.sp +Added in version 216\&. +.RE +.PP +\fIMulticastDNS=\fR +.RS 4 +Takes a boolean argument or +"resolve"\&. Controls Multicast DNS support (\m[blue]\fBRFC 6762\fR\m[]\&\s-2\u[2]\d\s+2) on the local host\&. If true, enables full Multicast DNS responder and resolver support\&. If false, disables both\&. If set to +"resolve", only resolution support is enabled, but responding is disabled\&. Note that +\fBsystemd-networkd.service\fR(8) +also maintains per\-link Multicast DNS settings\&. Multicast DNS will be enabled on a link only if the per\-link and the global setting is on\&. +.sp +Added in version 234\&. +.RE +.PP +\fIDNSSEC=\fR +.RS 4 +Takes a boolean argument or +"allow\-downgrade"\&. +.sp +If set to true, all DNS lookups are DNSSEC\-validated locally (excluding LLMNR and Multicast DNS)\&. If the response to a lookup request is detected to be invalid a lookup failure is returned to applications\&. Note that this mode requires a DNS server that supports DNSSEC\&. If the DNS server does not properly support DNSSEC all validations will fail\&. +.sp +If set to +"allow\-downgrade", DNSSEC validation is attempted, but if the server does not support DNSSEC properly, DNSSEC mode is automatically disabled\&. Note that this mode makes DNSSEC validation vulnerable to "downgrade" attacks, where an attacker might be able to trigger a downgrade to non\-DNSSEC mode by synthesizing a DNS response that suggests DNSSEC was not supported\&. +.sp +If set to false, DNS lookups are not DNSSEC validated\&. In this mode, or when set to +"allow\-downgrade" +and the downgrade has happened, the resolver becomes security\-unaware and all forwarded queries have DNSSEC OK (DO) bit unset\&. +.sp +Note that DNSSEC validation requires retrieval of additional DNS data, and thus results in a small DNS lookup time penalty\&. +.sp +DNSSEC requires knowledge of "trust anchors" to prove data integrity\&. The trust anchor for the Internet root domain is built into the resolver, additional trust anchors may be defined with +\fBdnssec-trust-anchors.d\fR(5)\&. Trust anchors may change at regular intervals, and old trust anchors may be revoked\&. In such a case DNSSEC validation is not possible until new trust anchors are configured locally or the resolver software package is updated with the new root trust anchor\&. In effect, when the built\-in trust anchor is revoked and +\fIDNSSEC=\fR +is true, all further lookups will fail, as it cannot be proved anymore whether lookups are correctly signed, or validly unsigned\&. If +\fIDNSSEC=\fR +is set to +"allow\-downgrade" +the resolver will automatically turn off DNSSEC validation in such a case\&. +.sp +Client programs looking up DNS data will be informed whether lookups could be verified using DNSSEC, or whether the returned data could not be verified (either because the data was found unsigned in the DNS, or the DNS server did not support DNSSEC or no appropriate trust anchors were known)\&. In the latter case it is assumed that client programs employ a secondary scheme to validate the returned DNS data, should this be required\&. +.sp +It is recommended to set +\fIDNSSEC=\fR +to true on systems where it is known that the DNS server supports DNSSEC correctly, and where software or trust anchor updates happen regularly\&. On other systems it is recommended to set +\fIDNSSEC=\fR +to +"allow\-downgrade"\&. +.sp +In addition to this global DNSSEC setting +\fBsystemd-networkd.service\fR(8) +also maintains per\-link DNSSEC settings\&. For system DNS servers (see above), only the global DNSSEC setting is in effect\&. For per\-link DNS servers the per\-link setting is in effect, unless it is unset in which case the global setting is used instead\&. +.sp +Site\-private DNS zones generally conflict with DNSSEC operation, unless a negative (if the private zone is not signed) or positive (if the private zone is signed) trust anchor is configured for them\&. If +"allow\-downgrade" +mode is selected, it is attempted to detect site\-private DNS zones using top\-level domains (TLDs) that are not known by the DNS root server\&. This logic does not work in all private zone setups\&. +.sp +Defaults to +"no"\&. +.sp +Added in version 229\&. +.RE +.PP +\fIDNSOverTLS=\fR +.RS 4 +Takes a boolean argument or +"opportunistic"\&. If true all connections to the server will be encrypted\&. Note that this mode requires a DNS server that supports DNS\-over\-TLS and has a valid certificate\&. If the hostname was specified in +\fIDNS=\fR +by using the format +"address#server_name" +it is used to validate its certificate and also to enable Server Name Indication (SNI) when opening a TLS connection\&. Otherwise the certificate is checked against the server\*(Aqs IP\&. If the DNS server does not support DNS\-over\-TLS all DNS requests will fail\&. +.sp +When set to +"opportunistic" +DNS request are attempted to send encrypted with DNS\-over\-TLS\&. If the DNS server does not support TLS, DNS\-over\-TLS is disabled\&. Note that this mode makes DNS\-over\-TLS vulnerable to "downgrade" attacks, where an attacker might be able to trigger a downgrade to non\-encrypted mode by synthesizing a response that suggests DNS\-over\-TLS was not supported\&. If set to false, DNS lookups are send over UDP\&. +.sp +Note that DNS\-over\-TLS requires additional data to be send for setting up an encrypted connection, and thus results in a small DNS look\-up time penalty\&. +.sp +Note that in +"opportunistic" +mode the resolver is not capable of authenticating the server, so it is vulnerable to "man\-in\-the\-middle" attacks\&. +.sp +In addition to this global +\fIDNSOverTLS=\fR +setting +\fBsystemd-networkd.service\fR(8) +also maintains per\-link +\fIDNSOverTLS=\fR +settings\&. For system DNS servers (see above), only the global +\fIDNSOverTLS=\fR +setting is in effect\&. For per\-link DNS servers the per\-link setting is in effect, unless it is unset in which case the global setting is used instead\&. +.sp +Defaults to +"no"\&. +.sp +Added in version 239\&. +.RE +.PP +\fICache=\fR +.RS 4 +Takes a boolean or +"no\-negative" +as argument\&. If +"yes" +(the default), resolving a domain name which already got queried earlier will return the previous result as long as it is still valid, and thus does not result in a new network request\&. Be aware that turning off caching comes at a performance penalty, which is particularly high when DNSSEC is used\&. If +"no\-negative", only positive answers are cached\&. +.sp +Note that caching is turned off by default for host\-local DNS servers\&. See +\fICacheFromLocalhost=\fR +for details\&. +.sp +Added in version 231\&. +.RE +.PP +\fICacheFromLocalhost=\fR +.RS 4 +Takes a boolean as argument\&. If +"no" +(the default), and response cames from host\-local IP address (such as 127\&.0\&.0\&.1 or ::1), the result wouldn\*(Aqt be cached in order to avoid potential duplicate local caching\&. +.sp +Added in version 248\&. +.RE +.PP +\fIDNSStubListener=\fR +.RS 4 +Takes a boolean argument or one of +"udp" +and +"tcp"\&. If +"udp", a DNS stub resolver will listen for UDP requests on addresses 127\&.0\&.0\&.53 and 127\&.0\&.0\&.54, port 53\&. If +"tcp", the stub will listen for TCP requests on the same addresses and port\&. If +"yes" +(the default), the stub listens for both UDP and TCP requests\&. If +"no", the stub listener is disabled\&. +.sp +The DNS stub resolver on 127\&.0\&.0\&.53 provides the full feature set of the local resolver, which includes offering LLMNR/MulticastDNS resolution\&. The DNS stub resolver on 127\&.0\&.0\&.54 provides a more limited resolver, that operates in "proxy" mode only, i\&.e\&. it will pass most DNS messages relatively unmodified to the current upstream DNS servers and back, but not try to process the messages locally, and hence does not validate DNSSEC, or offer up LLMNR/MulticastDNS\&. (It will translate to DNS\-over\-TLS communication if needed however\&.) +.sp +Note that the DNS stub listener is turned off implicitly when its listening address and port are already in use\&. +.sp +Added in version 232\&. +.RE +.PP +\fIDNSStubListenerExtra=\fR +.RS 4 +Takes an IPv4 or IPv6 address to listen on\&. The address may be optionally prefixed with a protocol name ("udp" +or +"tcp") separated with +":"\&. If the protocol is not specified, the service will listen on both UDP and TCP\&. It may be also optionally suffixed by a numeric port number with separator +":"\&. When an IPv6 address is specified with a port number, then the address must be in the square brackets\&. If the port is not specified, then the service uses port 53\&. Note that this is independent of the primary DNS stub configured with +\fIDNSStubListener=\fR, and only configures +\fIadditional\fR +sockets to listen on\&. This option can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. Defaults to unset\&. +.sp +Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DNSStubListenerExtra=192\&.168\&.10\&.10 +DNSStubListenerExtra=2001:db8:0:f102::10 +DNSStubListenerExtra=192\&.168\&.10\&.11:9953 +DNSStubListenerExtra=[2001:db8:0:f102::11]:9953 +DNSStubListenerExtra=tcp:192\&.168\&.10\&.12 +DNSStubListenerExtra=udp:2001:db8:0:f102::12 +DNSStubListenerExtra=tcp:192\&.168\&.10\&.13:9953 +DNSStubListenerExtra=udp:[2001:db8:0:f102::13]:9953 +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 247\&. +.RE +.PP +\fIReadEtcHosts=\fR +.RS 4 +Takes a boolean argument\&. If +"yes" +(the default), +\fBsystemd\-resolved\fR +will read +/etc/hosts, and try to resolve hosts or address by using the entries in the file before sending query to DNS servers\&. +.sp +Added in version 240\&. +.RE +.PP +\fIResolveUnicastSingleLabel=\fR +.RS 4 +Takes a boolean argument\&. When false (the default), +\fBsystemd\-resolved\fR +will not resolve A and AAAA queries for single\-label names over classic DNS\&. Note that such names may still be resolved if search domains are specified (see +\fIDomains=\fR +above), or using other mechanisms, in particular via LLMNR or from +/etc/hosts\&. When true, queries for single\-label names will be forwarded to global DNS servers even if no search domains are defined\&. +.sp +This option is provided for compatibility with configurations where +\fIpublic DNS servers are not used\fR\&. Forwarding single\-label names to servers not under your control is not standard\-conformant, see +\m[blue]\fBIAB Statement\fR\m[]\&\s-2\u[3]\d\s+2, and may create a privacy and security risk\&. +.sp +Added in version 246\&. +.RE +.PP +StaleRetentionSec=\fISECONDS\fR +.RS 4 +Takes a duration value, which determines the length of time DNS resource records can be retained in the cache beyond their Time To Live (TTL)\&. This allows these records to be returned as stale records\&. By default, this value is set to zero, meaning that DNS resource records are not stored in the cache after their TTL expires\&. +.sp +This is useful when a DNS server failure occurs or becomes unreachable\&. In such cases, +\fBsystemd-resolved\fR(8) +continues to use the stale records to answer DNS queries, particularly when no valid response can be obtained from the upstream DNS servers\&. However, this doesn\*(Aqt apply to NXDOMAIN responses, as those are still perfectly valid responses\&. This feature enhances resilience against DNS infrastructure failures and outages\&. +.sp +\fBsystemd\-resolved\fR +always attempts to reach the upstream DNS servers first, before providing the client application with any stale data\&. If this feature is enabled, cache will not be flushed when changing servers\&. +.sp +Added in version 254\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-resolved.service\fR(8), +\fBsystemd-networkd.service\fR(8), +\fBdnssec-trust-anchors.d\fR(5), +\fBresolv.conf\fR(5) +.SH "NOTES" +.IP " 1." 4 +RFC 4795 +.RS 4 +\%https://tools.ietf.org/html/rfc4795 +.RE +.IP " 2." 4 +RFC 6762 +.RS 4 +\%https://tools.ietf.org/html/rfc6762 +.RE +.IP " 3." 4 +IAB Statement +.RS 4 +\%https://www.iab.org/documents/correspondence-reports-documents/2013-2/iab-statement-dotless-domains-considered-harmful/ +.RE diff --git a/upstream/fedora-40/man5/rpc.5 b/upstream/fedora-40/man5/rpc.5 new file mode 100644 index 00000000..15277eff --- /dev/null +++ b/upstream/fedora-40/man5/rpc.5 @@ -0,0 +1,83 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI; +.TH rpc 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +rpc \- RPC program number data base +.SH SYNOPSIS +.nf +.B /etc/rpc +.fi +.SH DESCRIPTION +The +.I rpc +file contains user readable names that +can be used in place of RPC program numbers. +Each line has the following information: +.P +.PD 0 +.IP \[bu] 3 +name of server for the RPC program +.IP \[bu] +RPC program number +.IP \[bu] +aliases +.PD +.P +Items are separated by any number of blanks and/or +tab characters. +A \[aq]#\[aq] indicates the beginning of a comment; characters from +the \[aq]#\[aq] to the end of the line are not interpreted by routines +which search the file. +.P +Here is an example of the +.I /etc/rpc +file from the Sun RPC Source distribution. +.P +.in +4n +.EX +# +# rpc 88/08/01 4.0 RPCSRC; from 1.12 88/02/07 SMI +# +portmapper 100000 portmap sunrpc +rstatd 100001 rstat rstat_svc rup perfmeter +rusersd 100002 rusers +nfs 100003 nfsprog +ypserv 100004 ypprog +mountd 100005 mount showmount +ypbind 100007 +walld 100008 rwall shutdown +yppasswdd 100009 yppasswd +etherstatd 100010 etherstat +rquotad 100011 rquotaprog quota rquota +sprayd 100012 spray +3270_mapper 100013 +rje_mapper 100014 +selection_svc 100015 selnsvc +database_svc 100016 +rexd 100017 rex +alis 100018 +sched 100019 +llockmgr 100020 +nlockmgr 100021 +x25.inr 100022 +statmon 100023 +status 100024 +bootparam 100026 +ypupdated 100028 ypupdate +keyserv 100029 keyserver +tfsd 100037 +nsed 100038 +nsemntd 100039 +.EE +.in +.SH FILES +.TP +.I /etc/rpc +RPC program number data base +.SH SEE ALSO +.BR getrpcent (3) diff --git a/upstream/fedora-40/man5/rsyncd.conf.5 b/upstream/fedora-40/man5/rsyncd.conf.5 new file mode 100644 index 00000000..249edd46 --- /dev/null +++ b/upstream/fedora-40/man5/rsyncd.conf.5 @@ -0,0 +1,1313 @@ +.TH "rsyncd.conf" "5" "20 Oct 2022" "rsyncd.conf from rsync 3.2.7" "User Commands" +.\" prefix=/usr +.P +.SH "NAME" +.P +rsyncd.conf \- configuration file for rsync in daemon mode +.P +.SH "SYNOPSIS" +.P +rsyncd.conf +.P +The online version of this manpage (that includes cross-linking of topics) +is available at https://download.samba.org/pub/rsync/rsyncd.conf.5. +.P +.SH "DESCRIPTION" +.P +The rsyncd.conf file is the runtime configuration file for rsync when run as an +rsync daemon. +.P +The rsyncd.conf file controls authentication, access, logging and available +modules. +.P +.SH "FILE FORMAT" +.P +The file consists of modules and parameters. A module begins with the name of +the module in square brackets and continues until the next module begins. +Modules contain parameters of the form \fBname\ =\ value\fP. +.P +The file is line-based\ \-\- that is, each newline-terminated line represents +either a comment, a module name or a parameter. +.P +Only the first equals sign in a parameter is significant. Whitespace before or +after the first equals sign is discarded. Leading, trailing and internal +whitespace in module and parameter names is irrelevant. Leading and trailing +whitespace in a parameter value is discarded. Internal whitespace within a +parameter value is retained verbatim. +.P +Any line \fBbeginning\fP with a hash (\fB#\fP) is ignored, as are lines containing +only whitespace. (If a hash occurs after anything other than leading +whitespace, it is considered a part of the line's content.) +.P +Any line ending in a \fB\\\fP is "continued" on the next line in the customary UNIX +fashion. +.P +The values following the equals sign in parameters are all either a string (no +quotes needed) or a boolean, which may be given as yes/no, 0/1 or true/false. +Case is not significant in boolean values, but is preserved in string values. +.P +.SH "LAUNCHING THE RSYNC DAEMON" +.P +The rsync daemon is launched by specifying the \fB\-\-daemon\fP option to rsync. +.P +The daemon must run with root privileges if you wish to use chroot, to bind to +a port numbered under 1024 (as is the default 873), or to set file ownership. +Otherwise, it must just have permission to read and write the appropriate data, +log, and lock files. +.P +You can launch it either via inetd, as a stand-alone daemon, or from an rsync +client via a remote shell. If run as a stand-alone daemon then just run the +command "\fBrsync\ \-\-daemon\fP" from a suitable startup script. +.P +When run via inetd you should add a line like this to /etc/services: +.RS 4 +.P +.nf +rsync 873/tcp +.fi +.RE +.P +and a single line something like this to /etc/inetd.conf: +.RS 4 +.P +.nf +rsync stream tcp nowait root /usr/bin/rsync rsyncd --daemon +.fi +.RE +.P +Replace "/usr/bin/rsync" with the path to where you have rsync installed on +your system. You will then need to send inetd a HUP signal to tell it to +reread its config file. +.P +Note that you should \fBnot\fP send the rsync daemon a HUP signal to force it to +reread the \fBrsyncd.conf\fP file. The file is re-read on each client connection. +.P +.SH "GLOBAL PARAMETERS" +.P +The first parameters in the file (before a [module] header) are the global +parameters. Rsync also allows for the use of a "[global]" module name to +indicate the start of one or more global-parameter sections (the name must be +lower case). +.P +You may also include any module parameters in the global part of the config +file in which case the supplied value will override the default for that +parameter. +.P +You may use references to environment variables in the values of parameters. +String parameters will have %VAR% references expanded as late as possible (when +the string is first used in the program), allowing for the use of variables +that rsync sets at connection time, such as RSYNC_USER_NAME. Non-string +parameters (such as true/false settings) are expanded when read from the config +file. If a variable does not exist in the environment, or if a sequence of +characters is not a valid reference (such as an un-paired percent sign), the +raw characters are passed through unchanged. This helps with backward +compatibility and safety (e.g. expanding a non-existent %VAR% to an empty +string in a path could result in a very unsafe path). The safest way to insert +a literal % into a value is to use %%. +.P +.IP "\fBmotd\ file\fP" +This parameter allows you to specify a "message of the day" (MOTD) to display +to clients on each connect. This usually contains site information and any +legal notices. The default is no MOTD file. This can be overridden by the +\fB\-\-dparam=motdfile=FILE\fP command-line option when starting the daemon. +.IP "\fBpid\ file\fP" +This parameter tells the rsync daemon to write its process ID to that file. +The rsync keeps the file locked so that it can know when it is safe to +overwrite an existing file. +.IP +The filename can be overridden by the \fB\-\-dparam=pidfile=FILE\fP command-line +option when starting the daemon. +.IP "\fBport\fP" +You can override the default port the daemon will listen on by specifying +this value (defaults to 873). This is ignored if the daemon is being run +by inetd, and is superseded by the \fB\-\-port\fP command-line option. +.IP "\fBaddress\fP" +You can override the default IP address the daemon will listen on by +specifying this value. This is ignored if the daemon is being run by +inetd, and is superseded by the \fB\-\-address\fP command-line option. +.IP "\fBsocket\ options\fP" +This parameter can provide endless fun for people who like to tune their +systems to the utmost degree. You can set all sorts of socket options which +may make transfers faster (or slower!). Read the manpage for the +\fBsetsockopt()\fP system call for details on some of the options you may be +able to set. By default no special socket options are set. These settings +can also be specified via the \fB\-\-sockopts\fP command-line option. +.IP "\fBlisten\ backlog\fP" +You can override the default backlog value when the daemon listens for +connections. It defaults to 5. +.P +.SH "MODULE PARAMETERS" +.P +After the global parameters you should define a number of modules, each module +exports a directory tree as a symbolic name. Modules are exported by specifying +a module name in square brackets [module] followed by the parameters for that +module. The module name cannot contain a slash or a closing square bracket. +If the name contains whitespace, each internal sequence of whitespace will be +changed into a single space, while leading or trailing whitespace will be +discarded. Also, the name cannot be "global" as that exact name indicates that +global parameters follow (see above). +.P +As with GLOBAL PARAMETERS, you may use references to environment variables in +the values of parameters. See the GLOBAL PARAMETERS section for more details. +.P +.IP "\fBcomment\fP" +This parameter specifies a description string that is displayed next to the +module name when clients obtain a list of available modules. The default is +no comment. +.IP "\fBpath\fP" +This parameter specifies the directory in the daemon's filesystem to make +available in this module. You must specify this parameter for each module +in \fBrsyncd.conf\fP. +.IP +If the value contains a "/./" element then the path will be divided at that +point into a chroot dir and an inner-chroot subdir. If \fBuse\ chroot\fP +is set to false, though, the extraneous dot dir is just cleaned out of the +path. An example of this idiom is: +.RS 4 +.IP +.nf +path = /var/rsync/./module1 +.fi +.RE +.IP +This will (when chrooting) chroot to "/var/rsync" and set the inside-chroot +path to "/module1". +.IP +You may base the path's value off of an environment variable by surrounding +the variable name with percent signs. You can even reference a variable +that is set by rsync when the user connects. For example, this would use +the authorizing user's name in the path: +.RS 4 +.IP +.nf +path = /home/%RSYNC_USER_NAME% +.fi +.RE +.IP +It is fine if the path includes internal spaces\ \-\- they will be retained +verbatim (which means that you shouldn't try to escape them). If your +final directory has a trailing space (and this is somehow not something you +wish to fix), append a trailing slash to the path to avoid losing the +trailing whitespace. +.IP "\fBuse\ chroot\fP" +If "use chroot" is true, the rsync daemon will chroot to the "path" before +starting the file transfer with the client. This has the advantage of +extra protection against possible implementation security holes, but it has +the disadvantages of requiring super-user privileges, of not being able to +follow symbolic links that are either absolute or outside of the new root +path, and of complicating the preservation of users and groups by name (see +below). +.IP +If \fBuse\ chroot\fP is not set, it defaults to trying to enable a chroot but +allows the daemon to continue (after logging a warning) if it fails. The +one exception to this is when a module's \fBpath\fP has a "/./" chroot +divider in it\ \-\- this causes an unset value to be treated as true for that +module. +.IP +Prior to rsync 3.2.7, the default value was "true". The new "unset" +default makes it easier to setup an rsync daemon as a non-root user or to +run a daemon on a system where chroot fails. Explicitly setting the value +to "true" in rsyncd.conf will always require the chroot to succeed. +.IP +It is also possible to specify a dot-dir in the module's "path" to +indicate that you want to chdir to the earlier part of the path and then +serve files from inside the latter part of the path (with sanitizing and +default symlink munging). This can be useful if you need some library dirs +inside the chroot (typically for uid & gid lookups) but don't want to put +the lib dir into the top of the served path (even though they can be hidden +with an \fBexclude\fP directive). However, a better choice for a modern +rsync setup is to use a \fBname\ converter\fP" and try to avoid inner lib +dirs altogether. See also the \fBdaemon\ chroot\fP parameter, which causes +rsync to chroot into its own chroot area before doing any path-related +chrooting. +.IP +If the daemon is serving the "/" dir (either directly or due to being +chrooted to the module's path), rsync does not do any path sanitizing or +(default) munging. +.IP +When it has to limit access to a particular subdir (either due to chroot +being disabled or having an inside-chroot path set), rsync will munge +symlinks (by default) and sanitize paths. Those that dislike munged +symlinks (and really, really trust their users to not break out of the +subdir) can disable the symlink munging via the "munge symlinks" +parameter. +.IP +When rsync is sanitizing paths, it trims ".." path elements from args that +it believes would escape the module hierarchy. It also substitutes leading +slashes in absolute paths with the module's path (so that options such as +\fB\-\-backup-dir\fP & \fB\-\-compare-dest\fP interpret an absolute path as rooted in +the module's "path" dir). +.IP +When a chroot is in effect \fIand\fP the "name converter" parameter is +\fInot\fP set, the "numeric ids" parameter will default to being enabled +(disabling name lookups). This means that if you manually setup +name-lookup libraries in your chroot (instead of using a name converter) +that you need to explicitly set \fBnumeric\ ids\ =\ false\fP for rsync to do name +lookups. +.IP +If you copy library resources into the module's chroot area, you should +protect them through your OS's normal user/group or ACL settings (to +prevent the rsync module's user from being able to change them), and then +hide them from the user's view via "exclude" (see how in the discussion of +that parameter). However, it's easier and safer to setup a name converter. +.IP "\fBdaemon\ chroot\fP" +This parameter specifies a path to which the daemon will chroot before +beginning communication with clients. Module paths (and any "use chroot" +settings) will then be related to this one. This lets you choose if you +want the whole daemon to be chrooted (with this setting), just the +transfers to be chrooted (with "use chroot"), or both. Keep in mind that +the "daemon chroot" area may need various OS/lib/etc files installed to +allow the daemon to function. By default the daemon runs without any +chrooting. +.IP "\fBproxy\ protocol\fP" +When this parameter is enabled, all incoming connections must start with a +V1 or V2 proxy protocol header. If the header is not found, the connection +is closed. +.IP +Setting this to \fBtrue\fP requires a proxy server to forward source IP +information to rsync, allowing you to log proper IP/host info and make use +of client-oriented IP restrictions. The default of \fBfalse\fP means that the +IP information comes directly from the socket's metadata. If rsync is not +behind a proxy, this should be disabled. +.IP +\fICAUTION\fP: using this option can be dangerous if you do not ensure that +only the proxy is allowed to connect to the rsync port. If any non-proxied +connections are allowed through, the client will be able to use a modified +rsync to spoof any remote IP address that they desire. You can lock this +down using something like iptables \fB\-uid-owner\ root\fP rules (for strict +localhost access), various firewall rules, or you can require password +authorization so that any spoofing by users will not grant extra access. +.IP +This setting is global. If you need some modules to require this and not +others, then you will need to setup multiple rsync daemon processes on +different ports. +.IP "\fBname\ converter\fP" +This parameter lets you specify a program that will be run by the rsync +daemon to do user & group conversions between names & ids. This script +is started prior to any chroot being setup, and runs as the daemon user +(not the transfer user). You can specify a fully qualified pathname or +a program name that is on the $PATH. +.IP +The program can be used to do normal user & group lookups without having to +put any extra files into the chroot area of the module \fIor\fP you can do +customized conversions. +.IP +The nameconvert program has access to all of the environment variables that +are described in the section on \fBpre-xfer\ exec\fP. This is useful if you +want to customize the conversion using information about the module and/or +the copy request. +.IP +There is a sample python script in the support dir named "nameconvert" that +implements the normal user & group lookups. Feel free to customize it or +just use it as documentation to implement your own. +.IP "\fBnumeric\ ids\fP" +Enabling this parameter disables the mapping of users and groups by name +for the current daemon module. This prevents the daemon from trying to +load any user/group-related files or libraries. This enabling makes the +transfer behave as if the client had passed the \fB\-\-numeric-ids\fP +command-line option. By default, this parameter is enabled for chroot +modules and disabled for non-chroot modules. Also keep in mind that +uid/gid preservation requires the module to be running as root (see "uid") +or for "fake super" to be configured. +.IP +A chroot-enabled module should not have this parameter set to false unless +you're using a "name converter" program \fIor\fP you've taken steps to ensure +that the module has the necessary resources it needs to translate names and +that it is not possible for a user to change those resources. +.IP "\fBmunge\ symlinks\fP" +This parameter tells rsync to modify all symlinks in the same way as the +(non-daemon-affecting) \fB\-\-munge-links\fP command-line option (using a method +described below). This should help protect your files from user trickery +when your daemon module is writable. The default is disabled when +"use chroot" is on with an inside-chroot path of "/", OR if "daemon chroot" +is on, otherwise it is enabled. +.IP +If you disable this parameter on a daemon that is not read-only, there are +tricks that a user can play with uploaded symlinks to access +daemon-excluded items (if your module has any), and, if "use chroot" is +off, rsync can even be tricked into showing or changing data that is +outside the module's path (as access-permissions allow). +.IP +The way rsync disables the use of symlinks is to prefix each one with the +string "/rsyncd-munged/". This prevents the links from being used as long +as that directory does not exist. When this parameter is enabled, rsync +will refuse to run if that path is a directory or a symlink to a directory. +When using the "munge symlinks" parameter in a chroot area that has an +inside-chroot path of "/", you should add "/rsyncd-munged/" to the exclude +setting for the module so that a user can't try to create it. +.IP +Note: rsync makes no attempt to verify that any pre-existing symlinks in +the module's hierarchy are as safe as you want them to be (unless, of +course, it just copied in the whole hierarchy). If you setup an rsync +daemon on a new area or locally add symlinks, you can manually protect your +symlinks from being abused by prefixing "/rsyncd-munged/" to the start of +every symlink's value. There is a perl script in the support directory of +the source code named "munge-symlinks" that can be used to add or remove +this prefix from your symlinks. +.IP +When this parameter is disabled on a writable module and "use chroot" is +off (or the inside-chroot path is not "/"), incoming symlinks will be +modified to drop a leading slash and to remove ".." path elements that +rsync believes will allow a symlink to escape the module's hierarchy. +There are tricky ways to work around this, though, so you had better trust +your users if you choose this combination of parameters. +.IP "\fBcharset\fP" +This specifies the name of the character set in which the module's +filenames are stored. If the client uses an \fB\-\-iconv\fP option, the daemon +will use the value of the "charset" parameter regardless of the character +set the client actually passed. This allows the daemon to support charset +conversion in a chroot module without extra files in the chroot area, and +also ensures that name-translation is done in a consistent manner. If the +"charset" parameter is not set, the \fB\-\-iconv\fP option is refused, just as if +"iconv" had been specified via "refuse options". +.IP +If you wish to force users to always use \fB\-\-iconv\fP for a particular module, +add "no-iconv" to the "refuse options" parameter. Keep in mind that this +will restrict access to your module to very new rsync clients. +.IP "\fBmax\ connections\fP" +This parameter allows you to specify the maximum number of simultaneous +connections you will allow. Any clients connecting when the maximum has +been reached will receive a message telling them to try later. The default +is 0, which means no limit. A negative value disables the module. See +also the "lock file" parameter. +.IP "\fBlog\ file\fP" +When the "log file" parameter is set to a non-empty string, the rsync +daemon will log messages to the indicated file rather than using syslog. +This is particularly useful on systems (such as AIX) where \fBsyslog()\fP +doesn't work for chrooted programs. The file is opened before \fBchroot()\fP +is called, allowing it to be placed outside the transfer. If this value is +set on a per-module basis instead of globally, the global log will still +contain any authorization failures or config-file error messages. +.IP +If the daemon fails to open the specified file, it will fall back to using +syslog and output an error about the failure. (Note that the failure to +open the specified log file used to be a fatal error.) +.IP +This setting can be overridden by using the \fB\-\-log-file=FILE\fP or +\fB\-\-dparam=logfile=FILE\fP command-line options. The former overrides all the +log-file parameters of the daemon and all module settings. The latter sets +the daemon's log file and the default for all the modules, which still +allows modules to override the default setting. +.IP "\fBsyslog\ facility\fP" +This parameter allows you to specify the syslog facility name to use when +logging messages from the rsync daemon. You may use any standard syslog +facility name which is defined on your system. Common names are auth, +authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user, +uucp, local0, local1, local2, local3, local4, local5, local6 and local7. +The default is daemon. This setting has no effect if the "log file" +setting is a non-empty string (either set in the per-modules settings, or +inherited from the global settings). +.IP "\fBsyslog\ tag\fP" +This parameter allows you to specify the syslog tag to use when logging +messages from the rsync daemon. The default is "rsyncd". This setting has +no effect if the "log file" setting is a non-empty string (either set in +the per-modules settings, or inherited from the global settings). +.IP +For example, if you wanted each authenticated user's name to be included in +the syslog tag, you could do something like this: +.RS 4 +.IP +.nf +syslog tag = rsyncd.%RSYNC_USER_NAME% +.fi +.RE +.IP "\fBmax\ verbosity\fP" +This parameter allows you to control the maximum amount of verbose +information that you'll allow the daemon to generate (since the information +goes into the log file). The default is 1, which allows the client to +request one level of verbosity. +.IP +This also affects the user's ability to request higher levels of \fB\-\-info\fP +and \fB\-\-debug\fP logging. If the max value is 2, then no info and/or debug +value that is higher than what would be set by \fB\-vv\fP will be honored by the +daemon in its logging. To see how high of a verbosity level you need to +accept for a particular info/debug level, refer to \fBrsync\ \-\-info=help\fP and +\fBrsync\ \-\-debug=help\fP. For instance, it takes max-verbosity 4 to be able to +output debug TIME2 and FLIST3. +.IP "\fBlock\ file\fP" +This parameter specifies the file to use to support the "max connections" +parameter. The rsync daemon uses record locking on this file to ensure that +the max connections limit is not exceeded for the modules sharing the lock +file. The default is \fB/var/run/rsyncd.lock\fP. +.IP "\fBread\ only\fP" +This parameter determines whether clients will be able to upload files or +not. If "read only" is true then any attempted uploads will fail. If +"read only" is false then uploads will be possible if file permissions on +the daemon side allow them. The default is for all modules to be read only. +.IP +Note that "auth users" can override this setting on a per-user basis. +.IP "\fBwrite\ only\fP" +This parameter determines whether clients will be able to download files or +not. If "write only" is true then any attempted downloads will fail. If +"write only" is false then downloads will be possible if file permissions +on the daemon side allow them. The default is for this parameter to be +disabled. +.IP +Helpful hint: you probably want to specify "refuse options = delete" for a +write-only module. +.IP "\fBopen\ noatime\fP" +When set to True, this parameter tells the rsync daemon to open files with +the O_NOATIME flag +(on systems that support it) to avoid changing the access time of the files +that are being transferred. If your OS does not support the O_NOATIME flag +then rsync will silently ignore this option. Note also that some +filesystems are mounted to avoid updating the atime on read access even +without the O_NOATIME flag being set. +.IP +When set to False, this parameters ensures that files on the server are not +opened with O_NOATIME. +.IP +When set to Unset (the default) the user controls the setting via +\fB\-\-open-noatime\fP. +.IP "\fBlist\fP" +This parameter determines whether this module is listed when the client +asks for a listing of available modules. In addition, if this is false, +the daemon will pretend the module does not exist when a client denied by +"hosts allow" or "hosts deny" attempts to access it. Realize that if +"reverse lookup" is disabled globally but enabled for the module, the +resulting reverse lookup to a potentially client-controlled DNS server may +still reveal to the client that it hit an existing module. The default is +for modules to be listable. +.IP "\fBuid\fP" +This parameter specifies the user name or user ID that file transfers to +and from that module should take place as when the daemon was run as root. +In combination with the "gid" parameter this determines what file +permissions are available. The default when run by a super-user is to +switch to the system's "nobody" user. The default for a non-super-user is +to not try to change the user. See also the "gid" parameter. +.IP +The RSYNC_USER_NAME environment variable may be used to request that rsync +run as the authorizing user. For example, if you want a rsync to run as +the same user that was received for the rsync authentication, this setup is +useful: +.RS 4 +.IP +.nf +uid = %RSYNC_USER_NAME% +gid = * +.fi +.RE +.IP "\fBgid\fP" +This parameter specifies one or more group names/IDs that will be used when +accessing the module. The first one will be the default group, and any +extra ones be set as supplemental groups. You may also specify a "\fB*\fP" as +the first gid in the list, which will be replaced by all the normal groups +for the transfer's user (see "uid"). The default when run by a super-user +is to switch to your OS's "nobody" (or perhaps "nogroup") group with no +other supplementary groups. The default for a non-super-user is to not +change any group attributes (and indeed, your OS may not allow a +non-super-user to try to change their group settings). +.IP +The specified list is normally split into tokens based on spaces and +commas. However, if the list starts with a comma, then the list is only +split on commas, which allows a group name to contain a space. In either +case any leading and/or trailing whitespace is removed from the tokens and +empty tokens are ignored. +.IP "\fBdaemon\ uid\fP" +This parameter specifies a uid under which the daemon will run. The daemon +usually runs as user root, and when this is left unset the user is left +unchanged. See also the "uid" parameter. +.IP "\fBdaemon\ gid\fP" +This parameter specifies a gid under which the daemon will run. The daemon +usually runs as group root, and when this is left unset, the group is left +unchanged. See also the "gid" parameter. +.IP "\fBfake\ super\fP" +Setting "fake super = yes" for a module causes the daemon side to behave as +if the \fB\-\-fake-super\fP command-line option had been specified. This allows +the full attributes of a file to be stored without having to have the +daemon actually running as root. +.IP "\fBfilter\fP" +The daemon has its own filter chain that determines what files it will let +the client access. This chain is not sent to the client and is independent +of any filters the client may have specified. Files excluded by the daemon +filter chain (\fBdaemon-excluded\fP files) are treated as non-existent if the +client tries to pull them, are skipped with an error message if the client +tries to push them (triggering exit code 23), and are never deleted from +the module. You can use daemon filters to prevent clients from downloading +or tampering with private administrative files, such as files you may add +to support uid/gid name translations. +.IP +The daemon filter chain is built from the "filter", "include from", +"include", "exclude from", and "exclude" parameters, in that order of +priority. Anchored patterns are anchored at the root of the module. To +prevent access to an entire subtree, for example, "\fB/secret\fP", you \fBmust\fP +exclude everything in the subtree; the easiest way to do this is with a +triple-star pattern like "\fB/secret/***\fP". +.IP +The "filter" parameter takes a space-separated list of daemon filter rules, +though it is smart enough to know not to split a token at an internal space +in a rule (e.g. "\fB\-\ /foo\ \ \-\ /bar\fP" is parsed as two rules). You may specify +one or more merge-file rules using the normal syntax. Only one "filter" +parameter can apply to a given module in the config file, so put all the +rules you want in a single parameter. Note that per-directory merge-file +rules do not provide as much protection as global rules, but they can be +used to make \fB\-\-delete\fP work better during a client download operation if +the per-dir merge files are included in the transfer and the client +requests that they be used. +.IP "\fBexclude\fP" +This parameter takes a space-separated list of daemon exclude patterns. As +with the client \fB\-\-exclude\fP option, patterns can be qualified with "\fB\-\ \fP" or +"\fB+\ \fP" to explicitly indicate exclude/include. Only one "exclude" parameter +can apply to a given module. See the "filter" parameter for a description +of how excluded files affect the daemon. +.IP "\fBinclude\fP" +Use an "include" to override the effects of the "exclude" parameter. Only +one "include" parameter can apply to a given module. See the "filter" +parameter for a description of how excluded files affect the daemon. +.IP "\fBexclude\ from\fP" +This parameter specifies the name of a file on the daemon that contains +daemon exclude patterns, one per line. Only one "exclude from" parameter +can apply to a given module; if you have multiple exclude-from files, you +can specify them as a merge file in the "filter" parameter. See the +"filter" parameter for a description of how excluded files affect the +daemon. +.IP "\fBinclude\ from\fP" +Analogue of "exclude from" for a file of daemon include patterns. Only one +"include from" parameter can apply to a given module. See the "filter" +parameter for a description of how excluded files affect the daemon. +.IP "\fBincoming\ chmod\fP" +This parameter allows you to specify a set of comma-separated chmod strings +that will affect the permissions of all incoming files (files that are +being received by the daemon). These changes happen after all other +permission calculations, and this will even override destination-default +and/or existing permissions when the client does not specify \fB\-\-perms\fP. +See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1) +manpage for information on the format of this string. +.IP "\fBoutgoing\ chmod\fP" +This parameter allows you to specify a set of comma-separated chmod strings +that will affect the permissions of all outgoing files (files that are +being sent out from the daemon). These changes happen first, making the +sent permissions appear to be different than those stored in the filesystem +itself. For instance, you could disable group write permissions on the +server while having it appear to be on to the clients. See the description +of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1) manpage for information +on the format of this string. +.IP "\fBauth\ users\fP" +This parameter specifies a comma and/or space-separated list of +authorization rules. In its simplest form, you list the usernames that +will be allowed to connect to this module. The usernames do not need to +exist on the local system. The rules may contain shell wildcard characters +that will be matched against the username provided by the client for +authentication. If "auth users" is set then the client will be challenged +to supply a username and password to connect to the module. A challenge +response authentication protocol is used for this exchange. The plain text +usernames and passwords are stored in the file specified by the +"secrets file" parameter. The default is for all users to be able to +connect without a password (this is called "anonymous rsync"). +.IP +In addition to username matching, you can specify groupname matching via a +\&'@' prefix. When using groupname matching, the authenticating username +must be a real user on the system, or it will be assumed to be a member of +no groups. For example, specifying "@rsync" will match the authenticating +user if the named user is a member of the rsync group. +.IP +Finally, options may be specified after a colon (:). The options allow you +to "deny" a user or a group, set the access to "ro" (read-only), or set the +access to "rw" (read/write). Setting an auth-rule-specific ro/rw setting +overrides the module's "read only" setting. +.IP +Be sure to put the rules in the order you want them to be matched, because +the checking stops at the first matching user or group, and that is the +only auth that is checked. For example: +.RS 4 +.IP +.nf +auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam +.fi +.RE +.IP +In the above rule, user joe will be denied access no matter what. Any user +that is in the group "guest" is also denied access. The user "admin" gets +access in read/write mode, but only if the admin user is not in group +"guest" (because the admin user-matching rule would never be reached if the +user is in group "guest"). Any other user who is in group "rsync" will get +read-only access. Finally, users susan, joe, and sam get the ro/rw setting +of the module, but only if the user didn't match an earlier group-matching +rule. +.IP +If you need to specify a user or group name with a space in it, start your +list with a comma to indicate that the list should only be split on commas +(though leading and trailing whitespace will also be removed, and empty +entries are just ignored). For example: +.RS 4 +.IP +.nf +auth users = , joe:deny, @Some Group:deny, admin:rw, @RO Group:ro +.fi +.RE +.IP +See the description of the secrets file for how you can have per-user +passwords as well as per-group passwords. It also explains how a user can +authenticate using their user password or (when applicable) a group +password, depending on what rule is being authenticated. +.IP +See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE +SHELL CONNECTION" in \fBrsync\fP(1) for information on how handle an +rsyncd.conf-level username that differs from the remote-shell-level +username when using a remote shell to connect to an rsync daemon. +.IP "\fBsecrets\ file\fP" +This parameter specifies the name of a file that contains the +username:password and/or @groupname:password pairs used for authenticating +this module. This file is only consulted if the "auth users" parameter is +specified. The file is line-based and contains one name:password pair per +line. Any line has a hash (#) as the very first character on the line is +considered a comment and is skipped. The passwords can contain any +characters but be warned that many operating systems limit the length of +passwords that can be typed at the client end, so you may find that +passwords longer than 8 characters don't work. +.IP +The use of group-specific lines are only relevant when the module is being +authorized using a matching "@groupname" rule. When that happens, the user +can be authorized via either their "username:password" line or the +"@groupname:password" line for the group that triggered the authentication. +.IP +It is up to you what kind of password entries you want to include, either +users, groups, or both. The use of group rules in "auth users" does not +require that you specify a group password if you do not want to use shared +passwords. +.IP +There is no default for the "secrets file" parameter, you must choose a +name (such as \fB/etc/rsyncd.secrets\fP). The file must normally not be +readable by "other"; see "strict modes". If the file is not found or is +rejected, no logins for an "auth users" module will be possible. +.IP "\fBstrict\ modes\fP" +This parameter determines whether or not the permissions on the secrets +file will be checked. If "strict modes" is true, then the secrets file +must not be readable by any user ID other than the one that the rsync +daemon is running under. If "strict modes" is false, the check is not +performed. The default is true. This parameter was added to accommodate +rsync running on the Windows operating system. +.IP "\fBhosts\ allow\fP" +This parameter allows you to specify a list of comma- and/or +whitespace-separated patterns that are matched against a connecting +client's hostname and IP address. If none of the patterns match, then the +connection is rejected. +.IP +Each pattern can be in one of six forms: +.IP +.RS +.IP o +a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address of +the form a:b:c::d:e:f. In this case the incoming machine's IP address +must match exactly. +.IP o +an address/mask in the form ipaddr/n where ipaddr is the IP address and n +is the number of one bits in the netmask. All IP addresses which match +the masked IP address will be allowed in. +.IP o +an address/mask in the form ipaddr/maskaddr where ipaddr is the IP +address and maskaddr is the netmask in dotted decimal notation for IPv4, +or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP +addresses which match the masked IP address will be allowed in. +.IP o +a hostname pattern using wildcards. If the hostname of the connecting IP +(as determined by a reverse lookup) matches the wildcarded name (using +the same rules as normal Unix filename matching), the client is allowed +in. This only works if "reverse lookup" is enabled (the default). +.IP o +a hostname. A plain hostname is matched against the reverse DNS of the +connecting IP (if "reverse lookup" is enabled), and/or the IP of the +given hostname is matched against the connecting IP (if "forward lookup" +is enabled, as it is by default). Any match will be allowed in. +.IP o +an '@' followed by a netgroup name, which will match if the reverse DNS +of the connecting IP is in the specified netgroup. +.RE +.IP +Note IPv6 link-local addresses can have a scope in the address +specification: +.RS 4 +.IP +.nf +fe80::1%link1 +fe80::%link1/64 +fe80::%link1/ffff:ffff:ffff:ffff:: +.fi +.RE +.IP +You can also combine "hosts allow" with "hosts deny" as a way to add +exceptions to your deny list. When both parameters are specified, the +"hosts allow" parameter is checked first and a match results in the client +being able to connect. A non-allowed host is then matched against the +"hosts deny" list to see if it should be rejected. A host that does not +match either list is allowed to connect. +.IP +The default is no "hosts allow" parameter, which means all hosts can +connect. +.IP "\fBhosts\ deny\fP" +This parameter allows you to specify a list of comma- and/or +whitespace-separated patterns that are matched against a connecting clients +hostname and IP address. If the pattern matches then the connection is +rejected. See the "hosts allow" parameter for more information. +.IP +The default is no "hosts deny" parameter, which means all hosts can +connect. +.IP "\fBreverse\ lookup\fP" +Controls whether the daemon performs a reverse lookup on the client's IP +address to determine its hostname, which is used for "hosts allow" & +"hosts deny" checks and the "%h" log escape. This is enabled by default, +but you may wish to disable it to save time if you know the lookup will not +return a useful result, in which case the daemon will use the name +"UNDETERMINED" instead. +.IP +If this parameter is enabled globally (even by default), rsync performs the +lookup as soon as a client connects, so disabling it for a module will not +avoid the lookup. Thus, you probably want to disable it globally and then +enable it for modules that need the information. +.IP "\fBforward\ lookup\fP" +Controls whether the daemon performs a forward lookup on any hostname +specified in an hosts allow/deny setting. By default this is enabled, +allowing the use of an explicit hostname that would not be returned by +reverse DNS of the connecting IP. +.IP "\fBignore\ errors\fP" +This parameter tells rsyncd to ignore I/O errors on the daemon when +deciding whether to run the delete phase of the transfer. Normally rsync +skips the \fB\-\-delete\fP step if any I/O errors have occurred in order to +prevent disastrous deletion due to a temporary resource shortage or other +I/O error. In some cases this test is counter productive so you can use +this parameter to turn off this behavior. +.IP "\fBignore\ nonreadable\fP" +This tells the rsync daemon to completely ignore files that are not +readable by the user. This is useful for public archives that may have some +non-readable files among the directories, and the sysadmin doesn't want +those files to be seen at all. +.IP "\fBtransfer\ logging\fP" +This parameter enables per-file logging of downloads and uploads in a +format somewhat similar to that used by ftp daemons. The daemon always +logs the transfer at the end, so if a transfer is aborted, no mention will +be made in the log file. +.IP +If you want to customize the log lines, see the "log format" parameter. +.IP "\fBlog\ format\fP" +This parameter allows you to specify the format used for logging file +transfers when transfer logging is enabled. The format is a text string +containing embedded single-character escape sequences prefixed with a +percent (%) character. An optional numeric field width may also be +specified between the percent and the escape letter (e.g. +"\fB%\-50n\ %8l\ %07p\fP"). In addition, one or more apostrophes may be specified +prior to a numerical escape to indicate that the numerical value should be +made more human-readable. The 3 supported levels are the same as for the +\fB\-\-human-readable\fP command-line option, though the default is for +human-readability to be off. Each added apostrophe increases the level +(e.g. "\fB%''l\ %'b\ %f\fP"). +.IP +The default log format is "\fB%o\ %h\ [%a]\ %m\ (%u)\ %f\ %l\fP", and a "\fB%t\ [%p]\ \fP" +is always prefixed when using the "log file" parameter. (A perl script +that will summarize this default log format is included in the rsync source +code distribution in the "support" subdirectory: rsyncstats.) +.IP +The single-character escapes that are understood are as follows: +.IP +.RS +.IP o +%a the remote IP address (only available for a daemon) +.IP o +%b the number of bytes actually transferred +.IP o +%B the permission bits of the file (e.g. rwxrwxrwt) +.IP o +%c the total size of the block checksums received for the basis file +(only when sending) +.IP o +%C the full-file checksum if it is known for the file. For older rsync +protocols/versions, the checksum was salted, and is thus not a useful +value (and is not displayed when that is the case). For the checksum to +output for a file, either the \fB\-\-checksum\fP option must be in-effect or +the file must have been transferred without a salted checksum being used. +See the \fB\-\-checksum-choice\fP option for a way to choose the algorithm. +.IP o +%f the filename (long form on sender; no trailing "/") +.IP o +%G the gid of the file (decimal) or "DEFAULT" +.IP o +%h the remote host name (only available for a daemon) +.IP o +%i an itemized list of what is being updated +.IP o +%l the length of the file in bytes +.IP o +%L the string "\fB\ \->\ SYMLINK\fP", "\fB\ =>\ HARDLINK\fP", or "" (where \fBSYMLINK\fP +or \fBHARDLINK\fP is a filename) +.IP o +%m the module name +.IP o +%M the last-modified time of the file +.IP o +%n the filename (short form; trailing "/" on dir) +.IP o +%o the operation, which is "send", "recv", or "del." (the latter includes +the trailing period) +.IP o +%p the process ID of this rsync session +.IP o +%P the module path +.IP o +%t the current date time +.IP o +%u the authenticated username or an empty string +.IP o +%U the uid of the file (decimal) +.RE +.IP +For a list of what the characters mean that are output by "%i", see the +\fB\-\-itemize-changes\fP option in the rsync manpage. +.IP +Note that some of the logged output changes when talking with older rsync +versions. For instance, deleted files were only output as verbose messages +prior to rsync 2.6.4. +.IP "\fBtimeout\fP" +This parameter allows you to override the clients choice for I/O timeout +for this module. Using this parameter you can ensure that rsync won't wait +on a dead client forever. The timeout is specified in seconds. A value of +zero means no timeout and is the default. A good choice for anonymous rsync +daemons may be 600 (giving a 10 minute timeout). +.IP "\fBrefuse\ options\fP" +This parameter allows you to specify a space-separated list of rsync +command-line options that will be refused by your rsync daemon. You may +specify the full option name, its one-letter abbreviation, or a wild-card +string that matches multiple options. Beginning in 3.2.0, you can also +negate a match term by starting it with a "!". +.IP +When an option is refused, the daemon prints an error message and exits. +.IP +For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various +delete options: +.RS 4 +.IP +.nf +refuse options = c delete +.fi +.RE +.IP +The reason the above refuses all delete options is that the options imply +\fB\-\-delete\fP, and implied options are refused just like explicit options. +.IP +The use of a negated match allows you to fine-tune your refusals after a +wild-card, such as this: +.RS 4 +.IP +.nf +refuse options = delete-* !delete-during +.fi +.RE +.IP +Negated matching can also turn your list of refused options into a list of +accepted options. To do this, begin the list with a "\fB*\fP" (to refuse all +options) and then specify one or more negated matches to accept. For +example: +.RS 4 +.IP +.nf +refuse options = * !a !v !compress* +.fi +.RE +.IP +Don't worry that the "\fB*\fP" will refuse certain vital options such as +\fB\-\-dry-run\fP, \fB\-\-server\fP, \fB\-\-no-iconv\fP, \fB\-\-seclude-args\fP, etc. These +important options are not matched by wild-card, so they must be overridden +by their exact name. For instance, if you're forcing iconv transfers you +could use something like this: +.RS 4 +.IP +.nf +refuse options = * no-iconv !a !v +.fi +.RE +.IP +As an additional aid (beginning in 3.2.0), refusing (or "\fB!refusing\fP") the +"a" or "archive" option also affects all the options that the \fB\-\-archive\fP +option implies (\fB\-rdlptgoD\fP), but only if the option is matched explicitly +(not using a wildcard). If you want to do something tricky, you can use +"\fBarchive*\fP" to avoid this side-effect, but keep in mind that no normal +rsync client ever sends the actual archive option to the server. +.IP +As an additional safety feature, the refusal of "delete" also refuses +\fBremove-source-files\fP when the daemon is the sender; if you want the latter +without the former, instead refuse "\fBdelete-*\fP" as that refuses all the +delete modes without affecting \fB\-\-remove-source-files\fP. (Keep in mind that +the client's \fB\-\-delete\fP option typically results in \fB\-\-delete-during\fP.) +.IP +When un-refusing delete options, you should either specify "\fB!delete*\fP" (to +accept all delete options) or specify a limited set that includes "delete", +such as: +.RS 4 +.IP +.nf +refuse options = * !a !delete !delete-during +.fi +.RE +.IP +\&... whereas this accepts any delete option except \fB\-\-delete-after\fP: +.RS 4 +.IP +.nf +refuse options = * !a !delete* delete-after +.fi +.RE +.IP +A note on refusing "compress": it may be better to set the "dont compress" +daemon parameter to "\fB*\fP" and ensure that \fBRSYNC_COMPRESS_LIST=zlib\fP is set +in the environment of the daemon in order to disable compression silently +instead of returning an error that forces the client to remove the \fB\-z\fP +option. +.IP +If you are un-refusing the compress option, you may want to match +"\fB!compress*\fP" if you also want to allow the \fB\-\-compress-level\fP option. +.IP +Note that the "copy-devices" & "write-devices" options are refused by +default, but they can be explicitly accepted with "\fB!copy-devices\fP" and/or +"\fB!write-devices\fP". The options "log-file" and "log-file-format" are +forcibly refused and cannot be accepted. +.IP +Here are all the options that are not matched by wild-cards: +.IP +.RS +.IP o +\fB\-\-server\fP: Required for rsync to even work. +.IP o +\fB\-\-rsh\fP, \fB\-e\fP: Required to convey compatibility flags to the server. +.IP o +\fB\-\-out-format\fP: This is required to convey output behavior to a remote +receiver. While rsync passes the older alias \fB\-\-log-format\fP for +compatibility reasons, this options should not be confused with +\fB\-\-log-file-format\fP. +.IP o +\fB\-\-sender\fP: Use "write only" parameter instead of refusing this. +.IP o +\fB\-\-dry-run\fP, \fB\-n\fP: Who would want to disable this? +.IP o +\fB\-\-seclude-args\fP, \fB\-s\fP: Is the oldest arg-protection method. +.IP o +\fB\-\-from0\fP, \fB\-0\fP: Makes it easier to accept/refuse \fB\-\-files-from\fP without +affecting this helpful modifier. +.IP o +\fB\-\-iconv\fP: This is auto-disabled based on "charset" parameter. +.IP o +\fB\-\-no-iconv\fP: Most transfers use this option. +.IP o +\fB\-\-checksum-seed\fP: Is a fairly rare, safe option. +.IP o +\fB\-\-write-devices\fP: Is non-wild but also auto-disabled. +.RE +.IP "\fBdont\ compress\fP" +\fBNOTE:\fP This parameter currently has no effect except in one instance: if +it is set to "\fB*\fP" then it minimizes or disables compression for all files +(for those that don't want to refuse the \fB\-\-compress\fP option completely). +.IP +This parameter allows you to select filenames based on wildcard patterns +that should not be compressed when pulling files from the daemon (no +analogous parameter exists to govern the pushing of files to a daemon). +Compression can be expensive in terms of CPU usage, so it is usually good +to not try to compress files that won't compress well, such as already +compressed files. +.IP +The "dont compress" parameter takes a space-separated list of +case-insensitive wildcard patterns. Any source filename matching one of the +patterns will be compressed as little as possible during the transfer. If +the compression algorithm has an "off" level, then no compression occurs +for those files. If an algorithms has the ability to change the level in +mid-stream, it will be minimized to reduce the CPU usage as much as +possible. +.IP +See the \fB\-\-skip-compress\fP parameter in the \fBrsync\fP(1) manpage for the +list of file suffixes that are skipped by default if this parameter is not +set. +.IP "\fBearly\ exec\fP, \fBpre-xfer\ exec\fP, \fBpost-xfer\ exec\fP" +You may specify a command to be run in the early stages of the connection, +or right before and/or after the transfer. If the \fBearly\ exec\fP or +\fBpre-xfer\ exec\fP command returns an error code, the transfer is aborted +before it begins. Any output from the \fBpre-xfer\ exec\fP command on stdout +(up to several KB) will be displayed to the user when aborting, but is +\fInot\fP displayed if the script returns success. The other programs cannot +send any text to the user. All output except for the \fBpre-xfer\ exec\fP +stdout goes to the corresponding daemon's stdout/stderr, which is typically +discarded. See the \fB\-\-no-detatch\fP option for a way to see the daemon's +output, which can assist with debugging. +.IP +Note that the \fBearly\ exec\fP command runs before any part of the transfer +request is known except for the module name. This helper script can be +used to setup a disk mount or decrypt some data into a module dir, but you +may need to use \fBlock\ file\fP and \fBmax\ connections\fP to avoid concurrency +issues. If the client rsync specified the \fB\-\-early-input=FILE\fP option, it +can send up to about 5K of data to the stdin of the early script. The +stdin will otherwise be empty. +.IP +Note that the \fBpost-xfer\ exec\fP command is still run even if one of the +other scripts returns an error code. The \fBpre-xfer\ exec\fP command will \fInot\fP +be run, however, if the \fBearly\ exec\fP command fails. +.IP +The following environment variables will be set, though some are specific +to the pre-xfer or the post-xfer environment: +.IP +.RS +.IP o +\fBRSYNC_MODULE_NAME\fP: The name of the module being accessed. +.IP o +\fBRSYNC_MODULE_PATH\fP: The path configured for the module. +.IP o +\fBRSYNC_HOST_ADDR\fP: The accessing host's IP address. +.IP o +\fBRSYNC_HOST_NAME\fP: The accessing host's name. +.IP o +\fBRSYNC_USER_NAME\fP: The accessing user's name (empty if no user). +.IP o +\fBRSYNC_PID\fP: A unique number for this transfer. +.IP o +\fBRSYNC_REQUEST\fP: (pre-xfer only) The module/path info specified by the +user. Note that the user can specify multiple source files, so the +request can be something like "mod/path1 mod/path2", etc. +.IP o +\fBRSYNC_ARG#\fP: (pre-xfer only) The pre-request arguments are set in these +numbered values. RSYNC_ARG0 is always "rsyncd", followed by the options +that were used in RSYNC_ARG1, and so on. There will be a value of "." +indicating that the options are done and the path args are beginning\ \-\- +these contain similar information to RSYNC_REQUEST, but with values +separated and the module name stripped off. +.IP o +\fBRSYNC_EXIT_STATUS\fP: (post-xfer only) the server side's exit value. This +will be 0 for a successful run, a positive value for an error that the +server generated, or a \-1 if rsync failed to exit properly. Note that an +error that occurs on the client side does not currently get sent to the +server side, so this is not the final exit status for the whole transfer. +.IP o +\fBRSYNC_RAW_STATUS\fP: (post-xfer only) the raw exit value from +\fBwaitpid()\fP. +.RE +.IP +Even though the commands can be associated with a particular module, they +are run using the permissions of the user that started the daemon (not the +module's uid/gid setting) without any chroot restrictions. +.IP +These settings honor 2 environment variables: use RSYNC_SHELL to set a +shell to use when running the command (which otherwise uses your +\fBsystem()\fP call's default shell), and use RSYNC_NO_XFER_EXEC to disable +both options completely. +.P +.SH "CONFIG DIRECTIVES" +.P +There are currently two config directives available that allow a config file to +incorporate the contents of other files: \fB&include\fP and \fB&merge\fP. Both allow +a reference to either a file or a directory. They differ in how segregated the +file's contents are considered to be. +.P +The \fB&include\fP directive treats each file as more distinct, with each one +inheriting the defaults of the parent file, starting the parameter parsing as +globals/defaults, and leaving the defaults unchanged for the parsing of the +rest of the parent file. +.P +The \fB&merge\fP directive, on the other hand, treats the file's contents as if it +were simply inserted in place of the directive, and thus it can set parameters +in a module started in another file, can affect the defaults for other files, +etc. +.P +When an \fB&include\fP or \fB&merge\fP directive refers to a directory, it will read in +all the \fB*.conf\fP or \fB*.inc\fP files (respectively) that are contained inside that +directory (without any recursive scanning), with the files sorted into alpha +order. So, if you have a directory named "rsyncd.d" with the files "foo.conf", +"bar.conf", and "baz.conf" inside it, this directive: +.RS 4 +.P +.nf +&include /path/rsyncd.d +.fi +.RE +.P +would be the same as this set of directives: +.RS 4 +.P +.nf +&include /path/rsyncd.d/bar.conf +&include /path/rsyncd.d/baz.conf +&include /path/rsyncd.d/foo.conf +.fi +.RE +.P +except that it adjusts as files are added and removed from the directory. +.P +The advantage of the \fB&include\fP directive is that you can define one or more +modules in a separate file without worrying about unintended side-effects +between the self-contained module files. +.P +The advantage of the \fB&merge\fP directive is that you can load config snippets +that can be included into multiple module definitions, and you can also set +global values that will affect connections (such as \fBmotd\ file\fP), or globals +that will affect other include files. +.P +For example, this is a useful /etc/rsyncd.conf file: +.RS 4 +.P +.nf +port = 873 +log file = /var/log/rsync.log +pid file = /var/lock/rsync.lock + +&merge /etc/rsyncd.d +&include /etc/rsyncd.d +.fi +.RE +.P +This would merge any \fB/etc/rsyncd.d/*.inc\fP files (for global values that should +stay in effect), and then include any \fB/etc/rsyncd.d/*.conf\fP files (defining +modules without any global-value cross-talk). +.P +.SH "AUTHENTICATION STRENGTH" +.P +The authentication protocol used in rsync is a 128 bit MD4 based challenge +response system. This is fairly weak protection, though (with at least one +brute-force hash-finding algorithm publicly available), so if you want really +top-quality security, then I recommend that you run rsync over ssh. (Yes, a +future version of rsync will switch over to a stronger hashing method.) +.P +Also note that the rsync daemon protocol does not currently provide any +encryption of the data that is transferred over the connection. Only +authentication is provided. Use ssh as the transport if you want encryption. +.P +You can also make use of SSL/TLS encryption if you put rsync behind an +SSL proxy. +.P +.SH "SSL/TLS Daemon Setup" +.P +When setting up an rsync daemon for access via SSL/TLS, you will need to +configure a TCP proxy (such as haproxy or nginx) as the front-end that handles +the encryption. +.P +.IP o +You should limit the access to the backend-rsyncd port to only allow the +proxy to connect. If it is on the same host as the proxy, then configuring +it to only listen on localhost is a good idea. +.IP o +You should consider turning on the \fBproxy\ protocol\fP rsync-daemon parameter if +your proxy supports sending that information. The examples below assume that +this is enabled. +.P +An example haproxy setup is as follows: +.RS 4 +.P +.nf +frontend fe_rsync-ssl + bind :::874 ssl crt /etc/letsencrypt/example.com/combined.pem + mode tcp + use_backend be_rsync + +backend be_rsync + mode tcp + server local-rsync 127.0.0.1:873 check send-proxy +.fi +.RE +.P +An example nginx proxy setup is as follows: +.RS 4 +.P +.nf +stream { + server { + listen 874 ssl; + listen [::]:874 ssl; + + ssl_certificate /etc/letsencrypt/example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/example.com/privkey.pem; + + proxy_pass localhost:873; + proxy_protocol on; # Requires rsyncd.conf "proxy protocol = true" + proxy_timeout 1m; + proxy_connect_timeout 5s; + } +} +.fi +.RE +.P +.SH "DAEMON CONFIG EXAMPLES" +.P +A simple rsyncd.conf file that allow anonymous rsync to a ftp area at +\fB/home/ftp\fP would be: +.RS 4 +.P +.nf +[ftp] + path = /home/ftp + comment = ftp export area +.fi +.RE +.P +A more sophisticated example would be: +.RS 4 +.P +.nf +uid = nobody +gid = nobody +use chroot = yes +max connections = 4 +syslog facility = local5 +pid file = /var/run/rsyncd.pid + +[ftp] + path = /var/ftp/./pub + comment = whole ftp area (approx 6.1 GB) + +[sambaftp] + path = /var/ftp/./pub/samba + comment = Samba ftp area (approx 300 MB) + +[rsyncftp] + path = /var/ftp/./pub/rsync + comment = rsync ftp area (approx 6 MB) + +[sambawww] + path = /public_html/samba + comment = Samba WWW pages (approx 240 MB) + +[cvs] + path = /data/cvs + comment = CVS repository (requires authentication) + auth users = tridge, susan + secrets file = /etc/rsyncd.secrets +.fi +.RE +.P +The /etc/rsyncd.secrets file would look something like this: +.RS 4 +.P +.nf +tridge:mypass +susan:herpass +.fi +.RE +.P +.SH "FILES" +.P +/etc/rsyncd.conf or rsyncd.conf +.P +.SH "SEE ALSO" +.P +\fBrsync\fP(1), \fBrsync-ssl\fP(1) +.P +.SH "BUGS" +.P +Please report bugs! The rsync bug tracking system is online at +https://rsync.samba.org/. +.P +.SH "VERSION" +.P +This manpage is current for version 3.2.7 of rsync. +.P +.SH "CREDITS" +.P +Rsync is distributed under the GNU General Public License. See the file +COPYING for details. +.P +An rsync web site is available at https://rsync.samba.org/ and its github +project is https://github.com/WayneD/rsync. +.P +.SH "THANKS" +.P +Thanks to Warren Stanley for his original idea and patch for the rsync daemon. +Thanks to Karsten Thygesen for his many suggestions and documentation! +.P +.SH "AUTHOR" +.P +Rsync was originally written by Andrew Tridgell and Paul Mackerras. Many +people have later contributed to it. It is currently maintained by Wayne +Davison. +.P +Mailing lists for support and development are available at +https://lists.samba.org/. diff --git a/upstream/fedora-40/man5/sane-abaton.5 b/upstream/fedora-40/man5/sane-abaton.5 new file mode 100644 index 00000000..c36bb9ae --- /dev/null +++ b/upstream/fedora-40/man5/sane-abaton.5 @@ -0,0 +1,142 @@ +.TH sane\-abaton 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-abaton +.SH NAME +sane\-abaton \- SANE backend for Abaton flatbed scanners +.SH DESCRIPTION +The +.B sane\-abaton +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Abaton flatbed scanners. At present, only the Scan +300/GS (8bit, 256 levels of gray) is fully supported, due to the +absence of programming information. The Scan 300/S (black and white) +is recognized, but support for it is untested. +.PP +If you own a Abaton scanner other than the ones listed above that +works with this backend, or if you own an Abaton scanner that does not +work with this backend, please contact +.IR sane\-devel@alioth-lists.debian.net +with the model number, so that arrangements can be made to include +support for it. Have a look at +.I http://www.sane\-project.org/mailing\-lists.html +concerning subscription to sane\-devel. +.PP +Abaton is out of business, and these scanners are not supported by +Everex (the parent company of Abaton), nor is there any programming +information to be found. This driver is therefore based on +information obtained by running Abaton's scanning desk accessory under +MacsBug and tracing the MacOS SCSI Manager calls it made during image +acquisition. +.PP +However, the protocol is very similar to, though not compatible with, +the one used by the Apple scanners, therefore, if this backend is ever +extended to support the other Abaton models (they also made a color +flatbed scanner), it may be possible to fill in some "missing pieces" +from the (quite detailed) Apple scanner documentation. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a SCSI +scanner. For SCSI scanners, the special device name must be a generic +SCSI device or a symlink to such a device. Under Linux, such a device +name takes a format such as +.I /dev/sga +or +.IR /dev/sg0 , +for example. See +.BR sane\-scsi (5) +for details. + +.SH CONFIGURATION +The contents of the +.I abaton.conf +file is a list of device names that correspond to Abaton scanners. +Empty lines and lines starting with a hash mark (#) are ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. + +.SH FILES +.TP +.I /etc/sane.d/abaton.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-abaton.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-abaton.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory separator +character, then the default directories are searched after the explicitly +specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_ABATON +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.SH BUGS +There are a few known ones, and definitely some unknown ones. +.TP +.B Scan area miscalculations +For the sake of programmer efficiency, this backend handles all +measurements in millimetres, and floors (rather than rounds) values to +avoid possible damage to the scanner mechanism. Therefore, it may not +be possible to scan to the extreme right or bottom edges of the page. +.TP +.B Cancelling the scan +This might not work correctly, or it might abort the frontend. The +former is more likely than the latter. +.PP +If you have found something that you think is a bug, please attempt to +recreate it with the SANE_DEBUG_ABATON environment variable set to +255, and send a report detailing the conditions surrounding the bug to +.IR sane\-devel@alioth-lists.debian.net . + +.SH TODO +.TP +.B Implement non-blocking support +.TP +.B Finish reverse-engineering the MacOS driver +This will allow me to add support for other models with reasonable +confidence that it will work, as well as to fully exploit the +information returned by the INQUIRY command. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR scanimage (1) + +.SH AUTHOR +The +.B sane\-abaton +backend was partially written by David Huggins-Daines, +based on the +.BR sane\-apple (5) +backend by Milon Firikis. diff --git a/upstream/fedora-40/man5/sane-agfafocus.5 b/upstream/fedora-40/man5/sane-agfafocus.5 new file mode 100644 index 00000000..62e784bf --- /dev/null +++ b/upstream/fedora-40/man5/sane-agfafocus.5 @@ -0,0 +1,188 @@ +.TH sane\-agfafocus 5 "10 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-agfafocus +.SH NAME +sane\-agfafocus \- SANE backend for AGFA Focus flatbed scanners +.SH DESCRIPTION +The +.B sane\-agfafocus +library implements a SANE (Scanner Access Now Easy) backend that +provides access to AGFA Focus flatbed scanners. At present, the following +scanners are supported from this backend: +.PP +.RS +AGFA Focus GS Scanner (6 bit gray scale) (untested) +.br +AGFA Focus Lineart Scanner (lineart) (untested) +.br +AGFA Focus II (8 bit gray scale) (untested) +.br +AGFA Focus Color (24 bit color 3-pass) +.br +AGFA Focus Color Plus (24 bit color 3-pass) +.br +.PP +Siemens S9036 (8 bit gray scale) (untested) +.br +.RE +.PP +The driver supports line art, 6bpp and 8bpp gray, 18bpp and 24bpp +color scans. +.PP +If you own a scanner other than the ones listed above that works with +this backend, please let us know by sending the scanner's model name, +SCSI id, and firmware revision to +.IR sane\-devel@alioth-lists.debian.net . +Have a look at +.I http://www.sane\-project.org/mailing\-lists.html +concerning subscription to sane\-devel. +.PP +All of these scanners are pre-SCSI-2, and do not even report properly +to SCSI Inquiry. This is typically evident in SCSI bus scans, where +the scanner will come up with only garbage as vendor and models strings. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. For SCSI scanners, the special device name must be a +generic SCSI device or a symlink to such a device. Under Linux, such +a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH CONFIGURATION +The contents of the +.I agfafocus.conf +file is a list of device names that correspond to AGFA Focus +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +/dev/scanner +.br +# this is a comment +.br +/dev/sge +.RE + +.PP +.SH FILES +.TP +.I /etc/sane.d/agfafocus.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib/libsane\-agfafocus.a +The static library implementing this backend. +.TP +.I /usr/lib/libsane\-agfafocus.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory separator +character, then the default directories are searched after the +explicitly specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_AGFAFOCUS +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. E.g., a value of 128 +requests all debug output to be printed. Smaller levels reduce verbosity. +.B SANE_DEBUG_AGFAFOCUS +values: + +.sp +.ft CR +.nf +Number Remark +\ + 0 print important errors (printed each time) + 1 print errors + 2 print sense + 3 print warnings + 4 print scanner-inquiry + 5 print information + 6 print less important information + 7 print called procedures + 8 print reader_process messages + 10 print called sane\-init-routines + 11 print called sane\-procedures + 12 print sane infos + 13 print sane option-control messages +.fi +.ft R + +.SH MISSING FUNCTIONALITY + +Uploading of dither matrices and tonecurves has been implemented, but +so far has not proven to be useful for anything. For this reason +these options have been disabled. + +.SH BUGS +The scanners that do not support disconnect have problems with SCSI +timeouts if the SCSI bus gets loaded, eg. if you do a kernel build at +the same time as scanning. To see if your scanner supports +disconnect, run +.I "SANE_DEBUG_AGFAFOCUS=128 scanimage \-L" +in a terminal and look for the "disconnect:" line. + +.SH DEBUG +If you have problems with SANE not detecting your scanner, make sure the +Artec backend is disabled. Somehow, this backend causes at least my scanner +not to respond correctly to SCSI inquiry commands. +.PP +If you encounter a bug please set the environment variable +.B SANE_DEBUG_AGFAFOCUS +to 128 and try to regenerate the problem. Then send me a report with the +log attached. +.PP +If you encounter a SCSI bus error or trimmed and/or displaced images please +also set the environment variable +.B SANE_DEBUG_SANEI_SCSI +to 128 before sending me the report. + +.SH TODO +.TP +.B More scanners? + +The AGFA ACS and ARCUS scanners are similar to the FOCUS scanners. +The driver could probably be extended to support these scanners +without too many changes. I do not have access to such scanners, and +cannot add support for it. However, if you are in possession of such +a scanner, I could be helpful in adding support for these scanners. + +The AGFA HORIZON scanners are SCSI-2 scanners, and it would probably +be easier to support these scanners in a SCSI-2 compliant backend. + +.SH SEE ALSO +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHOR +Ingo Schneider and Karl Anders \[/O]ygard. diff --git a/upstream/fedora-40/man5/sane-apple.5 b/upstream/fedora-40/man5/sane-apple.5 new file mode 100644 index 00000000..a78579df --- /dev/null +++ b/upstream/fedora-40/man5/sane-apple.5 @@ -0,0 +1,277 @@ +.TH sane\-apple 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-apple +.SH NAME +sane\-apple \- SANE backend for Apple flatbed scanners +.SH DESCRIPTION +The +.B sane\-apple +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Apple flatbed scanners. At present, the following +scanners are supported from this backend: +.PP +.br +.ft CR +.nf +--------------- ----- ------------------ ------ +AppleScanner 4bit 16 Shades of Gray +OneScanner 8bit 256 Shades of Gray +ColorOneScanner 24bit RGB color 3-pass +.fi +.ft R + +.PP +If you own a Apple scanner other than the ones listed above that +works with this backend, please let us know by sending the scanner's +model name, SCSI id, and firmware revision to +.IR sane\-devel@alioth-lists.debian.net . +See +.I http://www.sane\-project.org/mailing\-lists.html +for details on how to subscribe to sane\-devel. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. For SCSI +scanners, the special device name must be a generic SCSI device or a +symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH CONFIGURATION +The +.I apple.conf +file is a list of options and device names that correspond to Apple +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. +.PP +Options come in two flavors: global and positional ones. Global +options apply to all devices managed by the backend, whereas positional +options apply just to the most recently mentioned device. Note that +this means that the order in which the options appear matters! + +.SH SCSI ADAPTER TIPS +SCSI scanners are typically delivered with an ISA SCSI adapter. +Unfortunately, that adapter is not worth much since it is not +interrupt driven. It is sometimes possible to get the supplied card +to work, but without an interrupt line, scanning will put so much load on +the system that it becomes almost unusable for other tasks. +.SH FILES +.TP +.I /etc/sane.d/apple.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-apple.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-apple.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable is list of directories where SANE looks +for the configuration file. On *NIX systems, directory names are +separated by a colon (`:'), under OS/2 by a semi-colon (`;'). +If SANE_CONFIG_DIR is not set, SANE defaults to +searching the current working directory (".") and then +.IR /etc/sane.d . +If the value of $SANE_CONFIG_DIR ends with the separator +character, the default directories are searched after the directory list. +For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in that order). +.TP +.B SANE_DEBUG_APPLE +Controls the debug level. A value of 255 prints +all debug output. Smaller values reduce verbosity. Requires a +library compiled with debug support. + +.SH CURRENT STATUS +The apple backend is now in version 0.3 (Tue Jul 21 1998). Since +I only have the AppleScanner and not the other models (OneScanner, +ColorOneScanner) I can only develop/test for the AppleScanner effectively. +However with this release I almost completed the GUI part of all scanners. +Most of the functionality is there. At least OneScanner should scan +at the AppleScanner's compatible modes (LineArt, HalfTone, Gray16). My +personal belief is that with a slight touch of debugging the OneScanner +could be actually usable. The ColorOneScanner needs more work. AppleScanner +is of course almost fully supported. + +.SH MISSING FUNCTIONALITY +Currently all three models lack upload/download support. +.TP +.B AppleScanner +Cannot up/download a halftone pattern. +.TP +.B OneScanner +Cannot up/download halftone patterns or calibration vectors. +.TP +.B ColorOneScanner +Cannot up/download halftone patterns, calibration vectors, +custom Color Correction Tables (CCT) and of course custom gamma tables. +.TP +.B Park/UnPark (OneScanner, ColorOneScanner) +Some capabilities are missing. +.PP +The above functionalities are missing because I don't +have the hardware to experiment on. Another reason is my lack +of understanding as to how or if the SANE API provide means +to describe any array type besides gamma. + + +.SH UNSUPPORTED FEATURES +The following "features" will never be supported, at least while I maintain +the sane\-apple backend. +.TP +.B NoHome (AppleScanner) +The scanner lamp stays on and the carriage assembly remains where it stops +at the end of the scan. After two minutes, if the scanner does not receive +another SCAN command, the lamp goes off and the carriage returns to the home +position. +.TP +.B Compression (AppleScanner) +The Scanner can compress data with CCITT Group III one dimensional algorithm +(fax) and the Skip White Line algorithm. +.TP +.B Multiple Windows (AppleScanner) +AppleScanner may support multiple windows. It would be a cool feature +and a challenge for me to code if it could intermix different options +for different windows (scan areas). This way it could scan a document +in LineArt mode but the figures in it in Gray and at a different resolution. +Unfortunately this is impossible. +.TP +.B Scan Direction (OneScanner) +It controls the scan direction. (?) +.TP +.B Status/Reset Button (OneScanner) +This option controls the status of the button on the OneScanner model. You can +also reset the button status by software. + +.SH BUGS +SANE backend bugs are divided in two classes. We have +.B GUI +bugs and +.B scanner specific +bugs. +.PP +We know we have a GUI bug when a parameter is not showing up when it +should (active) or vice versa. Finding out which parameters are active +across various Apple modes and models from the documentation +.I ftp://ftpdev.info.apple.com/devworld/Technical_Documentation/Peripherals_Documentation/ +is an interesting exercise. I may have missed some dependencies. For example +of the threshold parameter the Apple Scanners Programming Guide says +nothing. I had to assume it is valid only in LineArt mode. +.PP +Scanner specific bugs are mostly due to mandatory round-offs in order to +scan. In the documentation in one place states that the width of the +scan area should be a byte multiple. In another place it says that the +width of the scan area should be an even byte multiple. Go figure... +.PP +Other sources of bugs are due to scsi communication, scsi connects and +disconnects. However the classical bugs are still there. So you may +encounter buffer overruns, null pointers, memory corruption and +.B SANE +API violations. +.TP +.B SIGSEGV on SliceBars +When you try to modify the scan area from the slice bar you have a nice +little cute core dump. I don't know why. If you select the scan area from +the preview window or by hand typing the numbers everything is fine. The +SIGSEGV happens deep in gtk library (gdk). I really cannot debug it. +.TP +.B Options too much +It is possible, especially for the ColorOneScanner, for the backend's +options panel to extend beyond your screen. It happens with mine +and I am running my X Server at 1024x768. What can I say? Try smaller +fonts in the X server, or virtual screens. +.TP +.B Weird SCSI behaviour +I am quoting David Myers Here... + +>> OS: FreeBSD 2.2.6 +.br +>> CC: egcs-1.02 +.br +Just wanted to follow up on this... I recently changed my SCSI card from +the Adaptec 2940UW to a dual-channel Symbios 786 chipset. When I started up +SANE with your driver, I managed to scan line art drawings okay, but Gray16 +scans led to a stream of SCSI error messages on the console, ultimately +hanging with a message saying the scanner wasn't releasing the SCSI bus. +This may be that the Symbios is simply less tolerant of ancient +hardware, or may be bugs in your driver or in SANE itself... + +.SH DEBUG +If you encounter a GUI bug please set the environmental variable +.B SANE_DEBUG_APPLE +to 255 and rerun the exact sequence of keystrokes +and menu selections to reproduce it. Then send me a report with the +log attached. +.PP +If you have an Apple Macintosh with the AppleScanners driver installed, +reporting to me which options are grayed out (inactive) in what modes +would be very helpful. +.PP +If you want to offer some help but you don't have a scanner, or you +don't have the model you would like to help with, or you are +a SANE developer and you just want to take a look at how the apple backend +looks like, goto to +.I apple.h +and #define the +.B NEUTRALIZE_BACKEND +macro. You can select the scanner model through the APPLE_MODEL_SELECT +macro. Available options are +.BR APPLESCANNER , +.BR ONESCANNER , +and +.BR COLORONESCANNER . +.PP +If you encounter a SCSI bus error or trimmed and/or displaced images please +set the environment variable SANE_DEBUG_SANEI_SCSI to 255 before sending me +the report. + +.SH TODO +.TP +.B Non Blocking Support +Make +.B sane\-apple +a non blocking backend. Properly support +.BR sane_set_io_mode () +and +.BR sane_get_select_fd () +.TP +.B Scan +Make scanning possible for all models in all supported modes. +.PP +Add other missing functionality + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHOR +The +.B sane\-apple +backend was written not entirely from scratch by +Milon Firikis. It is mostly based on the +.BR sane\-mustek (5) +backend from David Mosberger and Andreas Czechanowski diff --git a/upstream/fedora-40/man5/sane-artec.5 b/upstream/fedora-40/man5/sane-artec.5 new file mode 100644 index 00000000..73523f5a --- /dev/null +++ b/upstream/fedora-40/man5/sane-artec.5 @@ -0,0 +1,179 @@ +.TH sane\-artec 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-artec + +.SH NAME +sane\-artec \- SANE backend for Artec flatbed scanners + +.SH DESCRIPTION +The +.B sane\-artec +library implements a SANE (Scanner Access Now Easy) backend +that provides access to Artec/Ultima SCSI flatbed scanners. At present, +the following scanners are known to work at least partially with this backend: +.PP +.RS +* Artec A6000C +.br +* Artec A6000C PLUS +.br +* Artec ViewStation AT3 +.br +* BlackWidow BW4800SP (rebadged Artec AT3) +.br +* Artec ViewStation AT6 +.br +* Artec ViewStation AT12 +.br +* Artec AM12S +.br +* Plustek 19200S (rebadged Artec AM12S) +.RE +.PP +Although this manual page is generally updated with each release, +up-to-date information on new releases and extraneous helpful hints +are available from the backend homepage: +.IR http://www4.infi.net/~cpinkham/sane . + +.SH CONFIGURATION + +The contents of the +.I artec.conf +file are a list of device names that +correspond to Artec scanners. Empty lines and lines starting with a +hash mark (#) are ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. + +Sample file: +.br +.nf +# artec.conf +# +# this is a comment. +# +# this line says search for any SCSI devices which are scanners and have +# a vendor string of 'ULTIMA' +scsi ULTIMA +# +# the next line forces the backend to assume the next scanner found has +# the specified vendor string (useful for testing rebadged models). +vendor ULTIMA +# +# the next line forces the backend to assume the next scanner found has +# the specified model string (useful for testing rebadged models). +model AT3 +# +# now a line that actually specifies a device. The backend is going to +# assume this is an Artec/Ultima AT3 because we forced the vendor and +# model above. +/dev/scanner +# +# once we hit a scanner device line, the forced vendor and model +# string are +# 'forgotten', so the vendor and model for this next device will be +# determined from the result of a SCSI inquiry. +/dev/sge +# +.fi + +.SH SCSI ADAPTER TIPS + +Some Artec scanners come with an included SCSI adapter. If your scanner came +with a DTC ISA SCSI cards, you can probably use it with recent (>= 2.2.0) +kernels using the generic NCR5380 support. You must pass the following +boot argument to the kernel: "dtc3181e=0x2c0,0" +.br +I do not have any information on the PCI SCSI adapter included with some +newer Artec scanners. + +.SH FILES +.TP +.I /etc/sane.d/artec.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-artec.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-artec.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file is +searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_ARTEC +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. E.g., a value of 128 +requests all debug output to be printed. Smaller levels reduce verbosity: +.B SANE_DEBUG_ARTEC +values: + +.ft CR +.nf +Number Remark +\ + 0 print important errors + 1 print errors + 2 print sense + 3 print warnings + 4 print scanner-inquiry + 5 print information + 6 print less important information + 7 print major called procedures + 8 print all called procedures + 9 print procedure info/data messages + 10 print called sane\-init-routines + 11 print called sane\-procedures + 12 print sane infos + 13 print sane option-control messages +\ + 50 print verbose data/debug messages +\ + == 100 print software RGB calibration data + == 101 print raw data from scanner to artec.data.raw file +\ + == 128 print out all messages +.fi +.ft R +.PP +Example: +export SANE_DEBUG_ARTEC=13 + +.SH BUGS + +Known bugs in this release: A6000C+ users with firmware v1.92 or +earlier have problems with the backend, the cause has not been determined. +Sometimes the backend is not particularly robust, you can possibly lock up +the SCSI bus (and/or machine) by not having patience enough when scanning. +3-channel gamma correction is not implemented and single-channel gamma +correction is not totally working on models other than the AT3. + +.SH "SEE ALSO" +.BR sane (7) , +.BR sane\-scsi (5) + +.SH AUTHOR + +Chris Pinkham +.I diff --git a/upstream/fedora-40/man5/sane-artec_eplus48u.5 b/upstream/fedora-40/man5/sane-artec_eplus48u.5 new file mode 100644 index 00000000..7df45067 --- /dev/null +++ b/upstream/fedora-40/man5/sane-artec_eplus48u.5 @@ -0,0 +1,162 @@ +.TH sane\-artec_eplus48u 5 "11 Jul 2008" "" "SANE" +.SH NAME +sane\-artec_eplus48u \- SANE backend for the scanner Artec E+ 48U and re-badged models +.SH DESCRIPTION +The +.B sane\-artec_eplus48u +library implements a SANE (Scanner Access Now Easy) backend that provides +access to several USB flatbed scanners using the GT6816 chipset like the Artec E+ 48U. +These scanners have a contact image sensor (CIS). +.PP +A complete list of supported devices can be found on +.IR http://www.sane\-project.org/sane\-supported\-devices.html . +.PP +This is ALPHA software. Especially if you test new or untested scanners, keep +your hand at the scanner's plug and unplug it, if the head bumps at the end of +the scan area. +.PP +If you own a scanner other than the ones mentioned on the list that works with this +backend, please let us know this by sending the scanner's exact model name and +the USB vendor and product ids (e.g. from +.IR /proc/bus/usb/devices , +.BR sane\-find\-scanner (1) +or syslog) to me. Even if the scanner's name is only +slightly different from the models mentioned above, please let me know. +.PP +.SH KERNEL ISSUES +If libusb-0.1.6 or later is installed, this section can be skipped. The +scanner should be found by +.BR sane\-find\-scanner (1) +without further actions. For setting permissions and general USB information +look at +.BR sane\-usb (5). +.PP +When you are using the scanner module, a Linux kernel 2.4.12 or newer is +required. + +.SH FIRMWARE FILE +You need a firmware file for your scanner. That's a small file containing +software that will be uploaded to the scanner's memory. For the scanners +mentioned above, it's usually named +.I Artec48.usb +or +.IR 1200.usb . +You can find it on the installation CD that was provided by the manufacturer, +normally in the directory Win98, WinMe or similar. +If the Windows-driver is installed on your computer, then you can also +find the firmware file under +.IR c:\\windows\\system32\\drivers . + +.SH CONFIGURATION +The contents of the +.I artec_eplus48u.conf +file is a list of usb lines containing vendor and product ids that correspond +to USB scanners. The file can also contain option lines. Empty lines and +lines starting with a hash mark (#) are ignored. The scanners are +autodetected by +.I usb vendor_id product_id +statements which are already included into +.I artec_eplus48u.conf . +"vendor_id" and "product_id" are hexadecimal numbers that identify the scanner. +.PP +Every usb section can have additional options. +.TP +.B artecFirmwareFile /usr/share/sane/artec_eplus48u/Artec48.usb +The path to the firmware file. This option is required. +.TP +.B redGamma 1.0 +.TP +.B greenGamma 1.0 +.TP +.B blueGamma 1.0 +.TP +.B masterGamma 1.9 +These are the default gamma values. If you set the "Defaults" option with a frontend, +then the gamma options are reset to the values specified here. +.TP +.B redOffset 0x28 +.TP +.B greenOffset 0x2f +.TP +.B blueOffset 0x2f +.TP +.B redExposure 0xa7 +.TP +.B greenExposure 0x116 +.TP +.B blueExposure 0xdc +These are the default values for offset and exposure time. +You can change them (e.g. to speed up calibration) +if you don't want to save the calibration data permanently. +.TP +.B vendorString "Artec" +.TP +.B modelString "E+ 48U" +By default, the scanner is reported as "Artec E+ 48U". If you don't like this, e.g. +because you have an Tevion MD 9693, then change the options accordingly. +.SH FILES +.TP +.I /usr/local/etc/sane.d/artec_eplus48u.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/local/lib/sane/libsane\-artec_eplus48u.a +The static library implementing this backend. +.TP +.I /usr/local/lib/sane/libsane\-artec_eplus48u.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory +separator character, then the default directories are searched after +the explicitly specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_ARTEC_EPLUS48U +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_ARTEC_EPLUS48U=3 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) + +.SH AUTHOR +Michael Herder. +.br +This backend is based on the gt68xx test-program written by Sergey Vlasov, Andreas Nowack, and +David Stevenson. Thanks to everyone who tested the backend or reported bugs. +.br +This man page is based on man +.BR sane\-gt68xx (5), +written by Henning Meier-Geinitz. + +.SH BUGS +This backend has been tested on Linux only. If you are using it on a different platform, please +contact us. +.PP +Interpolation with 1200 dpi is weak. +.PP +Support for buttons is missing due to missing support in SANE. +.PP +Please contact us if you find a bug: +.IR http://www.sane\-project.org/bugs.html . diff --git a/upstream/fedora-40/man5/sane-as6e.5 b/upstream/fedora-40/man5/sane-as6e.5 new file mode 100644 index 00000000..f2607e30 --- /dev/null +++ b/upstream/fedora-40/man5/sane-as6e.5 @@ -0,0 +1,49 @@ +.TH sane\-as6e 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" + +.SH NAME +sane\-as6e \- SANE backend for using the Artec AS6E parallel port interface scanner. + +.SH DESCRIPTION +The +.B sane\-as6e +library implements a SANE (Scanner Access Now Easy) backend +that provides access to Artec AS6E flatbed scanner. +It requires the +.B as6edriver +program in order to operate. The +.B as6edriver +program is not included with the SANE +package. It can be found at +.IR http://as6edriver.sourceforge.net . +See the as6edriver documentation for technical information. +.PP +The +.B as6edriver +program must be in the path for executables +.RB ( $PATH ). +Especially if you run +.BR saned (8) +(the SANE network scanning daemon), take care to setup the path for +.BR inetd (8) +or +.BR xinetd (8) +correctly or place the program in a directory that is in the path. + +.SH FILES +.B as6edriver +\- driver program that controls the scanner. + +.SH SEE ALSO +.BR sane (7), +.BR as6edriver (5), +.BR saned (8), +.BR inetd (8), +.BR xinetd (8) +.br +.I http://as6edriver.sourceforge.net + +.SH AUTHOR +Eugene S. Weiss + +.SH EMAIL-CONTACT +.I yossarian@users.sourceforge.net diff --git a/upstream/fedora-40/man5/sane-avision.5 b/upstream/fedora-40/man5/sane-avision.5 new file mode 100644 index 00000000..d79a7d79 --- /dev/null +++ b/upstream/fedora-40/man5/sane-avision.5 @@ -0,0 +1,187 @@ +.TH sane\-avision 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-avision + +.SH NAME +sane\-avision \- SANE backend for Avision branded and Avision OEM +(HP, Minolta, Mitsubishi, UMAX and possibly more) flatbed and film scanners. + +.SH DESCRIPTION +The +.B sane\-avision +library implements a SANE (Scanner Access Now Easy) backend that +provides access to various Avision scanners and the Avision OEM +scanners labelled by HP, Minolta, Mitsubishi or Fujitsu. + +It is fully big-endian aware and in everyday use on PowerPC and SPARC +systems. + +.B I suggest you hold one hand on the power-button of the scanner while +.B you try the first scans \- especially with film-scanners! + +.SH CONFIGURATION + +The configuration file for this backend resides in +.IR /etc/sane.d/avision.conf . + +Its contents is a list of device names that correspond to Avision and Avision +compatible scanners and backend-options. Empty lines and lines starting with +a hash mark (#) are ignored. A sample configuration file is shown below: + +.nf + # this is a comment +\ + option force\-a4 + option force\-a3 + option skip\-adf + option disable\-gamma\-table + option disable\-calibration +\ + #scsi Vendor Model Type Bus Channel ID LUN + scsi AVISION + scsi HP + scsi /dev/scanner + usb 0x03f0 0x0701 +.fi + +.TP +force\-a4: +Forces the backend to overwrite the scanable area +returned by the scanner to ISO A4. Scanner that are +known to return bogus data are marked in the backend +so if you need this option please report this to the +backend maintainer. USE WITH CARE! +.TP +force\-a3: +Forces the backend to overwrite the scanable area +returned by the scanner to ISO A3. Scanner that are +known to return bogus data are marked in the backend +so if you need this option please report this to the +backend maintainer. USE WITH CARE! +.TP +skip\-adf: +Forces the backend to ignore an inconsistent ADF +status returned by the scanner (ADF not present, but +ADF model number non-zero). Without this option, the +backend will make several attempts to reset the ADF +and retry the query in this situation, and will fail +with a "not supported" error if the ADF still doesn't +respond. +.TP +disable\-gamma\-table: +Disables the usage of the scanner's gamma-table. You +might try this if your scans hang or only produce +random garbage. +.TP +disable\-calibration: +Disables the scanner's color calibration. You +might try this if your scans hang or only produce +random garbage. +.TP +Note: +Any option above modifies the default code-flow +for your scanner. The options should only be used +when you encounter problems with the default behavior +of the backend. Please report the need of +options to the backend-author so the backend can +be fixed as soon as possible. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I scsi scsi-spec + +.I usb usb-spec +.RE +.PP +Where +.I scsi-spec +is the path-name to a special device or a device ID for the device that +corresponds to a SCSI scanner. The special device name must be a generic +SCSI device or a symlink to such a device, for example on Linux +.I /dev/sga +or +.IR /dev/sg0 . +The device ID is the ID returned by the scanner, for example +"HP" or "AVISION". See +.BR sane\-scsi (5) +for details. +.TP +Note: +Since the backend now includes native USB access, +it is no longer needed \- even considered obsolete \- +to access USB scanner via the SCSI emulation (named +hpusbscsi on Linux) for Avision USB devices such as +the HP 53xx, HP 74xx or Minolta film-scanners. +.PP +.I usb-spec +is the USB device name, the vendor/product ID pair or the name used by +libusb corresponding to the USB scanner. For example "0x03f0 0x0701" or +"libusb:002:003". See +.BR sane\-usb (5) +for details. + +The program +.BR sane\-find\-scanner (1) +helps to find out the correct scsi or usb device name. + +A list with supported devices is built into the avision backend so +normally specifying an ID should not be necessary. + +.SH FILES +.TP +.I /etc/sane.d/avision.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-avision.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-avision.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_AVISION +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. +Higher debug levels increase the verbosity of the output. The debug +level 7 is the author's preferred value to debug backend problems. + +Example: +export SANE_DEBUG_AVISION=7 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-usb (5) +.br +.I http://exactcode.com/site/open_source/saneavision + +.SH MAINTAINER +Ren\['e] Rebe + +.SH AUTHOR +Ren\['e] Rebe and Meino Christian Cramer diff --git a/upstream/fedora-40/man5/sane-bh.5 b/upstream/fedora-40/man5/sane-bh.5 new file mode 100644 index 00000000..129c6a40 --- /dev/null +++ b/upstream/fedora-40/man5/sane-bh.5 @@ -0,0 +1,581 @@ +.TH sane\-bh 5 "10 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-bh +.SH NAME +sane\-bh \- SANE backend for Bell+Howell Copiscan II series document +scanners +.SH DESCRIPTION +The +.B sane\-bh +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Bell+Howell Copiscan II series document +scanners. The Copiscan II 6338 has been the primary scanner model +used during development and testing, but since the programming interface +for the entire series is consistent the backend should work for the +following scanner models: +.PP +.RS +COPISCAN II 6338 Duplex Scanner with ACE +.br +COPISCAN II 2135 Simplex Scanner +.br +COPISCAN II 2137(A) Simplex Scanner (with ACE) +.br +COPISCAN II 2138A Simplex Scanner with ACE +.br +COPISCAN II 3238 Simplex Scanner +.br +COPISCAN II 3338(A) Simplex Scanner (with ACE) +.br +.RE +.PP +If you have a Bell+Howell scanner and are able to test it with this +backend, please contact +.I sane\-devel@alioth-lists.debian.net +with the model number and testing results. Have a look at +.I http://www.sane\-project.org/mailing\-lists.html +concerning subscription to sane\-devel. Additionally, the author is +curious as to the likelihood of using this backend with the newer 4000 +and 8000 series scanners. If you have such a beast, please let me know. +.PP +The Bell+Howell Copiscan II series document scanners are high +volume, high throughput scanners designed for document scanning +applications. As such, they are lineart/grayscale scanners supporting +a fixed number of fairly low resolutions (e.g. 200/240/300dpi). +However, they do have a number of interesting and useful features +suited to needs of document imaging applications. +This backend attempts to support as many of these features as possible. +.PP +The main technical reference used in writing this backend is the +.B Bell and Howell Copiscan II Remote SCSI Controller (RSC) OEM +.B Technical Manual Version 1.5. +The Linux SCSI programming HOWTO, the SANE API documentation, and +SANE source code were also extremely valuable resources. + +.PP +The latest backend release, additional information and helpful hints +are available from the backend homepage: +.br +.RS +.I http://www.martoneconsulting.com/sane\-bh.html +.RE +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a SCSI +scanner. For SCSI scanners, the special device name must be a generic +SCSI device or a symlink to such a device. Under Linux, such a device +name takes a format such as +.I /dev/sga +or +.IR /dev/sg0 , +for example. See +.BR sane\-scsi (5) +for details. + +.SH OPTIONS +.TP +.B Scan Mode Options: +.TP +.B \-\-preview[=(yes|no)] [no] +Request a preview-quality scan. When preview is set to yes image +compression is disabled and the image is delivered in a +.B SANE_FRAME_GRAY +frame. +.TP +.B \-\-mode lineart|halftone [lineart] +Selects the scan mode (e.g., lineart,monochrome, or color). +.TP +.B \-\-resolution 200|240|300dpi [200] +Sets the resolution of the scanned image. Each scanner model supports +a list of standard resolutions; only these resolutions can be used. +.TP +.B \-\-compression none|g31d|g32d|g42d [none] +Sets the compression mode of the scanner. Determines the type of data +returned from the scanner. Values are: + +.RS +.br +.B none +\- uncompressed data \- delivered in a SANE_FRAME_GRAY frame +.br +.B g31d +\- CCITT G3 1 dimension (MH) \- delivered in a SANE_FRAME_G31D frame +.br +.B g32d +\- CCITT G3 2 dimensions (MR, K=4) \- delivered in a SANE_FRAME_G32D frame +.br +.B g42d +\- CCITT G4 (MMR) \- delivered in a SANE_FRAME_G42D frame +.br + +.BR NOTE : +The use of g31d, g32d, and g42d compression values causes the backend +to generate optional frame formats which may not be supported by all SANE +frontends. +.RE + +.TP +.B Geometry Options: +.TP +.B \-\-autoborder[=(yes|no)] [yes] +Enable/Disable automatic image border detection. When enabled, the RSC unit +automatically detects the image area and sets the window geometry to match. +.TP +.B \-\-paper\-size Custom|Letter|Legal|A3|A4|A5|A6|B4|B5 [Custom] +Specify the scan window geometry by specifying the paper size of the +documents to be scanned. +.TP +.B \-\-tl\-x 0..297.18mm [0] +Top-left x position of scan area. +.TP +.B \-\-tl\-y 0..431.8mm [0] +Top-left y position of scan area. +.TP +.B \-\-br\-x 0..297.18mm [297.18] +Bottom-right x position of scan area. +.TP +.B \-\-br\-y 0..431.8mm [431.8] +Bottom-right y position of scan area. +.TP +.B Feeder Options: +.TP +.B \-\-source Automatic Document Feeder|Manual Feed Tray [Automatic Document Feeder] +Selects the scan source (such as a document feeder). This option is provided +to allow multiple image scans with +.BR xsane (1); it has no other purpose. +.TP +.B \-\-batch[=(yes|no)] [no] +Enable/disable batch mode scanning. Batch mode allows scanning at maximum throughput +by buffering within the RSC unit. This option is recommended when performing multiple +pages scans until the feeder is emptied. +.TP +.B \-\-duplex[=(yes|no)] [no] +Enable duplex (dual-sided) scanning. The scanner takes an image of each side +of the document during a single pass through the scanner. The front page is +delivered followed by the back page. Most options, such as compression, +affect both the front and back pages. +.TP +.B \-\-timeout\-adf 0..255 [0] +Sets the timeout in seconds for the automatic document feeder (ADF). +The value 0 specifies the hardware default value which varies based +on the scanner model. +.TP +.B \-\-timeout\-manual 0..255 [0] +Sets the timeout in seconds for semi-automatic feeder. The value 0 specifies +the hardware default value which varies based on the scanner model. +.TP +.B \-\-check\-adf[=(yes|no)] [no] +Check ADF Status prior to starting scan using the OBJECT POSITION command. +Note that this feature requires RSC firmware level 1.5 or higher and dip +switch 4 must be in the on position. NOTE: This option has not been tested +extensively and may produce undesirable results. +.TP +.B Enhancement: +.TP +.B \-\-control\-panel[=(yes|no)] [yes] +Enables the scanner's control panel for selecting image enhancement +parameters. When the option is set to no the following options are +used to control image enhancement. See the Bell+Howell scanner users' +guide for complete information on ACE functionality. +.TP +.B \-\-ace\-function \-4..4 [3] +Specify the Automatic Contrast Enhancement (ACE) Function. +.TP +.B \-\-ace\-sensitivity 0..9 [5] +Specify the Automatic Contrast Enhancement (ACE) Sensitivity. +.TP +.B \-\-brightness 0..255 [0] +Controls the brightness of the acquired image. Ignored for ACE +capable scanners. +.TP +.B \-\-threshold 0..255 [0] +Select minimum-brightness to get a white point. Ignored for ACE +capable scanners. +.TP +.B \-\-contrast 0..255 [inactive] +Controls the contrast of the acquired image. This option is not +currently used by the scanner (and perhaps never will be). +.TP +.B \-\-negative[=(yes|no)] [no] +Swap black and white, yielding a reverse-video image. +.TP +.B Icon: +.TP +.B \-\-icon\-width 0..3600pel (in steps of 8) [0] +Width of icon (thumbnail) image in pixels. +.TP +.B \-\-icon\-length 0..3600pel (in steps of 8) [0] +Length of icon (thumbnail) image in pixels. +.TP +.B Barcode Options: +.TP +.B \-\-barcode\-search\-bar [none] +Specifies the barcode type to search for. If this option is +not specified, or specified with a value of none, then the barcode decoding +feature is completely disabled. The valid barcode type are: + +.RS +.br +.B none +.br +.B ean\-8 +.br +.B ean\-13 +.br +.B reserved\-ean\-add +.br +.B code39 +.br +.B code2\-5\-interleaved +.br +.B code2\-5\-3lines\-matrix +.br +.B code2\-5\-3lines\-datalogic +.br +.B code2\-5\-5lines\-industrial +.br +.B patchcode +.br +.B codabar +.br +.B codabar\-with\-start\-stop +.br +.B code39ascii +.br +.B code128 +.br +.B code2\-5\-5lines\-iata +.br +.RE +.TP +.B \-\-barcode\-search\-count 1..7 [3] +Number of times that the RSC performs the decoding algorithm. Specify +the smallest number possible to increase performance. If you are having +trouble recognizing barcodes, it is suggested that you increase this option +to its maximum value (7). +.TP +.B \-\-barcode\-search\-mode [horiz\-vert] +Chooses the orientation of barcodes to be searched. The valid orientations +are: + +.RS +.br +.B horiz\-vert +.br +.B horizontal +.br +.B vertical +.br +.B vert\-horiz +.RE +.TP +.B \-\-barcode\-hmin 0..1660mm [5] +Sets the barcode minimum height in millimeters (larger values increase +recognition speed). Of course the actual barcodes in the document must be +of sufficient size. +.TP +.B \-\-barcode\-search\-timeout 20..65535us [10000] +Sets the timeout for barcode searching in milliseconds. When the timeout +expires, the decoder will stop trying to decode barcodes. +.TP +.B \-\-section [] +Specifies a series of image sections. A section can be used to gather +a subset image or to provide a small area for barcode decoding. +Each section is specified in the following format (units are in millimeters): +.PP +.B x++[:functioncode...] +.PP +Multiple sections can be specified by separating them with commas. +.PP +For example +.B 76.2x25.4+50.8+0:frontbar +identifies an area 3 inches wide and 1 inch high with a top left corner +at the top of the page two inches from the left hand edge of the page. +This section will be used for barcode decoding on the front page only. +.PP +For example +.B 50.8x25.4+25.4+0:frontbar:front:g42d +identifies an area 2 inches wide and 1 inch high with a top left corner +at the top of the page one inch from the left hand edge of the page. +This section will be used for barcode decoding on the front page as well +as generating an image compressed in g42d format. +.PP +Ordinarily barcodes are searched in the entire image. However, when you +specify sections all barcode searching is done within the specific sections +identified. This can significantly speed up the decoding process. + +The following function codes are available: + +.RS +.br +.B front +\- generate an image for the front page section +.br +.B back +\- generate an image for the back page section +.br +.B frontbar +\- perform barcode search in front page section +.br +.B backbar +\- perform barcode search in back page section +.br +.B frontpatch +\- perform patchcode search in front page section +.br +.B backpatch +\- perform patchcode search in back page section +.br +.B none +\- use no image compression +.br +.B g31d +\- use Group 3 1 dimension image compression +.br +.B g32d +\- use Group 3 2 dimensions image compression +.br +.B g42d +\- use Group 4 2 dimensions image compression +.br +.RE +.PP +If you omit a compression functioncode, the full page compression setting +is used. If you specify multiple compression functioncodes, only the +last one is used. + +.TP +.B \-\-barcode\-relmax 0..255 [0] +Specifies the maximum relation from the widest to the smallest bar. +.TP +.B \-\-barcode\-barmin 0..255 [0] +Specifies the minimum number of bars in Bar/Patch code. +.TP +.B \-\-barcode\-barmax 0..255 [0] +Specifies the maximum number of bars in a Bar/Patch code. +.TP +.B \-\-barcode\-contrast 0..6 [3] +Specifies the image contrast used in decoding. Use higher values when +there are more white pixels in the code. +.TP +.B \-\-barcode\-patchmode 0..1 [0] +Controls Patch Code detection. + +.SH CONFIGURATION +The contents of the +.I bh.conf +file is a list of device names that correspond to Bell+Howell +scanners. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. +Additionally, options can be specified; these lines begin with the word "option". +Each option is described in detail below. Empty lines and lines starting +with a hash mark (#) are ignored. + +.SH OPTIONS +The following options can be specified in the +.I bh.conf +file. +.TP +.B disable\-optional\-frames +This option prevents the backend from sending any optional frames. This +option may be useful when dealing with frontends which do not support these +optional frames. When this option is in effect, the data is sent in a +.B SANE_FRAME_GRAY +frame. The optional frames sent by this backend are: +.BR SANE_FRAME_G31D ", " SANE_FRAME_G32D ", " SANE_FRAME_G42D " and " SANE_FRAME_TEXT . +These frames are generated based on the compression and barcode options. +These frames are never sent in preview mode. +.TP +.B fake\-inquiry +This option is used for debugging purposes and its use is not encouraged. +Essentially, it allows the backend to initialize in the absence of +a scanner. This is useful for development and not much else. +This option must be specified earlier in the configuration file than +the devices which are to be "faked". + +.SH FILES +.TP +.I /etc/sane.d/bh.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-bh.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-bh.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory +separator character, then the default directories are searched after +the explicitly specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_BH +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.SH "SUPPORTED FEATURES" +.TP +.B ADF support +With document scanners, automatic document feeder (ADF) support is a key +feature. The backend supports the ADF by default and returns +.B SANE_STATUS_NO_DOCS +when the out-of-paper condition is detected. The SANE frontend +.BR scanadf (1) +is a command line frontend that supports multi-page scans. It has been +used successfully with this backend. The SANE frontend +.BR xsane (1) +is an improved GUI frontend by Oliver Rauch. Support for multi-page +scans is included in xsane version 0.35 and above. + +.TP +.B Duplex scanning +Some models, such as the COPISCAN II 6338, support duplex scanning. That +is, they scan both sides of the document during a single pass through the +scanner (the scanner has two cameras). This backend supports duplex +scanning (with the +.B \-\-duplex +option). The front and back page images are delivered consecutively +as if they were separately scanned pages. + +.TP +.B Hardware compression +The scanner is capable of compressing the data into several industry +standard formats (CCITT G3, CCITT G3-2D, CCITT G4). This results in +increased performance as less data is passed from the scanner to the +host over the SCSI bus. The backend supports these compression formats +via the +.B \-\-g31d, \-\-g32d, \-\-g42d +options, respectively. Many SANE frontends are not equipped to deal with +these formats, however. The SANE frontend +.BR scanadf (1) +supports these optional frame formats. The compressed image data +is written directly to a file and can then be processed by a scan-script +using the +.B \-\-scan\-script +option. Examples of this are given on the +.BR scanadf (1) +homepage. + +.TP +.B Automatic Border Detection +The scanner can automatically detect the paper size and adjust the +scanning window geometry appropriately. The backend supports this +useful feature with the +.B \-\-autoborder +option. It is enabled by default. + +.TP +.B Batch Mode Scanning +The batch scan mode allows for maximum throughput. The Set Window +parameters must remain constant during the entire batch. + +.TP +.B Icon Generation +The Icon function generates a thumbnail of the full page image, that can be +transferred as if it were a separate page. This allows the host to +quickly display a thumbnail representation during the scanning operation. +Perhaps this would be a great way of implementing a preview scan, but +since a normal scan is so quick, it might not be worth the trouble. + +.TP +.B Multiple Sections +Multiple sections (scanning sub-windows) can be defined for the front and +back pages. Each section can have different characteristics (e.g. geometry, +compression). The sections are returned as if they were separately +scanned images. Additionally sections can be used to greatly enhance the +accuracy and efficiency of the barcode/patchcode decoding process by +limiting the search area to a small subset of the page. Most Copiscan II +series scanners support up to 8 user-defined sections. + +.TP +.B Support Barcode/Patchcode Decoding +The RSC unit can recognize Bar and Patch Codes of various types embedded +in the scanned image. The codes are decoded and the data is returned to +the frontend as a text frame. The text is encoded in xml and contains +a great deal of information about the decoded data such as the location +where it was found, its orientation, and the time it took to find. +Further information on the content of this text frame as well as some +barcode decoding examples can be found on the backend homepage. + +.SH LIMITATIONS +.TP +.B Decoding a single barcode type per scan +The RSC unit can search for up to six different barcode types at a time. +While the code generally supports this as well, the +.B \-\-barcode\-search\-bar +option only allows the user to specify a single barcode type. +Perhaps another option which allows a comma separated list of barcode +type codes could be added to address this. +.TP +.B Scanning a fixed number of pages in batch mode +The separation of front and back end functionality in SANE presents a +problem in supporting the 'cancel batch' functionality in the scanner. +In batch mode, the scanner is always a page ahead of the host. The host, +knowing ahead of time which page will be the last, can cancel batch mode +prior to initiating the last scan command. Currently, there is no mechanism +available for the frontend to pass this knowledge to the backend. +If batch mode is enabled and the +.B \-\-end\-count +terminates a scanadf session, +an extra page will be pulled through the scanner, but is neither read +nor delivered to the frontend. The issue can be avoided by specifying +.B \-\-batch=no +when scanning a fixed number of pages. +.TP +.B Revision 1.2 Patch detector +There is an enhanced patchcode detection algorithm available in the RSC +with revision 1.2 or higher that is faster and more reliable than the +standard Bar/Patch code decoder. This is not currently supported. + +.SH BUGS +This is a new backend; detailed bug reports are welcome -- and expected ;) +.PP +If you have found something that you think is a bug, please attempt to +recreate it with the +.B SANE_DEBUG_BH +environment variable set to 255, and send a report detailing the conditions +surrounding the bug to +.IR sane\-devel@alioth-lists.debian.net . + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR scanimage (1), +.BR scanadf (1), +.BR xsane (1) + +.SH AUTHOR +The +.B sane\-bh backend +was written by Tom Martone, based on the +.BR sane\-ricoh (5) +backend by Feico W. Dillema and the bnhscan program by Sean Reifschneider +of tummy.com ltd. Some 8000 enhancements added by Mark Temple. diff --git a/upstream/fedora-40/man5/sane-canon.5 b/upstream/fedora-40/man5/sane-canon.5 new file mode 100644 index 00000000..8a78007a --- /dev/null +++ b/upstream/fedora-40/man5/sane-canon.5 @@ -0,0 +1,111 @@ +.TH sane\-canon 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-canon +.SH NAME +sane\-canon \- SANE backend for Canon SCSI scanners +.SH DESCRIPTION +The +.B sane\-canon +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the following Canon flatbed and film scanners: +.PP +.RS +CanoScan 300 +.br +CanoScan 600 +.br +CanoScan FB620S +.br +CanoScan FB1200S +.br +CanoScan FS2700F +.br +CanoScan FS2710S +.br +.RE +.PP +Parallel port and USB scanners are not supported by this backend; see +the manual pages for +.BR sane\-canon_pp (5) +and +.BR sane\-canon630u (5) +for further information. +.PP +IMPORTANT: This is beta code. We tested the code on the scanners listed +above, using the computers and operating systems available to us, but we +cannot guarantee that the backend will work smoothly with future operating +systems, SCSI adapters, SANE frontend programs, or Canon scanners not +contained in the list above. In some cases your computer might even hang. +It cannot be excluded (although we consider it extremely unlikely) that your +scanner will be damaged. +.PP +That said, TESTERS ARE WELCOME. Send your bug reports and comments to +Manuel Panea +.IR ; +for questions concerning the FB620 and FB1200S contact Mitsuru Okaniwa +.IR , +for the FS2710S Ulrich Deiters +.IR . + +.SH TIPS (FS2700F) +.PP +Scanning either slides or negatives has been found to require rather +large gamma corrections of about 2.2 to 2.4 (same value for red, green, +and blue). It is recommended to use the automatic exposure controls +of the frontend +.BR xsane (1) +for best results. +.PP +The "Auto Focus" function triggers a special pass to determine the focus +value. After that, the real scanning pass takes place. +.PP +Even with "Auto Focus" turned on, the scanned image is often a bit too +blurred. Using the +.BR gimp (1) +to do a "Filter->Enhance->Sharpen" at about 40 to 60 improves the image +considerably. + +.SH TIPS (FS2710S) +.PP +Gamma corrections are done not by the scanner, but by the backend. +The scanner is always run in 12-bit mode. In "color" mode the image +data are corrected for gamma, shadow point, etc., and then truncated +to 8-bit intensities; the default gamma value is 2.0. In "raw" mode the +image data are exported without corrections as 16-bit intensities; this +mode can be recommended if extensive adjustments have to be made to a +picture (and if the frontend can handle 16-bit intensities). +.PP +Negatives are handled by simple color inversion and will require manual +removal of blue discoloration. +.PP +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-canon.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-canon.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_CANON +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_CANON=4 + +.SH "SEE ALSO" +.BR sane\-scsi (5) +.br +.I http://www.rzg.mpg.de/~mpd/sane/doc/canon.install2700F.txt +(installation of a CanoScan 2700F) +.br +.SH AUTHOR +Helmut Koeberle, Manuel Panea, and Markus Mertinat; +.br +FB620S and FB1200S support by Mitsuru Okaniwa; +.br +FS2710S support by Ulrich Deiters +.br +Man page by Henning Meier-Geinitz (mostly based on canon.README) diff --git a/upstream/fedora-40/man5/sane-canon630u.5 b/upstream/fedora-40/man5/sane-canon630u.5 new file mode 100644 index 00000000..fec16f8c --- /dev/null +++ b/upstream/fedora-40/man5/sane-canon630u.5 @@ -0,0 +1,123 @@ +.TH sane\-canon630u 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-canon630u +.SH NAME +sane\-canon630u \- SANE backend for the Canon 630u USB flatbed scanner +.SH DESCRIPTION +The +.B sane\-canon630u +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the following Canon flatbed scanners: +.PP +.RS +CanoScan 630u +.br +CanoScan 636u +.br +.RE +.PP +Color scanning is supported at 75, 150, 300, and 600 dpi, and gamma and +analog gain are adjustable. +.PP +TESTERS ARE WELCOME. Send your bug reports and comments to +Nathan Rutman +.IR . +.PP +.SH CONFIGURATION +The contents of the +.I canon630u.conf +file is a list of device names that correspond to Canon +USB scanners. Empty lines and lines starting with a hash mark (#) are +ignored. Only one device name can be listed in +.IR canon630u.conf . +The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name +could be +.I /dev/usb/scanner0 +for example. See +.BR sane\-usb (5) +for details. +.PP +This product-specific scanner driver uses the lower-level kernel USB driver +"scanner". Check for "Driver=usbscanner" under +.IR /proc/bus/usb/devices . +If "Driver=(none)", try forcing it with +.I "insmod scanner vendor=0x04a9 product=0x2204" +.SH NOTES +.PP +Due to Canon's unwillingness to provide scanner documentation, this +software was developed by analyzing the USB traffic of the Windows +2000 driver. So things like the calibration procedure I kind of made up; +it seems to work for my scanner. If you have complaints, let me know. +.PP +This driver requires the ability to send USB Control Messages, available in +kernel 2.4.12 or later. +.PP +Some users have reported that this driver doesn't work at all. This seems +to be a hardware specific issue, although I dsane\-uson't know what exactly the +problem is. If you are having problems, please send me the info in +.IR /proc/bus/usb/devices , +.IR /proc/pci , +the kernel +.I scanner.c +driver version from +.IR /var/log/messages , +and the output from +.I "SANE_DEBUG_CANON630U=12 scanimage > /dev/null" +.PP +.SH FILES +.TP +.I /etc/sane.d/canon630u.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-canon630u.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-canon630u.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.TP +.I /tmp/canon.cal +The calibration file used to normalize pixel brightness. This is +calculated every time the scanner is first used after it has lost power. +Deleting this file will force recalibration. +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory +separator character, then the default directories are searched after +the explicitly specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_CANON630U +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +.br +SANE_DEBUG_CANON630U=12 scanimage > /dev/null +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-find\-scanner (1) +.br +.I http://canon-fb630u.sourceforge.net/ +.br +.SH AUTHOR +Nathan Rutman diff --git a/upstream/fedora-40/man5/sane-canon_dr.5 b/upstream/fedora-40/man5/sane-canon_dr.5 new file mode 100644 index 00000000..9649f012 --- /dev/null +++ b/upstream/fedora-40/man5/sane-canon_dr.5 @@ -0,0 +1,232 @@ +.TH sane\-canon_dr 5 "13 Feb 2021" "" "SANE Scanner Access Now Easy" +.IX sane\-canon_dr + +.SH NAME +sane\-canon_dr \- SANE backend for Canon DR-series scanners + +.SH DESCRIPTION +The +.B sane\-canon_dr +library implements a SANE (Scanner Access Now Easy) backend which +provides access to some Canon DR-series scanners. + +This document describes backend version 60, which shipped with SANE 1.0.32. + +.SH SUPPORTED HARDWARE +This version has only been tested with a few scanner models. Please see +.I http://www.sane\-project.org/sane\-supported\-devices.html +for the most recent list. + +This backend may support other Canon scanners. The best +way to determine level of support is to test the scanner directly, +or to collect a trace of the windows driver in action. +Please contact the author for help or with test results. + +In general, the larger machines (DR-4000 and up) which have been tested use +a fairly complete protocol, with hardware support for many modes, resolutions +and features. The smaller machines have many limitations, like missing +horizontal resolutions, missing binary mode, always scanning full-width, etc. +There is code in the backend to address these problems, but there seems to be +no way to detect if they are required, so they must be hard-coded. + +.SH OPTIONS +Effort has been made to expose most hardware options, including: +.TP +.B \-\-source Flatbed|ADF Front|ADF Back|ADF Duplex +Selects the source for the scan. + +.TP +.B \-\-mode Lineart|Halftone|Gray|Color +Selects the mode for the scan. + +.TP +.B \-\-resolution +Controls scan resolution. + +.TP +.B \-\-tl\-x, \-\-tl\-y, \-\-br\-x, \-\-br\-y +Sets scan area upper left and lower right coordinates. These are renamed +.BR -t , +.BR -l , +.BR -x , +.B -y +by some frontends. + +.TP +.B \-\-page\-width, \-\-page\-height +Sets paper size. Used by scanner to determine centering of scan +coordinates when using the ADF (Automatic Document Feeder) and +to detect double feed errors. + +.PP +Other options will be available based on the capabilities of the scanner: +enhancement, compression, buttons and sensors, etc. +.PP +Additionally, several 'software' options are exposed by the backend. These +are reimplementations of features provided natively by larger scanners, but +running on the host computer. This enables smaller machines to have similar +capabilities. Please note that these features are somewhat simplistic, and +may not perform as well as the native implementations. Note also that these +features all require that the driver cache the entire image in memory. This +will almost certainly result in a reduction of scanning speed. + +.TP +.B \-\-swcrop +Requests the driver to detect the extremities of the paper within the larger +image, and crop the empty edges. + +.TP +.B \-\-swdeskew +Requests the driver to detect the rotation of the paper within the larger +image, and counter the rotation. + +.TP +.B \-\-swdespeck X +Requests the driver to find and remove dots of X diameter or smaller from the +image, and fill the space with the average surrounding color. + +Use 'scanimage \-\-help' to get a list, but be aware that some options may +be settable only when another option has been set, and that advanced options +may be hidden by some frontend programs. + +.SH CONFIGURATION FILE +The configuration file +.I canon_dr.conf +is used to tell the backend how to look for scanners, and provide options +controlling the operation of the backend. This file is read each time the +frontend asks the backend for a list of scanners, generally only when the +frontend starts. If the configuration file is missing, the backend will +fail to run. +.PP +Scanners can be specified in the configuration file in 4 ways: +.PP +"scsi CANON DR" +.RS +Requests backend to search all scsi buses in the system for a device +which reports itself to be a scanner made by 'CANON', with a model name +starting with 'DR'. +.RE +.PP +"scsi /dev/sg0" (or other scsi device file) +.RS +Requests backend to open the named scsi device. Only useful if you have +multiple compatible scanners connected to your system, and need to +specify one. Probably should not be used with the other "scsi" line above. +.RE +.PP +"usb 0x04a9 0x1603" (or other vendor/product ids) +.RS +Requests backend to search all usb buses in the system for a device +which uses that vendor and product id. The device will then be queried +to determine if it is a Canon scanner. +.RE +.PP +"usb /dev/usb/scanner0" (or other device file) +.RS +Some systems use a kernel driver to access usb scanners. This method is untested. +.RE +.PP +Besides the 'scsi' and 'usb' lines, the configuration file supports the +following 'option' lines: +.PP +"option buffer-size [number of bytes]" +.RS +Set the number of bytes in the data buffer to something other than the +compiled\-in default of 4MB. Large values may cause timeouts or hangs, small +values may cause slow scans. +.PP +Note: The backend does not place an upper bound on this value, as some users +required it to be quite large. Values above the default are not recommended, +and may crash your OS or lockup your scsi card driver. You have been +warned. +.RE +.PP +"option vendor-name [string of text]" +.br +"option model-name [string of text]" +.br +"option version-name [string of text]" +.RS +These options can be used collectively to override the values provided by the +scanner, or to provide the values when the scanner cannot. +.RE +.PP +"option padded-read [0|1]" +.RS +Some scanners prepend all data transmitted to host with 12 bytes. Enable this option if the scanner fails to respond to commands. +.RE +.PP +"option duplex-offset [integer]" +.RS +Some scanners pad the upper edge of one side of a duplex scan. There is some variation in the amount of padding. Modify this option if your unit shows an unwanted band of image data on only one side. +.RE +.PP +.BR NOTE : +"option" lines may appear multiple times in the configuration file. +They only apply to scanners discovered by the next 'scsi/usb' line. +.PP + +.SH ENVIRONMENT +The backend uses a single environment variable, +.BR SANE_DEBUG_CANON_DR , +which enables debugging output to stderr. Valid values are: +.PP +.RS +5 Errors +.br +10 Function trace +.br +15 Function detail +.br +20 Option commands +.br +25 SCSI/USB trace +.br +30 SCSI/USB detail +.br +35 Useless noise +.RE + +.SH KNOWN ISSUES +This backend was entirely reverse engineered from usb traces of the proprietary +driver. Various advanced features of the machines may not be enabled. Many +machines have not been tested. Their protocol is unknown. + +.SH CREDITS + +The various authors of the +.BR sane\-fujitsu (5) +backend provided useful code. +.br +Yabarana Corp. +.I www.yabarana.com +provided significant funding. +.br +EvriChart, Inc. +.I www.evrichart.com +provided funding and loaned equipment. +.br +Canon, USA. +.I www.usa.canon.com +loaned equipment. +.br +HPrint +.I hprint.com.br +provided funding and testing for DR-2510 support. +.br +Stone-IT +.I www.stone-it.com +provided funding for DR-2010 and DR-2050 support. +.br +Gerhard Pfeffer provided access and testing for P-208 and P-215. +.br +Special thanks to: Alejandro Imass, Andre Shimakawa, Martijn van Brummelen, Thanos Diacakis and Junren Shi for testing and feedback. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-usb(5) + +.SH AUTHOR +m. allan noah: +.IR "" . diff --git a/upstream/fedora-40/man5/sane-canon_lide70.5 b/upstream/fedora-40/man5/sane-canon_lide70.5 new file mode 100644 index 00000000..eae9507a --- /dev/null +++ b/upstream/fedora-40/man5/sane-canon_lide70.5 @@ -0,0 +1,104 @@ +.TH sane\-canon_lide70 5 "22 Aug 2020" "" "SANE Scanner Access Now Easy" +.IX sane\-canon_lide70 +.SH NAME +sane\-canon_lide70 \- SANE backend for the Canon LiDE 70 and 600(F) USB flatbed scanners +.SH DESCRIPTION +The +.B canon_lide70 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the Canon Inc. CanoScan LiDE 70 and 600(F) +flatbed scanners. The film unit of the LiDE 600F is not supported. +.PP +Due to Canon's unwillingness to provide scanner documentation, this +software was developed by analyzing the USB traffic of the Windows +XP driver. The precise meaning of the individual commands that are sent +to the scanner is known only to a very limited extent. Some sophistication +present in the Windows XP driver has been left out. There is, for example, +no active calibration. +.PP +Testers and reviewers are welcome. Send your bug reports and comments to +the sane\-devel mailing list +.IR . +.PP +.SH CONFIGURATION +The +.I /etc/sane.d/canon_lide70.conf +file identifies the LiDE 70 by its vendor code 0x04a9 and its +product code 0x2225. For the LiDE 600(f) the product code is 0x2224. + +.SH BACKEND SPECIFIC OPTIONS +.B Scan Mode: + +.TP +.B \-\-resolution 75|150|300|600|1200 [default 600] +Sets the resolution of the scanned image in dots per inch. Scanning at 1200 dpi +is not available on the LiDE 600(F) and it is very slow on the LiDE 70. + +.TP +.B \-\-mode Color|Gray|Lineart [default: Color] +Selects the scan mode. Lineart means fully black and fully white pixels only. + +.TP +.B \-\-threshold 0..100 (in steps of 1) [default 75] +Select minimum-brightness percentage to get a white point, relevant only for Lineart + +.TP +.B \-\-non-blocking[=(yes|no)] [inactive] +This option has not yet been implemented. Scans are captured in a temporary file with a typical size of 100MB. + +.PP +.B Geometry: +.TP +.B \-l 0..216.069 [default 0] +Top-left x position of scan area in millimeters. +.TP +.B \-t 0..297 [default 0] +Top-left y position of scan area in millimeters. +.TP +.B \-x 0..216.069 [default 80] +Width of scan-area in millimeters. +.TP +.B \-y 0..297 [default 100] +Height of scan-area in millimeters. + +.SH FILES +.TP +.I /etc/sane.d/canon_lide70.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-canon_lide70.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-canon_lide70.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_CANON_LIDE70 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +.br +SANE_DEBUG_CANON_LIDE70=128 scanimage > /dev/null +.SH KNOWN PROBLEMS +At low resolutions (75 and 150 dpi, implying high slider speeds) +the LiDE 70 misses the top one millimeter of the scan area. This can +be remedied by shifting the document one millimeter downward, in cases +where such precision matters. Note that +.BR xsane (1) +uses the 75 dpi mode for prescans. The problem is worse on the LiDE 600(F), +where the offset is five millimeters. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-find\-scanner (1), +.BR scanimage (1), +.BR xsane (1), +.br +http://www.juergen-ernst.de/info_sane.html + +.SH AUTHOR +pimvantend, building upon pioneering work by Juergen Ernst. diff --git a/upstream/fedora-40/man5/sane-canon_pp.5 b/upstream/fedora-40/man5/sane-canon_pp.5 new file mode 100644 index 00000000..799695ba --- /dev/null +++ b/upstream/fedora-40/man5/sane-canon_pp.5 @@ -0,0 +1,237 @@ +.TH sane\-canon_pp 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-canon_pp +.SH NAME +sane\-canon_pp \- SANE backend for Canon CanoScan Parallel Port flatbed scanners +.SH DESCRIPTION +The +.B sane\-canon_pp +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the following Canon flatbed scanners: +.PP +.RS +CanoScan FB320P +.br +CanoScan FB620P +.br +CanoScan FB330P +.br +CanoScan FB630P +.br +CanoScan N340P +.br +CanoScan N640P +.br +CanoScan N640P ex +.br +.RE +.PP +No USB scanners are supported and there are no plans to support them in the +future. Other projects are working on support for USB scanners. See the +.I PROJECTS +file for more detail. The FB310P and FB610P are re-badged Avision scanners +which use a different command set, so are unlikely to be supported by this +backend in the future. +.PP +IMPORTANT: this is alpha code. While we have made every effort to make it as +reliable as possible, it will not always work as expected. Feedback is still +appreciated. Please send any bug reports to the maintainers as listed on the +web page (listed in +.B SEE ALSO +below). + +.SH "DEVICE NAMES" +This backend expects device names of the form presented by +.BR libieee1284 (3). +These names are highly dependent on operating system and version. + +On Linux 2.4 kernels this will be of the form +.I "parport0" +or older (2.2 and before) kernels may produce names like +.IR "0x378" +(the base address of your port) or simply +.IR "0" +depending on your module configuration. Check the contents of +.I /proc/parport +if it exists. If you don't want to specify a default port (or don't know its +name), the backend should be able to detect which port your scanner is on. + +.SH CONFIGURATION +The contents of the +.I canon_pp.conf +file is a list of options for the driver to use. Empty lines and lines +starting with a hash mark (#) are ignored. +.PP +The supported options are currently +.BR ieee1284 , +.BR calibrate , +.BR init_mode , +and +.BR force_nibble + +Option +.B ieee1284 +.IR port-name +defines which port to use. The format of port-name is OS dependent, based on +the names presented by libieee1284. Please only have one of these lines, or +all but one will be ignored. + +Option +.B calibrate +.IR cal-file +.IR [port-name] +defines which calibration file to use on a per-port basis. If you only have +one parport, the port-name argument may be omitted \- but be careful as this +will cause problems on multi-scanner systems. You may have as many of these +lines as you like, as long as each has a unique port name. The tilde (`~') +character is acceptable and will be expanded to the value of the HOME +environment. + +Option +.B init_mode +.IR +.IR [portname] +defines which initialisation (wake-up) mode to use on a per-port basis. +If you only have one parport, the portname argument may be omitted \- but +be careful as this may cause problems on multi-scanner systems. +You may have as many of these lines as you like, as long as each has a unique +port name. The valid initialisation modes are FB620P (which strobes 10101010 +and 01010101 on the data pins), FB630P (which strobes 11001100 and 00110011 +on the data pins) and AUTO, which will try FB630P mode first then FB620P mode +second. The FB620P mode is also used by the FB320P. The FB630P mode is used +by the FB330P, N340P, and N640P. + +Option +.B force_nibble +forces the driver to use nibble mode even if ECP mode is reported to work by +libieee1284. This works-around the rare issue of ECP mode being reported to +work by the library, then not working. + +.SH TIPS +.PP +Hit the "Calibrate" button before scanning. It vastly improves the quality of +scans. +.PP +To enable automatic detection of your scanner, uncomment the "canon_pp" line +from +.I /etc/sane.d/dll.conf +.PP +.SH FILES +.TP +.I /etc/sane.d/canon_pp.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-canon_pp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-canon_pp.so +The shared library implementing this backend (present on systems that support +dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may contain +the configuration file. On *NIX systems, the directories are separated by a colon +(`:'), under OS/2, they are separated by a semi-colon (`;'). If this variable +is not set, the configuration file is searched in two default directories: +first, the current working directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory separator +character, then the default directories are searched after the explicitly +specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_CANON_PP +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. Higher debug levels +increase the verbosity of the output. + +Example: +export SANE_DEBUG_CANON_PP=4 +.SH NOTES +.B Features available in the Windows interface +.TP +.B Brightness and Contrast +These are not implemented, and probably never will be. These appear to be +implemented entirely in software. Use GIMP or a similar program if you need +these features. +.TP +.B Descreen Mode +This appears on our first analysis to be just oversampling with an +anti-aliasing filter. Again, it seems to be implemented entirely in software, +so GIMP is your best bet for now. +.TP +.B Gamma Tables +This is under investigation, but for now only a simple gamma profile (ie: the +one returned during calibration) will be loaded. +.PP +.B Communication Problems +.PP +ECP mode in libieee1284 doesn't always work properly, even with new hardware. +We believe that this is a ppdev problem. If you change the configuration file +to include +.B force_nibble +, the problem will go away, but you will only be able to scan in nibble mode. +.PP +Sometimes the scanner can be left in a state where our code cannot revive it. +If the backend reports no scanner present, try unplugging the power and +plugging it back in. Also try unplugging printers from the pass-through port. +.PP +The scanner will not respond correctly to our commands when you first plug in +the power. You may find if you try a scan very soon after plugging in the +power that the backend will incorrectly report that you have no scanner present. +To avoid this, give it about 10 seconds to reset itself before attempting any +scans. +.PP +.B Repeated Lines +.PP +Sometimes at high resolutions (ie. 600dpi) you will notice lines which appear +twice. These lines correspond to points where the scanner head has stopped +during the scan (it stops every time the internal 64kb buffer is full). +Basically it's a mechanical problem inside the scanner, that the tolerance of +movement for a start/stop event is greater than 1/600 inches. I've never tried +the windows driver so I'm not sure how (or if) it works around this problem, +but as we don't know how to rewind the scanner head to do these bits again, +there's currently no nice way to deal with the problem. +.PP +.B Grey-scale Scans +.PP +Be aware that the scanner uses the green LEDs to read grey-scale scans, meaning +green coloured things will appear lighter than normal, and red and blue +coloured items will appear darker than normal. For high-accuracy grey-scale +scans of colour items, it's best just to scan in colour and convert to +grey-scale in graphics software such as the GIMP. +.PP +.B FB620P/FB320P Caveats +.PP +These models can not be reset in the same way as the others. The windows driver +doesn't know how to reset them either \- when left with an inconsistent scanner, +it will start scanning half way down the page! +.PP +Aborting is known to work correctly on the FB*30P models, and is known to be +broken on the FB*20P models. The FB620P which I tested on simply returns +garbage after a scan has been aborted using the method we know. +Aborting is able to leave the scanner in a state where it can be shut down, +but not where another scan can be made. + + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-dll(5), +.BR libieee1284 (3), +.br +.I http://canon\-fb330p.sourceforge.net/ + +.SH AUTHOR +This backend is primarily the work of Simon Krix (Reverse Engineering), and +Matthew Duggan (SANE interface). +.PP +Many thanks to Kevin Easton for his comments and help, and Kent A. Signorini +for his help with the N340P. diff --git a/upstream/fedora-40/man5/sane-cardscan.5 b/upstream/fedora-40/man5/sane-cardscan.5 new file mode 100644 index 00000000..d47ea060 --- /dev/null +++ b/upstream/fedora-40/man5/sane-cardscan.5 @@ -0,0 +1,117 @@ +.TH sane\-cardscan 5 "10 Feb 2010" "" "SANE Scanner Access Now Easy" +.IX sane\-cardscan + +.SH NAME +sane\-cardscan \- SANE backend for Corex CardScan usb scanners + +.SH DESCRIPTION +The +.B sane\-cardscan +library implements a SANE (Scanner Access Now Easy) backend which +provides access to the Corex CardScan 800c & 600c small-format scanners. + +The backend supports only grayscale and color modes and media of +(theoretically) infinite length. + +This backend may support other scanners. The best +way to determine level of support is to get a trace of the windows +driver in action, and send it to the author. + +.SH OPTIONS +The cardscan backend supports the following options: + +.TP +.B --mode Gray|Color +Selects the mode for the scan. + +.SH CONFIGURATION FILE +The configuration file +.I cardscan.conf +is used to tell the backend how to look +for scanners, and provide options controlling the operation of the backend. +This file is read each time the frontend asks the backend for a list +of scanners, generally only when the frontend starts. If the configuration +file is missing, the backend will use a set of compiled defaults, which +are identical to the default configuration file shipped with SANE. +.PP +Scanners can be specified in the configuration file in 2 ways: +.PP +"usb 0x04c5 0x1042" (or other vendor/product ids) +.RS +Requests backend to search all usb buses in the system for a device +which uses that vendor and product id. The device will then be queried +to determine if it is a cardscan scanner. +.RE +.PP +"usb /dev/usb/scanner0" (or other device file) +.RS +Some systems use a kernel driver to access usb scanners. This method is untested. +.RE + +Additionally, there are two configuration options that control the protocol +used by the backend: + +.PP +"lines_per_block 16" (or other number from 1 to 32) +.RS +Controls the number of lines of image data which will be acquired in each pass. +Older scanners will require this number set lower, often 1. +.RE +.PP +"has_cal_buffer 1" (1 or 0) +.RS +Causes the backend to get calibration data from scanner during initialization. +Older scanners do not support this request, and must be set to 0. +.RE + +.SH ENVIRONMENT +The backend uses a single environment variable, +.BR SANE_DEBUG_CARDSCAN, +which enables debugging output to stderr. Valid values are: +.PP +.RS +5 Errors +.br +10 Function trace +.br +15 Function detail +.br +20 Option commands +.br +25 SCSI/USB trace +.br +30 SCSI/USB detail +.br +35 Useless noise +.RE + +.SH KNOWN ISSUES +.PP +.RS +The scanner does not seem to have much control possible, so the backend +cannot set x/y coordinate values, resolutions, etc. These things could +be simulated in the backend, but there are plenty of command line tools. +.br +.br +The backend also does not send all the commands that the windows driver +does, so it may not function the same. +.br +.br +The backend does not have the calibration or ejection options of the +windows driver. +.br +.br +.RE + +.SH CREDITS +The hardware to build this driver was provided to the author by: +Jeff Kowalczyk +.IR "" . + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) + +.SH AUTHOR +m. allan noah: +.I "" . diff --git a/upstream/fedora-40/man5/sane-coolscan.5 b/upstream/fedora-40/man5/sane-coolscan.5 new file mode 100644 index 00000000..68ce70a7 --- /dev/null +++ b/upstream/fedora-40/man5/sane-coolscan.5 @@ -0,0 +1,111 @@ +.TH sane\-coolscan 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-coolscan + +.SH NAME +sane\-coolscan \- SANE backend for Nikon film-scanners + +.SH ABOUT THIS FILE + +This file is a short description of the coolscan backend for +.BR SANE . + +.SH DESCRIPTION + +The +.B sane\-coolscan +library implements a SANE backend that provides the interface to the following Nikon +Coolscan Film scanners: Nikon LS20, LS30, LS1000, LS2000. + +.B Even though the backend has worked for a number of people, there are still some +problems, especially in combination with some SCSI card/drivers (AHA-1505/aha152x.o) +and the autofocus command. +You should consider this backend 'alpha' and be careful when using it the first time. + +.SH CONFIGURATION + +The configuration file for this backend resides in +.IR /etc/sane.d/coolscan.conf . + +Its content is a list of device names that correspond to Nikon Coolscan scanners. Empty lines +and lines starting with a hash mark (#) are ignored. A sample configuration file is +shown below: + +.nf + #scsi Vendor Model Type + scsi Nikon * Scanner + /dev/scanner +.fi + +The special device name must be a generic SCSI device or a symlink to such a device. +To find out to which device your scanner is assigned and how you can set the +permissions of that device, have a look at +.BR sane\-scsi (5). + +.SH SCSI ADAPTER TIPS + +Some SCSI-adapters and low-level SCSI drivers do not work correctly with this backend and the +Coolscan scanners. These systems hang when the autofocus command is send to the Scanner. +To see a list of which card/driver combinations work or don't work have a look at: +.I http://andreas.rick.free.fr/sane/autofocus.html. + +.SH FILES +.TP +The backend configuration file: +.I /etc/sane.d/coolscan.conf +.TP +The static library implementing this backend: +.I /usr/lib64/sane/libsane\-coolscan.a +.TP +The shared library implementing this backend: +.I /usr/lib64/sane/libsane\-coolscan.so +(present on systems that support dynamic loading) + +.SH ENVIRONMENT + +.TP +.B SANE_DEBUG_COOLSCAN +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. E.g., a value of 128 +requests all debug output to be printed. Smaller levels reduce verbosity. + +Examples: + +On bash: +.br +export SANE_DEBUG_COOLSCAN=8 + +On csh: +.br +setenv SANE_DEBUG_COOLSCAN 8 + +.SH BUGS + +The autofocus command does not work with some SCSI card/driver combinations. +.PP +The gamma table is not implemented for the LS1000 yet. +.PP +The dust-removal is not working yet. + +.SH SEE ALSO +.BR sane (7), +.BR sane\-scsi (5) + +.TP +.I http://andreas.rick.free.fr/sane/ +The homepage of this backend. +.TP +.I http://www.sema.be/coolscan/ +The original version of the coolscan backend by Didier. + +.SH THANKS TO +Didier Carlier \- For writing the original Coolscan backend (without it I would not have started this). +.PP +Oliver Rauch \- For adapting xsane so quickly to the infrared stuff. +.PP +All the other people working on SANE. + +.SH AUTHOR +Andreas Rick + +.SH EMAIL-CONTACT +.I andreas.rick@free.fr diff --git a/upstream/fedora-40/man5/sane-coolscan2.5 b/upstream/fedora-40/man5/sane-coolscan2.5 new file mode 100644 index 00000000..bec35913 --- /dev/null +++ b/upstream/fedora-40/man5/sane-coolscan2.5 @@ -0,0 +1,206 @@ +.TH sane\-coolscan2 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-coolscan2 +.SH NAME +sane\-coolscan2 \- SANE backend for Nikon Coolscan film scanners +.SH DESCRIPTION +The +.B sane\-coolscan2 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Nikon Coolscan film scanners. Some functions of this +backend should be considered +.B beta-quality +software. Most functions have been stable for a long time, but of +course new development can not and will not function properly from +the very first day. Please report any strange behaviour to the +maintainer of the backend. + +.PP +At present, the following scanners are known to work with this backend: +.PP +.RS +.ft CR +.nf +Model: Connection Type +--------------------------- ------------------- +LS-30 (Coolscan III) SCSI +LS-2000 SCSI +LS-40 ED (Coolscan IV) USB +LS-4000 ED IEEE 1394 +LS-8000 ED IEEE 1394 +.fi +.ft R +.RE + +Please send mail to the backend author (andras@users.sourceforge.net) to +report successes or failures. + +.SH OPTIONS +The options the backend supports can either be selected through command line +options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). + +Valid command line options and their syntax can be listed by using: +.PP +.RS +scanimage \-\-help \-d coolscan2:: +.RE +.PP +where and specify the device in question, as in the +configuration file (see next section). The +.B \-d +parameter and its argument +can be omitted to obtain information on the first scanner identified. Use +the command: +.PP +.RS +scanimage \-L +.RE +.PP +to list all devices recognized by your SANE installation. + +The options should be fully described by the description or tooltips given by +frontend. Here is a description of some of the most important options, in the +syntax with which they must be supplied to +.BR scanimage (1): +.TP +.B \-\-frame +This option specifies which frame to operate on, if a motorized film strip +feeder or APS adapter are used. The frame number +.I +ranges from 1 to the number of frames available, which is sensed each time +the backend is initialized (usually each time you start the frontend). +.TP +.B \-\-subframe +This option shifts the scan window by the specified amount (default +unit is mm). +.TP +.B \-\-infrared=yes/no +If set to "yes", the scanner will read the infrared channel, thus allowing +defect removal in software. The infrared image is read during a second scan, +with no options altered. The backend must not be restarted between the scans. +If you use +.BR scanimage (1), +perform a batch scan with +.B \-\-batch\-count=2 +to obtain the IR information. +.TP +.B \-\-depth +Here can either be 8 or the maximum number of bits supported by the +scanner (10, 12, or 14). It specifies whether or not the scanner reduces +the scanned data to 8 bits before sending it to the backend. If 8 bits are +used, some information and thus image quality is lost, but the amount of data +is smaller compared to higher depths. Also, many imaging programs and image +formats cannot handle depths greater than 8 bits. +.TP +.B \-\-autofocus +Perform autofocus operation. Unless otherwise specified by the other options ( +.B \-\-focus\-on\-centre +and friends), focusing is performed on the centre of the selected scan area. +.TP +.B \-\-ae\-wb +.TP +.B \-\-ae +Perform a pre-scan to calculate exposure values automatically. +.B \-\-ae\-wb +will maintain the white balance, while +.B \-\-ae +will adjust each channel separately. +.TP +.B \-\-exposure +Multiply all exposure times with this value. This allows exposure +correction without modifying white balance. +.TP +.B \-\-load +Load the next slide when using the slide loader +(applies only to the SF\-200 bulk feeder). +.TP +.B \-\-eject +Eject the film strip or mounted slide when using the slide loader. +.TP +.B \-\-reset +Reset scanner. The scanner will perform the same action as when power is +turned on: it will eject the film strip (with the SF\-200 bulk feeder) +and calibrate itself. Use this whenever the scanner refuses to load +a film strip properly, as a result of +which +.B \-\-eject +does not work. + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/coolscan2.conf +specifies the device(s) +that the backend will use. Owing to the nature of the supported connection +types SCSI, USB, and IEEE 1394, the default configuration file supplied with +the SANE distribution should work without being edited. + +Each line in the configuration file is either of the following, where all +entries are case-sensitive: +.TP +.I blank or starting with a '#' character +These lines are ignored, thus '#' can be used to include comments. +.TP +.I containing only the word """auto""" +This instructs the backend to probe for a scanner by scanning the buses for +devices with known identifiers. This is the default action when no +configuration file is present. +.TP +.I a line of the form : +Here can be one of "scsi" or "usb", and is the device +file of the scanner. Note that IEEE 1394 devices are handled by the SBP-2 +module in the kernel and appear to SANE as SCSI devices. + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-coolscan2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-coolscan2.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.TP +.I /etc/sane.d/coolscan2.conf +Configuration file for this backend, read each time the backend is +initialized. + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_COOLSCAN2 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR sane\-usb (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH BUGS +Currently, the SANE protocol does not allow automatically updating options +whenever the hardware changes. Thus the number of choices for the +.B \-\-frame +option will be fixed when the backend is initialized (usually when the user +runs the frontend). In particular, if there is no film strip in the +automatic film strip feeder when the backend is initialized, the +.B \-\-frame +option will not appear at all. Also, restarting the frontend after swapping film +adapters is strongly recommended. + +Linux kernels prior to 2.4.19 had a patch that truncated INQUIRY data +from IEEE 1394 scanners to 36 bytes, discarding vital information +about the scanner. The IEEE 1394 models therefore only work with +2.4.19 or later. + +No real bugs currently known, please report any to the backend maintainer +or the SANE developers' email list. + +.SH AUTHORS +The backend is written and maintained by Andr\['a]s Major +.IR . diff --git a/upstream/fedora-40/man5/sane-coolscan3.5 b/upstream/fedora-40/man5/sane-coolscan3.5 new file mode 100644 index 00000000..24b0dc5b --- /dev/null +++ b/upstream/fedora-40/man5/sane-coolscan3.5 @@ -0,0 +1,204 @@ +.TH sane\-coolscan3 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-coolscan3 +.SH NAME +sane\-coolscan3 \- SANE backend for Nikon Coolscan film scanners +.SH DESCRIPTION +The +.B sane\-coolscan3 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Nikon Coolscan film scanners. Some functions of this +backend should be considered +.B beta-quality +software. Most functions have been stable for a long time, but of +course new development can not and will not function properly from +the very first day. + +.PP +At present, the following scanners are known to work with this backend: +.PP +.RS +.ft CR +.nf +Model: Connection Type +--------------------------- ------------------- +LS-30 (Coolscan III) SCSI +LS-40 ED (Coolscan IV) USB +LS-50 ED (Coolscan V) USB +LS-2000 SCSI +LS-4000 ED IEEE 1394 +LS-8000 ED IEEE 1394 +.fi +.ft R +.RE + +Please send mail to +.I sane-devel@alioth-lists.debian.net +to report successes or failures. + +.SH OPTIONS +The options the backend supports can either be selected through command line +options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). + +Valid command line options and their syntax can be listed by using: +.PP +.RS +scanimage \-\-help \-d coolscan3:: +.RE +.PP +where and specify the device in question, as in the +configuration file (see next section). The +.B \-d +parameter and its argument can be omitted to obtain information on the +first scanner identified. Use the command: +.PP +.RS +scanimage \-L +.RE +.PP +to list all devices recognized by your SANE installation. + +The options should be fully described by the description or tooltips given by +frontend. Here is a description of some of the most important options, in the +syntax with which they must be supplied to +.BR scanimage (1): +.TP +.B \-\-frame +This option specifies which frame to operate on, if a motorized film strip +feeder or APS adapter are used. The frame number +.I +ranges from 1 to the number of frames available, which is sensed each time +the backend is initialized (usually each time you start the frontend). +.TP +.B \-\-subframe +This option shifts the scan window by the specified amount (default +unit is mm). +.TP +.B \-\-infrared=yes/no +If set to "yes", the scanner will read the infrared channel, thus allowing +defect removal in software. The infrared image is read during a second scan, +with no options altered. The backend must not be restarted between the scans. +If you use scanimage, perform a batch scan with +.B \-\-batch\-count=2 +to obtain the IR information. +.TP +.B \-\-depth +Here can either be 8 or the maximum number of bits supported by the +scanner (10, 12, or 14). It specifies whether or not the scanner reduces +the scanned data to 8 bits before sending it to the backend. If 8 bits are +used, some information and thus image quality is lost, but the amount of data +is smaller compared to higher depths. Also, many imaging programs and image +formats cannot handle depths greater than 8 bits. +.TP +.B \-\-autofocus +Perform autofocus operation. Unless otherwise specified by the other options ( +.B \-\-focus\-on\-centre +and friends), focusing is performed on the centre of the selected scan area. +.TP +.B \-\-ae\-wb +.TP +.B \-\-ae +Perform a pre-scan to calculate exposure values automatically. +.B \-\-ae\-wb +will maintain the white balance, while +.B \-\-ae +will adjust each channel separately. +.TP +.B \-\-exposure +Multiply all exposure times with this value. This allows exposure +correction without modifying white balance. +.TP +.B \-\-load +Load the next slide when using the slide loader (SF\-200 bulk loader only). +.TP +.B \-\-eject +Eject the film strip or mounted slide when using the slide loader. +.TP +.B \-\-reset +Reset scanner. The scanner will perform the same action as when power is +turned on: it will eject the film strip (with the SF\-200 bulk loader) +and calibrate itself. Use this +whenever the scanner refuses to load a film strip properly, as a result of +which +.B \-\-eject +does not work. + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/coolscan3.conf +specifies the device(s) that the backend will use. Owing to the nature of +the supported connection types SCSI, USB, and IEEE 1394, the default +configuration file supplied with the SANE distribution should work without +being edited. + +Each line in the configuration file is either of the following, where all +entries are case-sensitive: +.TP +.I blank or starting with a '#' character +These lines are ignored, thus '#' can be used to include comments. +.TP +.I containing only the word """auto""" +This instructs the backend to probe for a scanner by scanning the buses for +devices with known identifiers. This is the default action when no +configuration file is present. +.TP +.I a line of the form : +Here can be one of "scsi" or "usb", and is the device +file of the scanner. Note that IEEE 1394 devices are handled by the SBP-2 +module in the kernel and appear to SANE as SCSI devices. + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-coolscan3.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-coolscan3.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.TP +.I /etc/sane.d/coolscan3.conf +Configuration file for this backend, read each time the backend is +initialized. + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_COOLSCAN3 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR sane\-usb (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH BUGS +Currently, the SANE protocol does not allow automatically updating options +whenever the hardware changes. Thus the number of choices for the +.B \-\-frame +option will be fixed when the backend is initialized (usually when the user +runs the frontend). In particular, if there is no film strip in the +automatic film strip feeder when the backend is initialized, the +.B \-\-frame +option will not appear at all. +Also, restarting the frontend after swapping film adapters is strongly recommended. + +Linux kernels prior to 2.4.19 had a patch that truncated INQUIRY data +from IEEE 1394 scanners to 36 bytes, discarding vital information +about the scanner. The IEEE 1394 models therefore only work with +2.4.19 or later. + +No real bugs currently known, please report any to the SANE developers' list. + +.SH AUTHORS +coolscan3 written by A. Zummo +.RI < a.zummo@towertech.it >, +based heavily on coolscan2 written by Andr\['a]s Major +.RI < andras@users.sourceforge.net >. diff --git a/upstream/fedora-40/man5/sane-dc210.5 b/upstream/fedora-40/man5/sane-dc210.5 new file mode 100644 index 00000000..45a4ec12 --- /dev/null +++ b/upstream/fedora-40/man5/sane-dc210.5 @@ -0,0 +1,121 @@ +.TH sane\-dc210 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-dc210 +.SH NAME +sane\-dc210 \- SANE backend for Kodak DC210 Digital Camera +.SH DESCRIPTION +The +.B sane\-dc210 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the Kodak DC210 camera. THIS IS EXTREMELY ALPHA +CODE! USE AT YOUR OWN RISK!! +.SH "DEVICE NAMES" +The current version of the backend only allows one camera to be +connected. The device name is always "0". +.SH CONFIGURATION +The contents of the +.I dc210.conf +specify the serial port and baud rate to use. The +.B baud +rate specifies the maximum rate to use while downloading pictures. (The +camera is always initialized using 9600 baud, then switches to the +higher rate). On my 90MHz Pentium, I usually have no problems downloading +at 115200 baud as long as the system is not excessively busy and +the "interrupt-unmask flag" is set in the IDE driver +.RI ( "hdparm \-u1" ). +Supported baud rates are: 9600, 19200, 38400, 57600, and 115200. +.PP +The +.B dumpinquiry +line causes some information about the camera to +be printed. +.PP +.B cmdrespause +specifies how many usec (1,000,000ths of a second) to wait between +writing the command and reading the result. 125000 seems to be the +lowest I could go reliably. +.PP +.B breakpause +specifies how many usec (1,000,000ths of a second) between sending the +"back to default" break and sending commands. +.PP +Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +port=/dev/ttyS0 +.br +# this is a comment +.br +baud=115200 +.br +dumpinquiry +.br +cmdrespause=125000 +.br +breakpause=1000000 +.RE +.PP +.SH FILES +.TP +.I /etc/sane.d/dc210.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-dc210.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-dc210.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d. +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config", +.IR ".", +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_DC210 +If the library was compiled with debugging support enabled, this +environment variable controls the debug level for this backend. +A value of 128 requests maximally copious debug output; smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane (7) + +.SH AUTHOR +Brian J. Murrell +.PP +This backend is based somewhat on the dc25 backend included in this +package by Peter Fales. +.PP +The manpage was copied from the dc25 backend and somewhat edited by +Henning Meier-Geinitz. + +.SH BUGS +Known bugs/limitations are: ? +.PP +More general comments, suggestions, and inquiries about frontends +or SANE should go to the SANE Developers mailing list +(see +.I http://www.sane\-project.org/mailing\-lists.html +for details). +You must be subscribed to the list, otherwise your mail won't be +sent to the subscribers. diff --git a/upstream/fedora-40/man5/sane-dc240.5 b/upstream/fedora-40/man5/sane-dc240.5 new file mode 100644 index 00000000..d588c5d8 --- /dev/null +++ b/upstream/fedora-40/man5/sane-dc240.5 @@ -0,0 +1,131 @@ +.TH sane\-dc240 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-dc240 +.SH NAME +sane\-dc240 \- SANE backend for Kodak DC240 Digital Camera +.SH DESCRIPTION +The +.B sane\-dc240 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the Kodak DC240 camera. THIS IS EXTREMELY ALPHA +CODE! USE AT YOUR OWN RISK!! +.SH "DEVICE NAMES" +The current version of the backend only allows one camera to be +connected. The device name is always "0". +.SH CONFIGURATION +The contents of the +.I dc240.conf +specify the serial port and baud rate to use. The +.B baud +rate specifies the maximum rate to use while downloading pictures. (The +camera is always initialized using 9600 baud, then switches to the +higher rate). On a 450MHz Pentium, I usually have no problems downloading +at 115200 baud, though the camera sometimes has to resend packets due +to lost characters. Results are better when +the "interrupt-unmask flag" is set in the IDE driver +.RI ( "hdparm \-u1" ). +Supported baud rates are: 9600, 19200, 38400, 57600, and 115200. +.PP +The +.B dumpinquiry +line causes some information about the camera to be printed. +.PP +.B cmdrespause +specifies how many usec (1,000,000ths of a second) to wait between +writing the command and reading the result. 125000 seems to be the +lowest I could go reliably. +.PP +.B breakpause +specifies how many usec (1,000,000ths of a second) between sending the +"back to default" break and sending commands. +.PP +Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +port=/dev/ttyS0 +.br +# this is a comment +.br +baud=115200 +.br +dumpinquiry +.br +cmdrespause=125000 +.br +breakpause=1000000 +.RE +.PP +.SH FILES +.TP +.I /etc/sane.d/dc240.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-dc240.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-dc240.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.I /etc/sane.d. +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config", +.IR ".", +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_DC240 +If the library was compiled with debugging support enabled, this +environment variable controls the debug level for this backend. +A value of 128 requests maximally copious debug output; smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane (7) + +.SH AUTHOR +Peter S. Fales + +.PP +This backend borrows heavily from the +.BR sane\-dc210 (5) +backend by Brian J. Murrell +which is based somewhat on the +.BR sane\-dc25 (5) +backend by Peter Fales. +.PP +The manpage was largely copied from the +.BR sane\-dc210 (5) +manpage. + +.SH BUGS +The major limitation that I know of is that the backend assumes +the directory in the camera is 100dc240. Once the camera has +taken more than 9999 pictures, the directory will increment to 101dc240. +Not only should we check for the additional directory, but pictures may +actually be found in multiple directories. +.PP +More general comments, suggestions, and inquiries about frontends +or SANE should go to the SANE Developers mailing list +(see +.I http://www.sane\-project.org/mailing\-lists.html +for details). +You must be subscribed to the list, otherwise your mail won't be +sent to the subscribers. diff --git a/upstream/fedora-40/man5/sane-dc25.5 b/upstream/fedora-40/man5/sane-dc25.5 new file mode 100644 index 00000000..2fe2524c --- /dev/null +++ b/upstream/fedora-40/man5/sane-dc25.5 @@ -0,0 +1,109 @@ +.TH sane\-dc25 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-dc25 +.SH NAME +sane\-dc25 \- SANE backend for Kodak DC20/DC25 Digital Cameras +.SH DESCRIPTION +The +.B sane\-dc25 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Kodak DC20 and DC25 cameras. At present, only +the DC25 has been tested, but since the code is based on a DC20 +interface program, it is likely to work for that model also. +.SH "DEVICE NAMES" +The current version of the backend only allows one camera to be +connected. The device name is always "0". +.SH CONFIGURATION +The contents of the +.I dc25.conf +specify the serial port and baud rate to use. The baud rate +specifies the maximum rate to use while downloading pictures. (The +camera is always initialized using 9600 baud, then switches to the +higher rate). On my 90MHz Pentium, I usually have no problems downloading +at 115200 baud as long as the system is not excessively busy and +the "interrupt-unmask flag" is set in the IDE driver +.RI ( "hdparm \-u1" ). +Supported baud rates are: 9600, 19200, 38400, 57600, and 115200. +.PP +The dumpinquiry line causes some information about the camera to +be printed to stderr during startup. Note: This is not compatible +with saned, so make sure you don't have any dumpinquiry lines if you are +using saned (i.e. scanning on a remote machine using a +network). +.PP +Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +port=/dev/ttyS0 +.br +# this is a comment +.br +baud=115200 +.br +dumpinquiry +.RE +.PP +.SH FILES +.TP +.I /etc/sane.d/dc25.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-dc25.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-dc25.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_DC25 +If the library was compiled with debugging support enabled, this +environment variable controls the debug level for this backend. +A value of 128 requests maximally copious debug output; smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane (7) + +.SH AUTHOR +Peter Fales, +.IR dc25\-devel@fales\-lorenz.net . + +.SH BUGS +Known bugs/limitations are: +.PP +I haven't figured out how to trigger an option reload following a "scan." +This causes problems when a new picture is snapped for example, the +slider that is used to select the picture from the camera may not be +updated immediately. +.PP +More general comments, suggestions, and inquiries about frontends +or SANE should go to the SANE Developers mailing list +(see +.I http://www.sane\-project.org/mailing\-lists.html +for details). +You must be subscribed to the list, otherwise your mail won't be +sent to the subscribers. diff --git a/upstream/fedora-40/man5/sane-dll.5 b/upstream/fedora-40/man5/sane-dll.5 new file mode 100644 index 00000000..c1ac8771 --- /dev/null +++ b/upstream/fedora-40/man5/sane-dll.5 @@ -0,0 +1,183 @@ +.TH sane\-dll 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-dll +.SH NAME +sane\-dll \- SANE dynamic backend loader +.SH DESCRIPTION +The +.B sane\-dll +library implements a SANE (Scanner Access Now Easy) backend that +provides access to an arbitrary number of other SANE backends. These +backends may either be pre-loaded at the time the +.B sane\-dll +library is built or, on systems that support dynamic loading of shared +libraries, the backends may be loaded at runtime. In the latter case, +adding support for a new backend simply involves installing the +relevant library in +.I /usr/lib64/sane +and adding an entry to the +.I dll.conf +configuration file. In other words, no applications need to be +modified or recompiled to add support for new devices. +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.IR backend : device +.RE +.PP +Where +.I backend +is the name of the backend and +.I device +is the name of the device in this backend that should be addressed. +If the device name does not contain a colon (:), then the entire string +is treated as the +.I device +string for the default backend. The default backend is the backend +listed last in the configuration file (see below) or the first +pre-loaded backend (if any). +.SH CONFIGURATION +The contents of the +.I dll.conf +file is a list of backend names that may be loaded dynamically upon demand. +Empty lines are ignored, also everything after a hash mark (#). A sample +configuration file is shown below: +.PP +.RS +net +.br +# this is a comment +.br +pnm +.br +mustek +.RE +.PP +It is also possible to add a file in +.I /etc/sane.d/dll.d +that contains the list of backends to be added. Backends mentioned in a +file included in this directory will be added before any backends listed +in +.I dll.conf. +Files in +.I /etc/sane.d/dll.d +can be freely named. They shall follow the format conventions as apply for +.I dll.conf. + +.PP +Note that backends that were pre-loaded when building this library do +not have to be listed in this configuration file. That is, if a +backend was preloaded, then that backend will always be present, +regardless of whether it's listed in the configuration file or not. +.PP +The list of preloaded backends is determined by macro +.B PRELOADABLE_BACKENDS +in file backend/Makefile.in of the SANE source code distribution. After +changing the value of this macro, it is necessary to reconfigure, rebuild, +and reinstall SANE for the change to take effect. + +Aliases are defined in the config file +.IR dll.aliases . +It can contain entries of the form +.PP +.RS +.br +alias SomeName SaneDeviceName +.br +alias "Some Name" SaneDeviceName +.br +hide SaneDeviceName +.RE +.PP +For example: + +.PP +.RS +.br +alias Epson net:somehost:epson:/dev/sgX +.br +alias "Siemens ST400" st400:/dev/sgY +.br +hide net:somehost:pnm:0 +.br +hide net:somehost:pnm:1 +.br +alias "Read from file" pnm:0 +.br +hide pnm:1 +.RE +.PP + +Aliased device names are automatically hidden. + +The idea is that users don't have to deal with complicated device +names (especially for networked devices), and to hide other exported +devices which might confuse them. Note that a hidden device can still +be accessed if the device name is known, it just doesn't appear on the +list. + +.SH FILES +.TP +.I /etc/sane.d/dll.aliases +The list of aliased or hidden backends. +.TP +.I /etc/sane.d/dll.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-dll.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-dll.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory +separator character, then the default directories are searched after +the explicitly specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_DLL +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.ft CR +.nf +Value Description +0 print severe errors only +1 print normal errors and important messages +2 print normal messages +3 print debugging messages +4 print everything +.fi +.ft R + +Example: +export SANE_DEBUG_DLL=3 + + +.SH "SEE ALSO" +.BR sane (7), +.BR scanimage (1), +.BR sane\-"backendname" (5) + +.SH AUTHOR +David Mosberger diff --git a/upstream/fedora-40/man5/sane-dmc.5 b/upstream/fedora-40/man5/sane-dmc.5 new file mode 100644 index 00000000..92ed2f1a --- /dev/null +++ b/upstream/fedora-40/man5/sane-dmc.5 @@ -0,0 +1,153 @@ +.TH sane\-dmc 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-dmc +.SH NAME +sane\-dmc \- SANE backend for the Polaroid Digital Microscope Camera +.SH DESCRIPTION +The +.B sane\-dmc +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the Polaroid Digital Microscope Camera. +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the UNIX path-name for the special device that corresponds to the +scanner. The special device name must be a generic SCSI device or a +symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. +.SH IMAGING MODES +The Polaroid DMC supports a number of imaging modes. This driver supports +five of the imaging modes: +.PP +.TP +.B Full Frame +This mode corresponds to the 801-by-600 pixel full-color full-frame image. +.TP +.B Viewfinder +This mode corresponds to the 270-by-201 pixel grey-scale viewfinder image. +This image is acquired very quickly. +.TP +.B Raw +This mode corresponds to the 1599-by-600 pixel "raw" image from the +CCD. It is grey-scale, with pixels alternating horizontally between +red, green and blue stripes. The pixels are twice as high as they are +wide, so the image is distorted. +.TP +.B Thumbnail +This mode corresponds to the 80-by-60 pixel full-color thumbnail image. +.TP +.B Super Resolution +This image is a 1599-by-1200 pixel full-color image constructed by filtering +and interpolating the "raw" image. The filtering and interpolation is +done in software, so this mode is very slow. Also, this mode places +restrictions on how the image is read which means that the "preview" mode +of xscanimage does not work in Super Resolution mode. +.RB ( xcam (1) +and the non-preview modes of +.BR scanimage (1) +and +.BR xscanimage (1) +work fine, however.) +.PP +.SH OTHER SETTINGS +.TP +.B ASA Setting +This setting adjusts the camera's sensitivity. You can choose one of +25, 50, or 100 "equivalent" ASA. +.TP +.B Shutter Speed +You can select a shutter speed from 8 to 1000 milliseconds. The shutter +speed is quantized in units of 32 microseconds. +.TP +.B White Balance +You can choose one of "Daylight", "Incandescent" or "Fluorescent" +white balances. This setting more-or-less corresponds to the +"Color Temperature" settings on Polaroid's Windows and Mac software. +.SH CONFIGURATION +The contents of the +.I dmc.conf +file is a list of device names that correspond to DMC +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +/dev/scanner +.br +# this is a comment +.br +/dev/sge +.RE +.SH FILES +.TP +.I /etc/sane.d/dmc.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-dmc.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-dmc.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory separator +character, then the default directories are searched after the explicitly +specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config", +.IR ".", +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_DMC +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.SH BUGS +In the "Full Frame" and "Raw" modes, images must be read in units +of entire lines. The driver performs no buffering in these modes; +if you ask sane_read to read a non-integral number of lines, it +may read less than you ask for. If you ask sane_read to read +less than a single line, it returns SANE_STATUS_INVAL. +.PP +In the "Super Resolution" mode, images must be read in units of +\fItwo\fR lines (3198 pixels or 9594 bytes). If you try to read less +than two lines, you get SANE_STATUS_INVAL. The Super Resolution mode +is very slow. +.PP +In the "Viewfinder" and "Thumbnail" modes, the entire image must +be read in one SCSI transfer. In this case, the driver performs +buffering and you can read the image in as small an increment as you +like. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHOR +David F. Skoll +.PP +The backend is derived from +.BR sane\-hp (5) +by David Mosberger diff --git a/upstream/fedora-40/man5/sane-epjitsu.5 b/upstream/fedora-40/man5/sane-epjitsu.5 new file mode 100644 index 00000000..7eb345bd --- /dev/null +++ b/upstream/fedora-40/man5/sane-epjitsu.5 @@ -0,0 +1,124 @@ +.TH sane\-epjitsu 5 "15 Nov 2022" "" "SANE Scanner Access Now Easy" +.IX sane\-epjitsu + +.SH NAME +sane\-epjitsu \- SANE backend for Epson-based Fujitsu USB scanners. + +.SH DESCRIPTION +The +.B sane\-epjitsu +library implements a SANE (Scanner Access Now Easy) backend which provides basic access the +Fujitsu fi\-60F/fi\-65F and ScanSnap S300/S1300(i)/S1100(i) scanners. + +.SH HARDWARE SUPPORT +These scanners are fairly limited, only supporting a couple of modes and resolutions, and +always scanning full width. The backend supports missing modes (binary, grayscale) and +intermediate resolutions in software, but provides only minimal scan area controls. See +.B KNOWN ISSUES. + +This backend may support other scanners. If physical inspection reveals an Epson chipset, +please contact the author for instructions on collecting a USB trace under Windows to verify. + +.SH OPTIONS +A limited effort has been made to expose the standard options to the API. This allows a +frontend to set resolution, color mode, and choose the ADF setting. The +.B sane\-epjitsu +backend supports the following basic options for most scanners: +.PP +.B source s +.RS +Selects the source for the scan. Options may include "Flatbed", "ADF Front", "ADF Back", "ADF Duplex". +.RE +.PP +.B mode m +.RS +Selects the mode for the scan. Options may include "Lineart", "Gray", "Color". +.RE +.PP +.B resolution, y\-resolution +.RS +Controls scan resolution. Setting +.B \-\-resolution +also sets +.B \-\-y\-resolution, +though this behavior is overridden by some frontends. +.RE +.PP +Other options will be available based on the capabilities of the scanner. Use +.I 'scanimage \-\-help' +to get a list. Be aware that some options may appear only when another option has been set, and that advanced options may be hidden by the frontend. +.PP +.SH CONFIGURATION FILE +The configuration file +.I "/etc/sane.d/epjitsu.conf" +is used to tell the backend how to look for scanners, and provide options controlling the operation of the backend. This file is read each time the frontend asks the backend for a list of scanners, generally only when the frontend starts. If the configuration file is missing, the backend will not work. +.PP +Scanners can be specified in the configuration file in two ways: +.PP +"usb 0x04c5 0x10c7" (or other vendor/product ids) +.RS +Requests backend to search all usb buses in the system for a device which uses that vendor and product id. The device will then be queried to determine if it is a supported scanner. +.RE +.PP +"usb /dev/usb/scanner0" (or other device file) +.RS +Some systems use a kernel driver to access usb scanners. This method is untested. +.RE +.PP +The only configuration option supported is "firmware /PATH/TO/FILE", allowing you to set the location of the firmware file you have extracted from the Windows driver. +.PP +.B Note: +This firmware is a copyrighted work of Fujitsu, so cannot be provided by the backend or the author. Please do not ask. +.PP +.B Note: +These scanners REQUIRE a firmware file to function. See the supplied configuration file for more detail. +.PP +.B Note: +This option may appear multiple times in the configuration file. It only applies to scanners discovered by 'usb' lines that follow this option. +.PP + +.SH ENVIRONMENT +The backend uses a single environment variable, +.BR SANE_DEBUG_EPJITSU, +which enables debugging output to stderr. Valid values are: +.PP +.RS +5 Errors +.br +10 Function trace +.br +15 Function detail +.br +20 Option commands +.br +25 USB trace +.br +30 USB detail +.br +35 Useless noise +.RE + +.SH KNOWN ISSUES +.PP +.RS +Only limited scan area options are exposed. +.br +.br +fi\-60F and fi\-65F hardware grayscale mode is not used, because the calibration code is not finished. +.RE + +.SH CREDITS +S300 support funded by Microdea, Inc. and Archivista, GmbH. +.br +fi\-60F support funded by TrueCheck, Inc. +.br +Improved calibration code provided by Richard Goedeken. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) +.BR scanimage (1) + +.SH AUTHOR +m. allan noah: +.RI < "kitno455 a t gmail d o t com" > diff --git a/upstream/fedora-40/man5/sane-epson.5 b/upstream/fedora-40/man5/sane-epson.5 new file mode 100644 index 00000000..44ecf875 --- /dev/null +++ b/upstream/fedora-40/man5/sane-epson.5 @@ -0,0 +1,327 @@ +.TH sane\-epson 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-epson +.SH NAME +sane\-epson \- SANE backend for EPSON scanners +.SH DESCRIPTION +The +.B sane\-epson +library implements a SANE Scanner Access Now Easy) backend that +provides access to Epson flatbed scanners. Some functions of this +backend should be considered +.B beta-quality +software! Most functions have been stable for a long time, but of +course new development can not and often times will not function properly from +the very first day. Please report any strange behavior to the +maintainer of the backend. +.PP +At present, the following scanners are known to work with this backend: +.PP +.RS +.ft CR +.nf +Model: Connection Type +--------------------------- ------------------- +GT-5000 SCSI, parallel +GT-6000 parallel +GT-6500 SCSI (use only the line "scsi" in epson.conf) +ActionScanner II SCSI, parallel +GT-7000 SCSI +Perfection 636 SCSI +Perfection 636U USB +Perfection 610 USB +Perfection 640 USB +Perfection 1200S SCSI +Perfection 1200U USB +Perfection 1240 USB, SCSI +Perfection 1640 USB, SCSI +Perfection 1650 USB +Perfection 1660 USB +Perfection 2400 USB +Perfection 2450 USB, IEEE-1394 +Expression 636 / GT-9500 SCSI +Expression 1600 USB, SCSI, IEEE-1394 +Expression 1680 USB, SCSI, IEEE-1394 +CX-3200 USB +CX-5200 USB +.fi +.ft R +and many more. The official list is on the Sane web site. +.RE + +For other scanners the software may or may not work. Please send mail to +the backend author +.RI ( khk@khk.net ) +to report success with scanners not on the list or problems with scanners +that are listed. +.SH OPTIONS +The options the backend supports can either be selected through command line +options to programs like +.BR scanimage (1) +or through GUI elements in programs like +.BR xscanimage (1) +or +.BR xsane (1). + +Valid command line options and their syntax can be listed by using: +.PP +.RS +scanimage \-\-help \-d epson +.RE +.PP +Not all devices support all options. +.TP +.I Scan Mode +The +.B \-\-mode +switch selects the basic mode of operation of the scanner. Valid choices +are Binary, Gray and Color. The Binary mode is black and white only, +Gray will produce 256 levels of gray or more depending on the scanner +and Color means 24 bit color mode or more depending on the scanner. +Some scanners will internally use 36 bit color, their external interface +however may only support 24 bits. + +The +.B \-\-depth +option selects the bit depth the scanner is using. This option is only +available for scanners that support more than one bit depth. Older +scanners will always transfer the image in 8bit mode. Newer scanners +allow one to select either 8 bits, 12 or 14 bits per color channel. For a +color scan this means an effective color depth of 36 or 42 bits over +all three channels. The valid choices depend on the scanner model. + +The +.B \-\-halftoning +switch selects the mode that is used in Binary mode. Valid options +are "None", "Halftone A (Hard Tone)", "Halftone B (Soft Tone)", "Halftone C +(Net Screen)", "Dither A (4x4 Bayer)", "Dither B (4x4 Spiral)", "Dither C +(4x4 Net Screen)", "Dither D (8x4 Net Screen)", "Text Enhanced Technology", +"Download pattern A", and "Download pattern B". + +The +.B \-\-dropout +switch selects the so called dropout color. Valid options are None, +Red, Green and Blue. The default is None. The dropout color is used for +monochrome scanning and selects the color that is not scanned. This can +be used to e.g. scan an original with a colored background. + +The +.B \-\-brightness +switch controls the brightness of the scan. Valid options are integer +values from \-3 to 3. The default is 0. The larger the brightness value, +the brighter the image gets. If a user defined table for the gamma +correction is selected, the brightness parameter is not available. + +The +.B \-\-sharpness +switch sets the sharpness of the image data. Valid options are integer +values from \-2 to 2, with \-2 meaning "Defocus", \-1 "Defocus slightly", +0 "Normal", 1 "Sharpen slightly" and 2 "Sharpen". + +The +.B \-\-gamma\-correction +switch controls the scanner's internal gamma correction. Valid options are +"Default", "User defined", "High density printing" "Low density printing" +and "High contrast printing". + +The +.B \-\-color\-correction +switch controls the scanner's internal color correction function. Valid +options are "No Correction", "Impact\-dot printers", "Thermal printers", +"Ink\-jet printers" and "CRT monitors". The default is "CRT monitors". + +The +.B \-\-resolution +switch selects the resolution for a scan. Some EPSON scanners will scan in +any resolution between the lowest and highest possible value. The list +reported by the scanner can be displayed using the "\-\-help \-d epson" +parameters to +.BR scanimage (1). + +The +.B \-\-mirror +option controls the way the image is scanned. By reading the image data +from right to left the image is mirrored. Valid options are "yes" and +"no". The default is "no". + +The +.B \-\-speed +option can improve the scan speed in monochrome mode. Valid options are +"yes" or "no", the "yes" option will speed up the scan if this option +is supported. + +The +.B \-\-auto\-area\-segmentation +switch activates the automatic area segmentation for monochrome scans. The +scanner will try to determine which areas are text and which contain +images. The image areas will be halftoned, and the text will be +improved. Valid options are "yes" and "no". The default is "yes". + +The +.B \-\-gamma\-table +parameter can be used to download a user defined gamma table. The option +takes 256 values from the range 0-255. In color mode this option equally +affects the red, green, and blue channel. + +The +.B \-\-red\-gamma\-table +parameter can be used to download a user defined gamma table for the +red channel. The valid options are the same as for \-\-gamma\-table. + +The +.B \-\-green\-gamma\-table +parameter can be used to download a user defined gamma table for the +green channel. The valid options are the same as for \-\-gamma\-table. + +The +.B \-\-blue\-gamma\-table +parameter can be used to download a user defined gamma table for the +blue channel. The valid options are the same as for \-\-gamma\-table. + +The color correction coefficients +.B \-\-cct\-1 \-\-cct\-2 \-\-cct\-3 ... \-\-cct\-9 +will install color correction coefficients for the user defined color +correction. Values are specified as integers in the range \-127..127. + +The +.B \-\-preview +option requests a preview scan. The frontend software automatically selects a low +resolution. Valid options are "yes" and "no". The default is "no". + +The +.B \-\-preview\-speed +options will increase the scan speed if this is supported by the +scanner. Valid options are "yes" and "no", the default is "no". + + +The geometry options +.B \-l \-t \-x \-y +control the scan area: +.B \-l +sets the top left x coordinate, +.B \-t +the top left y coordinate, +.B \-x +selects the width and +.B \-y +the height of the scan area. All parameters are specified in millimeters. + +The +.B \-\-quick\-format +option lets the user select a scan area with predefined sizes. Valid +parameters are "CD", "A5 portrait", "A5 landscape", "Letter", "A4" and +"max". The default is "max", which selects the largest possible area. + +The +.B \-\-source +option selects the scan source. Valid options depend on the installed +options. The default is "Flatbed". + +The +.B \-\-auto\-eject +option will eject a page after scanning from the document feeder. + +The +.B \-\-film\-type +option will select the film type for scans with the transparency +unit. This option is only activated if the TPU is selected as scan +source. Valid options are "Negative Film" and "Positive Film". + +The +.B \-\-focus\-position +option selects the focus position for all scans. Valid options are "Focus +2.5mm above glass" and "Focus on glass". The focus on the 2.5mm point +above the glass is necessary for scans with the transparency unit, so +that the scanner can focus on the film if one of the film holders is used. +This option is only functional for selected scanners, all other scanners +will ignore this option. + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/epson.conf +specifies the device(s) that the backend will use. Possible connection types are: +.TP +.I SCSI +This is the default, and if nothing else is specified the backend software will +open a given path as SCSI device. More information about valid syntax for SCSI +devices can be found in +.BR sane\-scsi (5). +.br +Usually SCSI scanners are configured with a line "scsi EPSON" in this file. In +some cases it may be necessary to only use the string "scsi" (e.g. for the GT-6500). +.TP +.I PIO \- Parallel Interface +The parallel interface can be configured in two ways: An integer value starting +at the beginning of a line will be interpreted as the IO address of the parallel +port. To make it clearer that a configured IO address is a parallel port the +port address can be preceded by the string "PIO". The PIO connection does not +use a special device file in the /dev directory. The IO address can be specified +in hex mode (prefixed with "0x"). +.TP +.I USB +A device file that is preceded by the string "USB" is treated as a scanner +connected via the Universal Serial Bus. The correct special device file has +to be created prior to using it with Sane. See the USB documentation for +more information about how to set up the USB subsystem and the required +device files. +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-epson.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-epson.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_EPSON +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.TP +.B SANE_DEBUG_EPSON_SCSI +If the library was compiled with debug support enabled, this +environment variable controls the SCSI related debug level for this backend. +Only a value of 2 is supported. +.TP +.B SANE_EPSON_CMD_LVL +This allows one to override the function or command level that the backend +uses to communicate with the scanner. The function level a scanner +supports is determined during the initialization of the device. If +the backend does not recognize the function level reported by the +scanner it will default to function level B3. Valid function levels +are A1, A2, B1, B2, B3, B4, B5, B6, B7, B8, D1 and F5. Use this feature +only if you know what you are doing! + +.SH "SEE ALSO" + +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH BUGS + +None :-) At least none are currently known. + +.SH UNSUPPORTED DEVICES +The backend may be used with Epson scanners that are not yet listed +under the list of supported devices. A scanner that is not recognized +may default to the function level B3, which means that not all +functions that the scanner may be capable of are accessible. + +If the scanner is not even recognized as an Epson scanner this is +probably because the device name reported by the scanner is not in the +correct format. Please send this information to the backend maintainer +(email address is in the AUTHOR section of this man page or in the +AUTHORS file of the SANE distribution). + +The Perfection 600, Perfection 650, Perfection 660, Perfection 1250 and +Perfection 1260 are not supported by this backend. + +.SH AUTHOR + +The package is actively maintained by Karl Heinz Kremer +.RI ( khk@khk.net ). +The software is based on work by Christian Bucher and Kazuhiro Sasayama. diff --git a/upstream/fedora-40/man5/sane-epson2.5 b/upstream/fedora-40/man5/sane-epson2.5 new file mode 100644 index 00000000..854ec02f --- /dev/null +++ b/upstream/fedora-40/man5/sane-epson2.5 @@ -0,0 +1,380 @@ +.TH sane\-epson2 5 "22 Jan 2009" "" "SANE Scanner Access Now Easy" +.IX sane\-epson2 +.SH NAME +sane\-epson2 \- SANE backend for EPSON scanners +.SH DESCRIPTION +The +.B sane\-epson2 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Epson flatbed scanners. This library supports +a similar set of scanners as the sane\-epson driver but was +developed to support a wider range of connections to the scanner; +include network access. +.PP +Because +.B sane\-epson +and +.B sane\-epson2 +drivers support many of the same devices, if one +driver gives you problems you may try disabling it to try the other. +This can be done by removing the driver name from the +.I dll.conf +or perhaps by commenting out the options in +.I epson.conf +or +.I epson2.conf. +.PP +At present, the following scanners are known to work with this backend: +.PP +.RS +.ft CR +.nf +Model: Connection Type +--------------------------- ------------------- +ActionScanner II SCSI, parallel +AcuLaser CX11 Series USB, Network +AcuLaser CX21 Series USB, Network +CX-3200 USB +CX-3600 USB +CX-3650 USB +CX-4050 USB +CX-4600 USB +CX-4800 USB +CX-5000 USB +CX-5200 USB +CX-5400 USB +CX-6300 USB +CX-6400 USB +CX-6500 USB +CX-6600 USB +DX-3800 USB +DX-5000 USB +DX-5050 USB +DX-6000 USB +DX-7400 USB +ES-300C SCSI, parallel +ES-300GS SCSI +ES-600C parallel +ES-1200C parallel +Expression 636 SCSI +Expression 800 SCSI +Expression 1600 USB, SCSI, IEEE-1394 +Expression 1680 USB, SCSI, IEEE-1394 +FilmScan 200 SCSI +GT-5000 SCSI, parallel +GT-5500 SCSI +GT-6000 parallel +GT-6500 parallel +GT-7000 SCSI +GT-8000 SCSI +GT-8500 SCSI +Perfection 610 USB +Perfection 636S SCSI +Perfection 636U USB +Perfection 640 USB +Perfection 1200S SCSI +Perfection 1200U USB +Perfection 1240 USB, SCSI +Perfection 1640 USB, SCSI +Perfection 1650 USB +Perfection 1660 USB +Perfection 2400 USB +Perfection 2450 USB, IEEE-1394 +Perfection 3200 USB +Perfection 4870 USB +Perfection 4990 USB +RX-425 USB +RX-500 USB +RX-600 USB +RX-700 USB +V700 USB, IEEE-1394 +V750 USB, IEEE-1394 +.fi +.ft R +and many more. The official list is on the Sane web site. +.RE + +For other scanners the software may or may not work. Please send mail to +the sane-backend mailing list to report success with scanners not on +the list or problems with scanners that are listed. +.SH OPTIONS +The options the backend supports can either be selected through command line +options to programs like +.BR scanimage (1) +or through GUI elements in programs like +.BR xscanimage (1) +or +.BR xsane (1). + +Valid command line options and their syntax can be listed by using +.PP +.RS +scanimage \-\-help \-d epson2 +.RE +.PP +Not all devices support all options. +.TP +.I Scan Mode +The +.B \-\-mode +switch selects the basic mode of operation of the scanner. Valid choices +are Binary, Gray and Color. The Binary mode is black and white only, +Gray will produce 256 levels of gray or more depending on the scanner +and Color means 24 bit color mode or more depending on the scanner. +Some scanners will internally use 36 bit color, their external interface +however may only support 24 bits. + +The +.B \-\-depth +option selects the bit depth the scanner is using. This option is only +available for scanners that support more than one bit depth. Older +scanners will always transfer the image in 8bit mode. Newer scanners +allow one to select either 8 bits, 12 or 14 bits per color channel. For a +color scan this means an effective color depth of 36 or 42 bits over +all three channels. The valid choices depend on the scanner model. + +The +.B \-\-halftoning +switch selects the mode that is used in Binary mode. Valid options +are "None", "Halftone A (Hard Tone)", "Halftone B (Soft Tone)", "Halftone C +(Net Screen)", "Dither A (4x4 Bayer)", "Dither B (4x4 Spiral)", "Dither C +(4x4 Net Screen)", "Dither D (8x4 Net Screen)", "Text Enhanced Technology", +"Download pattern A", and "Download pattern B". + +The +.B \-\-dropout +switch selects the so called dropout color. Valid options are None, +Red, Green and Blue. The default is None. The dropout color is used for +monochrome scanning and selects the color that is not scanned. This can +be used to e.g. scan an original with a colored background. + +The +.B \-\-brightness +switch controls the brightness of the scan. Valid options are integer +values from \-3 to 3. The default is 0. The larger the brightness value, +the brighter the image gets. If a user defined table for the gamma +correction is selected, the brightness parameter is not available. + +The +.B \-\-sharpness +switch sets the sharpness of the image data. Valid options are integer +values from \-2 to 2, with \-2 meaning "Defocus", \-1 "Defocus slightly", +0 "Normal", 1 "Sharpen slightly" and 2 "Sharpen". + +The +.B \-\-gamma\-correction +switch controls the scanner's internal gamma correction. Valid options are +"Default", "User defined", "High density printing" "Low density printing" +and "High contrast printing". + +The +.B \-\-color\-correction +switch controls the scanner's internal color correction function. Valid +options are "No Correction", "Impact\-dot printers", "Thermal printers", +"Ink\-jet printers" and "CRT monitors". The default is "CRT monitors". + +The +.B \-\-resolution +switch selects the resolution for a scan. Some EPSON scanners will scan in +any resolution between the lowest and highest possible value. The list +reported by the scanner can be displayed using the "\-\-help \-d epson" +parameters to +.BR scanimage (1). + +The +.B \-\-threshold +switch selects the minimum brightness to get a white point. + +The +.B \-\-mirror +option controls the way the image is scanned. By reading the image data +from right to left the image is mirrored. Valid options are "yes" and +"no". The default is "no". + +The +.B \-\-auto\-area\-segmentation +switch activates the automatic area segmentation for monochrome scans. The +scanner will try to determine which areas are text and which contain +images. The image areas will be halftoned, and the text will be +improved. Valid options are "yes" and "no". The default is "yes". + +The +.B \-\-red\-gamma\-table +parameter can be used to download a user defined gamma table for the +red channel. The valid options are the same as for \-\-gamma\-table. + +The +.B \-\-green\-gamma\-table +parameter can be used to download a user defined gamma table for the +green channel. The valid options are the same as for \-\-gamma\-table. + +The +.B \-\-blue\-gamma\-table +parameter can be used to download a user defined gamma table for the +blue channel. The valid options are the same as for \-\-gamma\-table. + +The +.B --wait-for-button +parameter can be used to wait until the button on the scanner is +pressed to actually start the scan process. + +The color correction coefficients +.B \-\-cct\-1 \-\-cct\-2 \-\-cct\-3 ... \-\-cct\-9 +will install color correction coefficients for the user defined color +correction. Values are specified as integers in the range \-127..127. + +The +.B \-\-preview +option requests a preview scan. The frontend software automatically selects a low +resolution. Valid options are "yes" and "no". The default is "no". + +The geometry options +.B \-l \-t \-x \-y +control the scan area: +.B \-l +sets the top left x coordinate, +.BR \-t +the top left y coordinate, +.BR \-x +selects the width and +.BR \-y +the height of the scan area. All parameters are specified in millimeters. + +The +.B \-\-source +option selects the scan source. Valid options depend on the installed +options. The default is "Flatbed". + +The +.B \-\-auto\-eject +option will eject a page after scanning from the document feeder. + +The +.B \-\-film\-type +option will select the film type for scans with the transparency +unit. This option is only activated if the TPU is selected as scan +source. Valid options are "Negative Film" and "Positive Film". + +The +.B \-\-focus\-position +option selects the focus position for all scans. Valid options are "Focus +2.5mm above glass" and "Focus on glass". The focus on the 2.5mm point +above the glass is necessary for scans with the transparency unit, so +that the scanner can focus on the film if one of the film holders is used. +This option is only functional for selected scanners, all other scanners +will ignore this option. + +The +.B \-\-bay +option selects which bay to scan + +The +.B \-\-eject +option ejects the sheet in the ADF. + +The +.B \-\-adf-mode +option select the ADF mode (simplex/duplex). + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/epson2.conf +specifies the device(s) that the +backend will use. Possible connection types are: +.TP +.B SCSI +This is the default, and if nothing else is specified the backend software will +open a given path as SCSI device. More information about valid syntax for SCSI +devices can be found in +.BR sane\-scsi (5). +.br +Usually SCSI scanners are configured with a line "scsi EPSON" in this file. In +some cases it may be necessary to only use the string "scsi" (e.g. for the GT-6500). +.TP +.B PIO \- Parallel Interface +The parallel interface can be configured in two ways: An integer value starting +at the beginning of a line will be interpreted as the IO address of the parallel +port. To make it clearer that a configured IO address is a parallel port the +port address can be preceded by the string "PIO". The PIO connection does not +use a special device file in the +.I /dev +directory. The IO address can be specified +in hex mode (prefixed with "0x"). +.TP +.B USB +For USB scanners not automatically detect, their VENDOR and PRODUCT ID can +be specified manually in the config file. +More information about valid syntax for USB devices can be found in +.BR sane\-usb (5). +.TP +.B Network +Network scanners can be auto-discovered if +.B autodiscovery +is specified after +.B net +keyword. An IP address to connect to can also be used. +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-epson2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-epson2.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_EPSON2 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.TP +.B SANE_DEBUG_EPSON2_SCSI +If the library was compiled with debug support enabled, this +environment variable controls the SCSI related debug level for this backend. +Only a value of 2 is supported. +.TP +.B SANE_DEBUG_EPSON2_NET +If the library was compiled with debug support enabled, this +environment variable controls the network related debug level for this +backend. E.g., a value of 128 requests all debug output to be printed. +Smaller levels reduce verbosity. +.TP +.B SANE_EPSON2_CMD_LVL +This allows one to override the function or command level that the backend +uses to communicate with the scanner. The function level a scanner +supports is determined during the initialization of the device. If +the backend does not recognize the function level reported by the +scanner it will default to function level B3. Valid function levels +are A1, A2, B1, B2, B3, B4, B5, B6, B7, B8, D1 and F5. Use this feature +only if you know what you are doing! + +.SH "SEE ALSO" + +.BR sane\-scsi (5), +.BR sane\-usb (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH BUGS + +None :-) At least none are currently known. + +.SH UNSUPPORTED DEVICES +The backend may be used with Epson scanners that are not yet listed +under the list of supported devices. A scanner that is not recognized +may default to the function level B3, which means that not all +functions that the scanner may be capable of are accessible. + +If the scanner is not even recognized as an Epson scanner this is +probably because the device name reported by the scanner is not in the +correct format. Please send this information to the backend maintainer +(email address is in the AUTHOR section of this man page or in the +AUTHORS file of the SANE distribution). + +.SH AUTHOR + +The package is written by Alessandro Zummo and is based on previous +work done by Karl Hienz Kremer in the epson package as well as based +on work by Christian Bucher and Kazuhiro Sasayama. diff --git a/upstream/fedora-40/man5/sane-epsonds.5 b/upstream/fedora-40/man5/sane-epsonds.5 new file mode 100644 index 00000000..ca718795 --- /dev/null +++ b/upstream/fedora-40/man5/sane-epsonds.5 @@ -0,0 +1,114 @@ +.TH sane\-epsonds 5 "29 Mar 2015" "" "SANE Scanner Access Now Easy" +.IX sane\-epsonds +.SH NAME +sane\-epsonds \- SANE backend for EPSON ESC/I-2 scanners +.SH DESCRIPTION +The +.B sane\-epsonds +library implements a SANE (Scanner Access Now Easy) backend that provides access +to Epson ESC/I-2 scanners. +.PP +Valid command line options and their syntax can be listed by using +.PP +.RS +scanimage \-\-help \-d epsonds +.RE +.PP +Not all devices support all options. +.TP +.I Scan Mode +The +.B \-\-mode +switch selects the basic mode of operation of the scanner. Valid choices +are Lineart, Gray and Color. The Lineart mode is black and white only, +Gray will produce 256 levels of gray or more depending on the scanner +and Color means 24 bit color mode or more depending on the scanner. +Some scanners will internally use 36 bit color, their external interface +however may only support 24 bits. + +The +.B \-\-depth +option selects the bit depth the scanner is using. This option is only +available for scanners that support more than one bit depth. Older +scanners will always transfer the image in 8bit mode. Newer scanners +allow one to select either 8 bits, 12 or 14 bits per color channel. For a +color scan this means an effective color depth of 36 or 42 bits over +all three channels. The valid choices depend on the scanner model. + +The +.B \-\-resolution +switch selects the resolution for a scan. Some EPSON scanners will scan in +any resolution between the lowest and highest possible value. The list +reported by the scanner can be displayed using the "\-\-help \-d epson" +parameters to +.BR scanimage (1). + +The geometry options +.B \-l \-t \-x \-y +control the scan area: +.B \-l +sets the top left x coordinate, +.B \-t +the top left y coordinate, +.B \-x +selects the width and +.B \-y +the height of the scan area. All parameters are specified in millimeters. + +The +.B \-\-source +option selects the scan source. Valid options depend on the installed +options. The default is "Flatbed". + +The +.B \-\-eject +option ejects the sheet in the ADF. + +The +.B \-\-adf-mode +option select the ADF mode (simplex/duplex). + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/epsonds.conf +specifies the device(s) that the backend will use. Possible connection types are: +.TP +.B USB +For not automatically detected USB scanners, their VENDOR and PRODUCT ID can +be specified manually in the config file. +More information about valid syntax for USB devices can be found in +.BR sane\-usb (5). +.TP +.B Network (not yet supported) +Network scanners can be auto-discovered if +.B autodiscovery +is specified after +.B net +keyword. An IP address to connect to can also be used. +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-epsonds.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-epsonds.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_EPSONDS +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. Values around 11-16 will usually be enough for +a bug report. + +.SH "SEE ALSO" + +.BR sane\-usb (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH AUTHOR + +The backend is written by Alessandro Zummo. diff --git a/upstream/fedora-40/man5/sane-fujitsu.5 b/upstream/fedora-40/man5/sane-fujitsu.5 new file mode 100644 index 00000000..34864cb6 --- /dev/null +++ b/upstream/fedora-40/man5/sane-fujitsu.5 @@ -0,0 +1,273 @@ +.TH sane\-fujitsu 5 "15 Nov 2022" "" "SANE Scanner Access Now Easy" +.IX sane\-fujitsu + +.SH NAME +sane\-fujitsu \- SANE backend for Fujitsu flatbed and ADF scanners + +.SH DESCRIPTION +The +.B sane\-fujitsu +library implements a SANE (Scanner Access Now Easy) backend which provides +access to most Fujitsu flatbed and ADF scanners. + +This document describes backend version 139, which initially shipped with SANE 1.1.2. + +.SH SUPPORTED HARDWARE +This version supports every known model which speaks the Fujitsu SCSI and +SCSI\-over\-USB protocols. Specifically, the SCSI M309x and M409x series, the +SCSI fi\-series, and most of the USB fi\-, ScanSnap, & iX series scanners are +supported. Please see the list at +.I http://www.sane\-project.org/sane\-supported\-devices.html +for details. + +This backend may support other Fujitsu scanners. The best +way to determine level of support is to test the scanner directly, +or to collect a trace of the windows driver in action. +Please contact the author for help or with test results. + +.SH UNSUPPORTED HARDWARE +The following scanners are known NOT to work with this backend, +either because they have a non\-Fujitsu chipset, or an unsupported +interface type. Some of these scanners may be supported by another +backend. +.PP +.RS +.ft CR +.nf +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +SCSI: SERIAL: USB: +\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\- +ScanStation M3093E/DE/EX fi\-4110EOX/2 +ScanPartner M3096EX fi\-4010CU +SP\-Jr M3097E+/DE S300/S300M +SP\-10/10C M3099A/EH/EX S1300/S1100 +SP\-15C/300C fi\-60F/65F +SP\-600C/620C fi\-5015C + SP\-2x/3x +.fi +.ft R +.RE +.P + +.SH OPTIONS +Effort has been made to expose all hardware options, including: +.PP +.B source s +.RS +Selects the source for the scan. Options +may include "Flatbed", "ADF Front", "ADF Back", "ADF Duplex", "Card Front", "Card Back", "Card Duplex". +.RE +.PP +.B mode m +.RS +Selects the mode for the scan. Options +may include "Lineart", "Halftone", "Gray", and "Color". +.RE +.PP +.B resolution, y\-resolution +.RS +Controls scan resolution. Setting +.B \-\-resolution +also sets +.BR \-\-y\-resolution, +though this behavior is overridden by some frontends. +.RE +.PP +.B tl\-x, tl\-y, br\-x, br\-y +.RS +Sets scan area upper left and lower right coordinates. These are renamed +.B t, l, x, y +by some frontends. +.RE +.PP +.B page\-width, page\-height +.RS +Sets paper size. Used by scanner to determine centering of scan +coordinates when using the ADF (Automatic Document Feeder) and to detect +double feed errors. +.RE +.PP +Other options will be available based on the capabilities of the scanner: +machines with IPC or DTC will have additional enhancement options, those +with CMP will have compression options, those with a printer will have a +group of endorser options. + +Additionally, several 'software' options are exposed by the backend. These +are reimplementations of features provided natively by larger scanners, but +running on the host computer. This enables smaller machines to have similar +capabilities. Please note that these features are somewhat simplistic, and +may not perform as well as the native implementations. Note also that these +features all require that the driver cache the entire image in memory. This +will almost certainly result in a reduction of scanning speed. +.PP +.B swcrop +.RS +Requests the driver to detect the extremities of the paper within the larger +image, and crop the empty edges. +.RE +.PP +.B swdeskew +.RS +Requests the driver to detect the rotation of the paper within the larger +image, and counter the rotation. +.RE +.PP +.B swdespeck X +.RS +Requests the driver to find and remove dots of X diameter or smaller from the +image, and fill the space with the average surrounding color. +.RE + +Use +.I 'scanimage \-\-help' +to get a list, but be aware that some options may +be settable only when another option has been set, and that advanced options +may be hidden by some frontend programs. + +.SH CONFIGURATION FILE +The configuration file +.I fujitsu.conf +is used to tell the backend how to look +for scanners, and provide options controlling the operation of the backend. +This file is read each time the frontend asks the backend for a list +of scanners, generally only when the frontend starts. If the configuration +file is missing, the backend will be unable to locate any scanners. +.PP +Scanners can be specified in the configuration file in 4 ways: +.PP +"scsi FUJITSU" +.RS +Requests backend to search all scsi buses in the system for a device +which reports itself to be a scanner made by 'FUJITSU'. +.RE +.PP +"scsi /dev/sg0" (or other scsi device file) +.RS +Requests backend to open the named scsi device. Only useful if you have +multiple compatible scanners connected to your system, and need to +specify one. Probably should not be used with the other "scsi" line above. +.RE +.PP +"usb 0x04c5 0x1042" (or other vendor/product ids) +.RS +Requests backend to search all usb buses in the system for a device +which uses that vendor and product id. The device will then be queried +to determine if it is a Fujitsu scanner. +.RE +.PP +"usb /dev/usb/scanner0" (or other device file) +.RS +Some systems use a kernel driver to access usb scanners. This method is +untested. +.RE +.PP +The only configuration option supported is "buffer\-size=xxx", allowing you +to set the number of bytes in the data buffer to something other than the +compiled\-in default, 65536 (64K). Some users report that their scanner will +"hang" mid\-page, or fail to transmit the image if the buffer is not large +enough. +.PP +Note: This option may appear multiple times in the configuration file. It only +applies to scanners discovered by 'scsi/usb' lines that follow this option. +.PP +Note: The backend does not place an upper bound on this value, as some users +required it to be quite large. Values above the default are not recommended, +and may crash your OS or lockup your scsi card driver. You have been +warned. +.PP + +.SH ENVIRONMENT +The backend uses a single environment variable, +.BR SANE_DEBUG_FUJITSU , +which enables debugging output to stderr. Valid values are: +.PP +.RS +5 Errors +.br +10 Function trace +.br +15 Function detail +.br +20 Option commands +.br +25 SCSI/USB trace +.br +30 SCSI/USB writes +.br +31 SCSI/USB reads +.br +35 Useless noise +.RE + +.SH KNOWN ISSUES +Flatbed units may fail to scan at maximum area, particularly at +high resolution. +.PP +Any model that does not support VPD during inquiry will not function until +an override is added to the backend. +.PP +CCITT Fax compression used by older scanners is not supported. +.PP +JPEG output is supported by the backend, but not by the SANE protocol, so is +disabled in this release. It can be enabled if you rebuild from source. +.PP +Network interfaces are not supported on any scanner model. + +.SH CREDITS +m3091 backend: Frederik Ramm +.RI < "frederik a t remote d o t org" > +.br +m3096g backend: Randolph Bentson +.RI < "bentson a t holmsjoen d o t com" > +.br + (with credit to the unnamed author of the coolscan driver) +.br +fujitsu backend, m3093, fi\-4340C, ipc, cmp, long\-time maintainer: +.br + Oliver Schirrmeister +.RI < "oschirr a t abm d o t de" > +.br +m3092: Mario Goppold +.RI < "mgoppold a t tbzpariv d o t tcc\-chemnitz dot de" > +.br +fi\-4220C and basic USB support: Ron Cemer +.RI < "ron a t roncemer d o t com" > +.br +fi\-4120, fi\-series color, backend re\-write, jpeg, current maintainer: + m. allan noah: +.RI < "kitno455 a t gmail d o t com" > + +JPEG output and low memory usage support funded by: + Archivista GmbH +.I www.archivista.ch + +Endorser support funded by: + O A S Oilfield Accounting Service Ltd + 1500, 840 \- 7th Avenue S.W. + Calgary, Alberta + T2P 3G2 Canada + 1\-403\-263\-2600 +.I www.oas.ca + +Automatic length detection support funded by: + Martin G. Miller +.I mgmiller at optonline.net + +Hardware donated, software image enhancement and fi-6/7xxx support funded by: + PFU America, Inc. +.I fujitsuscanners.com + +iX500 support funded by: + Prefix Computer Services +.I www.prefixservice.com + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-usb (5), +.BR sane\-sp15c (5), +.BR sane\-avision (5), +.BR sane\-epjitsu (5) + +.SH AUTHOR +m. allan noah: diff --git a/upstream/fedora-40/man5/sane-genesys.5 b/upstream/fedora-40/man5/sane-genesys.5 new file mode 100644 index 00000000..72ef8de0 --- /dev/null +++ b/upstream/fedora-40/man5/sane-genesys.5 @@ -0,0 +1,306 @@ +.TH "sane\-genesys" "5" "4 Jul 2012" "" "SANE Scanner Access Now Easy" +.IX sane\-genesys +.SH "NAME" +sane\-genesys \- SANE backend for GL646, GL841, GL843, GL847 and GL124 based USB flatbed scanners +.SH "DESCRIPTION" +The +.B sane\-genesys +library implements a SANE (Scanner Access Now Easy) backend that provides +access to USB flatbed scanners based on the Genesys GL646, GL841, GL843, GL847 and GL124 chips. +At present, the following scanners are known to work with this backend: +.PP +.RS +Canon LiDE 35/40/50/60/100/110/120/200/210/220/700 +.br +Hewlett-Packard HP2300C/HP2400/HP3670/HP3690/G4010/G4050 +.br +Medion MD5345/MD6228/MD6274 +.br +Panasonic KV-SS080 +.br +Plustek OpticBook 3600 +.br +Pentax DSmobile 600 +.br +Syscan/Ambir DocketPORT 467/485/487/665/685 +.br +Visioneer OneTouch 7100/Strobe XP100 (rev3)/XP200/XP300/Roadwarrior +.br +Xerox Travel Scanner 100, OneTouch 2400 +.RE + +.PP +This is stable software for supported models. But if you test new or untested scanners, keep +your hand at the scanner's plug and unplug it, if the head bumps at the end of +the scan area. +.PP +If you own a scanner other than the ones listed above that works with this +backend, please let me know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.IR /proc/bus/usb/devices , +.I sane\-find\-scanner +or syslog) to the sane\-devel mailing list. Even if the scanner's name is only +slightly different from the models mentioned above, please let me know. +.PP +If you own a scanner that isn't detected by the genesys backend but has a GL646, +GL841, GL843, GL847 or GL124 chipset, you can try to add it to the backend. +.PP +.SH "CALIBRATION" +To give correct image quality, sheet fed scanners need to be calibrated using the +calibration sheet sold with the scanner. To do calibration, you must insert this target +in the feeder then start calibration either by passing the \-\-calibrate option to scanimage +or by clicking on the available 'calibrate' button in the 'advanced options' in a graphical +frontend. The result of the calibration is stored in a file in the home directory of the user doing it. +If you plug the scanner in another machine or use it with another account, calibration +will have to be redone, unless you use the \-\-calibration\-file option. +If no home directory is defined, +.B USERAPPPROFILE +will be used, then +.B TMPDIR +or +.BR TMP. +If none of these directories exist, the backend will try +to write in the current working directory. Flatbed scanners also make use of the calibration file as a cache +to avoid calibration before each scan. Calibration file name is the name of the scanner model if only +one scanner is detected. In the case of several identical model, the file name will be the name +of the logical USB device name. The expiration time manages the time a calibration is valid in cache. +A value of -1 means forever, 0 means no cache. + +.SH EXTRAS SCAN OPTIONS + +.TP +.B \-\-lamp\-off\-time number +The lamp will be turned off after the given time (in minutes). A value of 0 means that the lamp won't be turned off. + +.TP +.B \-\-threshold percent +0..100% (in steps of 1). Select minimum brightness to get a white point. Pixels +with brightness below that value will be scanned as black. + +.TP +.B \-\-brightness value +\-100..100 (in steps of 1). Set the brightness enhancement. 0 for no enhancement, negative +values to decrease brightness, and positive values to increase it. + +.TP +.B \-\-contrast value +\-100..100 (in steps of 1). Set the contrast enhancement. 0 for no enhancement, negative +values to decrease contrast, and positive values to increase it. + +.TP +.B \-\-disable-interpolation yes|no +When using high resolutions where the horizontal resolution is smaller than vertical resolution, +data is expanded by software to preserve picture geometry. This can be disabled by this option to get +real scanned data. + +.TP +.B \-\-disable-dynamic-lineart yes|no +Disable use of a software adaptive algorithm to generate lineart and rely on hardware lineart. + +.TP +.B \-\-color-filter None|Red|Green|Blue +When using gray or lineart this option selects the used color. Using a color filter +will give a monochrome scan. CIS based scanners can to true gray when no filter (None value) is +selected. + +.TP +.B \-\-lamp\-off\-scan +The lamp will be turned off during the scan. Calibration is still done with lamp on. + +.TP +.B \-\-clear\-calibration +Clear calibration cache data, triggering a new calibration for the device when the +next scan will happen. + +.TP +.B \-\-calibration\-file +Specify the calibration file name to use. At least the directory containing the file +must exist, since it won't be created. This option is disabled if the backend is run +as root. It maybe used in case of sheet-fed scanners to share a calibration file for several +users. + +.TP +.B \-\-expiration\-time +Specify the time (in minutes) a cached calibration is considered valid. If older than the given value, a new +calibration is done. A value of -1 means no expiration and cached value are kept forever unless cleared by +userwith the calibration clear option. A value of 0 means cache is disabled. + +.PP +Additionally, several 'software' options are exposed by the backend. These +are reimplementations of features provided natively by larger scanners, but +running on the host computer. This enables smaller machines to have similar +capabilities. Please note that these features are somewhat simplistic, and +may not perform as well as the native implementations. Note also that these +features all require that the driver cache the entire image in memory. This +will almost certainly result in a reduction of scanning speed. + +.TP +.B \-\-swcrop +Requests the driver to detect the extremities of the paper within the larger +image, and crop the empty edges. + +.TP +.B \-\-swdeskew +Requests the driver to detect the rotation of the paper within the larger +image, and counter the rotation. + +.TP +.B \-\-swdespeck \-\-despeck X +Requests the driver to find and remove dots of X diameter or smaller from the +image, and fill the space with the average surrounding color. + +.TP +.B \-\-swskip 0..100% (in steps of 1) [0] +Request driver to discard pages with low numbers of dark pixels. + +.TP +.B \-\-swderotate[=(yes|no)] [no] +Request driver to detect and correct 90 degree image rotation. + +.SH "SYSTEM ISSUES" +This backend needs libusb-0.1.6 or later installed, and hasn't tested in other +configuration than a linux kernel 2.6.9 or higher. However, it should work any +system with libusb where the SANE package can be compiled. For +setting permissions and general USB information look at +.BR sane\-usb (5). + + +.SH "CONFIGURATION" +The contents of the +.I genesys.conf +file is a list of usb lines containing vendor and product ids that correspond +to USB scanners. The file can also contain option lines. Empty lines and +lines starting with a hash mark (#) are ignored. The scanners are +autodetected by +.B usb vendor_id product_id +statements which are already included into +.IR genesys.conf . +"vendor_id" and "product_id" are hexadecimal numbers that identify the +scanner. +.PP + +.SH "FILES" +.TP +.I /etc/sane.d/genesys.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-genesys.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-genesys.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH "ENVIRONMENT" +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory separator +character, then the default directories are searched after the explicitly +specified directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_GENESYS +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. Higher debug levels +increase the verbosity of the output. If the debug level is set to 1 or higher, +some debug options become available that are normally hidden. Handle them with +care. This will print messages related to core genesys functions. +.TP +.B SANE_DEBUG_GENESYS_IMAGE +If the library was compiled with debug support enabled, this environment +variable enables logging of intermediate image data. To enable this mode, +set the environmental variable to 1. + + +Example (full and highly verbose output for gl646): +.br +export SANE_DEBUG_GENESYS=255 + +.SH CREDITS + +Jack McGill for donating several sheetfed and flatbed scanners, which made possible to add support +for them in the genesys backend: +.RS +Hewlett-Packard HP3670 +.br +Visioneer Strobe XP100 (rev3)/XP200/XP300/Roadwarrior +.br +Canon LiDE 200 +.br +Pentax DSmobile 600 +.br +Syscan/Ambir DocketPORT 467/485/487/665/685 +.br +Xerox Travel Scanner 100, Onetouch 2400 +.RE +.TP +cncsolutions +.RI ( http://www.cncsolutions.com.br ) +sponsored and supported the work on the Panasonic KV-SS080. +.br +.TP +Brian Paavo from Benthic Science Limited for donating a Canoscan LiDE 700F. +.br +.TP +Dany Qumsiyeh for donating a Canoscan LiDE 210 and a LiDE 220. +.br +.TP +Luc Verhaegen for donating a Canoscan LiDE 120. +.br + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) +.br + + +.SH "AUTHOR" +Oliver Rauch +.br +Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > +.br +Gerhard Jaeger +.RI < gerhard@gjaeger.de > +.br +St\['e]phane Voltz +.RI < stef.dev@free.fr > +.br +Philipp Schmid +.RI < philipp8288@web.de > +.br +Pierre Willenbrock +.RI < pierre@pirsoft.dnsalias.org > +.br +Alexey Osipov +.RI < simba@lerlan.ru > +for HP2400 final support + +.SH "LIMITATIONS" + +Powersaving isn't implemented for gl646 based scanner. Dynamic (emulated from gray data and with dithering) +isn't enabled for gl646 scanners. Hardware lineart is limited up to 600 dpi for gl847 based scanners, +due to the way image sensors are built. +.PP +This backend will be much slower if not using libusb\-1.0. So be sure that sane\-backends is built with +the +.B \-\-enable-libusb_1_0 option. + +.SH "BUGS" +For the LiDE 200, the scanned data at 4800 dpi is obtained "as is" from sensor. +It seems the windows driver does some digital processing to improve it, which is not implemented in the backend. +.PP diff --git a/upstream/fedora-40/man5/sane-gphoto2.5 b/upstream/fedora-40/man5/sane-gphoto2.5 new file mode 100644 index 00000000..f3ffb819 --- /dev/null +++ b/upstream/fedora-40/man5/sane-gphoto2.5 @@ -0,0 +1,147 @@ +.TH sane\-gphoto2 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-gphoto2 +.SH NAME +sane\-gphoto2 \- SANE backend for gphoto2 supported cameras +.SH DESCRIPTION +The +.B sane\-gphoto2 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the digital cameras supported by gphoto2. +This backend has only been tested with a handful of cameras so far. Patches +to support other models are welcome. +.PP +Because of the limited testing of this backend, it is commented out +in +.I /etc/sane.d/dll.conf +by default. Either the comment +character must be removed or the backend must be called explicitly. +E.g. +.I "scanimage \-d gphoto2" +or +.IR "xscanimage gphoto2" . +.SH "DEVICE NAMES" +The current version of the backend only allows one camera to be +connected. The device name is always "0". +.SH CONFIGURATION +The contents of the +.I gphoto2.conf +specify the characteristics of the camera to be used. Resolutions +(high resolution, low resolution, and thumbnail size) are +required since they are needed by the sane frontends, but can't be obtained +through the gphoto2 interface. Valid ports and cameras can be obtained +by +.I "gphoto2 \-\-list\-cameras" +and +.I "gphoto2 \-\-list\-ports". +.PP +The +.B dumpinquiry +line causes some information about the camera to be printed. +.PP +Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +The +.B topfolder +line specifies the "fixed" part of the file path. For +example, on the Kodak DC-240, files are stored in the directory +.IR /DCIM/100DC240. +The +.I /DCIM +portion is constant, but 100DC240 will change and must be read from the camera. +In this case, the line would read "topfolder=/DCIM" +.PP +Some cameras don't implement a file structure and store all pictures +in the +.I "/" +directory. This is indicated by setting "subdirs=0" with +"topfolder=/" +.PP +.RS +port=usb: +.br +camera=Kodak DC240 +.br +# this is a comment +.br +high_resolution=1280x960 +.br +low_resolution=640x480 +.br +thumb_resolution=160x120 +.br +dumpinquiry +.RE +.PP +.SH FILES +.TP +.I /etc/sane.d/gphoto2.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-gphoto2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-gphoto2.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory +.RI ( "." ) +and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_GPHOTO2 +If the library was compiled with debugging support enabled, this +environment variable controls the debug level for this backend. +A value of 128 requests maximally copious debug output; smaller +levels reduce verbosity. +.TP +.B GP_DEBUG +Set to 1, 2, or 3, to enable various levels of debugging within the +gphoto2 libraries. + +.SH "SEE ALSO" +.BR sane (7) , +.BR scanimage (1) , +.BR xscanimage (1) , +.BR libgphoto2 (3) + +.SH AUTHOR +Peter S. Fales + +.PP +The manpage was largely copied from the +.BR sane\-dc210 (5) +manpage. + +.SH BUGS +Many, no doubt. +.PP +More general comments, suggestions, and inquiries about frontends +or SANE should go to the SANE Developers mailing list +(see +.I http://www.sane\-project.org/mailing\-lists.html +for details). +You must be subscribed to the list, otherwise your mail won't be +sent to the subscribers. diff --git a/upstream/fedora-40/man5/sane-gt68xx.5 b/upstream/fedora-40/man5/sane-gt68xx.5 new file mode 100644 index 00000000..4957c6ce --- /dev/null +++ b/upstream/fedora-40/man5/sane-gt68xx.5 @@ -0,0 +1,232 @@ +.TH sane\-gt68xx 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-gt68xx +.SH NAME +sane\-gt68xx \- SANE backend for GT-68XX based USB flatbed scanners +.SH DESCRIPTION +The +.B sane\-gt68xx +library implements a SANE (Scanner Access Now Easy) backend that provides +access to USB flatbed scanners based on the Grandtech GT-6801 and GT-6816 +chips. A list of supported scanners can be found on the gt68xx backend +homepage: +.IR http://www.meier\-geinitz.de/sane/gt68xx\-backend/ . +.PP +This is BETA software. Especially if you test new or untested scanners, keep +your hand at the scanner's plug and unplug it, if the head bumps at the end of +the scan area. +.PP +If you own a scanner other than the ones listed on the gt68xx homepage that works with this +backend, please let me know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.BR sane\-find\-scanner (1) +or syslog) to me. Even if the scanner's name is only slightly different from +the models already listed as supported, please let me know. +.PP +If you own a scanner that isn't detected by the gt68xx backend but has a GT-6801 +or GT-6816 chipset, you can try to add it to the backend. Have a look at the +following web page: +.I http://www.meier\-geinitz.de/sane/gt68xx\-backend/adding.html +.PP +.SH LIBUSB ISSUES +Please use libusb-0.1.8 or later. Without libusb or with older libusb versions +all kinds of trouble can be expected. The scanner should be found by +.BR sane\-find\-scanner (1) +without further actions. For setting permissions and general USB information, look at +.BR sane\-usb (5). +.PP + +.SH FIRMWARE FILE +You need a firmware file for your scanner. That's a small file containing +software that will be uploaded to the scanner's memory. It's usually named +*.usb, e.g. +.IR PS1fw.usb . +It comes on the installation CD that was provided by the manufacturer, but it +may be packaged together with the installation program in an .exe file. For +Mustek scanners, the file can be downloaded from the gt68xx backend homepage. For +other scanners, check the CD for .usb files. If you only find *.cab files, try +.BR cabextract (1) +to unpack. If everything else fails, you must install the Windows +driver and get the firmware from there (usually in the +.I windows/system +or +.I system32 +directories). Put that firmware file into +.IR /usr/share/sane/gt68xx/ . +Make sure that it's readable by everyone. + +.SH CONFIGURATION +The contents of the +.I gt68xx.conf +file is a list of usb lines containing vendor and product ids that correspond +to USB scanners. The file can also contain option lines. Empty lines and +lines starting with a hash mark (#) are ignored. The scanners are +autodetected by +.B usb vendor_id product_id +statements which are already included into +.IR gt68xx.conf . +"vendor_id" and "product_id" are hexadecimal numbers that identify the +scanner. +.PP +The +.BR override , +.BR firmware , +.BR vendor , +.BR model , +and +.B afe +options must be placed after the +.B usb +line they refer to. +.PP +Option +.B override +is used to override the default model parameters. That's necessary for some +scanners that use the same vendor/product ids but are different. For these +scanners there are already commented out override lines in the configuration +file. +.B override "mustek\-scanexpress\-1200\-ub\-plus" +is necessary for the Mustek Scanexpress 1200 UB Plus, the +Medion/Lifetec/Tevion LT 9452, and the Trust Compact Scan USB 19200. +.B override "artec\-ultima\-2000" +is used for the Artec Ultima 2000, the Boeder SmartScan Slim Edition, the +Medion/ Lifetec/ Tevion/ Cytron MD/LT 9385, the Medion/ Lifetec/ Tevion MD +9458, and the Trust Flat Scan USB 19200. +.B override "mustek\-bearpaw\-2400\-cu" +is necessary for the Mustek BearPaw 2400 CU and the Fujitsu 1200CUS. The +.B override +option must be the first one after the +.B usb +line. +.PP +Option +.B firmware +selects the name and path of the firmware file. It's only necessary if the +default (or override) doesn't work. The default firmware directory is +.IR /usr/share/sane/gt68xx/ . +You may need to create this directory. If you want to place the firmware files +at a different path, use a +.B firmware +line. +.PP +The +.B vendor +and +.B model +options are not absolutely necessary but for convenience. Quite a lot of +scanners from different manufacturers share the same vendor/product ids so you +can set the "correct" name here. +.PP +The +.B afe +option allows one to set custom offset and gain values for the Analog FrontEnd of +the scanner. This option can be either used to select the AFE values if +automatic coarse calibration is disabled, or to make automatic coarse +calibration faster. For the latter usage, enable debug level 3 (see below), +scan an image and look for debug line string with "afe". Copy this line to +.IR gt68xx.conf . +The option has six parameters: red offset, red gain, green offset, green gain, +blue offset, and blue gain. +.PP +A sample configuration file is shown below: +.PP +.RS +usb 0x05d8 0x4002 +.br +override "mustek\-scanexpress\-1200\-ub\-plus" +.br +firmware "/opt/gt68xx/SBfw.usb" +.br +vendor "Trust" +.br +model "Compact Scan USB 19200" +.br +afe 0x20 0x02 0x22 0x03 0x1f 0x04 +.RE + +.SH FILES +.TP +.I /etc/sane.d/gt68xx.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-gt68xx.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-gt68xx.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_GT68XX +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. Higher debug levels +increase the verbosity of the output. If the debug level is set to 1 or higher, +some debug options become available that are normally hidden. Handle them with +care. + +Example: +export SANE_DEBUG_GT68XX=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-artec_eplus48u (5) +.BR sane\-plustek (5), +.BR sane\-ma1509 (5), +.BR sane\-mustek_usb (5), +.BR sane\-mustek (5), +.BR sane\-mustek_pp (5), +.BR cabextract (1) +.br +.I /usr/share/doc/sane-backends/gt68xx/gt68xx.CHANGES +.br +.I http://www.meier\-geinitz.de/sane/gt68xx + +.SH AUTHOR +Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > +.br +The original gt68xx driver was written by Sergey Vlasov, Andreas Nowack, and +David Stevenson. Thanks for sending patches and answering questions to them +and all the other contributors. + +.SH BUGS +The first few lines of the image are garbage for the 2400 TA +Plus. +.PP +Interpolation should be used instead of just copying data, when the X- and +Y-resolution differ. +.PP +Support for buttons is missing. +.PP +More detailed bug information is available at the gt68xx backend homepage +.IR http://www.meier\-geinitz.de/sane/gt68xx\-backend/ . +.br +Please contact us if you find a bug or missing feature: +.RI < sane\-devel@alioth-lists.debian.net >. +.br +Please send a debug log if your scanner isn't +detected correctly (see +.B SANE_DEBUG_GT68XX +above). diff --git a/upstream/fedora-40/man5/sane-hp.5 b/upstream/fedora-40/man5/sane-hp.5 new file mode 100644 index 00000000..e8f725d5 --- /dev/null +++ b/upstream/fedora-40/man5/sane-hp.5 @@ -0,0 +1,304 @@ +.TH sane\-hp 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hp +.SH NAME +sane\-hp \- SANE backend for HP ScanJet scanners +.SH DESCRIPTION +The +.B sane\-hp +library implements a SANE (Scanner Access Now Easy) backend that +provides access to HP ScanJet scanners which support SCL (Scanner +Control Language by HP). The following +scanners are known positively to work with this backend: +.PP +.RS +.ft CR +.nf +Model: Product id: Interface: +---------- ----------- ---------- +ScanJet Plus C9195A HP Parallel Interface Card +ScanJet IIc C1750A 3226 SCSI +ScanJet IIcx C2500A 3332 SCSI +ScanJet IIp C1790A SCSI +ScanJet 3C C2520A 3503 SCSI +ScanJet 3P C2570A 3406 SCSI +ScanJet 4C C2520A SCSI +ScanJet 4P C1130A 3540 SCSI +ScanJet 4100C C6290A USB +ScanJet 5P C5110A SCSI +ScanJet 5100C C5190A parallel port +ScanJet 5200C C7190A 3846 parallel port/USB +ScanJet 6100C C2520A 3644 SCSI +ScanJet 6200C C6270A 3828 SCSI/USB +ScanJet 6250C C6270A 3828 SCSI/USB +ScanJet 6300C C7670A SCSI/USB +ScanJet 6350C C7670A SCSI/USB +ScanJet 6390C C7670A SCSI/USB +PhotoSmart C5100A R029,R030,R032 SCSI +.fi +.ft R +.RE +.PP +Support for models 5100C/5200C connected to the parallel port requires +the ppSCSI driver available at +.I http://cyberelk.net/tim/parport/ppscsi.html +and +.IR http://penguin-breeder.org/kernel/download/ . + +.PP +Support for models 5200C/62X0C/63X0C connected to the USB require +the kernel scanner driver or libusb. See +.BR sane\-usb (5) +for more details. +.PP +The +.B sane\-hp +backend no longer supports OfficeJet multi-function peripherals. +For these devices use the external "hpoj" backend in version 0.90 and later of +the "HP OfficeJet Linux driver", available at +.br +.IR http://hpoj.sourceforge.net +. +.PP +Because Hewlett-Packard does no longer produce scanners that support +SCL (beside the OfficeJets), the above list of supported scanners is +complete. +Other HP scanners are not supported by the +.B sane\-hp +backend, but might be supported by another one. See +.IR http://www.sane\-project.org/ . +You can also watch the sane\-devel mailing list at +.IR http://www.sane\-project.org/mailing\-lists.html . +.PP +More details about the hp backend can be found on its homepage +.IR http://www.kirchgessner.net/sane.html . +.PP +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the UNIX path-name for the special device that corresponds to the +scanner. For SCSI scanners the special device name must be a generic SCSI +device or a symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.IR /dev/sg2 , +for example. If the special device name contains "usb", "uscanner" or "ugen", +it is assumed that the scanner is connected by USB. +For the HP ScanJet Plus the special device name must be the device +that corresponds to the parallel interface card that was shipped with the +scanner. That is +.IR /dev/hpscan . +A special driver is required for this card. +See +.I ftp://rvs.ctrl\-c.liu.se/pub/wingel/hpscan +for details. If the link +does not work, try +.IR ftp://sunsite.unc.edu/pub/Linux/kernel/patches/scanners . +.SH CONFIGURATION +The contents of the +.I hp.conf +file is a list of options and device names that correspond to HP ScanJet +scanners. Empty lines and lines starting with a hash mark +(#) are ignored. See +.BR sane\-scsi (5) +and +.BR sane\-usb (5) +on details of what constitutes a valid device name. +.PP +Options specified in front of the first line that contains a device name +are defaults for all devices. Options specified below a line that +contains a device name apply just to the most recently mentioned device. +.PP +Supported options are +.BR connect\-scsi , +.BR connect\-device , +.BR enable\-image\-buffering , +and +.BR dumb\-read . + +Option +.B connect\-scsi +specifies that the scanner is connected to the system by SCSI. +Input/output is performed using SCSI-commands. This is the default. +But if your SCSI device name contains "usb", "uscanner" or "ugen", +option connect\-scsi must be specified. Otherwise it is assumed that +the scanner is connected by USB. + +Option +.B connect\-device +specifies that the scanner is connected to the system by a special +device. Input/output is performed by +.BR read ()/ write "()-operations" +on the device. This option must be used for HP ScanJet Plus +or scanners connected to USB which are accessed through a named device +(e.g. +.IR /dev/usb/scanner0 ). +For device names that contain "usb", "uscanner" or "ugen", it is not +necessary to specify option connect\-device. + +Option +.B enable\-image\-buffering +stores the scanned image in memory before passing it to the frontend. Could be +used in case of forward/backward moving scanner lamp. + +Option +.B dumb\-read +can be used to work around problems with "Error during device I/O". These +problems may occur with certain SCSI-to-USB converters or Buslogic SCSI cards. +The option should not be used for SCSI devices which are working correctly. +Otherwise startup of frontends and changing parameters might be slower. +.PP +A sample configuration file is shown below: +.PP +.RS +.ft CR +.nf +/dev/scanner +# this is a comment +/dev/hpscan +option connect\-device +.fi +.ft R +.RE +.PP +.I /dev/scanner +is typically a symlink to the actual SCSI scanner device. +.RE +.SH FILES +.TP +.I /etc/sane.d/hp.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-hp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hp.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.TP +.I $HOME/.sane/calib-hp:.dat +Calibration data for HP PhotoSmart PhotoScanner that is retrieved from the +scanner after calibration. The data is uploaded to the scanner at start +of the backend if it is in media mode 'print media' or if the media mode is +changed to 'print media'. +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory +.RI ( "." ) +and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_HP +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.TP +.B SANE_HOME_HP +Only used for OS/2 and along with use of HP PhotoSmart PhotoScanner. +Must be set to the directory where the directory .sane is located. +Is used to save and read the calibration file. +.TP +.B SANE_HP_KEEPOPEN_SCSI +.TP +.B SANE_HP_KEEPOPEN_USB +.TP +.B SANE_HP_KEEPOPEN_DEVICE +For each type of connection (connect\-scsi, connect\-usb, connect\-device) +it can be specified if the connection to the device should be kept open ("1") +or not ("0"). +Usually the connections are closed after an operation is performed. +Keeping connection open to SCSI-devices can result in errors during device IO +when the scanner has not been used for some time. By default, USB-connections +are kept open. Other connections are closed. +.TP +.B SANE_HP_RDREDO +Specifies number of retries for read operation before returning an EOF error. +Only supported for non-SCSI devices. Default: 1 retry. Time between retries +is 0.1 seconds. + +.SH BUGS +.TP +.B HP PhotoSmart PhotoScanner +In media mode 'slide' and 'negative', scan resolutions are rounded to +multiple of 300 dpi. The scanner does not scale the data correctly +on other resolutions. Some newer models (firmware code R030 and later) +do not support adjustment of contrast/intensity level and tone map. +The backend will simulate this by software, but only for gray +and 24 bit color. +.TP +.B Automatic Document Feeder (ADF) +For use of the ADF with +.BR xscanimage (1), +first place paper in the ADF and +then change option scan source to 'ADF'. Press 'change document' +to load a sheet. Then press 'scan' to start a scan. +Maybe it is sufficient to press 'scan' without 'change document' +for repeated scans. The use of the preview window is not recommended +when working with the ADF. +Setting a window to scan from ADF is not supported with +.BR xscanimage (1). +Try +.BR xsane (1). +.TP +.B Immediate actions +Some actions in +.BR xscanimage (1) +(i.e. unload, select media, calibrate) +have an immediate effect on the scanner without starting a scan. +These options can not be used with +.BR scanimage (1). + +.SH TODO +.TP +.B HP PhotoSmart PhotoScanner +PhotoScanners with firmware release R030 and up have +no firmware support for contrast/brightness/gamma table. In the current +backend this is simulated by software on 24 bits data. +Simulation on 30 bits should give better results. +.TP +.B Data widths greater than 8 bits +Custom gamma table does not work. +.TP +.B Parallel scanner support +Beside the ScanJet Plus which came with its own parallel interface card, +currently only the HP ScanJet 5100C/5200C are supported. +These scanners are using an internal parallel-to-SCSI converter which +is supported by the ppSCSI-driver (see above). + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-usb (5) +.BR scanimage (1), +.BR xscanimage (1), +.BR scanimage (1) + +.SH AUTHOR +The sane\-hp backend was written by Geoffrey T. Dairiki. +.br +HP PhotoSmart PhotoScanner support by Peter Kirchgessner. diff --git a/upstream/fedora-40/man5/sane-hp3500.5 b/upstream/fedora-40/man5/sane-hp3500.5 new file mode 100644 index 00000000..242b455b --- /dev/null +++ b/upstream/fedora-40/man5/sane-hp3500.5 @@ -0,0 +1,53 @@ +.TH sane\-hp3500 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hp3500 +.SH NAME +sane\-hp3500 \- SANE backend for Hewlett-Packard ScanJet 3500 series scanners +.SH DESCRIPTION +The +.B sane\-hp3500 +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the following Hewlett-Packard USB flatbed scanners: +.PP +.RS +ScanJet 3500C +.br +ScanJet 3530C +.br +ScanJet 3570C +.RE +.PP +If you own a scanner other than the ones listed above that works with this +backend, please let us know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.IR /proc/bus/usb/devices , +.B sane\-find\-scanner (1) +or syslog) to us. Even if the scanner's name is only slightly different from +the models mentioned above, please let us know. +.SH CONFIGURATION +None required. +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-hp3500.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hp3500.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.B SANE_DEBUG_HP3500 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_HP3500=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.br +.I http://projects.troy.rollo.name/rt-scanners/ + +.SH AUTHOR +Troy Rollo +.RI < sane@troy.rollo.name > diff --git a/upstream/fedora-40/man5/sane-hp3900.5 b/upstream/fedora-40/man5/sane-hp3900.5 new file mode 100644 index 00000000..b863e9d2 --- /dev/null +++ b/upstream/fedora-40/man5/sane-hp3900.5 @@ -0,0 +1,124 @@ +.TH sane\-hp3900 5 "06 Jan 2009" "" "SANE Scanner Access Now Easy" +.IX sane\-hp3900 +.SH NAME +sane\-hp3900 \- SANE backend for RTS8822 chipset based scanners +.SH DESCRIPTION +The +.B sane\-hp3900 +library implements a SANE (Scanner Access Now Easy) backend that provides +access at least to the following USB flatbed scanners: +.PP +.RS +.ft CR +.nf +Model: Chipset: +------ -------- +HP ScanJet 3800 RTS8822BL-03A +HP ScanJet 3970 RTS8822L-01H +HP ScanJet 4070 Photosmart RTS8822L-01H +HP ScanJet 4370 RTS8822L-02A +HP ScanJet G2710 RTS8822BL-03A +HP ScanJet G3010 RTS8822L-02A +HP ScanJet G3110 RTS8822L-02A +UMAX Astra 4900/4950 RTS8822L-01H * +BenQ 5550 RTS8823L-01E * +.fi +.ft R +.RE +.PP +More details can be found on the +.BR sane\-hp3900 (5) +backend homepage +.IR http://sourceforge.net/projects/hp3900\-series/ . +.PP +This is ALPHA software. Keep your hand at the scanner's plug and unplug it, if +scanner does not start to scan. See also the +.B BUGS +section. +.PP +If you own a scanner other than the ones listed above that works with this +backend, please let us know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.IR /proc/bus/usb/devices , +.BR sane\-find\-scanner (1) +or syslog) to us. Even if the scanner's name is only slightly different from +the models mentioned above, please let us know. +.PP + +.SH CONFIGURATION +The contents of the +.I hp3900.conf +file is a list of usb lines containing vendor and product ids that correspond +to USB scanners. The file can also contain the names of device files that +correspond to an HP 39XX scanner. Empty lines and lines starting with a hash +mark (#) are ignored. The scanners are autodetected by +.B usb vendor_id product_id +statements which are already included into +.IR hp3900.conf . +"vendor_id" and "product_id" are hexadecimal numbers that identify the +scanner. If autodetection does not work, add the device name of your scanner +to the configuration file, +.PP + +.SH FILES +.TP +.I /etc/sane.d/hp3900.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-hp3900.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hp3900.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory +.RI ( "." ) +and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_HP3900 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_HP3900=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-find\-scanner (1), +.br +.I http://sourceforge.net/projects/hp3900\-series/ +.br +.I http://jkdsoftware.dyndns.org/drupal/?q=es/books/151 + +.SH AUTHOR +Jonathan Bravo Lopez +.RI < jkdsoft@gmail.com > + +.SH BUGS +Scanning is only tested with Linux/ix86/gcc. Be careful when testing on other +operating systems and especially on big-endian platforms. The scanner may get +wrong data. diff --git a/upstream/fedora-40/man5/sane-hp4200.5 b/upstream/fedora-40/man5/sane-hp4200.5 new file mode 100644 index 00000000..9e216eea --- /dev/null +++ b/upstream/fedora-40/man5/sane-hp4200.5 @@ -0,0 +1,115 @@ +.TH sane\-hp4200 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hp4200 +.SH NAME +sane\-hp4200 \- SANE backend for Hewlett-Packard 4200 scanners +.SH DESCRIPTION +The +.B sane\-hp4200 +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the following Hewlett-Packard USB flatbed scanners: +.PP +.RS +ScanJet 4200 C +.br +ScanJet 4200 Cxi +.br +ScanJet 4200 Cse +.RE +.PP +More details can be found on the hp4200 backend homepage +.IR http://hp4200\-backend.sourceforge.net/ . +.PP +This is BETA software. Keep your hand at the scanner's plug and unplug it, if +the head bumps at the end of the scan area. +.PP +If you own a scanner other than the ones listed above that works with this +backend, please let us know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.IR /proc/bus/usb/devices , +.BR sane\-find\-scanner (1) +or syslog) to us. Even if the scanner's name is only slightly different from +the models mentioned above, please let us know. +.PP + +.SH CONFIGURATION +The contents of the +.I hp4200.conf +file is a list of usb lines containing vendor and product ids that correspond +to USB scanners. The file can also contain the names of device files that +correspond to an HP 4200 scanner. Empty lines and lines starting with a hash +mark (#) are ignored. The scanners are autodetected by +.B usb vendor_id product_id +statements which are already included into +.IR hp4200.conf . +"vendor_id" and "product_id" are hexadecimal numbers that identify the +scanner. If autodetection does not work, add the device name of your scanner +to the configuration file, e.g. +.IR /dev/usb/scanner0 . +.PP + +.SH FILES +.TP +.I /etc/sane.d/hp4200.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-hp4200.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hp4200.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory +.RI ( "." ) +and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_HP4200 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_HP4200=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-find\-scanner (1), +.br +.I http://hp4200\-backend.sourceforge.net/ + +.SH AUTHOR +Adrian Perez Jorge, Andrew John Lewis, Arnar Mar Hrafnkelsson, Frank Zago, +Henning Meier-Geinitz. Current maintainer: Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de >. + +.SH BUGS +Tested only with Linux. +.PP +Only 8 bit color mode works. +.PP +Scanning is slow due to backtracking. +.PP +Send bug reports to the sane\-devel mailing list: +.IR sane\-devel@alioth-lists.debian.net . diff --git a/upstream/fedora-40/man5/sane-hp5400.5 b/upstream/fedora-40/man5/sane-hp5400.5 new file mode 100644 index 00000000..4400ea5c --- /dev/null +++ b/upstream/fedora-40/man5/sane-hp5400.5 @@ -0,0 +1,113 @@ +.TH sane\-hp5400 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hp5400 +.SH NAME +sane\-hp5400 \- SANE backend for Hewlett-Packard 54XX scanners +.SH DESCRIPTION +The +.B sane\-hp5400 +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the following Hewlett-Packard USB flatbed scanners: +.PP +.RS +ScanJet 5400C +.br +ScanJet 5470C +.br +ScanJet 5490C +.RE +.PP +More details can be found on the hp5400 backend homepage +.IR http://hp5400backend.sourceforge.net/ . +.PP +This is ALPHA software. Keep your hand at the scanner's plug and unplug it, if +the head bumps at the end of the scan area. See also the BUGS section. +.PP +If you own a scanner other than the ones listed above that works with this +backend, please let us know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.IR /proc/bus/usb/devices , +.BR sane\-find\-scanner (1) +or syslog) to us. Even if the scanner's name is only slightly different from +the models mentioned above, please let us know. +.PP + +.SH CONFIGURATION +The contents of the +.I hp5400.conf +file is a list of usb lines containing vendor and product ids that correspond +to USB scanners. The file can also contain the names of device files that +correspond to an HP 54XX scanner. Empty lines and lines starting with a hash +mark (#) are ignored. The scanners are autodetected by +.B usb vendor_id product_id +statements which are already included into +.IR hp5400.conf . +"vendor_id" and "product_id" are hexadecimal numbers that identify the +scanner. If autodetection does not work, add the device name of your scanner +to the configuration file, e.g. +.IR /dev/usb/scanner0 . +.PP + +.SH FILES +.TP +.I /etc/sane.d/hp5400.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-hp5400.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hp5400.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory +.RI ( "." ) +and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_HP5400 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_HP5400=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-find\-scanner (1), +.br +.I http://hp5400backend.sourceforge.net/ + +.SH AUTHOR +Martijn van Oosterhout +.RI < kleptog@svana.org >, +Thomas Soumarmon +.RI < soumarmt@nerim.net >. +Manpage by Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de >. + +.SH BUGS +Scanning is only tested with Linux/ix86/gcc. Be careful when testing on other +operating systems and especially on big-endian platforms. The scanner may get +wrong data. diff --git a/upstream/fedora-40/man5/sane-hp5590.5 b/upstream/fedora-40/man5/sane-hp5590.5 new file mode 100644 index 00000000..ae8a8877 --- /dev/null +++ b/upstream/fedora-40/man5/sane-hp5590.5 @@ -0,0 +1,343 @@ +.\" Automatically generated by Pandoc 2.7.2 +.\" +.TH "sane-hp5590" "5" "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.hy +.SH NAME +.PP +sane-hp5590 - SANE backend for Hewlett-Packard +4500C/4570C/5500C/5550C/5590/7650 Workgroup/Document scanners +.SH DESCRIPTION +.PP +The +.B sane-hp5590 +library implements a SANE (Scanner Access Now Easy) backend that provides access +to the following Hewlett-Packard Workgroup/Document scanners: +.IP \[bu] 2 +ScanJet 4500C +.IP \[bu] 2 +ScanJet 4570C +.IP \[bu] 2 +ScanJet 5500C +.IP \[bu] 2 +ScanJet 5550C +.IP \[bu] 2 +ScanJet 5590 +.IP \[bu] 2 +ScanJet 7650 +.PP +If you own a scanner other than the ones listed above that works with +this backend, please let us know this by sending the scanner\[cq]s exact +model name and the USB vendor and device ids (e.g.\ from +.IR /sys/bus/usb/devices , +.BR sane-find-scanner (1) +or syslog) to us. +Even if the scanner\[cq]s name is only slightly different from the +models mentioned above, please let us know. +.SH OPTIONS +.PP +The options the backend supports can either be selected through command +line options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). +Valid command line options and their syntax can be listed by using: +.IP +.nf +\f[C] +scanimage --help -d hp5590:interface:device +\f[R] +.fi +.PP +where \f[I]interface\f[R] and \f[I]device\f[R] specify the device in +question, as in the configuration file. +Add +.B --all-options +to also list the hardware read-out options. +The +.B \-d +parameter and its argument can be omitted to obtain information +on the first scanner identified. +.PP +Use the command: +.IP +.nf +\f[C] +scanimage -L +\f[R] +.fi +.PP +to list all devices recognized by your SANE installation. +.SH DEVICE SPECIFIC OPTIONS +.TP +.B -l \f[I]n\f[R] +Top-left X position of scan area in \f[B]mm\f[R]. +Allowed range: 0 .. +215.889. +.TP +.B -t \f[I]n\f[R] +Top-left Y position of scan area in \f[B]mm\f[R]. +Allowed range: 0 .. +297.699. +.TP +.B -x \f[I]n\f[R] +X width of scan-area in \f[B]mm\f[R]. +Allowed range: 0 .. +215.889. +.TP +.B -y \f[I]n\f[R] +Y height of scan-area in \f[B]mm\f[R]. +Allowed range: 0 .. +297.699. +.PP +By default, the maximum size will be scanned. +.TP +.B --mode \f[I]mode\f[R] +Select color mode. +\f[I]mode\f[R] must be one of: \[lq]Color\[rq], \[lq]Color (48 +bits)\[rq], \[lq]Gray\[rq], \[lq]Lineart\[rq]. +.RS +.IP \[bu] 2 +\[lq]Color\[rq] - Scanning is done with 3 * 8 bit RGB color values per +pixel. +.IP \[bu] 2 +\[lq]Color (48 bits)\[rq] - Scanning is done with 3 * 16 bit RGB color +values per pixel. +.IP \[bu] 2 +\[lq]Gray\[rq] - Scanning is done with 1 * 8 bit gray value per pixel. +.IP \[bu] 2 +\[lq]Lineart\[rq] - Scanning is done with 1 bit black and white value +per pixel. +.RE +.TP +.B --source \f[I]source\f[R] +Select the source for scanning. +\f[I]source\f[R] must be one of: \[lq]Flatbed\[rq], \[lq]ADF\[rq], +\[lq]ADF Duplex\[rq], \[lq]TMA Slides\[rq], \[lq]TMA Negatives\[rq]. +.RS +.IP \[bu] 2 +\[lq]Flatbed\[rq] - Scan document on the flat document glass. +.IP \[bu] 2 +\[lq]ADF\[rq] - Scan frontsides of documents with automatic document +feeder. +.IP \[bu] 2 +\[lq]ADF Duplex\[rq] - Scan front- and backsides of documents with +automatic document feeder. +Note, the backside images must be rotated in a separate post process +step. +.IP \[bu] 2 +\[lq]TMA Slides\[rq] - Slide scanning with transparent media adapter. +(Not fully supported by hp5590 backend). +.IP \[bu] 2 +\[lq]TMA Negatives\[rq] - Negative film scanning with transparent media +adapter. +(Not fully supported by hp5590 backend). +.RE +.TP +.B --resolution \f[I]res\f[R] +Set the resolution of the scanned image in \f[B]dpi\f[R]. +\f[I]res\f[R] must be one of: 100, 200, 300, 600, 1200, 2400. +.PP +Default settings: Lineart, Flatbed, 100dpi. +.TP +.B --extend-lamp-timeout[=yes|no] +Extend lamp timeout period. +no = 15 minutes, yes = 1 hour. +(Default: no) +.TP +.B --wait-for-button[=yes|no] +Wait for button press before scanning starts. +(Default: no) +.TP +.B --preview[=yes|no] +Request a preview-quality scan. +(Default: no) +.TP +.B --hide-eop-pixel[=yes|no] +Hide end-of-page indicator pixels and overwrite with color of next +neighbor pixels. +(Default: yes) +.br +The scanner uses the last pixel in every scan line for storing the +end-of-page status. +This is needed to detect the end of the document sheet when the +automatic document feeder (ADF) is used. +Unfortunately the end-of-page pixels are also generated in flatbed +scans. +It is recommended to hide these pixels. +.TP +.B --trailing-lines-mode \f[I]mode\f[R] +Filling mode of trailing lines after end of page when automatic document +feeder (ADF) is used. +\f[I]mode\f[R] must be one of: \[lq]last\[rq], \[lq]raw\[rq], +\[lq]raster\[rq], \[lq]white\[rq], \[lq]black\[rq], \[lq]color\[rq]. +(Default: \[lq]last\[rq]) +.RS +.IP \[bu] 2 +\[lq]last\[rq] = repeat the last scan line (recommended), +.IP \[bu] 2 +\[lq]raw\[rq] = read raw scan data (not recommended), +.IP \[bu] 2 +\[lq]raster\[rq] = generate black and white pixel pattern, +.IP \[bu] 2 +\[lq]white\[rq] = white pixels, +.IP \[bu] 2 +\[lq]black\[rq] = black pixels, +.IP \[bu] 2 +\[lq]color\[rq] = RGB or gray colored pixels (see next option). +.RE +.TP +.B --trailing-lines-color \f[I]n\f[R] +Set color value for filling trailing scan lines in trailing lines mode +\[lq]color\[rq] (see previous option). +(Default color: violet) +.br +The RGB color value must be specified and calculated as 65536 * r + 256 +* g + b, with r, g, b being values in the range of 0 .. +255. +.SH READ OUT OPTIONS +.PP +The following options allow reading out the button state, counter value, +color setting, and the state of document in ADF. +This can be used to programmatically control corresponding scanner +options like switching between \f[I]flatbed\f[R] and \f[I]ADF\f[R] mode, +or triggering post processing tasks after scanning. +.TP +.B --button-pressed +Get the id of the last button pressed. +Id is one of \[lq]none\[rq], \[lq]power\[rq], \[lq]scan\[rq], +\[lq]collect\[rq], \[lq]file\[rq], \[lq]email\[rq], \[lq]copy\[rq], +\[lq]up\[rq], \[lq]down\[rq], \[lq]mode\[rq], \[lq]cancel\[rq]. +.br +The scanner stores the id of the last button pressed until it is read. +After read out, the state is reset and subsequent readings will return +\[lq]none\[rq]. + +.TP +.B --color-led +Get the state of the color LED indicators. +The state is either \[lq]color\[rq] or \[lq]black_white\[rq]. + +.TP +.B --counter-value +Get the counter value as shown on LCD. +The value is in the range of 1 .. +99. + +.TP +.B --doc-in-adf +Get the state of the document-available indicator of the automatic +document feeder (ADF). +The state is either \[lq]yes\[rq] or \[lq]no\[rq]. + +.SH HINTS FOR USERS OF SCANBD +.PP +.BR scanbd (8) +is a scanner button daemon, which can read scanner +buttons and trigger scan actions. +.PP +Do not use the old +.BR scanbuttond (8) +interface with hp5590. +It is outdated and shall not be used any more. +The regular interface of +.BR scanbd (8) +is fully supported by the current version +of the \f[I]hp5590\f[R] backend. +.PP +This example shows a minimum configuration file and the corresponding +script file for +.BR scanbd (8) +to be included in +.IR scanbd.conf . +.IP \[bu] 2 +.I hp5590.conf +.IP +.nf +\f[C] +device hp5590 { + # Device matching + filter = \[dq]\[ha]hp5590.*\[dq] + desc = \[dq]HP5590 Scanner Family\[dq] + + # Read out counter value and store in environment variable. + function function_lcd_counter { + filter = \[dq]\[ha]counter-value.*\[dq] + desc = \[dq]hp5590: LCD counter\[dq] + env = \[dq]SCANBD_FUNCTION_LCD_COUNTER\[dq] + } + + # Run scan script when button is pressed. + action do-scan { + filter = \[dq]\[ha]button-pressed.*\[dq] + desc = \[dq]hp5590: Scan button pressed\[dq] + script = \[dq]scan_action.script\[dq] + string-trigger { + from-value = \[dq]none\[dq] + to-value = \[dq]scan\[dq] + } + } +} +\f[R] +.fi +.IP \[bu] 2 +\f[B]scan_action.script\f[R] +.IP +.nf +\f[C] +#!/bin/bash +echo device = $SCANBD_DEVICE +echo action = $SCANBD_ACTION +echo counter = $SCANBD_FUNCTION_LCD_COUNTER +scanfile=\[dq]$HOME/tmp/scans/scan-$(date +%s).pnm\[dq] +case $SCANBD_ACTION in +do-scan) + scanimage -d \[dq]$SCANBD_DEVICE\[dq] > \[dq]$scanfile\[dq] + ;; +*) + echo Warning: Unknown scanbd action: \[dq]$SCANBD_ACTION\[dq] + ;; +esac +\f[R] +.fi +.SH FILES +.TP +.B \f[I]\[at]LIBDIR\[at]/libsane-hp5590.a\f[R] +The static library implementing this backend. +.TP +.B \f[I]\[at]LIBDIR\[at]/libsane-hp5590.so\f[R] +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.PP +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. +.PP +\f[B]SANE_DEBUG_HP5590\f[R] +.PP +Higher debug levels increase the verbosity of the output: +.IP +.nf +\f[C] +10 - generic processing +20 - verbose backend messages +40 - HP5590 high-level commands +50 - HP5590 low-level (USB-in-USB) commands +\f[R] +.fi +.TP +.B Example: +export SANE_DEBUG_HP5590=50 +.SH SEE ALSO +.PP +.BR sane (7), +.BR sane\-usb (5) +.BR scanbd (8), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH AUTHORS +Ilia Sotnikov +.RI < hostcc@gmail.com >. diff --git a/upstream/fedora-40/man5/sane-hpljm1005.5 b/upstream/fedora-40/man5/sane-hpljm1005.5 new file mode 100644 index 00000000..97c77ade --- /dev/null +++ b/upstream/fedora-40/man5/sane-hpljm1005.5 @@ -0,0 +1,50 @@ +.TH sane\-hpljm1005 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hpljm1005 +.SH NAME +sane\-hpljm1005 \- SANE backend for Hewlett-Packard LaserJet M1005 MFP Scanner +.SH DESCRIPTION +The +.B sane\-hpljm1005 +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the following Hewlett-Packard scanner: +.PP +.RS +LaserJet M1005 +.RE +.PP +If you own a scanner other than the ones listed above that works with this +backend, please let us know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.IR /proc/bus/usb/devices , +.BR sane\-find\-scanner (1) +or syslog) to us. Even if the scanner's name is only slightly different from +the models mentioned above, please let us know. +.SH CONFIGURATION +None required. +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-hpljm1005.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hpljm1005.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH "ENVIRONMENT" +.TP +.B SANE_DEBUG_HPLJM1005 +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. Higher debug levels +increase the verbosity of the output. + +There is not currently a great deal of diagnostic output, it being mainly +confined to error conditions. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-find\-scanner (1) + +.SH AUTHOR +Philippe R\['e]tornaz +.RI < couriousous@mandriva.org > diff --git a/upstream/fedora-40/man5/sane-hpsj5s.5 b/upstream/fedora-40/man5/sane-hpsj5s.5 new file mode 100644 index 00000000..f7766102 --- /dev/null +++ b/upstream/fedora-40/man5/sane-hpsj5s.5 @@ -0,0 +1,121 @@ +.TH sane\-hpsj5s 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hpsj5s +.SH NAME +sane\-hpsj5s \- SANE backend for HP ScanJet 5S sheet-fed scanner +.SH DESCRIPTION +The +.B sane\-hpsj5s +library implements a SANE (Scanner Access Now Easy) backend that +provides access to a parallel port Hewlett-Packard ScanJet 5S scanner. +.PP +IMPORTANT: this is alpha code. Don't expect this to work +correctly. Many functions are missing, others contain errors. In some +cases, your computer might even hang. It cannot be excluded (although +I consider it extremely improbable) that your scanner will be +damaged. +.PP +LIMITATIONS: For now this backend works only on Linux. This limitation +is due to dependence on the +.BR libieee1284 (3) +library. If your system supports +.BR libieee1284 (3) +too, this backend should work. If you ported +.BR libieee1284 (3) +for your platform, please let me know. Your system should support +.B EPP +(or +.BR EPP+ECP ) +mode to operate this scanner. Future versions will support ECP and SPP +(Nibble and Byte) modes also. It's planned to support scanners not only +at daisy-chain position 0, but anywhere. Support for multiple scanners could +be implemented too. +.PP +Current version implements only gray scale scanning. True Color and B/W modes are +not supported for now. +.PP +That said, TESTERS ARE WELCOME. Send your bug reports and comments to +Max Vorobiev +.RI < pcwizard@yandex.ru >. +.PP +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the parallel port name in form, +.BR libieee1284 (3) +expects. It seems to be system dependent. Under Linux it's parport0, parport1, etc. +.SH CONFIGURATION +The contents of the +.I hpsj5s.conf +file is a list of parport names that correspond to HP ScanJet 5S +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. Only one device name can be listed in +.IR hpsj5s.conf +for this moment. Future versions will support daisy chain selection. + +.SH TIPS +.PP +It seems that HP ScanJet 5S scanner uses software noise correction. This +feature, along with gamma correction and calibration, are not implemented for now. +They will be handled in future versions. +Native resolution for this scanner is 300 DPI. +Other modes may present aliasing artifacts. +.PP +.SH FILES +.TP +.I /etc/sane.d/hpsj5s.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-hpsj5s.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hpsj5s.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_HPSJ5S +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. Higher debug levels +increase the verbosity of the output. + +.SH "SEE ALSO" +.BR sane (7), +.BR libieee1284 (3) +.br +.I http://hpsj5s.sourceforge.net +.br +.I http://cyberelk.net/tim/libieee1284 +.br +.SH AUTHOR +Max Vorobiev +.br +Man page mostly based on +.IR canon.man . diff --git a/upstream/fedora-40/man5/sane-hs2p.5 b/upstream/fedora-40/man5/sane-hs2p.5 new file mode 100644 index 00000000..1e802a49 --- /dev/null +++ b/upstream/fedora-40/man5/sane-hs2p.5 @@ -0,0 +1,131 @@ +.TH sane\-hs2p 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-hs2p +.SH NAME +sane\-hs2p \- SANE backend for Ricoh SCSI flatbed/ADF scanners +.SH DESCRIPTION +The +.B sane\-hs2p +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the Ricoh IS450 family of scanners. Should also work with the IS420, +IS410, and IS430 scanners, but these are untested. +Please contact the maintainer or the sane\-devel mailing list if you own such a scanner. +.PP +This backend is alpha-quality. It may have bugs and some scanners haven't been +tested at all. Be careful and pull the plug if the scanner causes unusual +noise. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a SCSI +scanner. The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name could be +.I /dev/sg0 +or +.IR /dev/sga , +for example. See +.BR sane\-scsi (5) +for details. + +.SH CONFIGURATION +The contents of the +.I hs2p.conf +file is a list of device names that correspond to SCSI +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. + +.SH FILES +.TP +.I /etc/sane.d/hs2p.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-hs2p.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-hs2p.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_HS2P +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. +A value of 255 prints all debug output. Smaller values reduce verbosity. + +.SH CURRENT STATUS +The +.B sane\-hs2p +backend is now in version 1.00. All major scanning-related features +are supported, except for those features requiring the optional IPU. Scanning +from the flatbed or ADF (either simplex or duplex) is supported. Lineart, +halftone, 4-bit gray, and 8-bit gray are supported. Pre-set gamma tables and +halftone patterns are supported, as well as brightness, threshold, contrast. +Also supported is scan wait mode, binary and gray filtering, negative scanning, +and absolute or relative white setting. Printing with the optional endorser +also is supported. + +.SH PLANNED FUNCTIONALITY +This scanner can scan from the ADF in continuous simplex mode. +Surprisingly, many scanners scan an entire document from the ADF +into memory before ejecting the sheet. Thus if the document is too +long, the scanner cannot hold the entire image data in memory. +But if the scanner would send its image data when its memory got full, +and then read the next buffer's worth of data, continuous scanning +could be achieved. + +.SH MISSING FUNCTIONALITY +The SCSI commands for uploading (2AH) or downloading (28H) +custom halftone patterns (02H) and gamma vectors (03H) should work, +but require implementing the SANE Option-Value code to allow the +user to create the tables to be uploaded to the scanner. No support +for Maintenance Data (80H) is planned as this functionality is more +suited to a stand-alone utility to be used by a technician when +replacing the lamp or ADF unit. Nor is support for reading or changing +IPU (93H) parameters and adjustments planned, since my IS450 lacks +such a unit. The 31-byte Auto Photo/Letter struct and 21-byte Dynamic +threshold struct are documented in the +.I hs2p-scsi.h +file should someone wish to use their IPU for image data processing. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-find\-scanner (1), +.BR sane\-scsi (5), + +.SH AUTHOR +jeremy +.RI < jeremy@acjlaw.net > +.br +Maintained by Jeremy Johnson +.RI < jeremy@acjlaw.net > diff --git a/upstream/fedora-40/man5/sane-ibm.5 b/upstream/fedora-40/man5/sane-ibm.5 new file mode 100644 index 00000000..bbf98a87 --- /dev/null +++ b/upstream/fedora-40/man5/sane-ibm.5 @@ -0,0 +1,96 @@ +.TH sane\-ibm 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-ibm +.SH NAME +sane\-ibm \- SANE backend for IBM and Ricoh SCSI flatbed scanners +.SH DESCRIPTION +The +.B sane\-ibm +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the IBM 2456 and the Ricoh IS-410, IS-420, and IS-430 flatbed +scanners. Support for the IS-410 and IS-430 is untested. Please contact the +maintainer or the sane\-devel mailing list if you own such a scanner. +.PP +This backend is alpha-quality. It may have bugs and some scanners haven't been +tested at all. Be careful and pull the plug if the scanner causes unusual +noise. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a SCSI +scanner. The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name could be +.I /dev/sg0 +or +.IR /dev/sga , +for example. See +.BR sane\-scsi (5) +for details. + +.SH CONFIGURATION +The contents of the +.I ibm.conf +file is a list of device names that correspond to SCSI +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. + +.SH FILES +.TP +.I /etc/sane.d/ibm.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-ibm.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-ibm.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_IBM +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-find\-scanner (1), +.BR sane\-scsi (5), + +.SH AUTHOR +mf +.RI < massifr@tiscalinet.it > +.br +Maintained by Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > diff --git a/upstream/fedora-40/man5/sane-kodak.5 b/upstream/fedora-40/man5/sane-kodak.5 new file mode 100644 index 00000000..606218f6 --- /dev/null +++ b/upstream/fedora-40/man5/sane-kodak.5 @@ -0,0 +1,154 @@ +.TH sane\-kodak 5 "10 Feb 2010" "" "SANE Scanner Access Now Easy" +.IX sane\-kodak + +.SH NAME +sane\-kodak \- SANE backend for big Kodak flatbed and ADF scanners + +.SH DESCRIPTION +The +.B sane\-kodak +library implements a SANE (Scanner Access Now Easy) backend which +provides access to large Kodak flatbed and ADF scanners. + +This document describes backend version 7, which shipped with SANE 1.0.21. + +.SH SUPPORTED HARDWARE +This version should support models which speak the Kodak SCSI and Firewire +protocols. The i1860 was used to develop the backend, but other models may +work with only minimal modifications. Please see the list at +.I http://www.sane\-project.org/sane\-supported\-devices.html +for an updated list. + +If you have a machine not on that list, or reported as 'untested': the best way +to determine level of support is to test the scanner directly, or to collect a +trace of the windows driver in action. Please contact the author for help or +with test results. + +.SH UNSUPPORTED HARDWARE +Most of the recent Kodak consumer or workgroup level machines are based on +other chipsets and are not supported by this backend. Some of these scanners +may be supported by another backend. + +.SH OPTIONS +Effort has been made to expose the basic hardware options, including: +.PP +.B --source s +.RS +Selects the source for the scan. Options +may include "Flatbed", "ADF Front", "ADF Back", "ADF Duplex". +.RE +.PP +.B --mode m +.RS +Selects the mode for the scan. Options +may include "Lineart", "Halftone", "Gray", and "Color". +.RE +.PP +.B --resolution +.RS +Controls scan resolution. Available choices may be limited by mode. +.RE +.PP +.BR --tl\-x ", " --tl\-y ", " --br\-x ", " --br\-y +.RS +Sets scan area upper left and lower right coordinates. These are renamed +.BR -t ", " -l ", " -x ", " -y +by some frontends. +.RE +.PP +.BR --page\-width ", " --page\-height +.RS +Sets paper size. Used by scanner to determine centering of scan +coordinates when using the ADF (Automatic Document Feeder) and to +detect double feed errors. +.RE +.PP +Other options will be available based on the capabilities of the scanner. +Use +.I scanimage \-\-help +to get a list, but be aware that some options may +be settable only when another option has been set, and that advanced options +may be hidden by some frontend programs. +.PP +.SH CONFIGURATION FILE +The configuration file +.I kodak.conf +is used to tell the backend how to look +for scanners, and provide options controlling the operation of the backend. +This file is read each time the frontend asks the backend for a list +of scanners, generally only when the frontend starts. If the configuration +file is missing, the backend will use a set of compiled defaults, which +are identical to the default configuration file shipped with SANE. +.PP +Scanners can be specified in the configuration file in 2 ways: +.PP +"scsi KODAK" +.RS +Requests backend to search all scsi buses in the system for a device +which reports itself to be a scanner made by 'KODAK'. +.RE +.PP +"scsi /dev/sg0" (or other scsi device file) +.RS +Requests backend to open the named scsi device. Only useful if you have +multiple compatible scanners connected to your system, and need to +specify one. Probably should not be used with the other "scsi" line above. +.RE +.PP +The only configuration option supported is "buffer\-size=xxx", allowing you +to set the number of bytes in the data buffer to something other than the +compiled\-in default, 32768 (32K). Some users report that their scanner will +"hang" mid\-page, or fail to transmit the image if the buffer is not large +enough. +.PP +Note: This option may appear multiple times in the configuration file. It only +applies to scanners discovered by 'scsi/usb' lines that follow this option. +.PP +Note: The backend does not place an upper bound on this value, as some users +required it to be quite large. Values above the default are not recommended, +and may crash your OS or lockup your scsi card driver. You have been +warned. +.PP + +.SH ENVIRONMENT +The backend uses a single environment variable, +.BR SANE_DEBUG_KODAK , +which enables debugging output to stderr. Valid values are: +.PP +.RS +5 Errors +.br +10 Function trace +.br +15 Function detail +.br +20 Option commands +.br +25 SCSI trace +.br +30 SCSI detail +.br +35 Useless noise +.RE + +.SH KNOWN ISSUES +Most hardware options are either not supported or not exposed for control by +the user, including: multifeed detection, image compression, autocropping, +endorser, thresholding, multi\-stream, etc. +.PP + +.SH CREDITS +The various authors of the +.BR sane\-fujitsu (5) +backend provided useful code. +.br +Kodak provided access to hardware, documentation and personnel. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR scanimage (1) + +.SH AUTHOR +m. allan noah: +.RI < "kitno455 a t gmail d o t com" > diff --git a/upstream/fedora-40/man5/sane-kodakaio.5 b/upstream/fedora-40/man5/sane-kodakaio.5 new file mode 100644 index 00000000..002cfd39 --- /dev/null +++ b/upstream/fedora-40/man5/sane-kodakaio.5 @@ -0,0 +1,49 @@ +.TH sane\-kodakaio 5 "17 Jun 2012" "" "SANE Scanner Access Now Easy" +.IX sane\-kodakaio + +.SH NAME +sane\-kodakaio \- SANE backend for Kodak aio printer / scanners + +.SH DESCRIPTION +The +.B sane\-kodakaio +library implements a SANE (Scanner Access Now Easy) backend which +provides access to Kodak aio printer/scanners, like the ESP and Hero series. + +This document describes backend version 2.4, which is the first candidate for +incorporation in sane-backends. + +.SH SUPPORTED HARDWARE +This version should support models of the Kodak ESP and Hero series, and possibly some +Advent AiO scanners. The ESP 5250 and Hero 9.1 were used to develop the backend, +but other models may work. Please see the supported devices list at +.IR http://www.sane-project.org/sane-backends.html#S-KODAKAIO . + +If you have a model not on that list, or reported as 'untested': the best way +to determine level of support is to test the scanner directly. + +.SH CONFIGURATION FILE +The configuration file +.I kodakaio.conf +is used to tell the backend how to look +for scanners, and provide options controlling the operation of the backend. +This file is read each time the frontend asks the backend for a list +of scanners, generally only when the frontend starts. + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_KODAKAIO +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +.SH KNOWN ISSUES +Most hardware options are either not supported or not exposed for control by +the user, including: multifeed detection, image compression etc. +.PP + +.SH "SEE ALSO" +.BR sane (7) + +.SH AUTHOR +P. Newall diff --git a/upstream/fedora-40/man5/sane-kvs1025.5 b/upstream/fedora-40/man5/sane-kvs1025.5 new file mode 100644 index 00000000..afc7dc9e --- /dev/null +++ b/upstream/fedora-40/man5/sane-kvs1025.5 @@ -0,0 +1,32 @@ +.TH sane\-kvs1025 5 "16 Apr 2010" "" "SANE Scanner Access Now Easy" +.IX sane\-kvs1025 + +.SH NAME +sane\-kvs1025 \- SANE backend for Panasonic KV-S102xC USB ADF scanners. + +.SH DESCRIPTION +The +.B sane\-kvs1025 +library implements a SANE (Scanner Access Now Easy) backend which +provides access to the Panasonic KV-S1020C/1025C and KV-S1045C scanners. + +.SH KNOWN ISSUES +This document was written by the SANE project, which has no information +regarding the capabilities or reliability of the backend. All information +contained here is suspect. + +.SH CREDITS +The backend was written by Tao Zhang / Panasonic Russia Ltd. + +The backend was ported to sane-backends 1.0.21 and updated to use +sanei_usb instead of libusb by m. allan noah. + +The backend was tested on KV-S1025C and 1045C by Tiago Zaniquelli. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) + +.SH AUTHOR +m. allan noah: +.RI < "kitno455 a t gmail d o t com" > diff --git a/upstream/fedora-40/man5/sane-kvs20xx.5 b/upstream/fedora-40/man5/sane-kvs20xx.5 new file mode 100644 index 00000000..06c8523f --- /dev/null +++ b/upstream/fedora-40/man5/sane-kvs20xx.5 @@ -0,0 +1,31 @@ +.TH sane\-kvs20xx 5 "09 Jun 2010" "" "SANE Scanner Access Now Easy" +.IX sane\-kvs20xx + +.SH NAME +sane\-kvs20xx \- SANE backend for Panasonic KV-S20xxC USB/SCSI ADF scanners + +.SH DESCRIPTION +The +.B sane\-kvs20xx +library implements a SANE (Scanner Access Now Easy) backend which +provides access to the Panasonic KV-S202xC and KV-S204xC scanners. + +.SH KNOWN ISSUES +This document was written by the SANE project, which has no information +regarding the capabilities or reliability of the backend. All information +contained here is suspect. + +.SH CREDITS +The backend was written by Panasonic Russia Ltd. + +The backend was ported to sane-backends 1.0.22 and downgraded to C89 +by m. allan noah. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-scsi (5) + +.SH AUTHOR +m. allan noah: +.RI < "kitno455 a t gmail d o t com" > diff --git a/upstream/fedora-40/man5/sane-kvs40xx.5 b/upstream/fedora-40/man5/sane-kvs40xx.5 new file mode 100644 index 00000000..6598e683 --- /dev/null +++ b/upstream/fedora-40/man5/sane-kvs40xx.5 @@ -0,0 +1,33 @@ +.TH sane\-kvs40xx 5 "03 Jun 2011" "" "SANE Scanner Access Now Easy" +.IX sane\-kvs40xx + +.SH NAME +sane\-kvs40xx \- SANE backend for Panasonic KV-S40xxC USB/SCSI ADF scanners. + +.SH DESCRIPTION +The +.B sane\-kvs40xx +library implements a SANE (Scanner Access Now Easy) backend which +provides access to the Panasonic KV-S40xxC and KV-S70xxC scanners. + +.SH KNOWN ISSUES +This document was written by the SANE project, which has no information +regarding the capabilities or reliability of the backend. All information +contained here is suspect. + +The backend uses pthreads directly, and so requires pthreads to be enabled. + +.SH CREDITS +The backend was written by Panasonic Russia Ltd. + +The backend was ported to sane-backends 1.0.23 and downgraded to C89 +by m. allan noah. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-scsi (5) + +.SH AUTHOR +m. allan noah: +.RI < "kitno455 a t gmail d o t com" > diff --git a/upstream/fedora-40/man5/sane-leo.5 b/upstream/fedora-40/man5/sane-leo.5 new file mode 100644 index 00000000..f08d0681 --- /dev/null +++ b/upstream/fedora-40/man5/sane-leo.5 @@ -0,0 +1,167 @@ +.TH sane\-leo 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-leo +.SH NAME +sane\-leo \- SANE backend for LEO Technologies scanners +.SH DESCRIPTION +The +.B sane\-leo +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some LEO SCSI flatbed scanners. This backend +should be considered +.B beta-quality +software! LEO scanners were also sold under the Across Technologies brand. +.PP +The scanners that should work with this backend are: +.PP +.RS +.ft CR +.nf + Vendor Model status +---------------------- ----------- + Across FS-1130 tested + LEO S3 tested +.fi +.ft R +.RE + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). + +.br +If you have any strange behavior, please report to the backend +maintainer or to the SANE mailing list. + +Valid command line options and their syntax can be listed by using +.RS +scanimage \-\-help \-d leo +.RE + +.TP +.B Scan Mode + +.TP +.B \-\-mode +selects the basic mode of operation of the scanner. Valid choices are +.IR "Black & White" , +.I Grayscale +and +.IR Color . +The +.I Black & White +mode is black and white only (1 bit). +.I Grayscale +mode will produce 256 levels of gray (8 bits). +.I Color +mode will produce a 24 bit color image. + +.TP +.B \-\-resolution +selects the resolution for a scan. The scanner can do all resolutions +between 1 and 300, in increments of 1. + + +.TP +.B Geometry options + +.TP +.B \-l \-t \-x \-y +control the scan area: \-l sets the top left x coordinate, \-t the top +left y coordinate, \-x selects the width and \-y the height of the scan +area. All parameters are specified in millimeters by default. + + +.TP +.B Enhancement options + +.TP +.B \-\-custom\-gamma +(grayscale and color mode only) allows the user to specify a gamma table (see the +next 3 parameters). + +.TP +.B \-\-red\-gamma\-table +(color mode only) can be used to download a user defined +gamma table for the red channel. The table must be 256 bytes long. + +.TP +.B \-\-green\-gamma\-table +(color mode only) can be used to download a user defined +gamma table for the green channel. The table must be 256 bytes long. + +.TP +.B \-\-blue\-gamma\-table +(color mode only) can be used to download a user defined gamma table +for the blue channel. The table must be 256 bytes long. + +.TP +.B \-\-halftone +(Black & White only) select the halftone mask to use. Possible values are +.IR Diamond , +.IR "8x8 Coarse Fatting" , +.IR "8x8 Fine Fatting" , +.I 8x8 Bayer +and +.IR "8x8 Vertical Line" . + +.TP +.B \-\-preview +requests a preview scan. The resolution used for that scan is 28 dpi +and the scan area is the maximum allowed. The scan mode is user +selected. The default is "no". + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/leo.conf +supports only one information: the device name to use (eg +.IR /dev/scanner ). + + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-leo.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-leo.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_LEO +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller levels +reduce verbosity. + + +.SH LIMITATIONS +The windows TWAIN driver has many more options than this SANE +backend. However they are only software adjustments. This backend only +implements what the scanner can support. + + +.SH BUGS +None known. + + +.SH "SEE ALSO" + +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + + +.SH AUTHOR + +.TP +The package is actively maintained by Frank Zago. +.I http://www.zago.net/sane/#leo diff --git a/upstream/fedora-40/man5/sane-lexmark.5 b/upstream/fedora-40/man5/sane-lexmark.5 new file mode 100644 index 00000000..8a6fb031 --- /dev/null +++ b/upstream/fedora-40/man5/sane-lexmark.5 @@ -0,0 +1,172 @@ +.TH "sane\-lexmark" "5" "12 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-lexmark +.SH "NAME" +sane\-lexmark \- SANE backend for Lexmark X1100/X1200 Series scanners +.SH "DESCRIPTION" +The +.B sane\-lexmark +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the scanner part of Lexmark X1100/X1200 AIOs. This backend +should be considered +.B beta-quality +software! +.PP +The scanners that should work with this backend are: +.PP +.RS +.ft CR +.nf + Vendor Model status +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- + Lexmark X74 good + Lexmark X1110 untested + Lexmark X1140 untested + Lexmark X1150 good + Lexmark X1170 good + Lexmark X1180 good + Lexmark X1185 complete + Lexmark X12xx good in USB1.1, + not fully tested in USB2.0 + Dell A920 good +.fi +.ft R +.RE + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). + +.br +If you notice any strange behavior, please report to the backend +maintainer or to the SANE mailing list. + +Valid command line options and their syntax can be listed by using +.RS +.PP +scanimage \-\-help \-d lexmark:usb: +.RE + +.TP +.B Scan Mode Options + +.TP +.B \-\-mode +selects the basic mode of operation of the scanner. Valid choices are +.IR Color , +.I Gray +and +.IR Lineart . +The default mode is +.IR Color . +The +.I Lineart +mode is black and white only (1 bit). +.I Gray +mode will produce 256 levels of gray (8 bits). +.I Color +mode allows for over 16 million different colors produced from 24 +bits of color information. + +.TP +.B \-\-resolution +selects the resolution for a scan. The horizontal and vertical resolutions are set +by the value of this option. The scanner is capable of the following resolutions for the specified option value: +.PP +.RS +.ft CR +.nf + Value Hor. Resolution Vert. Resolution + \-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 75 75dpi 75dpi + 150 150dpi 150dpi + 300 300dpi 300dpi + 600 600dpi 600dpi + 1200 600dpi 1200dpi (only for X11xx models with 'B2' sensor) +.fi +.ft R +.RE + +.TP +.B \-\-preview +requests a preview scan. The resolution used for that scan is 75 dpi +and the scan area and the scan mode are as specified through their options, +or the default if not specified. The default value for preview mode is "no". + +.TP +.B \-\-threshold +selects the minimum-brightness to get a white point. The threshold is only used with Lineart mode scans. +It is specified as a percentage in the range 0..100% (in steps of 1). +The default value of the threshold option is 50. + + +.SH "CONFIGURATION FILE" +The configuration file +.I /etc/sane.d/lexmark.conf +contains only the usb device id (eg usb 0x043d 0x007c). + + +.SH "FILES" +.TP +.I /usr/lib64/sane/libsane\-lexmark.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-lexmark.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH "ENVIRONMENT" +.TP +.B SANE_DEBUG_LEXMARK +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller levels +reduce verbosity. +.TP +.B SANE_DEBUG_LEXMARK_LOW +Provides debug output for low level Lexmark functions. + +.SH "LIMITATIONS" +The windows TWAIN driver has many more options than this SANE +backend. However they are only software adjustments. This backend only +implements what the scanner can support. For instance, shading correction +(vertical stripes due to sensor variation across its width) is done in +software. Head park position is also detected by software. +The data compression isn't supported for the X1200 series on USB 1.1, +leading to slow scans. + +.SH "BUGS" +.br +No bugs currently known. + + + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + + +.SH "AUTHOR" +.TP +The backend was originally written by Fred Odendaal. +.I http://ca.geocities.com/freshshelf@rogers.com/ +.TP +The new version is currently developed by St\['e]phane Voltz. +.I http://stef.dev.free.fr/sane/lexmark +.TP +X74 support was written by Torsten Houwaart +.RI < ToHo@gmx.de > + +.SH "CREDITS" +.TP +Many thanks go to: +Julien Furgerot who lent me a Dell A920. +Robert Price, Dani Ele and Dalai Felinto for the time they spent recording +USB activity and testing the experimental version. diff --git a/upstream/fedora-40/man5/sane-ma1509.5 b/upstream/fedora-40/man5/sane-ma1509.5 new file mode 100644 index 00000000..9a0f7e88 --- /dev/null +++ b/upstream/fedora-40/man5/sane-ma1509.5 @@ -0,0 +1,142 @@ +.TH sane\-ma1509 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-ma1509 +.SH NAME +sane\-ma1509 \- SANE backend for Mustek BearPaw 1200F USB scanner +.SH DESCRIPTION +The +.B sane\-ma1509 +library implements a SANE (Scanner Access Now Easy) backend that provides +access to the Mustek BearPaw 1200F USB flatbed scanner. This scanner is based +on the MA-1509 chipset. Other scanners that use this chip (if they exist) may +also work. +.PP +This backend is ALPHA software. Be careful and remove the power plug +immediately if your hear unusual noises. +.PP +More details can be found on the +.B sane\-ma1509 +backend homepage +.IR http://www.meier\-geinitz.de/sane/ma1509\-backend/ . +.PP +Other Mustek USB scanners are supported by the +.BR sane\-mustek_usb (5), +.BR sane\-gt68xx (5) +and +.BR sane\-plustek (5) +backends. +.PP +This backend can only work with scanners that are already detected by the +operating system. See +.BR sane\-usb (5) +for details. +.PP +If you own a scanner other than the Mustek BearPaw 1200F that works with this +backend, please let me know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.I /proc/bus/usb/devices +or syslog) to me. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is a path-name for the special device that corresponds to a USB scanner. +With Linux, such a device name could be +.I /dev/usb/scanner0 +or +.IR libusb:001:002 , +for example. +.PP + +.SH CONFIGURATION +The contents of the +.I ma1509.conf +file is a list of options and device names that correspond to Mustek BearPaw +1200F scanners. Empty lines and lines starting with a hash mark (#) are +ignored. +.PP +Instead of using the device name, the scanner can be autodetected by +.B "usb vendor_id product_id" +statements which are already included into +.IR ma1509.conf . +This is only supported with Linux 2.4.8 and higher and all systems that +support libsub. "vendor_id" and "product_id" are hexadecimal numbers that +identify the scanner. If this doesn't work, a device name must be placed in +.I ma1509.conf +as described above. +.PP +To set the time the lamp needs for warm-up, use +.B option +.B warmup-time +in +.IR ma1509.conf . +The time is given in seconds after the option. The default is 30 seconds. +.SH FILES +.TP +.I /etc/sane.d/ma1509.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-ma1509.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-ma1509.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_MA1509 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-gt68xx (5), +.BR sane\-plustek (5), +.BR sane\-mustek_usb (5), +.BR sane\-mustek (5), +.BR sane\-mustek_pp (5), +.br +.I http://www.meier\-geinitz.de/sane/ma1509\-backend/ + +.SH AUTHOR +Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > + +.SH BUGS +Resolutions higher than 600 dpi don't work +.br +Transparency adapter and automatic document feeder is not supported yet +.br +No support for "high-speed" mode (jpeg) +.PP +More detailed bug information is available at the MA-1509 backend homepage +.IR http://www.meier\-geinitz.de/sane/ma1509-backend/ . diff --git a/upstream/fedora-40/man5/sane-magicolor.5 b/upstream/fedora-40/man5/sane-magicolor.5 new file mode 100644 index 00000000..67a8a46a --- /dev/null +++ b/upstream/fedora-40/man5/sane-magicolor.5 @@ -0,0 +1,90 @@ +.\" .IX sane-magicolor +.TH "sane-magicolor" "5" "10 Jan 2011" "" "SANE Scanner Access Now Easy" +.SH "NAME" +sane\-magicolor \- SANE backend for KONICA MINOLTA magicolor scanners +.SH "DESCRIPTION" +The +.B sane\-magicolor +backend supports KONICA MINOLTA magicolor scanners connected via USB or LAN. Currently, only the magicolor 1690MF device is supported, no other devices with the same scanning protocol are known. +.SH "SUPPORTED DEVICES" +The following scanner should work with this backend: + +Device Details +.br +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.br +Vendor: KONICA MINOLTA +.br +Model: magicolor 1690MF + +.SH "CONFIGURATION" +.PP +This section describes the backend's configuration file entries. The file is located at: +.IP +.I /etc/sane.d/magicolor.conf +.PP +For a proper setup, at least one of the following entries are needed: +.IP +.I net autodiscovery +.br +.I net [IP ADDRESS] [DEVICE-ID] +.br +.I usb +.br +.I usb [VENDOR-ID] [DEVICE-ID] + +.SH "FILES" +.TP +.I /etc/sane.d/magicolor.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-magicolor.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-magicolor.so +The shared library implementing this backend (present on systems that support dynamic loading). + +.SH "ENVIRONMENT" +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may contain the +configuration file. On *NIX systems, the directories are separated by a +colon (`:'), under OS/2, they are separated by a semi\-colon (`;'). +If this variable is not set, the configuration file is searched in two +default directories: first, the current working directory (".") and then in +.IR /etc/sane.d . +If the value of the environment variable ends with the directory separator character, +then the default directories are searched after the explicitly specified directories. +For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "/tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_MAGICOLOR +If the library was compiled with debug support enabled, this environment variable controls the debug level for this backend. Higher debug levels increase the verbosity of the output. + +Example: export SANE_DEBUG_MAGICOLOR=127 + +To obtain debug messages from the backend, set this environment variable before calling your favorite frontend (e.g. +.BR xscanimage (1)). + +Example: SANE_DEBUG_MAGICOLOR=65 xscanimage +.SH "KNOWN BUGS AND RESTRICTIONS" +.PP +Large color scans may sometimes timeout due to unknown reasons (the scanner simply stops returning data). +.PP +Cancelling large scans may lock up the scanner. + +.SH "SEE ALSO" +.BR sane (7), +.br +.I http://wiki.kainhofer.com/hardware/magicolor_scan + +.SH "AUTHOR" +.PP +Reinhold Kainhofer +.RI < reinhold@kainhofer.com > diff --git a/upstream/fedora-40/man5/sane-matsushita.5 b/upstream/fedora-40/man5/sane-matsushita.5 new file mode 100644 index 00000000..29855e9a --- /dev/null +++ b/upstream/fedora-40/man5/sane-matsushita.5 @@ -0,0 +1,176 @@ +.TH sane\-matsushita 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-matsushita +.SH NAME +sane\-matsushita \- SANE backend for Panasonic KV-SS high speed scanners +.SH DESCRIPTION +The +.B sane\-matsushita +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some Panasonic KV-SS high speed scanners. This +backend is stable. +.PP +At present, the following scanners are known to work with this +backend: +.PP +.RS +.ft CR +.nf + Product id +-------------- + KV-SS25 + KV-SS25D + KV-SS55EX (*) + KV-S2025C (*) + KV-S2045C (*) + KV-S2065L (*) +.fi +.ft R +.RE +.PP +(*) WARNING: None of the advanced options of these scanners are available (ie no color, no high resolution, no automatic cropping). Basically, the driver does no more than what it does for the KV-SS25. I don't have access to such scanners, and thus cannot add these options. + +Other Panasonic high speed scanners may or may not work with that backend. + +Valid command line options and their syntax can be listed by using +.RS +.PP +scanimage \-\-help \-d matsushita +.RE + +.TP +.B Scan Mode + +.TP +.B \-\-mode +selects the basic mode of operation of the scanner. +.TP +.B \-\-resolution +selects the resolution for a scan. Each model supports all or a subset of these resolutions: 100, 150, 200, 240, 300, 360, 400. +.TP +.B \-\-duplex +indicates whether to scan both side of the sheet. +.TP +.B \-\-feeder\-mode +selects the number of pages to scan (one or until the tray is empty). + +.TP +.B Geometry + +.TP +.B \-\-paper\-size A4|...|Legal|Letter [A4] +options selects the area to scan. It adjust the +.B \-l \-t \-x \-y +options accordingly. It does not need to be the real size of the paper. + +.TP +.B \-l \-t \-x \-y +control the scan area: \-l sets the top left x coordinate, \-t the top +left y coordinate, \-x selects the width and \-y the height of the scan +area. All parameters are specified in millimeters. It is possible to use +the option +.I \-\-paper\-size +instead. + +.TP +.B Enhancement + +.TP +.B \-\-brightness +controls the brightness of the acquired image. The value varies from 1 to 255, or less, depending on the scanner model. +.TP +.B \-\-contrast +controls the contrast of the acquired image. Some models do not support that option. +.TP +.B \-\-automatic\-threshold +automatically sets brightness, contrast, white level, gamma, noise reduction and image emphasis. These options are not available when automatic\-threshold is in use. +.TP +.B \-\-halftone\-pattern +option sets the tonal gradation for the halftone mode. Pattern downloading is not implemented by the backend. +.TP +.B \-\-autoseparation +provides automatic separation of text and images. +.TP +.B \-\-white\-level +option indicate the source of the white base. +.TP +.B \-\-noise\-reduction +reduces the isolated dot noise. This option is not supported by all scanners. +.TP +.B \-\-image\-emphasis +option sets the image emphasis. Some selection are not available on all scanners. +.TP +.B \-\-gamma +options set the gamma curve. It is only valid for Gray modes, and is not available on all scanners. Gamma downloading is not implemented by the backend. + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/matsushita.conf +supports the device name to use (eg +.IR /dev/scanner ) +and the SCSI option to auto-detect the scanners supported. + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-matsushita.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-matsushita.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_MATSUSHITA +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + + +.SH LIMITATIONS +.TP +.B Memory in the KV-SS 25 +The KV-SS 25 has not enough internal memory to scan a whole A4 page in duplex mode at high resolution. The frontend will return a memory error in that case. Apparently, the KV-SS 25D has not that problem. +.TP +.B Pattern and gamma downloading +The scanner, with the proper firmware, can download a halftone pattern +and a gamma table. This is not implemented. +.TP +.B Sub-areas +The scanner can support up to 3 sub-areas on each side to define some +more precise enhancement options. This is not implemented. +.TP +.B Duplex mode +The backend does not support the setting of different options for each side. The scan will occur with the same options (halftone pattern, brightness, image emphasis) for both sides. + + +.SH SCANNING EXAMPLE +To date, the only frontend capable of using this scanner at full speed is +.BR scanadf (1). + +A +.BR scanadf (1) +command line would be: + +scanadf \-d matsushita \-\-output\-file scan%04d.pbm \-\-start\-count 0 \-\-duplex \-\-resolution 300 \-\-feeder\-mode="All pages" \-\-paper\-size="A4" + + +.SH BUGS +None known. + + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + + +.SH AUTHOR + +.TP +The package is actively maintained by Frank Zago. +.I http://www.zago.net/sane/#matsushita diff --git a/upstream/fedora-40/man5/sane-microtek.5 b/upstream/fedora-40/man5/sane-microtek.5 new file mode 100644 index 00000000..4f56f018 --- /dev/null +++ b/upstream/fedora-40/man5/sane-microtek.5 @@ -0,0 +1,205 @@ +.TH sane\-microtek 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-microtek +.SH NAME +sane\-microtek \- SANE backend for Microtek scanners +.SH DESCRIPTION +The +.B sane\-microtek +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the "second generation" Microtek scanners. At present, +the following hardware is known to work with this backend: +.PP +.RS +Microtek ScanMaker E2, E3, E6 +.br +Microtek ScanMaker II, IIG, IIHR, IISP, III +.br +Microtek ScanMaker 35t, 35t+, 45t +.br +Microtek ScanMaker 600GS, 600ZS (see bug notes) +.br +Agfa StudioScan +.br +Agfa StudioScan II, StudioScan IIsi +.br +Agfa Arcus II (but not the "Arcus") +.br +Agfa DuoScan (preliminary) +.br +Vobis "Highscreen Realscan" +.br +Microtek Color PageWiz (preliminary) +.br +.PP +Transparent Media Adapter +.br +Document AutoFeeder +.br +.RE +.PP +The driver supports line art, halftone, 8bpp gray, and 24bpp color scans +at normal and "expanded" resolutions (i.e. 1200x1200 on an E6), fast scans +for color previews, and downloadable gamma tables. +.PP +The supported scanners are all SCSI scanners. However, some parallel +port models may work (under Linux), if they use a parport->scsi chip, +and if you can find a scsi->parport driver. This is known to be the +case for the Color PageWiz. +.PP +The driver does +.B not +support the newest Microtek scanners, such as the V330 and V660, which use +a new and very different SCSI-II command set. For those, try the alternate +.BR microtek2 (5) +backend. Most non-SCSI scanners would use the new command set. Most +scanners newer than the Scanmaker E6 would use the new command set. +.PP +If you own a Microtek scanner other than the ones listed above, tell us +what happens --- see the +.BR BUGS +section at the end of this document. +.PP +Although this manual page is generally updated with each release, +up-to-date information on new releases and extraneous helpful hints +are available from the backend homepage: +.br +.PP +.RS +.I http://www.mir.com/mtek/ +.RE + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the UNIX path-name for the special device that corresponds to the +scanner. The special device name must be a generic SCSI device or a +symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. +.PP + +.SH CONFIGURATION +The contents of the +.I microtek.conf +file is a list of device names that correspond to Microtek +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +/dev/scanner +.br +# this is a comment +.br +/dev/sge +.RE +.PP +The configuration file may also contain the special tokens +.I norealcal +or +.I noprecal. +.I norealcal +will disable the use of magic, undocumented scanner calibration commands +which are known to work on the E6, but may not work with other models. +.I noprecal +will disable logic which tries to avoid scanner precalibration. This logic +would only have been activated if the magic calibration code was turned off. + +.PP +.SH FILES +.TP +.I /etc/sane.d/microtek.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-microtek.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-microtek.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_MICROTEK +If the library was compiled with debugging support enabled, this +environment variable controls the debug level for this backend. +A value of 128 requests maximally copious debug output; smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-microtek2 (5) + +.SH AUTHOR +Matt Marjanovic + +.SH BUGS +Known bugs/limitations are: +.PP +.RS +Brightness and contrast broken. +.br +The 600GS is grayscale only, and will lock up if you select color. +(Unfortunately, the 600GS and 600ZS are indistinguishable by software.) +.br +.RE +.PP +i.e. don't complain about these --- but if brightness and/or contrast +.B do +work for you, please tell me. +.PP +If your scanner locks up, try setting the +.I norealcal +or +.I noprecal +option in the configuration file (first one, then both), and see if it helps. +(If it does, report it.) +.PP +Send lengthy bug reports and new scanner information to +.IR mtek\-bugs@mir.com . +All bug reports and new scanner inquiries should include an error log file. +You can generate copious +stderr output by setting the +.B SANE_DEBUG_MICROTEK +environment variable described above. For example: +.PP +.RS +setenv SANE_DEBUG_MICROTEK 128 +.RE +.PP +More general comments, suggestions, and inquiries about frontends +or SANE should go to +.IR sane\-devel@alioth-lists.debian.net , +the SANE Developers mailing list. Have a look at +.I http://www.sane\-project.org/mailing\-lists.html +concerning subscription to sane\-devel. diff --git a/upstream/fedora-40/man5/sane-microtek2.5 b/upstream/fedora-40/man5/sane-microtek2.5 new file mode 100644 index 00000000..d02bd615 --- /dev/null +++ b/upstream/fedora-40/man5/sane-microtek2.5 @@ -0,0 +1,321 @@ +.TH sane\-microtek2 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.SH NAME +sane\-microtek2 \- SANE backend for Microtek scanners with SCSI-2 command set +.SH DESCRIPTION +The +.B sane\-microtek2 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Microtek scanners with a SCSI-2 command set. +This backend can be considered alpha to beta. Some scanner models are reported +to work well, others not. New development versions of this backend can be +obtained from +.IR http://karstenfestag.gmxhome.de . +.PP +There exists a different backend for Microtek scanners with SCSI-1 command +set. +Refer to +.BR sane\-microtek (5) +for details. +.PP +And there is work in progress for the ScanMaker 3600. +See +.IR http://sourceforge.net/projects/sm3600 . +.PP +At present, the following scanners are known positively to work with this +backend: +.PP +.ft CR +.nf +Vendor Product id Remark +-------------------------------------------------------------------- +Microtek E3+ Parport and SCSI +Microtek X6 SCSI +Microtek X6EL SCSI +Microtek X6USB USB +Microtek ScanMaker V300 Parport and SCSI +Microtek ScanMaker V310 Parport and SCSI +Microtek ScanMaker V600 Parport and SCSI +Microtek ScanMaker 330 SCSI +Microtek ScanMaker 630 SCSI +Microtek ScanMaker 636 SCSI +Microtek ScanMaker 9600XL SCSI; only flatbed mode? +Microtek Phantom 330CX Parport +Microtek SlimScan C3 Parport +Microtek SlimScan C6 USB +Microtek Phantom 636 SCSI +Microtek Phantom 636CX Parport +Microtek V6USL SCSI and USB +Microtek V6UPL USB; not stable +Microtek X12USL SCSI; only 8bit color, work in progress +Vobis HighScan SCSI (E3+ based models) +Scanport SQ300 Parport? +Scanport SQ4836 SCSI +Scanpaq SQ2030 Parport +.fi +.ft R +.PP +Additional information can be found at +.IR http://www.sane\-project.org/ . +.PP +If you own a Microtek scanner other than the ones listed above, +it may or may not work with SANE! Because equal scanners are sold under +different names in different countries your model may be equivalent to one of +the above. +.PP +The parport scanners work with the ppscsi + onscsi kernel modules. See +.I http://cyberelk.net/tim/parport/ppscsi.html +and +.IR http://penguin-breeder.org/kernel/download/ . + +.PP +The USB scanners work with the microtek kernel module. You may have to add the +vendor and model codes to microtek.c if they aren't yet listed there. +.PP +Both parport and USB scanners need the generic SCSI support, so check if you +have loaded the scsi_mod and sg modules! +.PP +If you try your scanner for the first time keep an eye on it. If it gets +commands that it doesn't understand the scanhead may go beyond the scan area. +The scanner then makes strange noises. In this case immediately switch off +the scanner or disconnect its power cable to prevent damages! +.PP +If your scanner is a different one than the models mentioned above and it is +working please tell the author about it. It would be nice if you add a logfile +to this information (creation of the logfile: see below). +.PP +If your scanner is not working properly you also should create a logfile and +send it to the author. He will use the information to improve the backend and +possibly make your scanner work. +.PP +.br +How to create the logfile? +.TP +\- put the line +.br +"option dump 2" into your +.I microtek2.conf +file or change the existing "option dump" to "2" +.TP +\- in a terminal (bash) type +.br +"export SANE_DEBUG_MICROTEK2=30" and then +.br +"scanimage \-l0 \-t0 \-x100 \-y20 2>scan.log >sout.pnm" +.br +You get two files: scan.log contains the logfile and sout.pnm the scanned +image (if there was scanned something). Zip them before sending. + +.SH "FRONTEND OPTIONS" +This backend dynamically enables the options for the frontend, that are +supported by the scanner in dependence of the scanning-mode and other +options. +Not supported options are disabled. +.PP +The following options are supported by the +.B sane\-microtek2 +driver: +.PP +Color, grayscale, halftone and lineart scans. +.PP +Highlight, midtone, shadow, contrast, brightness, exposure time control, +gamma correction, threshold (dependent of the scan mode and the scanner +capabilities) +.PP +Transparency media adapter, automatic document feeder +.PP +Additional options can be enabled or disabled in the +.I microtek2.conf +file. See the configuration section of this manpage. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the UNIX path-name for the special device that corresponds to the +scanner. The special device name must be a generic SCSI device or a +symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.I /dev/sge +for example. +.SH "CONFIGURATION" +The configuration file for this backend resides in +.IR /etc/sane.d/microtek2.conf . + +Its contents is a list of device names that correspond to Microtek +scanners with SCSI-2 interface. Empty lines and lines starting with +a hash mark (#) are ignored. +.PP +The configuration file may also contain options. Global options that are valid +for all devices are placed above the device names. Device-specific options +are +placed under the device name. Note that, except for option dump and +option strip-height , the entry in the microtek2.conf file only enables +the corresponding option for being showed in the frontend. There, in the +frontend, you can switch the options on and off. +Currently the following options are supported: +.PP +.RS +option dump +.br +option strip\-height +.br +option no\-backtrack\-option +.br +option lightlid\-35 +.br +option toggle\-lamp +.br +option lineart\-autoadjust +.br +option backend\-calibration +.br +option colorbalance\-adjust +.RE +.PP +.I option dump +enables printing of additional information about the SCSI commands that are +sent to the scanner to stderr. This option is primarily useful for debugging +purpose. This option has to be a global option and is best placed at the top +of the +.I microtek2.conf +file. +.PP +If n=1 the contents of the command blocks +and the results for the INQUIRY and READ SCANNER ATTRIBUTES command are +printed to stderr. +.PP +If n=2 the contents of the command blocks for all other SCSI commands are +printed to stderr, too. If n=3 the contents of the gamma table is +printed, too. If n=4 all scan data is additionally printed to stderr. +.PP +The default is n=1. +.PP +.I option strip\-height +, where is a floating point number, limits the amount of data that is +read from the scanner with one read command. +The unit is inch and defaults to 1.0, if this option is not set in the +configuration file. If less than inch of data fit into the SCSI buffer, +then the smaller value is used and this option has no effect. +.PP +If your system has a big SCSI buffer and you want to make use of the whole +buffer, increase the value for . For example, if is set to 14.0, +no restrictions apply for scanners with a letter, legal or A4 sized scan area. +.PP +.PP +The following options enable or disable additional frontend options. If an +option is set to an appropriate option will appear in the frontend. +.PP +.I option no\-backtrack\-option +prevents the scanner head from moving backwards between the read commands. +This speeds up scanning. Try it. +.PP +.I option lightlid\-35 +If you use the LightLid-35 transparency adapter you get an advanced +option which switches off the flatbed lamp during the scan. +.PP +.I option toggle\-lamp +You get a button in the frontend where you can switch on and off the flatbed +lamp. +.PP +.I option lineart\-autoadjust +You can tell the backend to try to determine a good value for the lineart +threshold. +.PP +.I option backend\-calibration +Some scanners (e.g. Phantom 330CX and 636CX) need to have calibrated the data +by the backend. Try this option if you see vertical stripes in your pictures. +.PP +.I option colorbalance\-adjust +Some scanners (e.g. Phantom 330CX and 636CX) need to have corrected +the color balance. If this option is enabled you get advanced options +where you can balance the colors. And you will have a button +to use the values that the firmware of the scanner provides. +.PP +A sample configuration file is shown below: +.PP +.RS +option dump 1 +.br +option strip\-height 1.0 +.br +/dev/scanner +.br +option no\-backtrack\-option on +.br +# this is a comment +.br +/dev/sge +.br +option lightlid\-35 on +.RE + +This backend also supports the new configuration file format which makes +it easier to detect scanners under Linux. If you have only one scanner it +would be best to use the following configuration file for this backend: +.PP +.RS +option dump 1 +.br +option strip\-height 14.0 +.br +option no\-backtrack\-option on +.br +option backend\-calibration on +.br +option lightlid\-35 on +.br +option toggle\-lamp on +.br +option lineart\-autoadjust on +.br +option colorbalance\-adjust off +.br +scsi * * Scanner +.RE + +In this case all SCSI-Scanners should be detected automatically because of the +.PP +scsi * * Scanner +.PP +line. + +.SH "FILES" +.TP +.I /etc/sane.d/microtek2.conf +The backend configuration file. +.TP +.I /usr/lib64/sane/libsane\-microtek2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-microtek2.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH "ENVIRONMENT" +.TP +.B SANE_DEBUG_MICROTEK2 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller +levels reduce verbosity. To see error messages on stderr set +.B SANE_DEBUG_MICROTEK2 +to 1 (Remark: The whole debugging levels should be better revised). +.br +E.g. just say: +.br +export SANE_DEBUG_MICROTEK2=128 + +.SH "SEE ALSO" +.BR sane\-scsi(5) , +.BR sane (7) + +.SH "AUTHORS" +Bernd Schroeder (not active anymore) +.br +Karsten Festag +.RI < karsten.festag@gmx.de >. diff --git a/upstream/fedora-40/man5/sane-mustek.5 b/upstream/fedora-40/man5/sane-mustek.5 new file mode 100644 index 00000000..c934b6e3 --- /dev/null +++ b/upstream/fedora-40/man5/sane-mustek.5 @@ -0,0 +1,421 @@ +.TH sane\-mustek 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-mustek +.SH NAME +sane\-mustek \- SANE backend for Mustek SCSI flatbed scanners (and some other devices) +.SH DESCRIPTION +The +.B sane\-mustek +library implements a SANE (Scanner Access Now Easy) backend that provides access +to Mustek (and some relabeled Trust and Primax) SCSI and parport flatbed +scanners. At present, the following scanners are known to work more or less +with this backend: +.PP +.RS +Paragon MFS-6000CX +.br +Paragon MFS-12000CX +.br +Paragon MFC-600S, 600 II CD, ScanMagic 600 II SP +.br +Paragon MFC-800S, 800 II SP +.br +Paragon MFS-6000SP +.br +Paragon MFS-8000SP +.br +Paragon MFS-1200SP, MFS-12000SP +.br +ScanExpress 6000SP +.br +ScanExpress 12000SP, 12000SP Plus, Paragon 1200 III SP, ScanMagic 9636S, 9636S Plus +.br +Paragon 1200 LS +.br +ScanExpress A3 SP +.br +Paragon 1200 SP Pro +.br +Paragon 1200 A3 Pro +.br +Paragon 600 II EP +.br +Paragon 600 II N +.br +Trust Imagery 1200 +.br +Trust Imagery 1200 SP +.br +Trust Imagery 4800 SP +.br +Trust SCSI Connect 19200 +.br +Primax Compact 4800 SCSI +.br +.RE +.PP +More details can be found on the Mustek SCSI backend homepage +.IR http://www.meier\-geinitz.de/sane/mustek\-backend/ . +.PP +Don't mix up MFS (Paragon), Pro and ScanExpress models! They're +completely different. Check the exact model name! +.PP +Note that most of the above scanners come with a SCSI interface. The only +non-SCSI scanners that have some support at this point is the 600 II N and 600 +II EP scanners. The former one comes with its own parallel port adapter (i.e., +it does +.I not +attach to the printer port). Both scanners use the SCSI protocol internally, +too. More info on how to use these parallel port scanners can be found below in +section +.BR "PARALLEL PORT SCANNERS" . +Other parallel port scanners are not supported by this backend but you may be +successful using the Mustek parallel port backend mustek_pp, see +.BR sane\-mustek_pp (5). +USB scanners are also not supported by this backend but the ma1509, mustek_usb, +gt68xx, and plustek backends include support for some of them, see +.BR sane\-ma1509 (5), +.BR sane\-mustek_usb (5), +.BR sane\-gt68xx "(5), and" +.BR sane\-plustek (5). +.PP +Mustek scanners have no protection against exceeding the physical scan +area height. That is, if a scan is attempted with a height that +exceeds the height of the scan surface, the scanner begins making loud +noises and the scan mechanism may be damaged. Thus, if you hear such +a noise, IMMEDIATELY turn off the scanner. This shouldn't happen if +your scanner is in the list of known scanners. There is more +information in the +.I /usr/share/doc/sane-backends/PROBLEMS +file. +.PP +If you own a Mustek (or Trust) scanner other than the ones listed +above that works with this backend, please let us know by sending the +scanner's exact model name (look at the front and back of the scanner) +and a debug output to +.IR sane\-devel@alioth-lists.debian.net . +You can get the debug output by setting the environment variable +.B SANE_DEBUG_MUSTEK +to 5 and showing the list of available scanners with +.IR "scanimage \-L" . +Please send all of it to the mailing list. You must be subscribed to sane\-devel +before you can send mail to the list. See +.I http://www.sane\-project.org/mailing\-lists.html +for details. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is either the path-name for the special device that corresponds to a +SCSI scanner or the port number at which the parallel port scanners can +be found (see section +.B "PARALLEL PORT SCANNERS" +below). For SCSI scanners, the special device name must be a generic SCSI +device or a symlink to such a device. The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name +could be +.I /dev/sg0 +or +.IR /dev/sg3 , +for example. See +.BR sane\-scsi (5) +for details. +.SH CONFIGURATION +The contents of the +.I mustek.conf +file is a list of options and device names that correspond to Mustek +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid device name. +.PP +The supported options are +.BR linedistance\-fix , +.BR lineart\-fix , +.BR legal\-size , +.BR buffersize , +.BR blocksize , +.BR strip\-height , +.BR disable\-double\-buffering , +.BR disable\-backtracking , +and +.BR force\-wait . +.PP +Options come in two flavors: global and positional ones. Global +options apply to all devices managed by the backend whereas positional +options apply just to the most recently mentioned device. Note that +this means that the order in which the options appear matters! +.PP +Option +.B linedistance\-fix +is positional and works around a problem that occurs with some SCSI +controllers (notably the ncr810 controller under Linux). If color +scans have horizontal stripes and/or the colors are off, then it's +likely that your controller suffers from this problem. Turning on +this option usually fixes the problem. +.PP +Option +.B lineart\-fix +is positional and works around a timing problem that seems to exist +with certain MFS-12000SP scanners. The problem manifests itself in +dropped lines when scanning in lineart mode. Turning on this option +should fix the problem but may slow down scanning a bit. +.PP +Option +.B legal\-size +is positional and sets the size of the scan area to Legal format. Set this +option if you own a Paragon 12000 LS. It can't be distinguished by +software from a ScanExpress 12000 SP (ISO A4 format). +.PP +Option +.B buffersize +is a positional option that overrides the default value set for the size of +the SCSI buffer. The buffer size is specified in kilobytes. The default value +is 128. Because of double buffering the buffer actually sent to the scanner +is half the size of this value. Try to increase this value to achieve higher +scan speeds. Note that some ScanExpress scanners don't like buffer sizes above +64 kb (buffersize = 128). If your sg driver can't set SCSI buffer sizes at +runtime you may have to change that value, too. See sane\-scsi(5) for details. +.PP +Option +.B blocksize +is a positional option that overrides the default value set for the maximum +amount of data scanned in one block. The buffer size is specified in +kilobytes. Some scanners freeze if this value is bigger than 2048. The default +value is 1 GB (so effectively no limit) for most scanners. Don't change this +value if you don't know exactly what you do. +.PP +Option +.B strip\-height +is a global option that limits the maximum height of the strip scanned with a +single SCSI read command. The height is specified in inches and may contain a +fractional part (e.g., 1.5). Setting the strip\-height to a small value (one +inch, for example) reduces the likelihood of encountering problems with SCSI +driver timeouts and/or timeouts with other devices on the same SCSI bus. +Unfortunately, it also increases scan times. With current SCSI adapters and +drivers this option shouldn't be needed any more. +.PP +Option +.B disable\-double\-buffering +is a global option. If set, the backend will only send one buffer at a time to +the scanner. Try this option if you have trouble while scanning, e.g. SCSI +errors, freezes, or the first few cm are repeated over and over again in your +image. +.PP +Option +.B disable\-backtracking +is a positional option. If set, the scanner will not move back its slider +after each SCSI buffer is filled (`backtracking'). Setting this option will +lead to faster scans but may also produce horizontal stripes. This option +doesn't work with every scanner (only some of the paragon models can modify +backtracking). +.PP +Finally, +.B force\-wait +is a global option. If set, the backend will wait until the device is ready +before sending the inquiry command. Further more the backend will force the +scan slider to return to its starting position (not implemented for all +scanners). This option may be necessary with the 600 II N or when +.BR scanimage (1) +is used multiple times (e.g. in scripts). The default is off (not set). +.PP +A sample configuration file is shown below: +.PP +.RS +# limit strip height of all scanners to 1.5 inches: +.br +option strip\-height 1.5 +.br +.br +/dev/scanner # first Mustek scanner +.br +# 1 MB buffer for /dev/scanner: +.br +option buffersize 1024 +.br +/dev/sge # second Mustek scanner +.br +# turn on fixes for /dev/sge: +.br +option lineart\-fix +.br +option linedistance\-fix +.RE + +.SH "SCSI ADAPTER TIPS" +.PP +You need a SCSI adapter for the SCSI scanners. Even if the connector is the +same as that of parallel port scanners, connecting it to the computers +parallel port will NOT work. +.PP +Mustek SCSI scanners are typically delivered with an ISA SCSI adapter. +Unfortunately, that adapter is not worth much since it is not +interrupt driven. It is (sometimes) possible to get the supplied card +to work, but without interrupt line, scanning will be very slow and put +so much load on the system, that it becomes almost unusable for other tasks. +.PP +If you already have a working SCSI controller in your system, you +should consider that Mustek scanners do not support the SCSI-2 +disconnect/reconnect protocol and hence tie up the SCSI bus while a +scan is in progress. This means that no other SCSI device on the same +bus can be accessed while a scan is in progress. +.PP +Because the Mustek-supplied adapter is not worth much and because +Mustek scanners do not support the SCSI-2 disconnect/reconnect +protocol, it is recommended to install a separate (cheap) SCSI +controller for Mustek scanners. For example, ncr810 based cards are +known to work fine and cost as little as fifty US dollars. +.PP +For Mustek scanners, it is typically necessary to configure the low-level SCSI +driver to disable synchronous transfers (sync negotiation), tagged command +queuing, and target disconnects. See +.BR sane\-scsi (5) +for driver- and platform-specific information. +.PP +The ScanExpress models have sometimes trouble with high resolution +color mode. If you encounter sporadic corrupted images (parts duplicated +or shifted horizontally) kill all other applications before scanning +and (if sufficient memory is available) disable swapping. +.PP +Details on how to get the Mustek SCSI adapters and other cards running can be +found at +.IR http://www.meier\-geinitz.de/sane/mustek\-backend/#SCSI . + +.SH "PARALLEL PORT SCANNERS" +This backend has support for the Paragon 600 II EP and Paragon 600 II N parallel +port scanners. Note that the latter scanner comes with its own ISA card that +implements a funky parallel port (in other words, the scanner does not connected +to the printer parallel port). +.PP +These scanners can be configured by listing the port number +of the adapter or the parallel port in the mustek.conf file. Valid port numbers +for the 600 II N are +.IR 0x26b ", " 0x2ab ", " 0x2eb ", " 0x22b ", " 0x32b ", " 0x36b ", " +.IR 0x3ab ", " 0x3eb . +For the 600 II EP use one of these: +.IR parport0 ", " parport1 ", " parport2 ", " 0x378 ", " 0x278 ", " 0x3bc . +Pick one that doesn't conflict with the other hardware in your computer. Put +only one number on a single line. Example: +.PP +.RS +.I 0x3eb +.RE +.PP +Note that for these scanners usually root privileges are required to access the +I/O ports. Thus, either make frontends such as +.BR scanimage (1) +and +.BR xscanimage (1) +setuid root (generally not recommended for safety reasons) or, alternatively, +access this backend through the network daemon +.BR saned (8). +.PP +If the Mustek backend blocks while sending the inquiry command to the scanner, +add the option +.B force\-wait +to +.IR mustek.conf . +.PP +Also note that after a while of no activity, some scanners themselves (not +the SANE backend) turns off their CCFL lamps. This shutdown is not always +perfect with the result that the lamp sometimes continues to glow +dimly at one end. This doesn't appear to be dangerous since as soon as +you use the scanner again, the lamp turns back on to the normal high +brightness. However, the first image scanned after such a shutdown may +have stripes and appear to be over-exposed. When this happens, just +take another scan, and the image will be fine. + +.SH FILES +.TP +.I /etc/sane.d/mustek.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-mustek.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-mustek.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_MUSTEK +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +.ft CR +.nf +Value Description +0 no output +1 print fatal errors +2 print important messages +3 print non-fatal errors and less important messages +4 print all but debugging messages +5 print everything +.fi +.ft R + +Example: +export SANE_DEBUG_MUSTEK=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-find\-scanner (1), +.BR sane\-scsi (5), +.BR sane\-mustek_usb (5), +.BR sane\-gt68xx (5), +.BR sane\-plustek (5), +.BR sane\-mustek_pp (5), +.BR sane\-ma1509 (5), +.BR scanimage (1), +.BR xscanimage (1) + +.br +.I /usr/share/doc/sane-backends/mustek/mustek.CHANGES +.br +.I http://www.meier\-geinitz.de/sane/mustek\-backend/ + +.SH AUTHOR +David Mosberger, Andreas Czechanowski, Andreas Bolsch (SE extensions), +Henning Meier-Geinitz, James Perry (600 II EP). + +.SH BUGS +Scanning with the SCSI adapters supplied by Mustek is very slow at +high resolutions and wide scan areas. +.PP +Some scanners (e.g. Paragon 1200 A3 + Pro, SE A3) need more testing. +.PP +The gamma table supports only 256 colors, even if some scanners can do more. +.PP +More detailed bug information is available at the Mustek backend +homepage: +.IR http://www.meier\-geinitz.de/sane/mustek\-backend/ . diff --git a/upstream/fedora-40/man5/sane-mustek_pp.5 b/upstream/fedora-40/man5/sane-mustek_pp.5 new file mode 100644 index 00000000..99b78fa9 --- /dev/null +++ b/upstream/fedora-40/man5/sane-mustek_pp.5 @@ -0,0 +1,524 @@ +.TH sane\-mustek_pp 5 "13 Jul 2008" +.de EX +.sp +.nf +.ft CW +.. +.de EE +.ft R +.fi +.sp +.. +.IX sane\-mustek_pp +.SH NAME +sane\-mustek_pp \- SANE backend for Mustek parallel port flatbed scanners +.SH DESCRIPTION +The +.B sane\-mustek_pp +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Mustek parallel port flatbed scanners and OEM versions. + +There are 2 classes of Mustek parallel port scanners: regular +.B CCD +(cold cathode device) scanners and +.B CIS +(contact image sensor) scanners. +.P +The current version of this backend supports both CCD type scanners and +CIS type scanners. +.P +The following scanners might work with this backend: + +.SS "CCD scanners" + +.EX +Model: ASIC ID: CCD Type: works: +-------------------------------------------------------------- +SE 6000 P 1013 00 yes +SM 4800 P 1013/1015 04/01 yes +SE 1200 ED Plus 1015 01 no +SM 1200 ED Plus 1015 01 no +SE 12000 P 1505 05 no +600 III EP Plus 1013/1015 00/01 yes +SE 600 SEP 1013 ?? yes +600 II EP ???? ?? no +MD9848 1015 00 yes +Gallery 4800 ???? ?? yes +Viviscan Compact II 1013 00 yes +.EE +.SS CIS scanners +.EX +Model: ASIC ID: works: +----------------------------------------------- +Mustek 600 CP & 96 CP 1015 yes (*) +Mustek 1200 CP 1015 yes +Mustek 1200 CP+ 1015 yes +.EE + +.EX +OEM versions Original works +-------------------------------------------------- +Medion/LifeTec/Tevion + MD/LT 9350/9351 1200 CP yes + MD/LT 9850/9851 1200 CP maybe (**) + MD/LT 9858 1200 CP probably + MD/LT 9890/9891 1200 CP yes +Targa + Funline TS12EP 1200 CP yes + Funline TS6EP 600 CP yes +Trust + Easy Connect 9600+ 600 CP yes +Cybercom + 9352 1200 CP yes (***) +.EE +.HP +(*) Calibration problems existed with earlier version of +this driver. They seem to be solved now. +.HP +(**) Problems have been reported in the past for the +MD/LT9850 type (striped scans, head moving in wrong +direction at some resolutions). It is not known whether +the current version of the driver still has these problems. +.PP +.B IF YOU HEAR LOUD CLICKING NOISES, IMMEDIATELY UNPLUG THE SCANNER ! +(This holds for any type of scanner). +.HP +(***) Possibly, the engine_delay parameter has to be set to 1 ms +for accurate engine movements. +.PP +Please note that this backend is still under construction. Certain models +are currently not supported and some may never be because the communication +protocol is still unknown (eg., SE 12000 P). +.PP +Some scanners work faster when +.B EPP/ECP +is enabled in the BIOS. EPP mode however may lead to hard-locks on some Linux +systems. If that is the case for you, you can either disable ECP/EPP in your +BIOS or disable it in the backend itself (see GLOBAL OPTIONS). +.PP +Note that the backend needs to run as root or has to have appropriate access +rights to +.I /dev/parport* +if libieee1284 support is compiled in. To allow user +access to the scanner run the backend through the network interface (See +.BR saned (8) +and +.BR sane\-net (5)). +Note also that the backend +.I does not +support +.IR "parport sharing" , +i.e. if you try printing while scanning, your computer may crash. To enable +parport sharing, you have to enable libieee1284 at compile time. This backend +also conflicts with the +.BR sane\-musteka4s2 (5) +backend. You can only enable one of them in your +.IR dll.conf . +However, you have +to enable the backend explicitly in your +.IR dll.conf , +just remove the hash mark in the line "mustek_pp". + +.SH "DEVICE DEFINITION" +This backend allows multiple devices being defined and configured via the +.I mustek_pp.conf +file (even simultaneously, provided that they are connected to different +parallel ports). Please make sure to edit this file +.B before +you use the backend. +.PP +A device can be defined as follows: +.PP +.RS +.I scanner +.RE +.PP +where +.HP +.B +is an arbitrary name for the device, optionally enclosed by double quotes, +for instance "LifeTec 9350". +.HP +.B +is the name of the parallel port to which the device is connected. In case +libieee1284 is used for communication with the port +.I (default +.IR setup) , +valid port names are +.BR parport0 , +.BR parport1 , +and +.BR parport2 . +.PP +In case the backend is configured for raw IO +.I (old +.IR setup) , +port addresses have to be used instead of port names: +.BR 0x378 , +.BR 0x278 , +or +.BR 0x3BC . +The mapping of parallel ports (lp0, lp1, and lp2) to these addresses +can be different for different Linux kernel versions. For instance, +if you are using a Kernel 2.2.x or better and you have only one +parallel port, this port is named lp0 regardless of the base address. However, +this backend requires the base address of your port. If you are not sure which +port your scanner is connected to, have a look at your +.IR /etc/conf.modules , +.I /etc/modules.conf +and/or +.IR /proc/ioports . +.PP +If you are unsure which port to use, you can use the magic value +.BR * +to probe for your scanner. +.PP +.HP +.B +is the driver to use for this device. Currently available drivers are: +.IP +.BR cis600 " : for 600 CP, 96 CP & OEM versions" +.br +.BR cis1200 " : for 1200 CP & OEM versions" +.br +.BR cis1200+ " : for 1200 CP+ & OEM versions" +.br +.BR ccd300 " : for 600 IIIE P & OEM version" +.IP +.B Choosing the wrong driver can damage your scanner! +.br +Especially, using the 1200CP settings on a 600CP can be +harmful. If the scanner starts making a loud noise, turn +it off immediately !!! +.PP +Using the cis600 driver on a 1200CP or a 1200CP+ is probably not +dangerous. The cis1200+ driver also works for the 1200CP, and using +the cis1200 driver on a 1200CP+ will typically result in scans that +cover only half of the width of the scan area (also not dangerous). +.PP +If unsure about the exact model of your OEM version, check the optical +resolution in the manual or on the box: the 600CP has a maximum optical +resolution of 300x600 DPI, whereas the 1200CP and 1200CP+ have a maximum +optical resolution of 600x1200 DPI. +.PP +Examples: +.PP +.RS +scanner "LifeTec 9350" 0x378 cis1200 +.PP +scanner Mustek_600CP 0x378 cis600 +.PP +scanner Mustek_600IIIEP * ccd300 +.RE + +If in doubt which port you have to use, or whether your scanner is +detected at all, you can use +.I sane\-find\-scanner \-p +to probe all configured ports. + +.SH CONFIGURATION +.PP +The contents of the +.I mustek_pp.conf +file is a list of device definitions and device options that correspond to +Mustek scanners. Empty lines and lines starting with a hash mark (#) are +ignored. Options have the following format: +.PP +.RS +.I option [] +.RE +.PP +Depending on the nature of the option, a value may or may not be present. +Options always apply to the scanner definition that precedes them. There +are no global options. Options are also driver-specific: not all drivers +support all possible options. + +.SS Common options +.TP +.B bw +Black/white discrimination value to be used during lineart scanning. Pixel +values below this value are assumed to be black, values above are +assumed to be white. +.br +Default value: 127 +.br +Minimum: 0 +.br +Maximum: 255 +.sp +Example: option bw 150 + +.SS CIS driver options +.TP +.B top_adjust +Vertical adjustment of the origin, expressed in millimeter (floating point). +This option can be used to calibrate the position of the origin, within +certain limits. Note that CIS scanners are probably temperature sensitive, and +that a certain inaccuracy may be hard to avoid. Differences in offset between +runs in the order of 1 to 2 mm are not unusual. +.br +Default value: 0.0 +.br +Minimum: \-5.0 +.br +Maximum: 5.0 +.br +.sp +Example: option top_adjust \-2.5 +.TP +.B slow_skip +Turns fast skipping to the start of the scan region off. When the region to +scan does not start at the origin, the driver will try to move the scanhead +to the start of the scan area at the fastest possible speed. On some models, +this may not work, resulting in large inaccuracies (up to centimeters). +By setting this option, the driver is forced to use normal speed during +skipping, which can circumvent the accuracy problems. Currently, there are +no models for which these inaccuracy problems are known to occur. +.sp +By default, fast skipping is used. +.sp +Example: option slow_skip +.TP +.B engine_delay +Under normal circumstances, it is sufficient for the driver to wait for the +scanner signaling that the engine is stable, before a new engine command can +be transmitted. In rare cases, certain scanners and/or parallel port chipsets +appear to prevent reliable detection of the engine state. As a result, engine +commands are transmitted too soon and the movement of the scanner head becomes +unreliable. Inaccuracies ranging up to 10 cm over the whole vertical scan +range have been reported. To work around this problem, the engine_delay option +can be set. If it is set, the driver waits an additional amount of time after +every engine command, equal to the engine_delay parameter, expressed in +milliseconds. It practice an engine_delay of 1 ms is usually sufficient. The +maximum delay is 100 ms. +.sp +Note that every additional ms of delay can add up to 14 seconds to the total +scanning time (highest resolution), so an as small as possible value is +preferred. +.sp +Default value: 0 +.br +Minimum: 0 +.br +Maximum: 100 +.sp +Example: option engine_delay 1 + +.SS CCD driver options +.TP +.B top +Number of scanlines to skip to the start of the scan area. The number can +be any positive integer. Values known to me are 47 and 56. +.sp +Default value: 47 +.br +Minimum: 0 +.br +Maximum: none +.br +.sp +Example: option top 56 +.TP +.B waitbank +The number of usecs to wait for a bank change. You should not touch this +value actually. May be any positive integer +.sp +Default value: 700 +.br +Minimum: 0 +.br +Maximum: none +.sp +Example: option waitbank 700 +.PP +A sample configuration file is shown below: +.PP +.EX +# +# LifeTec/Medion 9350 on port 0x378 +# +scanner "LifeTec 9350" 0x378 cis1200 + +# Some calibration options (examples!). +option bw 127 +option top_skip \-0.8 + +# +# A Mustek 600CP on port 0x3BC +# +scanner "Mustek 600CP" 0x3BC cis600 + +# Some calibration options (examples!). +option bw 120 +option top_skip 1.2 + +# +# A Mustek 1200CP+ on port 0x278 +# +scanner "Mustek 1200CP plus" 0x278 cis1200+ + +# Some calibration options (examples!). +option bw 130 +option top_skip 0.2 + +# +# A Mustek 600 III EPP on port parport0 +# +scanner "Mustek 600 III EPP" parport0 ccd300 + +# Some calibration options (examples!). +option bw 130 +option top 56 +.EE + +.SH GLOBAL OPTIONS +.PP +You can control the overall behaviour of the +.B sane-\mustek_pp +backend by global +options which precede any scanner definition in the +.I mustek_pp.conf +file. +.sp +Currently, there is only one global option: + +.SS Global options +.TP +.B no_epp +Disable parallel port mode EPP: works around a known bug in the Linux parport +code. Enable this option, if the backend hangs when trying to access the +parallel port in EPP mode. +.sp +Default value: use EPP +.sp +Example: option no_epp + +.SH FILES +.TP +.I /etc/sane.d/mustek_pp.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-mustek_pp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-mustek_pp.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_MUSTEK_PP +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.EX +level debug output +-------------------------------------- + 0 nothing + 1 errors + 2 warnings & minor errors + 3 additional information + 4 debug information + 5 code flow (not supported yet) + 6 special debug information +.EE +.TP +.B SANE_DEBUG_SANEI_PA4S2 +This variable sets the debug level for the SANE interface for the Mustek +chipset A4S2. Note that enabling this will spam your terminal with some +million lines of debug output. +.EX +level debug output +---------------------------- + 0 nothing + 1 errors + 2 warnings + 3 things nice to know + 4 code flow + 5 detailed code flow + 6 everything +.EE + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-mustek (5), +.BR sane\-net (5), +.BR saned (8), +.BR sane\-find\-scanner (1), +.BR scanimage (1) + +.TP +For latest bug fixes and information see +.I http://www.penguin\-breeder.org/sane/mustek_pp/ + +.TP +For additional information on the CIS driver, see +.I http://home.scarlet.be/eddy_de_greef/ + +.SH AUTHORS +.nf +Jochen Eisinger +.RI < "jochen at penguin\-breeder dot org" > +Eddy De Greef +.RI < "eddy_de_greef at scarlet dot be" > +.fi + +.SH BUGS +Too many... please send bug reports to +.I sane\-devel@alioth-lists.debian.net +(note that you have to subscribe first to the list before you can send +emails... see +.IR http://www.sane\-project.org/mailing\-lists.html ). + +.SH BUG REPORTS +If something doesn't work, please contact us (Jochen for the CCD scanners, +Eddy for the CIS scanners). But we need some information about +your scanner to be able to help you... + +.TP +.I SANE version +Run +.I scanimage \-V +to determine this. +.TP +.I the backend version and your scanner hardware +Run +.I SANE_DEBUG_MUSTEK_PP=128 scanimage \-L +as root. If you don't get any output from the +.BR sane\-mustek_pp +backend, make sure a line "mustek_pp" is included into your +.IR /etc/sane.d/dll.conf . +If your scanner isn't detected, make sure you've defined the right port address +in your +.IR mustek_pp.conf . +.TP +.I the name of your scanner/vendor also a worthy information. Please also include the +optical resolution and lamp type of your scanner, both can be found in the manual of +your scanner. +.TP +.I any further comments +if you have comments about the documentation (what could be done better), or you +think I should know something, please include it. diff --git a/upstream/fedora-40/man5/sane-mustek_usb.5 b/upstream/fedora-40/man5/sane-mustek_usb.5 new file mode 100644 index 00000000..a2018b7e --- /dev/null +++ b/upstream/fedora-40/man5/sane-mustek_usb.5 @@ -0,0 +1,213 @@ +.TH sane\-mustek_usb 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-mustek_usb +.SH NAME +sane\-mustek_usb \- SANE backend for Mustek USB flatbed scanners +.SH DESCRIPTION +The +.B sane\-mustek_usb +library implements a SANE (Scanner Access Now Easy) backend that provides +access to Mustek USB flatbed scanners (including a clone from Trust). At +present, the following scanners are known to work more or less with this +backend: +.PP +.RS +Mustek 600 CU +.br +Mustek 1200 UB +.br +Mustek 1200 CU +.br +Mustek 1200 CU Plus +.br +Trust Compact Scan USB 19200 +.br +.RE +.PP +More details can be found on the Mustek USB backend homepage +.IR http://www.meier\-geinitz.de/sane/mustek_usb\-backend/ . +.PP +The Mustek BearPaw 1200 and 2400 scanners are supported by the plustek +backend. See +.BR sane\-plustek (5) +for details. The Mustek BearPaw 1200F is supported by the MA-1509 backend. See +.BR sane\-ma1509 (5) +for details. Other Mustek USB scanners are supported by the gt68xx backend, +see +.BR sane\-gt68xx (5). +.PP +This backend can only work with scanners that are already detected by the +operating system. See +.BR sane\-usb (5) +for details. +.PP +If you own a Mustek (or Trust) scanner other than the ones listed above that +works with this backend, please let me know this by sending the scanner's +exact model name and the USB vendor and device ids (e.g. from +.I /proc/bus/usb/devices +or syslog) to me. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is a path-name for the special device that corresponds to a USB scanner. +With Linux, such a device name could be +.I /dev/usb/scanner0 +or +.IR /dev/usbscanner1 , +for example. +.PP +For FreeBSD use +.IR /dev/uscanner0 . + +.SH CONFIGURATION +The contents of the +.I mustek_usb.conf +file is a list of options and device names that correspond to Mustek +USB scanners. Empty lines and lines starting with a hash mark (#) are +ignored. If a device name is placed in +.IR mustek_usb.conf , +it must be followed by a line containing the keyword +.B option +and an option specifying the scanner type. The following options can be used: +.BR 600cu , +.BR 1200cu , +.BR 1200cu_plus , +.BR 1200ub . +For the Trust Compact Scan USB 19200 use `option 1200ub'. +.PP +Instead of using the device name, the scanner can be autodetected by +.B "usb vendor_id product_id" +statements which are already included into +.IR mustek_usb.conf . +This is only supported with Linux 2.4.8 and higher and all systems that +support libsub. "vendor_id" and "product_id" are hexadecimal numbers that +identify the scanner. If this doesn't work, a device name and the option +specifying the scanner type must be placed in +.I mustek_usb.conf +as described above. +.PP +The global +.B option max_block_size +can be used to limit the amount of data acquired in one turn from the USB +system. It may be worth trying, if USB errors occur. +.PP +A sample configuration file is shown below: +.PP +.RS +# Comment +.br +option max_block_size 1024 +.br +usb 0x055f 0x0001 +.br +/dev/usb/scanner0 +.br +option 600cu +.RE +.PP +The first line is ignored. The second line sets the buffer size to a maximum of +1024 bytes. The third line tries to autodetect a scanner with vendor id 0x055f +and product id 0x0001 (Mustek 1200 CU). The fourth line tells the backend to +attach to +.I /dev/usb/scanner0 +and the fifth line specifies that +.I /dev/usb/scanner0 +is a Mustek 600 CU. +.SH FILES +.TP +.I /etc/sane.d/mustek_usb.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-mustek_usb.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-mustek_usb.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_MUSTEK_USB +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +.ft CR +.nf +Value Description +0 no output +1 print fatal errors +2 print important messages +3 print non-fatal errors and less important messages +4 print all but debugging messages +5 print high level debugging messages +6 print medium level debugging messages +7 print low level debugging messages +.fi +.ft R + +Example: +export SANE_DEBUG_MUSTEK_USB=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-mustek (5), +.BR sane\-mustek_pp (5), +.BR sane\-plustek (5), +.BR sane\-gt68xx (5), +.BR sane\-ma1509 (5) +.br +.IR /usr/share/doc/sane-backends/mustek_usb/mustek_usb.CHANGES , +.br +.I /usr/share/doc/sane-backends/mustek_usb/mustek_usb.TODO +.br +.I http://www.meier\-geinitz.de/sane/mustek_usb\-backend/ + +.SH AUTHOR +Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > +.br +This backend is based on the Mustek 1200ub backend from Mustek, maintained by +Tom Wang. + +.SH BUGS +These devices have a hardware bug: Once data is written to them, they can't be +reset (toggle = DATA0). That means, any operation that tries to reset the +device will result in running into timeouts. + +In earlier versions this backend failed when it was loaded the second time in +some configurations. The only choice was to replug the scanner in this case. The +backend uses a workaround for that bug now but it's only tested on +Linux. Reports for other operating systems are appreciated. + +.PP +More detailed bug information is available at the Mustek backend homepage +.IR http://www.meier\-geinitz.de/sane/mustek_usb\-backend/ . diff --git a/upstream/fedora-40/man5/sane-mustek_usb2.5 b/upstream/fedora-40/man5/sane-mustek_usb2.5 new file mode 100644 index 00000000..9f95a06e --- /dev/null +++ b/upstream/fedora-40/man5/sane-mustek_usb2.5 @@ -0,0 +1,82 @@ +.TH sane\-mustek_usb2 5 "13 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-mustek_usb2 +.SH NAME +sane\-mustek_usb2 \- SANE backend for SQ113 based USB flatbed scanners +.SH DESCRIPTION +The +.B sane\-mustek_usb2 +library implements a SANE (Scanner Access Now Easy) backend that provides +access to USB flatbed scanners based on the Service & Quality SQ113 chipset. At +the moment, only the Mustek BearPaw 2448 TA Pro is supported. It's planned to add +support for other scanners that are based on the SQ113 and maybe SQ11 chip. For +more details, see the +.B sane\-mustek_usb2 +backend homepage: +.IR http://www.meier\-geinitz.de/sane/mustek_usb2\-backend/ . +.PP +This is BETA software. Especially if you test new or untested scanners, keep +your hand at the scanner's plug and unplug it, if the head bumps at the end of +the scan area. +.PP +If you own a scanner other than the ones listed on the mustek_usb2 homepage that works with this +backend, please let me know this by sending the scanner's exact model name and +the USB vendor and device ids (e.g. from +.BR sane\-find\-scanner (1) +or syslog) to me. Even if the scanner's name is only slightly different from +the models already listed as supported, please let me know. +.PP +.SH LIBUSB ISSUES +Please use libusb-0.1.8 or later. Without libusb or with older libusb versions +all kinds of trouble can be expected. The scanner should be found by +.BR sane\-find\-scanner (1) +without further actions. For setting permissions and general +USB information, look at +.BR sane\-usb (5). +.PP + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-mustek_usb2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-mustek_usb2.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_MUSTEK_USB2 +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. Higher debug levels +increase the verbosity of the output. + +Example: +export SANE_DEBUG_MUSTEK_USB2=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-plustek (5), +.BR sane\-ma1509 (5), +.BR sane\-mustek_usb (5), +.BR sane\-mustek (5), +.BR sane\-mustek_pp (5), +.BR sane\-find\-scanner (1) + +.br +.I /usr/share/doc/sane-backends/mustek_usb2/mustek_usb2.CHANGES +.br +.I http://www.meier\-geinitz.de/sane/mustek_usb2\-backend/ + +.SH AUTHOR +The driver has been written Roy Zhou, Jack Xu, and Vinci Cen from +Mustek. +.br +Adjustments to SANE by Henning Meier-Geinitz. + +.SH BUGS +Please contact me if you find a bug or missing feature: +.RI < henning@meier\-geinitz.de >. +.br +Please send a debug log if your scanner isn't detected correctly (see +.B SANE_DEBUG_MUSTEK_USB2 +above). diff --git a/upstream/fedora-40/man5/sane-nec.5 b/upstream/fedora-40/man5/sane-nec.5 new file mode 100644 index 00000000..d086c567 --- /dev/null +++ b/upstream/fedora-40/man5/sane-nec.5 @@ -0,0 +1,65 @@ +.TH sane\-nec 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-nec +.SH NAME +sane\-nec \- SANE backend for NEC scanners +.SH DESCRIPTION +The +.B sane\-nec +library implements a SANE (Scanner Access Now Easy) backend that +provides access to NEC SCSI scanners. This backend should be +considered +.B alpha-quality +software! In the current state it is known to work with PC-IN500/4C +scanners. Other MultiReader scanner series are not supported. PC-IN +500/4C and MultiReader scanner are only sold in Japan (except Multi +Reader PetiScan). + +For other scanners, it may or may not work. +.PP +The backend has the following known problems: +.RS +.TP +\- ColorLineart mode is not supported. +.TP +\- Device name is fixed to \fI/dev/scanner\fR +.RE +.PP +At present, +the following scanners are known to work with this backend. +.PP +.RS +.ft CR +.nf +Vendor Product id +------ ----------- +NEC PC-IN500/4C +.fi +.ft R +.RE + +.SH FILES +.TP +.I /etc/sane.d/nec.conf +The backend configuration file. +.TP +.I /usr/lib64/sane/libsane\-nec.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-nec.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_NEC +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHORS +Kazuya Fukuda diff --git a/upstream/fedora-40/man5/sane-net.5 b/upstream/fedora-40/man5/sane-net.5 new file mode 100644 index 00000000..f3782449 --- /dev/null +++ b/upstream/fedora-40/man5/sane-net.5 @@ -0,0 +1,167 @@ +.TH sane\-net 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-net +.SH NAME +sane\-net \- SANE network backend +.SH DESCRIPTION +The +.B sane\-net +library implements a SANE (Scanner Access Now Easy) backend that +provides access to image acquisition devices through a network +connection. This makes it possible to control devices attached to a +remote host and also provides a means to grant users access to +protected resources. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.IR host : device +.RE +.PP +Where +.I host +is the name (or IP address) of the (remote) host and +.I device +is the name of the device on this host that should be addressed. +If the device name does not contain a colon (:), then the entire string +is treated as the +.I device +string for the default host. The default host is the host listed last +in the configuration file (see below). +.PP +An IPv6 address can be specified enclosed in square brackets: +.PP +.RS +.IR [::1] : device +.RE +.SH CONFIGURATION +The +.IR net.conf +file contains both backend options and a list of host names (or IP +addresses) that should be contacted for scan requests. Anything that +isn't one of the options listed below will be treated as an host name. +.PP +.TP +.B connect_timeout = nsecs +Timeout (in seconds) for the initial connection to the +.BR saned (8) +server. This will prevent the backend from blocking for several +minutes trying to connect to an unresponsive +.BR saned (8) +host (network outage, host down, ...). The environment variable +.B SANE_NET_TIMEOUT +can also be used to specify the timeout at runtime. +.PP +Empty lines and lines starting with a hash mark (#) are +ignored. Note that IPv6 addresses in this file do not need to be enclosed +in square brackets. A sample configuration file is shown below: +.PP +.RS +scan\-server.somedomain.firm +.br +192.168.0.1 +.br +# this is a comment +.br +localhost +.br +::1 +.RE +.PP +The above list of hosts can be extended at run-time using environment +variable +.BR SANE_NET_HOSTS . +This environment variable is a colon-separated list of hostnames or IP +addresses that should be contacted in addition to the hosts mentioned in +the configuration file. For example, a user could set the environment +variable to the string: +.PP +.RS +new.scanner.com:[::1]:192.168.0.2:scanner.univ.edu +.RE +.PP +To request that hosts +.I new.scanner.com +, +.I [::1] +, +.I 192.168.0.2 +and +.I scanner.univ.edu +are contacted in addition to the hosts listed above. +.PP +For this backend to function properly, it is also necessary to define the +.B sane\-port +service in +.IR /etc/services . +The +.B sane +service should be defined using a line of the following form: +.PP +.RS +sane\-port 6566/tcp # SANE network scanner daemon +.RE +.PP +.SH FILES +.TP +.I /etc/sane.d/net.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-net.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-net.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_NET_HOSTS +A colon-separated list of host names or IP addresses to be contacted by this +backend. +.TP +.B SANE_NET_TIMEOUT +Number of seconds to wait for a response from the +.BR saned (8) +server for the initial connection request. +.TP +.B SANE_DEBUG_NET +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.SH BUGS +If +.BR saned (8) +has timed out, the net backend may loop with authorization requests. + +.SH "SEE ALSO" +.BR sane (7), +.BR saned (8), +.BR sane\-dll (5), +.BR scanimage (1) + +.I http://www.penguin-breeder.org/?page=sane\-net +.SH AUTHOR +David Mosberger and Andreas Beck diff --git a/upstream/fedora-40/man5/sane-niash.5 b/upstream/fedora-40/man5/sane-niash.5 new file mode 100644 index 00000000..ed47a8bc --- /dev/null +++ b/upstream/fedora-40/man5/sane-niash.5 @@ -0,0 +1,81 @@ +.TH sane\-niash 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-niash + +.SH NAME +sane\-niash \- SANE backend for scanners based on the NIASH chipset + +.SH DESCRIPTION +The +.B sane\-niash +implements a SANE (Scanner Access Now Easy) backend that +provides access to NIASH chipset based scanners. This backend will try to support +the following models: + +.ft CR +.nf +MANUFACTURER: MODEL: USB ID: +--------------- ---------------- --------- +Agfa Snapscan Touch 06BD-0100 (1)(a) +Trust Office Scan 19200 047B-1000 (1)(a) +Hewlett-Packard Scanjet 3300c 03F0-0205 (1)(a)(b) +Hewlett-Packard Scanjet 3400c 03F0-0405 (2)(b) +Hewlett-Packard Scanjet 4300c 03F0-0305 (2)(a) +Silitek ScanJet 4300c 047B-1002 (2)(b) +.fi +.ft R +.PP +.br +ASIC: (1) \- NIASH00012/00013/00014 / (2) \- NIASH00019 +.br +ANALOG FRONT-END: (a) \- ESIC ES8100QA / (b) \- WM8143-12 +.br + +.SH CONFIGURATION +The +.I niash.conf +file is meant for future configuration options. +Empty lines and lines starting with a hash mark (#) are +ignored. Currently no configuration options exist. + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-niash.a +The static library implementing this backend. + +.TP +.I /usr/lib64/sane/libsane\-niash.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH CAVEATS +If you use a +.br +Hewlett-Packard Scanjet 3400c +or +.br +Hewlett-Packard Scanjet 4300c +.br +together with Linux kernel +.BR 2.6 , +kernel version +.B 2.6.8 +or newer is necessary. + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_NIASH +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_NIASH=255 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) +.br +.I http://www.sourceforge.net/projects/hp3300backend +.SH AUTHOR +Bertrik Sikken +.RI < bertrik@zonnet.nl > diff --git a/upstream/fedora-40/man5/sane-p5.5 b/upstream/fedora-40/man5/sane-p5.5 new file mode 100644 index 00000000..bf2418ce --- /dev/null +++ b/upstream/fedora-40/man5/sane-p5.5 @@ -0,0 +1,162 @@ +.TH "sane\-p5" "5" "15 Feb 2010" "" "SANE Scanner Access Now Easy" +.IX sane\-p5 +.SH "NAME" +sane\-p5 \- SANE backend for the Primax PagePartner +.SH "DESCRIPTION" +The +.B sane\-p5 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the Primax PagePartner parallel port sheet fed scanner. +.PP +This backend handles 100, 150, 200, 300 and 600 dpi scan resolutions, +in color and gray modes. The 600 dpi is actually 300x600 with lines +enlarged to match the vertical resolution. +.PP +.B EPP/ECP MODES ONLY +The current version of the backend uses only EPP or ECP mode to communicate +with the scanner. It is +recommended that you set your parallel port to EPP in BIOS with the current +version of this backend. ECPEPP will only +work if you use a 2.4 or 2.6 kernel with ppdev character device support. +.PP + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I port value +.RE +.PP +Where +\fBvalue\fR is : + +.RS +.TP +auto +autodetect all parallel ports and probe +them for scanner +.TP +/dev/parport0 +uses linux ppdev device, depending on the +number of available parallel port, you +have to use /dev/parport1, /dev/parport2, ... +.PP +.RE +You can rename any device using the +.PP +.RS +.br +.I option name my_name +.RE +.PP +option. This option apply to the last port option. + +.SH "CONFIGURATION" +Please make sure to edit +.I dll.conf +.B before +you use the backend, since this backend isn't enabled by default. +.PP + +.SH "FILES" +.TP +.I /etc/sane.d/p5.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-p5.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-p5.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH "ENVIRONMENT" +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_P5 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.PP +.RS +.ft CR +.nf +level debug output +\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0 critical errors + 1 errors + 2 warnings & minor errors + 4 information messages + 8 start/stop of functions + 16 tracing messages + 32 I/O functions + 64 I/O functions with traces + 128 scanned/calibration data +.fi +.ft R + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-net (5), +.BR saned (8), +.BR scanimage (1) + +.SH "AUTHOR" +St\['e]phane Voltz +.RI < stef.dev@free.fr > + +.SH "CREDITS" +Support for the Prima PagePartner has been made possible thank to an hardware donation +by S\['e]bastien Lange. + +.SH "BUG REPORTS" +If something doesn't work mail sane-devel@alioth-lists.debian.net or submit an +issue via +.I https://gitlab.com/sane-project/backends/issues/new +with a label of backend/p5. +Please give as much information as you can. + +.TP +.I SANE version +run "scanimage \-V" to determine this +.TP +.I the backend version and your scanner hardware +run +.I "SANE_DEBUG_P5=255 scanimage \-L 2>log" +as root. If you don't get any output from the p5 backend, make sure a line "p5" is included into +your +.IR /etc/sane.d/dll.conf . +If your scanner isn't detected, make sure you've defined the right port address, or the +correct device +in your p5.conf. +.TP +.I the name of your scanner/vendor +also a worthy information. Please also include the optical resolution and lamp type of your +scanner, both can be found in the manual of your scanner. +.TP +.I any further comments +if you have comments about the documentation (what could be done better), or you +think I should know something, please include it. diff --git a/upstream/fedora-40/man5/sane-pie.5 b/upstream/fedora-40/man5/sane-pie.5 new file mode 100644 index 00000000..e692e02e --- /dev/null +++ b/upstream/fedora-40/man5/sane-pie.5 @@ -0,0 +1,59 @@ +.TH sane\-pie 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-pie +.SH NAME +sane\-pie \- SANE backend for PIE, Devcom and AdLib SCSI flatbed scanners + +.SH DESCRIPTION +The +.B sane\-pie +library implements a SANE (Scanner Access Now Easy) backend that +provides access to PIE, Devcom and AdLib SCSI flatbed scanners. +.br +At present, the following scanners should work with this backend: +.PP +.ft CR +.nf +Model: Status +---------------------- ------ +Devcom 9636PRO OK +Devcom 9636S Untested +Devcom 9630S Untested +ScanAce 1236S Untested +ScanAce 1230S Untested +ScanAce II Untested +ScanAce III OK +ScanAce Plus Untested +ScanAce II Plus Untested +ScanAce III Plus Untested +ScanAce V Untested +ScanAce ScanMedia Untested +ScanAce ScanMedia II Untested +ScanAce 630S Untested +ScanAce 636S Untested +JetScan 630 OK +JetScan 636PRO Untested +.fi +.ft R +.PP + +.SH FILES +.TP +.I /etc/sane.d/pie.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-pie.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-pie.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.PP + +.SH SEE ALSO +.BR sane (7) + +.SH "CONTACT AND BUG-REPORTS" +Please send any information and bug-reports to: +.br +Simon Munton +.RI < simon@munton.demon.co.uk > diff --git a/upstream/fedora-40/man5/sane-pieusb.5 b/upstream/fedora-40/man5/sane-pieusb.5 new file mode 100644 index 00000000..59f05380 --- /dev/null +++ b/upstream/fedora-40/man5/sane-pieusb.5 @@ -0,0 +1,120 @@ +.TH sane\-pieusb 5 "10 Aug 2015" "" "SANE Scanner Access Now Easy" +.IX sane\-pieusb +.SH NAME +sane\-pieusb \- SANE backend for USB-connected PIE PowerSlide and +Reflecta DigitDia/CrystalScan/ProScan slide scanners + +.SH DESCRIPTION +The +.B sane\-pieusb +library implements a SANE (Scanner Access Now Easy) backend that +provides access to USB-connected PIE and Reflecta slide scanners. +.br +At present, the following scanners should work with this backend: +.PP +.ft CR +.nf +Model: Status +------------------------- ------ +PIE PowerSlide 3600 Untested +PIE PowerSlide 3650 Untested +PIE PowerSlide 4000 Untested +PIE PowerSlide 5000 Untested +Reflecta CrystalScan 7200 Untested +Reflecta ProScan 4000 Untested +Reflecta ProScan 7200 Untested +Reflecta DigitDia 3600 Untested +Reflecta DigitDia 4000 Untested +Reflecta DigitDia 5000 Untested +Reflecta DigitDia 6000 Ok +.fi +.ft R +.PP + +.SH "MULTIPLE SLIDES" +Support for multiple slide scanners (like the PowerSlide or DigitDia +series) is done by auto-advancing ('Advance slide' setting) the slide +after each scan. + +However, for best results, it is recommended to do a preview for +every slide since this sets gamma, brightness, and contrast to optimal +values. + +Attention: SANE does not have an automatic landscape/portrait +detection and re-orientation when scanning multiple slides. You have +to put all slides into one orientation first ! + +.SH "DIRT REMOVAL" +If available, +.B sane\-pieusb +supports infrared scans for dirt detection and +removal. This must be enabled via the 'Clean image' setting. + +.SH "KNOWN PROBLEMS" +The +.B sane\-pieusb +backend supports dirt removal based on infrared scan +information. Since SANE does not provide post-processing in the +backend, +.B sane\-pieusb +does the scanning and dirt removal during the setup +phase. The 'scan' phase is only used to transfer the completed image. +Therefore +.B sane\-pieusb +does not multi-thread making a typical frontend +appear as 'blocked'. Also cancel requests are only honored between +scans. + +.SH "ENVIRONMENT" +.TP +.B SANE_DEBUG_PIEUSB +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.PP +.RS +.ft CR +.nf +level debug output +\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0 nothing + 1 errors + 2 warnings & minor errors + 5 additional information + 7 SANE api calls + 9 backend functions +11 scanner functions +13 usb functions +15 image buffer functions +.fi +.ft R +.RE +.PP + +.SH FILES +.TP +.I /etc/sane.d/pieusb.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-pieusb.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-pieusb.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.PP + +.SH SEE ALSO +.BR sane (7) + +.SH "CONTACT AND BUG-REPORTS" +Please send any information and bug-reports to: +.br +Klaus Kämpf +.RI < kkaempf@suse.com > + +.SH AUTHORS +The pieusb backend is based on work by Jan Vleeshouwers, Michael +Rickmann, and Klaus Kämpf diff --git a/upstream/fedora-40/man5/sane-pixma.5 b/upstream/fedora-40/man5/sane-pixma.5 new file mode 100644 index 00000000..1271832e --- /dev/null +++ b/upstream/fedora-40/man5/sane-pixma.5 @@ -0,0 +1,493 @@ +.TH "sane\-pixma" "5" "15 Aug 2020" "" "SANE Scanner Access Now Easy" +.IX sane\-pixma +.SH NAME +sane\-pixma \- SANE backend for Canon Multi-Function Printers and CanoScan Scanners +.SH DESCRIPTION +The +.B sane\-pixma +library implements a SANE (Scanner Access Now Easy) backend that provides +access to Canon PIXMA / i-SENSYS / imageCLASS / imageRUNNER multi-function +devices (All-in-one printers) and the Canon CanoScan Flatbed/TPU scanners. +The backend implements both the USB interface and network interface +(using Canon's BJNP and MFNP protocols). The network interface supports scanners +over IPv4 as well as IPv6 (MFNP over IPv6 is untested). +.PP +Currently, the following models work with this backend: + + +.PP +.RS +PIXMA E410, E510, E4500 +.br +PIXMA G600, G2000, G2010, G2100, G4000, G4511 +.br +PIXMA GX6000, GX7000 +.br +PIXMA MG2100, MG2200, MG2400, MG2500, MG2900, MG3000, MG3100 +.br +PIXMA MG3200, MG3500, MG3600, MG4200, MG5100, MG5200, MG5300 +.br +PIXMA MG5400, MG5500, MG5600, MG5700, MG6100, MG6200, MG6300 +.br +PIXMA MG6400, MG7100, MG7500, MG7700, MG8200 +.br +PIXMA MP140, MP150, MP160, MP170, MP180, MP190 +.br +PIXMA MP210, MP220, MP230, MP240, MP250, MP260, MP270, MP280 +.br +PIXMA MP360, MP370, MP390 +.br +PIXMA MP450, MP460, MP470, MP480, MP490, MP495 +.br +PIXMA MP500, MP510, MP520, MP530, MP540, MP550, MP560 +.br +PIXMA MP600, MP600R, MP610, MP620, MP630, MP640 +.br +PIXMA MP700, MP710, MP730, PIXMA MP750 (no grayscale) +.br +PIXMA MP800, MP800R, MP810, MP830 +.br +PIXMA MP960, MP970, MP980, MP990 +.br +PIXMA MX300, MX310, MX330, MX340, MX350, MX360, MX370 +.br +PIXMA MX410, MX420, MX470, MX510, MX520, MX530, MX700, MX720 +.br +PIXMA MX850, MX860, MX870, MX882, MX885, MX890, MX920, MX7600 +.br +PIXMA TR4500, TR4600, TR4700 +.br +PIXMA TS2400, TS2600, TS3100, TS3300, TS3450, TS3451, TS3452 +.br +PIXMA TS3500, TS5000, TS5100, TS5350i, TS5400, TS6100, TS6200 +.br +PIXMA TS7530, TS7450i ,TS8000, TS8530, TS8200 +.br +PIXUS MP10 +.br +imageCLASS MF634Cdw, MF733Cdw +.br +imageCLASS MF3110, MF3240, MF4010, MF4018 +.br +imageCLASS MF4120, MF4122, MF4140, MF4150 +.br +imageCLASS MF4270, MF4350d, MF4370dn, MF4380dn +.br +imageCLASS MF4410, MF4430, MF4570dw, MF4660, MF4690 +.br +imageCLASS MF5730, MF5770, MF6550, MPC200 +.br +imageCLASS D420, D480, D530, D570 +.br +i-SENSYS MF210, MF230, MF240, MF440, MF620, MF630, MF640 +.br +i-SENSYS MF645C, MF730, MF731/733, MF741/743 +.br +i-SENSYS MF3010, MF4320d, MF4330d, MF4500, MF4700, MF4800 +.br +i-SENSYS MF6100, MF8030, MF8200C, MF8300 +.br +imageRUNNER 1018/1022/1023, 1020/1024/1025, 1133 +.br +CanoScan 8800F, 9000F, 9000F Mark II +.br +CanoScan LiDE 300, 400 +.br +MAXIFY MB2000, MB2100, MB2300, MB2700, MB5000, MB5100, MB5400 +.RE +.PP +The following models are not well tested and/or the scanner sometimes hangs +and must be switched off and on. +.PP +.RS +PIXMA MP760, MP770, MP780, MP790 +.RE +.PP +The following models may use the same Pixma protocol as those listed +above, but have not yet been reported to work (or not). They are declared +in the backend so that they get recognized and activated. +Feedback in the sane\-devel mailing list welcome. +.PP +.RS +PIXMA E400, E460, E470, E480, E500, E560, E600, E610 +.br +PIXMA E3100, E3300, E3400, E4200 +.br +PIXMA G2020, G2060, G3020, G3060, G7000, G7080 +.br +PIXMA MG4100, MG6500, MG6600, MG6800, MG6900, MG8100 +.br +PIXMA MP375R, MP493, MP740 +.br +PIXMA MX320, MX390, MX430, MX450, MX490, MX710 +.br +PIXMA G3000, G3010, G4010, G6000, G6080, G7000, GM4000, GM4080 +.br +PIXMA TR7500, TR7530, TR7600, TR8500, TR8530, TR8580, TR8600 +.br +PIXMA TR8630, TR9530 +.br +PIXMA TS3400, TS5100, TS6000, TS6130, TS6180, TS6230, TS6280, TS6300 +.br +PIXMA TS6330, TS6330, TS6380, TS6400, TS7330, TS7400, TS7430, TS8100 +.br +PIXMA TS8130, TS8180, TS8230, TS8280, TS8300, TS8330, TS8380, TS9000 +.br +PIXMA TS9100, TS9180, TS9500, TS9580 +.br +PIXUS MP5, XK50, XK60, XK70, XK80, XK90, XK100, XK500 +.br +imageCLASS MF720, MF810/820, MF5630, MF5650, MF5750, MF8170c +.br +imageCLASS MPC190, D550 +.br +i-SENSYS MF110, MF220, MF260, MF410, MF420, MF510, MF520, MF740 +.br +i-SENSYS MF5880dn, MF5900, MF6680dn, MF8500C +.br +MAXIFY MB5300 +.RE +.PP +The following models may use partly the same Pixma protocol as other devices +listed above, but may still need some work. They are declared in the backend +as experimental and need the environment variable PIXMA_EXPERIMENT=1 to get +recognized and activated. Snoop logs are required to further investigate, +please contact the sane\-devel mailing list. +.PP +.RS +\-\- none \-\- +.RE +.PP +The backend supports: +.PP +.RS +* resolutions of 75, 150, 300, 600, 1200, 2400, 4800, and 9600 DPI (some maybe buggy), +.br +* color and grayscale mode, as well as lineart on certain models, +.br +* a custom gamma table, +.br +* Automatic Document Feeder, Simplex and Duplex. +.br +* Transparency Unit, 24 or 48 bits depth. Infrared channel on certain models. +.RE +.PP +The device name for USB devices is in the form pixma:xxxxyyyy_zzzzz +where x, y and z are vendor ID, product ID and serial number respectively. +.PP +Example: pixma:04A91709_123456 is a MP150. +.PP +Device names for BJNP/MFNP devices is in the form pixma:aaaa_bbbbb +where aaaa is the scanners model and bbbb is the hostname or ip-adress. +.PP +Example: pixma:MF4800_192.168.1.45 is a MF4800 Series multi-function peripheral. +.PP +This backend, based on cloning original Canon drivers protocols, is in +a production stage. Designed has been carried out without any applicable +manufacturer documentation, probably never available. However, we have tested +it as well as we could, but it may not work in all situations. You will find +an up-to-date status at the project homepage. (See below). +Users feedback is essential to help improve features and performances. +.SH OPTIONS +Besides "well-known" options (e.g. resolution, mode etc.) +.B sane\-pixma +backend also +provides the following options, i.e. the options might change in the future. +.br +The button status can be polled i.e. with +.I scanimage \-A. +.br +Button scan is disabled on MAC OS X due to darwin libusb not handling +timeouts in usb interrupt reads, but may work when using the network protocol. +.TP +.I adf\-wait +This option enables and sets the time in seconds waiting for a document +inserted into the +.BR Automatic +.BR Document +.BR Feeder . +The maximum allowed waiting time is 3600 sec (= 1 hour). +.TP +.I button\-controlled +This option can be used by applications (like +.BR scanadf (1) +and +.BR scanimage (1)) +in batch mode, for example when you want to scan many photos or +multiple-page documents. If it is enabled (i.e. is set to true or yes), the +backend waits before every scan until the user presses the "SCAN" button +(for MP150) or the color-scan button (for other models). Just put the +first page in the scanner, press the button, then the next page, press +the button and so on. When you finished, press the gray-scan button. (For +MP150 you have to stop the frontend by pressing Ctrl-C for example.) +.TP +.I button\-update (deprecated) +(write only) In the past this option was required to be set to force +reading of the button status for +.I button\-1 +and +.I button\-2. +The +.B sane\-pixma +backend no longer requires this option to be used: if no fresh data is available, it +will be now requested automatically from the scanner. This option is left for +backward compatibility reasons. +.TP +.I button\-1 button\-2 +(read only) These options will return the value of the respective buttons. +value 0 means that the button was not pressed, 1 is returned when the button +was pressed. Some scanners with more than two buttons send the button number +as target. +.TP +.I original +(read only) Returns the value of the type or size of original to be scanned +if the scanner provides that data. Known values of type: 1 = document, 2 = photo, +5 = film. Known values of size: 1 = A4, 2 = Letter, 8 = 10x15, 9 = 13x18, b = auto. +Not all scanners can provide this data. +.TP +.I target +(read only) Returns the value of the target of the scan operation if the scanner +provides that data. The values depend on the scanner type. Known values: +1 = save to disk, 2 = save to pdf, 3 = send to email, 4 = send to application +or 1 = JPEG, 2 = TIFF, 3 = PDF, 4 = Compact PDF. For some scanners this value +is equivalent to the number of the pressed button. Not all scanners can provide +this data. +.TP +.I scan\-resolution +(read only) Returns the resolution of the scan operation if the scanner +provides that data. Known values: 1 = 75 dpi, 2 = 150 dpi, 3 = 300 dpi, +4 = 600 dpi. Not all scanners can provide this data. +.TP +.I document\-type +(read only) Returns the type of the scanned document if the scanner provides +that data. Known values: 1 = Document, 2 = Photo, 3 = Auto scan. Not all scanners +can provide this data. +.TP +.I adf\-status +(read only) Returns the status of the document feeder if the scanner provides +that data. Known values: 1 = ADF empty, 2 = ADF filled. Not all scanners can +provide this data. +.TP +.I adf\-orientation +(read only) Returns the scan orientation of the medium scanned from ADF if the +scanner provides that data. Known values: 1 = Portrait, 2 = Landscape. Not all +scanners can provide this data. +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-pixma.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-pixma.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.TP +.I /etc/sane.d/pixma.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.RS +.PP +The file contains an optional list of networked scanners using the BJNP or MFNP protools +(See below for datails on networking support for scanners). Normally +only scanners that cannot be auto-detected because they are on a different +subnet shall be listed here. If you do not use Linux and your OS does not allow enumeration of +interfaces (i.e. it does not support the +.BR getifaddrs () +qfunction) you also may need +to add your scanner here as well. +.PP +Scanners shall be listed in the configuration file as follows: +.PP +.RS +.I ://[:port][/timeout=] +.RE +.PP +where method indicates the protocol used (bjnp is used for inkjet multi-functionals +and mfnp is used for laser multi-functionals). +.PP +host is the hostname or IP address of the scanner, e.g. bjnp://10.0.1.4 +for IPv4, bjnp://[2001:888:118e:18e2:21e:8fff:fe36:b64a] for a literal +IPv6-address or bjnp://myscanner.mydomain.org for a hostname. +.PP +The port number is optional and in normally implied by the method. +Port 8610 is the standard port for mfnp, 8612 for bjnp. +.PP +A scanner specific timeout value for the network protocol can be set using the +bjnp-timeout parameter. The value is in ms. +.PP +Define scanners each on a new line. +.PP +More globally applicable timeouts can be set using the bjnp-timeout parameter as follows: +.PP +.RS +.I bjnp-timeout= +.RE +.PP +A timeout defined using bjnp-timeout will apply to the following scanner definitions +in the file. If required the bjnp-timeout setting +can be defined multiple times, where each setting will apply only to the scanners that +follow the setting. The last setting is used for the auto discovered scanners. +If not explicitly set, the default 1000ms setting will apply. +.PP +Setting timeouts should only be required in exceptional cases. +.PP +.RE +.PP +If so desired networking can be disabled as follows: +.RS +.IP - +If the first non-commented line contains +.B networking=no +all networking will be disabled. +This will cause all further statements in the configuration file to be ignored. +.IP - +A line that contains +.B auto_detection=no +will cause auto-detection to be skipped. Explicitly defined network scanners will still be probed. +.SH USB SUPPORT +USB scanners will be auto-detected and require no configuration. +.SH NETWORKING SUPPORT +The +.B sane\-pixma +backend supports network scanners using the so called Canon BJNP +and MFNP protocols. +.PP +Canon seems to be dropping support for these protocols in recent scanners. +To verify if your scanner supports one of these protocols, check the content of +the _scanner._tcp service entry in mDNS/DNS-SD (using for example +.BR avahi-discover (1)). +If that does not list port 8610 +or 8612 your scanner probably does not support the mfmp or bjnp protols. +.PP +Both IPv4 and IPv6 are supported, but IPv6 is as +yet untested with MFNP. Please report your results on the mailing list. +.PP +Configuration is normally not required. +The +.B sane\-pixma +backend will auto-detect your scanner if it is within +the same subnet as your computer if your OS does support this. +.PP +If your scanner can not be auto-detected, you can add it to the +.B sane\-pixma +configuration file (see above). +.SH FIREWALLING FOR NETWORKED SCANNERS +The +.B sane\-pixma +backend communicates with port 8610 for MFNP or port 8612 +for BJNP on the scanner. So +you will have to allow outgoing traffic TO port 8610 or 8612 on the +common subnet for scanning. +.PP +Scanner detection is slightly more complicated. The +.B sane\-pixma +backend sends +a broadcast on all direct connected subnets it can find (provided your OS +allows for enumeration of all network interfaces). The broadcast is sent FROM +port 8612 TO port 8610 or 8612 on the broadcast address of each interface. +The outgoing packets will be allowed by the rule described above. +.PP +Responses from the scanner are sent back to the computer TO port 8612. +Connection tracking however does not see a match as the response does not come +from the broadcast address but from the scanners own address. +For automatic detection of your scanner, you will therefore have to allow +incoming packets TO port 8612 on your computer. This applies to both MFNP and +BJNP. +.PP +So in short: open the firewall for all traffic from your computer to port +8610 (for MFNP) or 8612 (for BJNP) +AND to port 8612 (for both BJNP and MFNP) to your computer. +.PP +With the firewall rules above there is no need to add the scanner to the +.I pixma.conf +file, unless the scanner is on a network that is not directly +connected to your computer. +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_PIXMA +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend itself. Higher value increases +the verbosity and includes the information printed at the lower levels. +.RS +0 print nothing (default) +.br +1 print error and warning messages (recommended) +.br +2 print informational messages +.br +3 print debug-level messages +.br +4 print verbose debug-level messages +.br +11 dump USB traffic +.br +21 full dump USB traffic +.br +.RE +.TP +.B SANE_DEBUG_BJNP +If the library was compiled with debug support enabled, this environment +variable controls the debug level for the +.B BJNP and MFNP +network protocols for this backend. Higher value increases +the verbosity and includes the information printed at the lower levels. +.RS +0 print nothing (default) +.br +1 Print error and warning messages (recommended) +.br +2 Print high level function tracing information +.br +3 Print more detailed protocol tracing information +.br +4 Print protocol headers +.br +5 Print full protocol contents +.RE +.TP +.B PIXMA_EXPERIMENT +Setting to a non-zero value will enable the support for experimental models. +You should also set SANE_DEBUG_PIXMA to 11. +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-dll (5), +.BR scanimage (1), +.BR scanadf (1), +.BR gamma4scanimage (1), +.BR getifaddrs (3) +.PP +In case of trouble with a recent Pixma model, try the latest code for +the +.B sane\-pixma +backend, available in the Sane git repository at: +.br +.I https://gitlab.com/sane-project/backends.git +.PP +You can also post into the Sane-devel mailing list for support. + +.SH AUTHORS +Wittawat Yamwong, Nicolas Martin, Dennis Lou, Louis Lagendijk, Rolf Bensch +.PP +We would like to thank all testers and helpers. Without them we could not be +able to write subdrivers for models we don't have. See also the project +homepage. diff --git a/upstream/fedora-40/man5/sane-plustek.5 b/upstream/fedora-40/man5/sane-plustek.5 new file mode 100644 index 00000000..83d9b7b3 --- /dev/null +++ b/upstream/fedora-40/man5/sane-plustek.5 @@ -0,0 +1,529 @@ +.TH sane\-plustek 5 "03 Nov 2017" "" "SANE Scanner Access Now Easy" +.IX sane\-plustek +.SH NAME +sane\-plustek \- SANE backend for LM983[1/2/3] based +USB flatbed scanners +.SH DESCRIPTION +The +.B sane\-plustek +library implements a SANE (Scanner Access Now Easy) backend that +provides access to USB flatbed scanners based on National Semiconductor +Merlin chipsets (LM9831, 9832 and 9833). +If you're looking for parallel-port support for Plustek scanner +please refer to the +.BR sane\-plustek_pp (5) +backend. + +.SH "SUPPORTED DEVICES" +The Backend is able to support USB scanner based on the National +Semiconductor chipsets LM9831, LM9832 and LM9833. The following tables +show various devices which are currently reported to work. If your +Plustek scanner has another Product ID, then the device is +.B NOT +supported by this backend. +.br + +Vendor Plustek \- ID: 0x07B3 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +OpticPro U12 LM9831 600x1200dpi 42bit 512Kb 0x0010 +OpticPro UT12 LM9831 600x1200dpi 42bit 512Kb 0x0013 +OpticPro UT12 LM9832 600x1200dpi 42bit 512Kb 0x0017 +OpticPro UT16 LM9832 600x1200dpi 42bit 512Kb 0x0017 +OpticPro U24 LM9831 1200x2400dpi 42bit 2Mb 0x0011 +OpticPro U24 LM9832 1200x2400dpi 42bit 2Mb 0x0015 +OpticPro UT24 LM9832 1200x2400dpi 42bit 2Mb 0x0017 +.fi +.ft R +.PP + +Vendor KYE/Genius \- ID: 0x0458 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +Colorpage HR6 V2 LM9832 600x1200dpi 42bit 512Kb 0x2007 +Colorpage HR6 V2 LM9832 600x1200dpi 42bit 512Kb 0x2008 +Colorpage HR6A LM9832 600x1200dpi 42bit 512Kb 0x2009 +Colorpage HR7 LM9832 600x1200dpi 42bit 512Kb 0x2013 +Colorpage HR7LE LM9832 600x1200dpi 42bit 512Kb 0x2015 +Colorpage HR6X LM9832 600x1200dpi 42bit 512Kb 0x2016 +.fi +.ft R +.PP + +Vendor Hewlett-Packard \- ID: 0x03F0 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +ScanJet 2100C LM9831 600x1200dpi 42bit 512Kb 0x0505 +ScanJet 2200C LM9832 600x1200dpi 42bit 512Kb 0x0605 +.fi +.ft R +.PP + +Vendor Mustek \- ID: 0x0400 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +BearPaw 1200 LM9831 600x1200dpi 42bit 512Kb 0x1000 +BearPaw 1200 LM9832 600x1200dpi 42bit 512Kb 0x1001* +BearPaw 2400 LM9832 1200x2400dpi 42bit 2Mb 0x1001 +.fi +.ft R +* see also description for model override switch below! +.PP + +Vendor UMAX \- ID: 0x1606 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +UMAX 3400 LM9832 600x1200dpi 42bit 512Kb 0x0050 +UMAX 3400/3450 LM9832 600x1200dpi 42bit 512Kb 0x0060 +UMAX 5400 LM9832 1200x2400dpi 42bit 512Kb 0x0160 +.fi +.ft R +.PP + +Vendor COMPAQ \- ID: 0x049F +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +S4-100 LM9832 600x1200dpi 42bit 512Kb 0x001A +.fi +.ft R +.PP + +Vendor Epson \- ID: 0x04B8 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +Perfection 1250 LM9832 1200x2400dpi 42bit 512Kb 0x010F +Perfection 1260 LM9832 1200x2400dpi 42bit 512Kb 0x011D +.fi +.ft R +.PP + +Vendor CANON \- ID: 0x04A9 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +CanoScan N650/656U LM9832 600x1200dpi 42bit 512Kb 0x2206 +CanoScan N1220U LM9832 1200x2400dpi 42bit 512Kb 0x2207 +CanoScan D660U LM9832 600x1200dpi 42bit 512Kb 0x2208 +CanoScan N670/676U LM9833 600x1200dpi 48bit 512Kb 0x220D +CanoScan N1240U LM9833 1200x2400dpi 48bit 512Kb 0x220E +CanoScan LIDE20 LM9833 600x1200dpi 48bit 512Kb 0x220D +CanoScan LIDE25 LM9833 1200x2400dpi 48bit 512Kb 0x2220 +CanoScan LIDE30 LM9833 1200x2400dpi 48bit 512Kb 0x220E +.fi +.ft R +.PP + +Vendor Syscan \- ID: 0x0A82 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +Travelscan 662 LM9833 600x1200dpi 48bit 512Kb 0x6620 +Travelscan 464 LM9833 600x1200dpi 48bit 512Kb 0x4600 +.fi +.ft R +.PP + +Vendor Portable Peripheral Co., Ltd. \- ID: 0x0A53 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +Q-Scan USB001 LM9832 300x600dpi 42bit 512Kb 0x1000 +Q-Scan USB201 LM9832 300x600dpi 42bit 512Kb 0x2000 +.fi +.ft R +.PP + +Vendor Visioneer \- ID: 0x04A7 +.br +.ft CR +.nf +---------------------------------------------------------- +USB Model: ASIC: Properties: Prod-ID +---------------------------------------------------------- +Strobe XP100 LM9833 600x1200dpi 48bit 512Kb 0x0427 +.fi +.ft R +.PP + +.SH "OTHER PLUSTEK SCANNERS" +For parallelport device support see the +.BR sane\-plustek_pp (5) +backend. +.br +The SCSI scanner OpticPro 19200S is a rebadged Artec AM12S scanner +and is supported by the +.BR sane\-artec (5) +backend. +.br +Only the National Semiconductor LM983[1/2/] based devices of Plustek +are supported by this backend. Older versions of the U12, the UT12, +the U1212 and U1248 (GrandTech chipset) are not supported. +.PP +.ft CR +.nf +Model Chipset backend +------------------------------------ +U1248 GrandTech gt68xx +UT16B GrandTech gt68xx +OpticSlim 1200 GrandTech gt68xx +OpticSlim 2400 GrandTech gt68xx +U12 P98003 u12 +UT12 P98003 u12 +1212U P98003 u12 +.fi +.ft R +For a more complete and up to date list see: +.IR http://www.sane\-project.org/sane\-supported\-devices.html . + +.SH "CONFIGURATION" +To use your scanner with this backend, you need at least two +entries in the configuration file +.I /etc/sane.d/plustek.conf +.RS +.PP +.I [usb] vendor-id product-id +.br +.I device /dev/usbscanner +.RE +.PP +.I [usb] +tells the backend, that the following devicename (here +.IR /dev/usbscanner ) +has to be interpreted as USB scanner device. If vendor- and +product-id has not been specified, the backend tries to +detect this by its own. If device is set to +.I auto +then the next matching device is used. +.br +The following options can be used for a default setup of +your device. Most of them are also available through +the frontend. +.PP +.B +The Options: +.PP +option warmup t +.RS +.I t +specifies the warmup period in seconds, if set to \-1, the +automatic warmup function will be used +.RE +.PP +option lampOff t +.RS +.I t +is the time in seconds for switching off the lamps in +standby mode +.RE +.PP +option lOffonEnd b +.RS +.I b +specifies the behaviour when closing the backend, 1 --> switch +lamps off, 0 --> do not change lamp status +.RE +.PP +option mov m +.RS +.I m +is the model override switch. It works only with Mustek +BearPaw devices. +.br +.br +.ft CR +.nf +m/PID | 0x1000 | 0x1001 +------+--------------+-------------- + 0 | BearPaw 1200 | BearPaw 2400 + 1 | no function | BearPaw 1200 +.fi +.ft R +.RE +.PP +option invertNegatives b +.RS +.I b +0 --> do not invert the picture during negative scans, +.br +1 --> invert picture +.RE +.PP +option cacheCalData b +.RS +.I b +0 --> do not save calibration results, +.br +1 --> save results of calibration in +.I ~/.sane/ +directory +.RE +.PP +option altCalibration b +.RS +.I b +0 --> use standard calibration routines, +.br +1 --> use alternate calibration (only non Plustek devices, standard for CIS devices) +.RE +.PP +option skipFine b +.RS +.I b +0 --> perform fine calibration, +.br +1 --> skip fine calibration (only non Plustek devices) +.RE +.PP +option skipFineWhite b +.RS +.I b +0 --> perform white fine calibration, +.br +1 --> skip white fine calibration (only non Plustek devices) +.RE +.PP +option skipDarkStrip b +.RS +.I b +0 --> perform dark calibration, with enabled lamp using the +dark calibration strip of the scanner. If the scanner does +not have such a strip, the alternative way is to switch off +the lamp during this step. +.br +1 --> always switch off the lamp for dark calibration, even +a black strip is available +.RE +.PP +option skipCalibration b +.RS +.I b +0 --> perform calibration, +.br +1 --> skip calibration (only non Plustek devices) +.RE +.PP +option enableTPA b +.RS +.I b +0 --> default behaviour, specified by the internal tables, +.br +1 --> override internal tables and allow TPA mode (EPSON/UMAX only) +.RE + +.PP +option posOffX x +.br +option posOffY y +.br +option tpaOffX x +.br +option tpaOffY y +.br +option negOffX x +.br +option negOffY y +.RS +.I x y +By using this settings, the user can adjust the given image +positions. +.B Please note, that there's no internal range checking for +.B this feature. +.RE +.PP +option posShadingY p +.br +option tpaShadingY p +.br +option negShadingY p +.RS +.I p +overrides the internal shading position. The values are in steps. +.B Please note, that there's no internal range checking for +.B this feature. +.RE +.PP +option redGamma r +.br +option greenGamma g +.br +option blueGamma b +.br +option grayGamma gr +.RS +.I r g b gr +.RE +By using these values, the internal linear gamma table (r,g,b,gr = 1.0) +can be adjusted. +.PP +option red_gain r +.br +option red_offset ro +.br +option green_gain g +.br +option green_offset go +.br +option blue_gain b +.br +option blue_offset bo +.RS +.I r g b ro go bo +These values can be used to set the gain and offset values of +the AFE for each channel. The range is between 0 and 63. \-1 +means autocalibration. +.RE + +.PP +See the plustek.conf file for examples. +.PP +.B Note: +.br +You have to make sure, that the USB subsystem is loaded +correctly and you have access to the device-node. For +more details see +.BR sane\-usb (5) +manpage. You might use +.BR sane\-find\-scanner (1) +to check that you have access to your device. +.PP +.B Note: +.br +If there's no configuration file, the backend defaults to +.B device auto + +.SH FILES +.TP +.I /etc/sane.d/plustek.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-plustek.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-plustek.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_PLUSTEK +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_PLUSTEK=10 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-u12 (5), +.BR sane\-gt68xx (5), +.BR sane-\mustek_pp (5), +.BR sane\-find\-scanner (1), +.BR scanimage (1) +.br +.I /usr/share/doc/sane-backends/plustek/Plustek-USB.changes + +.SH "CONTACT AND BUG-REPORTS" +Please send any information and bug-reports to: +.br +.B SANE Mailing List +.PP +Additional info and hints can be obtained from our +.br +Mailing-List archive at: +.br +.I http://www.sane\-project.org/mailing\-lists.html +.PP +To obtain debug messages from the backend, please set the +environment-variable +.B SANE_DEBUG_PLUSTEK +before calling your favorite scan-frontend (i.e. +.BR scanimage (1)), i.e.: + +.br +.I export SANE_DEBUG_PLUSTEK=20 ; scanimage +.PP +The value controls the verbosity of the backend. Please note, that +values greater than 24 force the backend to output raw data files, +which could be rather large. The ending of these files is ".raw". +For problem reports it should be enough the set the verbosity to +13. + +.SH "KNOWN BUGS & RESTRICTIONS" + +.PP +* The driver does not support these manic scalings up +to 16 times the physical resolution. The only scaling +is done on resolutions between the physical resolution +of the CCD-/CIS-sensor and the stepper motor i.e. you +have a 600x1200 dpi scanner and you are scanning using +800dpi, so scaling is necessary, because the sensor only +delivers 600dpi but the motor is capable to perform +1200dpi steps. +.PP +* Plusteks' model policy is somewhat inconsistent. They +sell technically different devices under the +same product name. Therefore it is possible that some +devices like the UT12 or U12 won't work \- please check +the model list above and compare the product-id to +the one your device has. +.PP +* Negative/Slide scanning quality is poor. diff --git a/upstream/fedora-40/man5/sane-plustek_pp.5 b/upstream/fedora-40/man5/sane-plustek_pp.5 new file mode 100644 index 00000000..ef8b5f6c --- /dev/null +++ b/upstream/fedora-40/man5/sane-plustek_pp.5 @@ -0,0 +1,350 @@ +.TH sane\-plustek_pp 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-plustek_pp +.SH NAME +sane\-plustek_pp \- SANE backend for Plustek parallel port +flatbed scanners +.SH DESCRIPTION +The +.B sane\-plustek_pp +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Plustek ASIC 9600[1/3] and P9800[1/3] based +parallel port flatbed scanners. + +.SH "SUPPORTED DEVICES" + +At present, the following scanners should work with this backend: +.PP +.B "PLUSTEK SCANNERS" +.PP +.ft CR +.nf +Parallelport Model: ASIC: Properties: +---------------------- ----- ------------------------ +OpticPro PT12 98003 600x1200 dpi 36bit 512Kb +OpticPro P12 98003 600x1200 dpi 36bit 512Kb +OpticPro 9636T/12000T 98001 600x1200 dpi 36bit 512Kb +OpticPro 12000P Turbo 98001 600x1200 dpi 36bit 512Kb +OpticPro 9636P+/Turbo 98001 600x1200 dpi 36bit 512Kb +OpticPro 9636P 96003 600x1200 dpi 36bit 128Kb +OpticPro 12000P/96000P 96003 600x1200 dpi 36bit 128Kb +OpticPro 1236P 96003 600x1200 dpi 30bit 128Kb +OpticPro 9600P 96003 600x1200 dpi 30bit 128Kb +OpticPro 9630P/FBIV 96003 600x1200 dpi 30bit 128Kb +OpticPro 9630PL (14") 96003 600x1200 dpi 30bit 128Kb +OpticPro A3I 96003 400x800 dpi 36bit 128Kb +OpticPro 600P/6000P 96003 300x600 dpi 30bit 32Kb +OpticPro 4831P 96003 300x600 dpi 30bit 32Kb +OpticPro 4830P/FBIII 96003 300x600 dpi 30bit 32Kb +OpticPro 4800P/FBII 96001 300x600 dpi 24bit 32Kb +.fi +.ft R +.PP + +.B "PRIMAX SCANNERS" + +There are some scanners sold by Primax, but they are in fact +Plustek devices. These scanners are also supported. +The following table will show the relationship: +.PP +.ft CR +.nf +Model: Plustek Model: Remarks: +--------------------------- -------------- ------------ +Colorado 4800 OpticPro 4800 not tested +Compact 4800 Direct OpticPro 600 mov=2 +Compact 4800 Direct 30bit OpticPro 4830 mov=7 +Compact 9600 Direct 30bit OpticPro 9630 works +.fi +.ft R +.PP + +.B "GENIUS SCANNERS" + +The following devices are sold as Genius Scanners, but are in fact +Plustek devices. +The table will show the relationship: +.PP +.ft CR +.nf +Model: Remarks: +--------------------------- ---------------------------- +Colorpage Vivid III V2 Like P12 but has two buttons + and Wolfson DAC +.fi +.ft R +.PP + +.B "ARIES SCANNERS" + +There's one scanner sold as Aries Scanner, but is in fact a +Plustek device. +The following table will show the relationship: +.PP +.ft CR +.nf +Model: Plustek Model: Remarks: +--------------------------- -------------- ------------ +Scan-It 4800 OpticPro 600 mov=2 +.fi +.ft R +.PP + +.B "BrightScan SCANNERS" + +There's one scanner sold as BrightScan OpticPro Scanner, this is also +a rebadged Plustek device. +The following table will show the relationship: +.PP +.ft CR +.nf +Model: Remarks: +--------------------------- ---------------------------- +BrightScan OpticPro OpticPro P12 +.fi +.ft R + +.SH "DEVICE NAMES" +This backend's default device is: +.PP +.RS +.I 0x378 +.RE +.PP +This "default device" will be used if no configuration +file can be found. It is the base address of the parallel port +on i386 machines. +.PP +As the backend supports up to four devices, it is possible to +specify them in the configuration file +.PP +.RS +.I /etc/sane.d/plustek_pp.conf +.RE +.PP +See this file for examples. +.PP + +.SH "CONFIGURATION" +.PP +This section describes the backend's configuration file entries. +The file is located at: +.I /etc/sane.d/plustek_pp.conf +.PP +For a proper setup, you will need at least two entries: +.RS +.PP +.I [direct] +.br +.I device 0x378 +.RE +.PP +.I direct +tells the backend, that the following devicename (here +.IR 0x378 ) +has to be interpreted as parallel port scanner device. In +fact it is the address to use. Alternatively you can use +.I /dev/parport0 +if the backend has been compiled with libieee1284 support. +.PP +Further options: +.PP +option warmup t +.RS +.I t +specifies the warmup period in seconds +.RE +.PP +option lampOff t +.RS +.I t +is the time in seconds for switching off the lamps in +standby mode +.RE +.PP +option lOffonEnd b +.RS +.I b +specifies the behaviour when closing the backend, 1 --> switch +lamps off, 0 --> do not change lamp status +.RE +.PP +option mov m +.RS +.I m +is the model override switch, which only works in direct mode. +.TP +.IR m " = 0" +default: no override +.TP +.IR m " = 1" +OpticPro 9630PL override (works if OP9630 +has been detected) forces legal size (14") +.TP +.IR m " = 2" +Primax 4800Direct override (works if OP600 +has been detected) swaps red/green color +.TP +.IR m " = 3" +OpticPro 9636 override (works if OP9636 has +been detected) disables backends +transparency/negative capabilities +.TP +.IR m " = 4" +OpticPro 9636P override (works if OP9636 has +been detected) disables backends +transparency/negative capabilities +.TP +.IR m " = 5" +OpticPro A3I override (works if OP12000 has +been detected) enables A3 scanning +.TP +.IR m " = 6" +OpticPro 4800P override (works if OP600 +has been detected) swaps red/green color +.TP +.IR m " = 7" +Primax 4800Direct 30bit override (works if +OP4830 has been detected) +.RE +.PP +See the +.I plustek_pp.conf +file for examples. +.PP + +.SH "PARALLEL PORT MODES" +.PP +The current driver works best, when the parallel port +has been set to EPP-mode. When detecting any other +mode such as ECP or PS/2 the driver tries to set to a +faster, supported mode. If this fails, it will use the +SPP mode, as this mode should work with all Linux supported +parallel ports. If in doubt, enter your BIOS and set it to +any mode except ECP. +.PP +Former Plustek scanner models (4830, 9630) supplied a +ISA parallel port adapter card. This card is +.BR not +supported by the driver. +.PP +The ASIC 96001/3 based models have sometimes trouble with +high resolution modes. If you encounter sporadic corrupted +images (parts duplicated or shifted horizontally) kill all +other applications before scanning and (if sufficient +memory available) disable swapping. +.PP +See the +.I plustek_pp.conf +file for examples. +.PP + +.SH FILES +.TP +.I /etc/sane.d/plustek_pp.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-plustek_pp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-plustek_pp.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_PLUSTEK_PP +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_PLUSTEK_PP=10 + +.SH "SEE ALSO" +.BR sane (7), +.BR xscanimage (1), +.br +.I /usr/share/doc/sane-backends/plustek/Plustek\-PARPORT.changes + +.SH "CONTACT AND BUG-REPORTS" +Please send any information and bug-reports to: +.br +.B SANE Mailing List +.PP +Additional info and hints can be obtained from our +.br +Mailing-List archive at: +.br +.I http://www.sane\-project.org/mailing\-lists.html +.PP +To obtain debug messages from the backend, please set the +environment-variable +.B SANE_DEBUG_PLUSTEK_PP +before calling your favorite scan-frontend (i.e. +.BR xscanimage (1)), i.e.: +.br +.I export SANE_DEBUG_PLUSTEK_PP=20 ; xscanimage +.PP +The value controls the verbosity of the backend. +.PP + +.SH "KNOWN BUGS & RESTRICTIONS" +.PP +* The Halftoning works, but the quality is poor +.PP +* Printers (especially HP models) will start to +print during scanning. This in fact is a problem +to other printers too, using bidirectional protocol +(see www.plustek.com (TAIWAN) page for further details) +.PP +* The driver does not support these manic scalings up +to 16 times the physical resolution. The only scaling +is done on resolutions between the physical resolution +of the CCD-sensor and the stepper motor i.e. you have a +600x1200 dpi scanner and you are scanning using 800dpi, +so scaling is necessary, because the sensor only delivers +600dpi but the motor is capable to perform 800dpi steps. +.PP +* On some devices, the pictures seems bluish +.PP +.I ASIC 98001 based models: +.PP +* The 300dpi transparency and negative mode does not work +correctly. +.PP +* There is currently no way to distinguish a model with +and without transparency unit. +.PP +* The scanned images seem to be too dark (P9636T) +.PP +.I ASIC 96003/1 based models: +.PP +* 30bit mode is currently not supported. +.PP +* On low end systems under heavy system load the +driver may lose data, which can result in picture +corruption or cause the sensor to hit the scan bed. +.PP +* The scanning speed on 600x1200 dpi models is slow. +.PP +* The scanning quality of the A3I is poor. diff --git a/upstream/fedora-40/man5/sane-qcam.5 b/upstream/fedora-40/man5/sane-qcam.5 new file mode 100644 index 00000000..ff6a524e --- /dev/null +++ b/upstream/fedora-40/man5/sane-qcam.5 @@ -0,0 +1,101 @@ +.TH sane\-qcam 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-qcam +.SH NAME +sane\-qcam \- SANE backend for Connectix QuickCam cameras +.SH DESCRIPTION +The +.B sane\-qcam +library implements a SANE (Scanner Access Now Easy) backend that +provides access Connectix QuickCam cameras. +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I port +.RE +.PP +where +.I port +is the I/O port address at which the device resides. This address is +normally specified in hexadecimal using C syntax (e.g., 0x37b) and may +be prefixed with the letter "u" (e.g., u0x37b) to force the backend to +access the camera in uni-directional mode. +.SH CONFIGURATION +The contents of the +.I qcam.conf +file is a list port addresses that may be connected to a +Connectix QuickCam. Empty lines and everything starting from a hash +mark (#) up to the end of a line are ignored. A sample configuration +file is shown below: +.PP +.RS +0x37b # /dev/lp0 +.br +0x378 # /dev/lp1 +.br +u0x278 # /dev/lp2 forced in uni-directional mode +.br +0x3bc # /dev/lp0 (alternate address) +.RE +.PP +In general, it is safest to list only the port addresses that really +correspond to a QuickCam. For example, if one of the listed addresses +actually connect to a printer, then starting up this backend will +cause the printer to perform a device reset (which is generally +undesirable). +.SH FILES +.TP +.I /etc/sane.d/qcam.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-qcam.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-qcam.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_QCAM +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.SH AUTHOR +David Mosberger + +.SH BUGS +Support is currently limited to the color version of the QuickCam. +The black-and-white camera is starting to work too, but I don't +believe it works in all cases yet. Reportedly, acquiring images of +certain sizes work fine, but others result in shifted images (sounds +like a problem due to byte-padding). +.PP +The program needs root-privileges since it needs to be able to access +the camera's I/O ports. + +.SH SEE ALSO +.BR sane (7) diff --git a/upstream/fedora-40/man5/sane-ricoh.5 b/upstream/fedora-40/man5/sane-ricoh.5 new file mode 100644 index 00000000..c9a87341 --- /dev/null +++ b/upstream/fedora-40/man5/sane-ricoh.5 @@ -0,0 +1,89 @@ +.TH sane\-ricoh 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-ricoh +.SH NAME +sane\-ricoh \- SANE backend for Ricoh flatbed scanners +.SH DESCRIPTION +The +.B sane\-ricoh +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the following Ricoh flatbed scanners: +.PP +.RS +IS50 +.br +IS60 +.br +.RE +.PP +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. The special device name must be a generic SCSI device or a +symlink to such a device. The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name +could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH FILES +.TP +.I /etc/sane.d/ricoh.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-ricoh.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-ricoh.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_RICOH +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_RICOH=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-find\-scanner (1) + +.SH AUTHOR +Feico W. Dillema diff --git a/upstream/fedora-40/man5/sane-ricoh2.5 b/upstream/fedora-40/man5/sane-ricoh2.5 new file mode 100644 index 00000000..113f3c1e --- /dev/null +++ b/upstream/fedora-40/man5/sane-ricoh2.5 @@ -0,0 +1,68 @@ +.TH sane\-ricoh2 5 "04 Sep 2019" "" "SANE Scanner Access Now Easy" +.IX sane\-ricoh2 +.SH NAME +sane\-ricoh2 \- SANE backend for Ricoh flatbed scanners +.SH DESCRIPTION +The +.B sane\-ricoh2 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the following Ricoh flatbed scanners: +.PP +.RS +SG-3110SFNw +.br +SG-3100SNw +.br +SP-100SU +.br +SP-111SU (SP-112SU) +.RE +.PP +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-ricoh2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-ricoh2.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH OPTIONS +The options the backend supports can either be selected through command line +options to programs like +.BR scanimage (1) +or through GUI elements in programs like +.BR xscanimage (1) +or +.BR xsane (1). +.PP +The following options are supported by ricoh2: + +.B \-\-mode color|gray + +.RS +Color or grayscale mode. +.RE + +.B \-\-resolution 300|600 + +.RS +DPI resolution. + +.RE +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_RICOH2 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + +.SH AUTHOR +Stanislav Yuzvinsky diff --git a/upstream/fedora-40/man5/sane-rts8891.5 b/upstream/fedora-40/man5/sane-rts8891.5 new file mode 100644 index 00000000..4ab8ce88 --- /dev/null +++ b/upstream/fedora-40/man5/sane-rts8891.5 @@ -0,0 +1,171 @@ +.TH "sane\-rts8891" "5" "8 Dec 2008" "" "SANE Scanner Access Now Easy" +.SH "NAME" +sane\-rts8891 \- SANE backend for rts8891 based scanners +.SH "DESCRIPTION" +The +.B sane\-rts8891 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to scanners based on the rts8891 ASIC. +.PP +The scanners that work with this backend are: +.PP +.RS +.ft CR +.nf + Vendor Model status +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- + Umax Astra 4400 untested + Umax Astra 4450 untested + HP scanjet 4000c good + HP scanjet 4470c good +.fi +.ft R +.RE + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). + +.br +If you notice any strange behavior, please report to the backend +maintainer or to the SANE mailing list. + +Valid command line options and their syntax can be listed by using + +.RS +scanimage \-\-help \-d rts8891 +.RE + +.TP +.B Scan Mode Options + +.TP +.B \-\-mode +selects the basic mode of operation of the scanner. Valid choices are +.IR "Color" , +.I Gray +and +.IR Lineart . +The default mode is +.IR Color . +The +.I Lineart +mode is for black and white only (1 bit). +.I Gray +will produce 256 levels of gray (8 bits). +.I Color +mode allows for over 16 million different colors produced from +24 bits of color information. + +.TP +.B \-\-resolution +selects the resolution for a scan. The horizontal and vertical resolutions are set +by the value of this option. The scanner is capable of the following resolutions for the specified option value: +.PP +.RS +.ft CR +.nf + Value Hor. Resolution Vert. Resolution + \-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 75 75dpi 75dpi + 150 150dpi 150dpi + 300 300dpi 300dpi + 600 600dpi 600dpi + 1200 1200dpi 1200dpi +.fi +.ft R +.RE + +.TP +.B \-\-preview +requests a preview scan. The resolution used for that scan is 75 dpi +and the scan area and the scan mode are as specified through their options, +or the default if not specified. The default value for preview mode is "no". + +.TP +.B \-\-threshold +selects the minimum\-brightness to get a white point. The threshold is only used with Lineart mode scans. +It is specified as a percentage in the range 0..100% (in steps of 1). +The default value of the threshold option is 50. + + +.SH "CONFIGURATION FILE" +The configuration file +.I /etc/sane.d/rts8891.conf +contains the usb device ids of supported scanners (eg usb 0x043d 0x007c) and scanner configuration options. +Empty lines and lines starting with a hash mark (#) are +ignored. +.PP +The options supported are +.BR allowsharing , +.B modelnumber +. + +Option +.TP +.B allowsharing +enables or not the sharing of the scanner between multiple frontends at the same time. +.TP +.B modelnumber +is used to force the reported model by the backend and is only useful in the case of a scanner which NVRAM has been erased. + +.RS +.ft CR +.nf +0 to report a HP4470c. +1 to report a HP4400c. +2 to report an Astra 4400. +.fi +.ft R +.RE + +.SH "FILES" +.TP +.I /usr/lib64/sane/libsane\-rts8891.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-rts8891.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH "ENVIRONMENT" +.TP +.B SANE_DEBUG_RTS8891 SANE_DEBUG_RTS8891_LOW SANE_DEBUG_RTS88XX_LIB +If the library was compiled with debug support enabled, these +environment variables control the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller levels +reduce verbosity. + +.SH "LIMITATIONS" +Scanners of the same model exist with different sensors, due to lack of data +(ie USB logs) some sensors are better supported than others. At least 75 dpi +mode is working for any model. Sharing the scanner between several frontends +at the same time (allowsharing option) may not work on some USB controllers. +.PP +XPA is not (yet) supported. +.SH "BUGS" +.br +No bugs currently known. + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + +.SH "AUTHOR" +.TP +This backend has been developed by St\['e]phane Voltz. +.I http://stef.dev.free.fr/sane/rts8891 + +.SH "CREDITS" +.TP +Many thanks go to: +Laurent Fournier who donated me a HP4470c. +Vladimir Sysoev and "TheUnruly Squash" for the time they spent recording +USB activity and testing the experimental version on HP4400 models. diff --git a/upstream/fedora-40/man5/sane-s9036.5 b/upstream/fedora-40/man5/sane-s9036.5 new file mode 100644 index 00000000..be4f2677 --- /dev/null +++ b/upstream/fedora-40/man5/sane-s9036.5 @@ -0,0 +1,81 @@ +.TH sane\-s9036 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-s9036 +.SH NAME +sane\-s9036 \- SANE backend for Siemens 9036 flatbed scanners +.SH DESCRIPTION +The +.B sane\-s9036 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Siemens 9036 flatbed scanners. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. The special device name must be a generic SCSI device or a +symlink to such a device. The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name +could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH FILES +.TP +.I /etc/sane.d/s9036.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-s9036.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-s9036.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_S9036 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_S9036=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHOR +Ingo Schneider diff --git a/upstream/fedora-40/man5/sane-sceptre.5 b/upstream/fedora-40/man5/sane-sceptre.5 new file mode 100644 index 00000000..2b627321 --- /dev/null +++ b/upstream/fedora-40/man5/sane-sceptre.5 @@ -0,0 +1,184 @@ +.TH sane\-sceptre 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-sceptre +.SH NAME +sane\-sceptre \- SANE backend for SCEPTRE scanners +.SH DESCRIPTION +The +.B sane\-sceptre +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Sceptre flatbed scanners. This backend should be +considered +.B beta-quality +software! Please report any strange behavior to the maintainer of the +backend or to the SANE mailing list. +.PP +At present, only one scanner is known to work with this backend: +.PP +.RS +.ft CR +.nf +Model Connection Type +--------------------------- ------------------- +Sceptre VividScan S1200 SCSI +.fi +.ft R +.RE + +The make of this scanner is KINPO, so other scanners from that manufacturer may also work (eg. the S600). +.SH OPTIONS +The options the backend supports can either be selected through command line +options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xscanimage (1) +or +.BR xsane (1). + +Valid command line options and their syntax can be listed by using + +.RS +scanimage \-\-help \-d sceptre +.RE + +.TP +.B Scan Mode + +.TP +.B \-\-mode Lineart|Halftone|Gray|Color +Selects the basic mode of operation of the scanner. +The +.I Lineart +and +.I Halftone +mode are black and white only (1 bit). +.I Gray +will produce 256 levels of gray (8 bits). +.I Color +will produce a 24 bits +color image. The scanner supports 30 bits internally but it only +exports 24. + +.TP +.B \-\-resolution 50..1200 +Selects the resolution for a scan. The scanner can do several +resolutions between 50 and 1200. + +.TP +.B \-\-halftone\-pattern 1|2|3|4 +Selects the pattern mode that is used in +.I Halftone +mode. + +.TP +.B \-\-gamma\-correction Default|User Defined|High Density Printing|\ +Low density printing|High contrast printing +controls the scanner internal gamma correction. + +.TP +.B \-\-custom\-gamma +Allows the user to specify a gamma table (see the +next 3 parameters). +.I Color +mode only. + +.TP +.B \-\-red\-gamma\-table +Can be used to download a user defined +gamma table for the red channel. The table must be 256 bytes long. +.I Color +mode only. + +.TP +.B \-\-green\-gamma\-table +Can be used to download a user defined +gamma table for the green channel. The table must be 256 bytes long. +.I Color +mode only. + +.TP +.B \-\-blue\-gamma\-table +Can be used to download a user defined gamma table +for the blue channel. The table must be 256 bytes long. +.I Color +mode only. + +.TP +.B \-\-threshold 0..255 +Sets the threshold for black and white pixels in +.I Lineart +mode. Possible values are from 0 (darker) to 255 (lighter). + +.TP +.B \-\-preview +Requests a preview scan. The resolution used for that scan is 30 dpi +and the scan area is the maximum allowed. The scan mode is user +selected. The default is "no". + +.TP +.B The geometry options + +.TP +.B \-l \-t \-x \-y +control the scan area: +.B -l +sets the top left x coordinate, +.B \-t +the top left y coordinate, +.B \-x +selects the width and +.B \-y +the height of the scan area. All parameters are specified in millimeters by default. + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/sceptre.conf +supports only one item: the device name to use +.RI "(eg " /dev/scanner ). + + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-sceptre.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-sceptre.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SCEPTRE +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller levels +reduce verbosity. + + +.SH LIMITATIONS +.TP +.B Resolutions +The windows TWAIN driver can be set to any resolution between 50 to 1200 +(excluding software interpolation). This backend cannot. Only a +handful of resolution are available, although they should be numerous +enough. + + +.SH BUGS +None known. + + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + + +.SH AUTHOR + +.TP +The package is actively maintained by Frank Zago. +.I http://www.zago.net/sane/#sceptre diff --git a/upstream/fedora-40/man5/sane-scsi.5 b/upstream/fedora-40/man5/sane-scsi.5 new file mode 100644 index 00000000..01f00f7d --- /dev/null +++ b/upstream/fedora-40/man5/sane-scsi.5 @@ -0,0 +1,355 @@ +.TH sane\-scsi 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-scsi +.SH NAME +sane\-scsi \- SCSI adapter tips for scanners +.SH DESCRIPTION +This manual page contains various operating-system specific tips and +tricks on how to get scanners with a SCSI interface working. +.SH GENERAL INFO +For scanners with a SCSI interface, it may be necessary to edit the +appropriate backend configuration file before using SANE for the first +time. For most systems, the configuration file should list the name +of the generic SCSI device that the scanner is connected to (e.g., under +Linux, +.I /dev/sg4 +or +.I /dev/sge +is such a generic SCSI device). It is customary to create a symlink +from +.I /dev/scanner +to the generic SCSI device that the scanner is connected to. In this +case, the configuration file simply lists the line +.IR /dev/scanner . +For a detailed description of each backend's configuration file, +please refer to the relevant backend manual page (e.g., +.BR sane\-epson (5) +for Epson scanners, +.BR sane\-hp (5) +for HP scanners, etc.). +.PP +For some operating systems (e.g. Linux and OS/2), there is an alternate way of +specifying scanner devices. This alternate way allows one to identify scanners by +the SCSI vendor and model string and/or by the SCSI device address (consisting +of bus number, channel number, id, and logical unit number). The syntax for +specifying a scanner in this way is: +.PP +.RS +scsi +.I VENDOR MODEL TYPE BUS CHANNEL ID LUN +.RE +.PP +where +.I VENDOR +is the SCSI vendor string, +.I MODEL +is the SCSI model string, +.I TYPE +is type SCSI device type string, +.I BUS +is the SCSI bus number (named "host" in +.IR /proc/scsi/scsi ), +.I CHANNEL +is the SCSI channel number, +.I ID +is the SCSI id, and +.I LUN +is the logical unit number of the scanner device. The first two fields are +strings which must be enclosed in double-quotes if they contain any +whitespace. The remaining four fields are non-negative integer numbers. The +correct values for these fields can be found by using operating system +specific tools, e.g. for Linux by looking at the output of the command +.IR "cat /proc/scsi/scsi" . +To simplify configuration, a field's value can be replaced +with an asterisk symbol (``*''). An asterisk has the effect that any value is +allowed for that particular field. This can have the effect that a single +scsi-line matches multiple devices. When this happens, each matching device +will be probed by the backend one by one and registered if the backend thinks +it is a compatible device. For example, the line +.PP +.RS +scsi MUSTEK MFS\-06000CX Scanner 0 00 03 00 +.RE +.PP +would attach the Mustek SCSI scanner with the following /proc/scsi/scsi entry: +.PP +.RS 2 +.ft CR +.nf +Host: scsi0 Channel: 00 Id: 03 Lun: 00 + Vendor: MUSTEK Model: MFS\-06000CX Rev: 4.04 + Type: Scanner ANSI SCSI revision: 0 +.fi +.ft R +.RE +.PP +Usually it's sufficient to use vendor and model strings only or even only the +vendor string. The following example +.PP +.RS +scsi MUSTEK * * * * * * +.RE +.PP +would have the effect that all SCSI devices in the system with a +vendor string of MUSTEK would be probed and recognized by the backend. +.PP +If the remainder of a scsi-string consists of asterisks only, the +asterisks can be omitted. For example, the following line is +equivalent to the one specified previously: +.PP +.RS +scsi MUSTEK +.RE +.PP +On some platforms (e.g., OpenStep), SANE device names take a special +form. This is explained below in the relevant platform-specific section. +.PP +When using a SCSI scanner, ensure that the access permission for the +generic SCSI device is set appropriately. We recommend to add a group +"scanner" to +.I /etc/group +which contains all users that should have +access to the scanner. The permission of the device should then be +set to allow group read and write access. For example, if the scanner +is at generic SCSI device +.IR /dev/sg0 , +then the following two commands would set the permission correctly: +.PP +.RS +$ chgrp scanner /dev/sg0 +.br +$ chmod 660 /dev/sg0 +.br +.RE +.PP +When your system uses the device filesystem (devfs), you have to edit +.IR /etc/devfs/perms. +There you should search the line +.PP +.RS +REGISTER ^sg[^/]* PERMISSIONS root.root 0600 +.RE +.PP +and add a new line (eg. for changing permissions of sg4): +.PP +.RS +REGISTER ^sg4 PERMISSIONS root.scanner 0660 +.RE +.PP +.SH FREEBSD INFO +Auto-configuration using the "scsi *" lines in the config files only works if +the user running the frontend has read/write access to +.IR /dev/xpt0 . +Instead, you can also set a link +.I /dev/scanner +to the appropriate +.I /dev/uk +device. +.RS +.TP +Adaptec AHA1542CF +Reported to work fine under FreeBSD 2.2.2R with the +.B aha +driver. +.TP +Adaptec 2940 +Reported to work fine under FreeBSD 2.2.2. +.TP +Adaptec 1522 +The scanner probes ok but any attempt to +access it +.I hangs +the entire system. It looks like something is disabling interrupts and +then not re-enabling them, so it looks like a bug in the FreeBSD +.B aic +driver. +.TP +Adaptec 1505 +Works on FreeBSD 2.2.5R and 3.0 using the +.B aic +driver, provided that Plug-and-Play support is disabled on the card. +If there are no +.I uk +devices, just do a +.I sh MAKEDEV uk0 +in the +.I /dev +directory. The scanner should then be accessible as +.I /dev/uk0 +if it was probed during boot. +.TP +Tekram DC390 +Reported to work fine under FreeBSD 2.2.2R with the +.B amd +driver. +.RE + +.SH LINUX INFO +First, make sure your kernel has SCSI generic support enabled. In +.IR "make xconfig" , +this shows up under ``SCSI support->SCSI generic support''. +.PP + +To keep scanning times to a minimum, it is strongly recommended to use a large +buffer size for the generic SCSI driver. From SG driver version 2.0 on, the +maximum buffer size can be changed at program run time, and there is no restriction in size. This driver version is part of the Linux kernels from +version 2.2.7 on. If the new SG driver is available some backends +(e.g. +.BR sane\-umax (5), +.BR sane\-mustek (5) , +.BR sane\-sharp (5)) +automatically request larger SCSI +buffers. If a backend does not automatically request a larger SCSI buffer, set +the environment variable +.B SANE_SG_BUFFERSIZE +to the desired buffer size in bytes. It is not recommended to use more +than 1 MB, because for large values the probability increases that the +SG driver cannot allocate the necessary buffer(s). For ISA cards, even +1 MB might be a too large value. For a detailed discussion of memory +issues of the SG driver, see +.I http://www.torque.net/sg. +.PP +For Linux kernels before version 2.2.7 the size of the buffer is only 32KB. +This works, but for many cheaper scanners this causes scanning to be slower by +about a factor of four than when using a size of 127KB. Linux defines the +size of this buffer by macro +.B SG_BIG_BUFF +in header file +.IR /usr/include/scsi/sg.h . +Unless a system is seriously short on memory, it is recommended to increase +this value to the maximum legal value of 128*1024-512=130560 bytes. After +changing this value, it is necessary to recompile both the kernel (or the SCSI +generic module) and the SCSI backends. Keep in mind that this is only +necessary with older Linux kernels. + +.PP +A common issue with SCSI scanners is what to do when you booted +the system while the scanner was turned off. In such a case, the +scanner won't be recognized by the kernel and SANE won't be able +to access it. Fortunately, Linux provides a simple mechanism to +probe a SCSI device on demand. Suppose you have a scanner connected +to SCSI bus 2 and the scanner has a SCSI id of 5. When the system +is up and running and the scanner is turned on, you can issue +the command: +.PP +.RS +echo "scsi add\-single\-device 2 0 5 0" > /proc/scsi/scsi +.RE +.PP +and the kernel will probe and recognize your scanner (this needs to be +done as root). It's also possible to dynamically remove a SCSI device +by using the ``remove\-single\-device'' command. For details, please +refer to to the SCSI-2.4-HOWTO. +.PP +Scanners are known to work with the following SCSI adapters under Linux. This +list isn't complete, usually any SCSI adapter supported by Linux should work. +.PP +.RS +.TP +Acard/Advance SCSI adapters +Some old versions of the kernel driver +.RI ( atp870u.c ) +cut the inquiry information. +Therefore the scanner couldn't be detected correctly. Use a current kernel. +.TP +Adaptec AHA-1505/AHA-1542/AHA-2940 +Reported to work fine with Linux since v2.0. If you encounter kernel freezes +or other unexpected behaviour get the latest Linux kernel (2.2.17 seems to +work) or reduce SCSI buffer size to 32 kB. +.TP +ASUS SC200 +Reported to work fine with Linux v2.0. +.TP +BusLogic BT958 +To configure the BusLogic card, you may need to follow +these instructions (contributed by Jeremy ): +During boot, when your BusLogic adapter is being initialized, press +Ctrl-B to enter your BusLogic adapter setup. Choose the address which +your BusLogic containing your scanner is located. Choose ``SCSI Device +Configuration''. Choose ``Scan SCSI Bus''. Choose whatever SCSI id +that contains your scanner and then choose ``View/Modify SCSI +configuration''. Change ``Negotiation'' to ``async'' and change +``Disconnect'' to ``off''. Press Esc, save, and Esc again until you +are asked to reboot. +.TP +NCR/Symbios 53c400/53c400a or Domex DTC3181E/L/LE (DTCT436/436P) ISA SCSI card +This card is supplied by Mustek (and other vendors). It's supported since +Linux 2.2. The SCSI cards are supported by the module g_NCR5380. It's +necessary to tell the kernel the io port and type of card. Example for a +53c400a: +.I "modprobe g_NCR5380 ncr_addr=0x280 ncr_53c400a=1" . +Once the kernel detects the card, it should work all right. +However, while it should work, do not expect good performance out of this +card---it has no interrupt line and therefore while a scan is in progress, +the system becomes almost unusable. You may change the values of the USLEEP +macros in +.IR drivers/scsi/g_NCR5380.c . +Some documentation is in this file and +.IR NCR5380.c . +.TP +NCR/Symbios 810 +For some scanners it may be necessary to disable disconnect/reconnect. To +achieve this use the option ncr53c8xx="disc:n". Some people reported that +their scanner only worked with the 53c7,8xx driver, not the ncr53c8xx. Try +both if you have trouble. +.br +For Linux kernels before 2.0.33 it may be necessary to increase the SCSI +timeout. The default timeout for the Linux kernels before 2.0.33 is 10 +seconds, which is way too low when scanning large area. If you get messages +of the form ``restart (ncr dead ?)'' in your +.I /var/log/messages +file or on the system console, it's an indication that the timeout is too short. +In this case, find the line ``if (np->latetime>10)'' in file +.I ncr53c8xx. +(normally in directory +.IR /usr/src/linux/drivers/scsi ) +and change the constant 10 to, say, 60 (one minute). +Then rebuild the kernel/module and try again. +.TP +Tekram DC315 +The driver can be downloaded from +.IR http://www.garloff.de/kurt/linux/dc395/ . +For some older scanners it may be necessary to disable all the more advanced +features by using e.g. +.IR "modprobe dc395x_trm dc395x_trm=7,5,1,32" . +.TP +Tekram DC390 +Version 1.11 of the Tekram driver seems to work fine mostly, except +that the scan does not terminate properly (it causes a SCSI timeout +after 10 minutes). The generic AM53C974 also seems to work fine +and does not suffer from the timeout problems. + +.SH SOLARIS, OPENSTEP AND NEXTSTEP INFO +Under Solaris, OpenStep and NeXTStep, the generic SCSI device name +refers to a SCSI bus, not to an individual device. For example, +.I /dev/sg0 +refers to the first SCSI bus. To tell SANE which device to use, +append the character 'a'+target-id to the special device name. For +example, the SCSI device connected to the first SCSI controller +and with target-id 0 would be called +.IR /dev/sg0a , +and the device with target-id 1 on that same bus would be +called +.IR /dev/sg0b, +and so on. + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SANEI_SCSI +If the library was compiled with debug support enabled, this environment +variable controls the debug level for the generic SCSI I/O subsystem. E.g., a +value of 128 requests all debug output to be printed by the backend. A value +of 255 also prints kernel messages from the SCSI subsystem (where available). +Smaller levels reduce verbosity. +.TP +.B SANE_SCSICMD_TIMEOUT +sets the timeout value for SCSI commands in seconds. Overriding the default +value of 120 seconds should only be necessary for very slow scanners. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-find\-scanner (1), +.BR sane\-"backendname" (5), +.BR sane\-usb (5) + +.SH AUTHOR +David Mosberger diff --git a/upstream/fedora-40/man5/sane-sharp.5 b/upstream/fedora-40/man5/sane-sharp.5 new file mode 100644 index 00000000..ef9f5659 --- /dev/null +++ b/upstream/fedora-40/man5/sane-sharp.5 @@ -0,0 +1,443 @@ +.TH sane\-sharp 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-sharp +.SH NAME +sane\-sharp \- SANE backend for SHARP scanners +.SH DESCRIPTION +The +.B sane\-sharp +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Sharp SCSI scanners. This backend should be +considered +.B beta-quality +software! In the current state it is known to work with JX-610 and JX-250 +scanners. It is prepared for usage with the JX-330 series scanners, +but we are not able to test it with these devices. +.PP +For other Sharp scanners, it may or may not work. +.PP +At present, +the following scanners are known to work with this backend. +.RS +.PP +.ft CR +.nf +Vendor Product id: +----- ----------- +Sharp JX-610 +Sharp JX-250 +Sharp JX-320 +Sharp JX-330 +Sharp JX-350 +.fi +.ft R +.RE +.PP +The following scanners are detected by the backend, but not tested: +.PP +.RS +.ft CR +.nf +Vendor Product id: +----- ----------- +Sharp JX-325 +.fi +.ft R +.RE +.SH DEVICE NAMES +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. The special device name must be a generic SCSI device or a +symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH SCAN OPTIONS +.TP +.B \-\-mode +Scan Mode. Possible settings are: +.I Lineart +(1 bit black & white scans), +.I Gray +(8 bit gray scale scans), +.I Lineart Color +(bi-level color scans), and +.I Color +(8 bit RGB scans). The default value is +.I Color. + +.TP +.B \-\-halftone\-pattern +Halftone Pattern. Available only for the JX-330 series scanners. +Possible settings: +.IR none ", " "Dither Bayer" ", " "Dither Spiral" ", " "Dither Dispersed" +and +.IR "Error Diffusion" . +The default value is +.IR none . + +.TP +.B \-\-source +Paper Source. This option is only available if an automatic document +feeder or a transparency adapter is installed. Possible settings are: +.IR Flatbed ", " "Automatic Document Feeder" , +and +.IR "Transparency Adapter" . +If an ADF or a transparency adapter is installed, using it is the +default selection. + +.TP +.B \-\-custom\-gamma +Custom Gamma This option determines whether a builtin or a custom +gamma table is used. Possible settings are: +.I yes +(enables custom gamma tables) or +.I no +(enables a built gamma table). + +.TP +.B \-\-gamma +Gamma. This option is only available if +.B Custom Gamma +is set to +.IR no . +Possible values are: +.IR 1.0 " or " 2.2 "." +The default value is +.IR 2.2 . +(The JX-250 and JX-350 have no built in gamma +correction; for these scanners, a gamma table is downloaded to the scanner +by the backend.) + +.TP +.B \-\-gamma\-table +Gamma Table. Allowed values: 0..255; 256 numbers must be defined. +The default values are 0, 1, 2, .. 255 (i.e., gamma == 1). This table +is only used for gray scale scans. + +.TP +.B \-\-red\-gamma\-table +Red Gamma Table. Allowed values: 0..255; 256 numbers must be defined. +The default values are 0, 1, 2, .. 255 (i.e., gamma == 1). + +.TP +.B \-\-green\-gamma\-table +Green Gamma Table. Allowed values: 0..255; 256 numbers must be defined. +The default values are 0, 1, 2, .. 255 (i.e., gamma == 1). + +.TP +.B \-\-blue\-gamma\-table +Blue Gamma Table. Allowed values: 0..255; 256 numbers must be defined. +The default values are 0, 1, 2, .. 255 (i.e., gamma == 1). + +.TP +.B \-\-resolution +Selects the resolution of the scanned image. Allowed values: +.I 30..600 +(JX-330, JX-350 and JX-610) and +.I 30..400 +(JX-250). +The default value is 150. + +.TP +.BR \-l ", " \-t ", " \-x ", " \-y +Scan Window. +Top-left x position of scan area +.RB ( \-l ), +top-left y position of scan area +.RB ( \-t ), +bottom right x position of scan area +.RB ( \-x ) +and bottom right y position of scan area +.RB ( \-y ). +The possible settings depend on the scanner model and, for the +JX-250 and the JX-350, also on the usage of the automatic document feeder resp. the +transparency adapter. Please refer to the values allowed by +.BR xscanimage (1), +or +.BR xsane (1). +With +.BR scanimage (1), +enter one of the following commands in order to see the allowed parameter values for +the scan window: + +.RS +scanimage \-d sharp \-\-source "Automatic Document Feeder" \-\-help + +scanimage \-d sharp \-\-source Flatbed \-\-help + +scanimage \-d sharp \-\-source "Transparency Adapter" \-\-help +.RE + +.TP +.B \-\-edge emphasis +Edge emphasis. This option is not available for the JX-250 and the JX-350. +Possible settings: +.IR None ", " Middle ", " Strong ", and " Blur . +The default value is +.IR None . + +.TP +.B \-\-threshold +Sets the threshold for black and white pixels in lineart mode. +Possible values are 1..255. +The default value is 128. +This option is only available in scan mode +.IR lineart . + +.TP +.B \-\-threshold-red +Sets the threshold for the red component of a pixel in +in lineart color scan mode. Possible values are 1..255. +The default value is 128. +This option is only available in scan mode color +.IR lineart . + +.TP +.B \-\-threshold-green +Sets the threshold for the green component of a pixel in +in lineart color scan mode. Possible values are 1..255. +The default value is 128. +This option is only available in scan mode color +.I lineart . + +.TP +.B \-\-threshold-blue +Sets the threshold for the blue component of a pixel in +in lineart color scan mode. Possible values are 1..255. +The default value is 128. +This option is only available in scan mode color +.IR lineart . + +.TP +.B \-\-lightcolor +Sets the color of the light source. Possible values are +.IR white , +.IR red , +.I green +and +.IR blue . +The default value is +.IR white . +This option is only available in scan modes +.I "lineart color" +and +.IR color . + +.SH ADF USAGE +If a paper jam occurrs, the maintenance cover +.I +must +be opened and closed, even if the jammed paper can be removed without opening +the maintenance cover. Otherwise, the error condition will not be cleared. + +.SH CONFIGURATION +The contents of the +.I sharp.conf +file is a list of options and device names that correspond to Sharp +scanners. Empty lines and lines beginning with a hash mark (#) are +ignored. See +.BR sane\-scsi (5) +for details about device names. +.PP +Lines setting an option start with the key word +.B option, +followed by the option's name and the option's value. At present, three +options are defined: +.B buffers, buffersize, +and +.B readqueue. +.PP +Options defined at the start of +.I sharp.conf +apply to all devices; options defined after a +device name apply to this device. +.PP +The options +.B buffers +and +.B +readqueue +are only significant if the backend has been compiled +so that for each scan a second process is forked (switch +.B USE_FORK +in +.I sharp.c +). This process reads the +scan data from the scanner and writes this data into a block of shared memory. +The parent process reads the data from this memory block and delivers it +to the frontend. The options control the size and usage of this shared +memory block. +.PP +.B option buffers +defines the number of buffers used. The smallest number allowed is 2. +.PP +.B option buffersize +defines the size of one buffer. Since each buffer is filled with a +single read command sent to the scanner, its size is limited automatically +to the size allowed by the operating system or by the Sane SCSI library +for SCSI read commands. A buffer size of 128 kB or 256 kB is recommended +for scan resolutions of 300 dpi and above. +.PP +.B option readqueue +defines how many read commands to be sent to the scanner +are queued. At present, the Sane SCSI library supports queued read +commands only for for Linux. For other operating systems, +.B option readqueue +should be set to 0. For Linux, +.B option readqueue +should be set to 2. Larger values than 2 for +.B option readqueue +are not reasonable in most cases. +.B option buffers +should be greater than +.B option readqueue. + +.SH Performance Considerations +This section focuses on the problem of stops of the scanner's carriage +during a scan. Carriage stops happen mainly with the JX-250. This scanner +has obviously only a small internal buffer compared to its speed. That +means that the backend must read the data as fast as possible from the +scanner in order to avoid carriage stops. +.PP +Even the JX-250 needs only less than 10 seconds for a 400 dpi A4 gray +scale scan, which results in a data transfer rate of more than 1.6 MB +per second. This means that the data produced by the scanner must be +processed fairly fast. Due to the small internal buffer of the JX-250, +the backend must issue a read request for the next data block as soon +as possible after reading a block of data in order to avoid carriage +stops. +.PP +Stops of the carriage can be caused by the following reasons: +.PP +.RS +\- too much "traffic" on the SCSI bus +.br +\- slow responses by the backend to the scanner, +.br +\- a program which processes the data acquired by the backend too slow. +.PP +.RE +Too much "traffic" on the SCSI bus: This happens for example, if hard disks +are connected to the same SCSI bus as the scanner, and when data transfer +from/to these hard disks requires a considerable part of the SCSI bandwidth +during a scan. If this is the case, you should consider to connect the +scanner to a separate SCSI adapter. +.PP +Slow responses by the backend to the scanner: Unfortunately, +UNIX-like operating systems generally have no real time capabilities. +Thus there is no guarantee that the backend is under any circumstances +able to communicate with the scanner as fast as required. To minimize this +problem, the backend should be compiled so that a separate reader process +is forked: Make sure that +.B USE_FORK +is defined when you compile +.I sharp.c. +If slow responses of the backend remain to be problem, you could try to +reduce the load of the system. Even while the backend and the reader +process need only a minor amount of processor time, other running +processes can cause an increase in the time delay between two time +slices given to the reader process. On slower systems, such an +increased delay can be enough to cause a carriage stop with the JX-250. +For Linux, the usage of the SG driver version 2.1.36 or above is +recommended, because it supports, in combination with +the SCSI library of Sane version 1.0.2, command queueing within the kernel. +This queueing implementation, combined with a buffer size of at least +128 kB, should avoid most carriage stops. +.PP +Slow processing of the scan data: An example for this situation is +the access to the scanner via a 10 MBit Ethernet, which is definitely +too slow to transfer the scan data as fast as they are produced by the +scanner. If you have enough memory available, you can increase +.B option buffers, +so that an entire image can be stored in these buffers. +.PP +In order to see, if the backend is too slow or if the further processing +of the data is too slow, set the environment variable +.B SANE_DEBUG_SHARP +to 1. When a scan is finished, the backend writes the line "buffer full +conditions: +.IR nn """ +to stderr. If +.I nn +is zero, carriage stops are caused by too slow responses of the backend +or too much "traffic" on the SCSI bus. If +.I nn +is greater than zero, the backend had to wait +.I nn +times until a buffer has been processed by the frontend. (Please note that +.B option buffers +must be greater than +.B option readqueue +in order to get useful output for "buffer full conditions".) + +.SH FILES +.TP +.I /etc/sane.d/sharp.conf +The backend configuration file. +.TP +.I /usr/lib64/sane/libsane\-sharp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-sharp.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SHARP +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.SH KNOWN PROBLEMS +1. ADF Mode +.RS +After several ADF scans, the scanner moves the carriage back to the idle +position and back to ADF scan position, before a scan starts. We do not +know, if this is a problem of the scanner, or if this is a bug of the +backend. At present, the scanner must power off and on to stop this +annoying behaviour. +.RE + +2. Threshold level does not work (only JX-610) +.PP +3. The maximum resolution is limited to 600 dpi(JX-610 supported +to 1200 dpi) resp. 400 dpi (JX-250) +.PP +4. If the JX250 is used with an ADF, the following situation can occur: After +several scans, the scanner moves, after loading a new sheet of paper, the +carriage to the idle position, and then back to the position used for ADF +scans. This happens for +.I +every +scan, in contrast to the calibration, which is done after 10 scans. (For the +calibration, the carriage is also moved to the idle position.) We do not +know if this behavior is caused by the backend, or if it is a bug in the +firmware of the scanner. +.PP +5. Usage of a transparency adapter (film scan unit) is supported, but not +tested. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHORS +Kazuya Fukuda, Abel Deuring + +.SH CREDITS +The Sharp backend is based on the Canon backend written by Helmut Koeberle +.PP +Parts of this man page are a plain copy of +.BR sane\-mustek (5) +by David Mosberger-Tang, Andreas Czechanowski and Andreas Bolsch diff --git a/upstream/fedora-40/man5/sane-sm3600.5 b/upstream/fedora-40/man5/sane-sm3600.5 new file mode 100644 index 00000000..23fa9f1a --- /dev/null +++ b/upstream/fedora-40/man5/sane-sm3600.5 @@ -0,0 +1,92 @@ +.TH sane\-sm3600 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-sm3600 +.SH NAME +sane\-sm3600 \- SANE backend for Microtek scanners with M011 USB chip +.SH DESCRIPTION +The +.B sane\-sm3600 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some Microtek scanners with the Toshiba M011 custom +USB chip. This backend should be considered alpha. +.PP +There are also backends for Microtek scanners with SCSI command set. +Refer to +.BR sane\-microtek (5) +and +.BR sane\-microtek2 (5) +for details. +.PP +At present, the following +scanners are known positively to work with this backend: +.PP +.RS +.ft CR +.nf +Vendor Product id: Remark: +-------- -------------- ----------- +Microtek ScanMaker 3600 all modes ok +Microtek ScanMaker 3700 reported to work +Microtek ScanMaker 3750 reported to work +.fi +.ft R +.RE +.PP +If you own a Microtek scanner with the M011 chip other than the ones +listed above, it may or may not work with SANE! + +.SH "FRONTEND OPTIONS" +This backend dynamically enables the options for the frontend, +that are supported by the scanner dependent on the scanning-mode +and other options. Unsupported options are disabled. +.PP +The following options are supported by the +.B sane\-sm3600 +backend: +Color, grayscale, halftone and lineart scans. +Also contrast, brightness, and gamma correction. + +.SH "DEVICE NAMES" +This backend does not support device names in a standardized form. + +.SH CONFIGURATION +This backend does not support a configuration file right now. + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-sm3600.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-sm3600.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SM3600 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. To see error messages on stderr set +.B SANE_DEBUG_SM3600 +to 1. + +.br +E.g. just say: +.br +export SANE_DEBUG_SM3600=5 + +.SH "SEE ALSO" +.BR sane (7) , +.BR sane\-microtek (5), +.BR sane\-microtek2 (5) +.br +.I http://sm3600.sourceforge.net + +.SH AUTHOR +.br +Marian Eichholz +.RI < eichholz@computer.org > +.br +Glenn Ramsey +.RI < glenn@componic.com > +.br diff --git a/upstream/fedora-40/man5/sane-sm3840.5 b/upstream/fedora-40/man5/sane-sm3840.5 new file mode 100644 index 00000000..4eb41391 --- /dev/null +++ b/upstream/fedora-40/man5/sane-sm3840.5 @@ -0,0 +1,106 @@ +.TH sane\-sm3840 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-sm3840 +.SH NAME +sane\-sm3840 \- SANE backend for Microtek scanners with SCAN08 USB chip +.SH DESCRIPTION +The +.B sane\-sm3840 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some Microtek scanners with the SCAN08 +USB chip. +.PP +There exist backends for Microtek scanners with SCSI command set. +Refer to +.BR sane\-microtek (5) +and +.BR sane\-microtek2 (5) +for details. +.PP +There also exists a Microtek 3600 series driver, see +.BR sane\-sm3600 (5) +for details. +.PP +At present, the following +scanners are known positively to work with this backend: +.PP +.RS +.ft CR +.nf +Vendor Product ID: Remark: +-------- -------------- ----------- +Microtek ScanMaker 3840 All modes OK +Microtek ScanMaker 4800 All modes OK +.fi +.ft R +.RE +.PP +If you own a Microtek scanner with the SCAN08 chip other than the ones +listed above, it may or may not work with SANE. Feel free to contact the +backend author +.RI ( earle@ziplabel.com ) +to report results with scanners not on the list. + + +.SH "FRONTEND OPTIONS" +.PP +The following options are supported by the +.BR sane\-sm3840 +driver: +.TP +.B \-\-mode color|gray|lineart|halftone +Color or grayscale mode. + +.TP +.B \-\-resolution 150|300|600|1200 +Pixels per inch for scans. + +.TP +.B \-\-depth 8|16 +Note that the least significant bits of 16bpp mode may be noise. + +.TP +.B \-\-brightness 1..4096 +Higher numbers increase brightness of returned image. + +.TP +.B \-\-contrast 0.1..9.9 +Larger numbers decrease contrast of returned image. + +.TP +.B \-\-lamp\-timeout 1..15 +Time in minutes until the lamp is turned off after a scan. + +.SH CONFIGURATION +This backend does not support a configuration file right now. + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-sm3840.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-sm3840.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SM3840 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. To see error messages on stderr set +.B SANE_DEBUG_SM3840 +to 1. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-microtek (5), +.BR sane\-microtek2 (5), +.BR sane\-sm3600 (5) +.br +.I http://www.ziplabel.com/sm3840 + +.SH AUTHOR +Earle F. Philhower III +.RI < earle@ziplabel.com > diff --git a/upstream/fedora-40/man5/sane-snapscan.5 b/upstream/fedora-40/man5/sane-snapscan.5 new file mode 100644 index 00000000..3208637a --- /dev/null +++ b/upstream/fedora-40/man5/sane-snapscan.5 @@ -0,0 +1,122 @@ +.TH sane\-snapscan 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-snapscan +.SH NAME +sane\-snapscan \- SANE backend for AGFA SnapScan flatbed scanners +.SH DESCRIPTION +The +.B sane\-snapscan +library implements a SANE (Scanner Access Now Easy) backend that provides +access to AGFA SnapScan flatbed scanners. At present, the following scanners +are supported from this backend: AGFA SnapScan 300, 310, 600, and 1236s, +1236u, 1212u, e20, e25, +e40, e50, e60, Vuego 310s, Acer 300f, 310s, 610s, 610plus, Prisa 620s, Prisa +620u, Prisa 620ut, Prisa 640u, Prisa 640bu, Prisa 1240, Prisa 3300, Prisa +4300, Prisa 5300 and Guillemot Maxi Scan A4 Deluxe (SCSI) (with +varying success). +.PP + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. For SCSI +scanners, the special device name must be a generic SCSI device or a +symlink to such a device. Under Linux, such a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. +.P +For USB scanners the devicename must contain the keyword "usb", as in +.I /dev/usbscanner +or +.IR /dev/usb/scanner0 . +For scanners that need a firmware upload before scanning add a line starting +with "firmware" followed by the fully qualified path to your firmware file, +e.g. +.PP +.RS +firmware /usr/share/sane/snapscan/firmware.bin +.RE +.PP +For further details read +.IR http://snapscan.sourceforge.net . + +.SH CONFIGURATION +The contents of the +.I snapscan.conf +file is a list of device names that correspond to SnapScan +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. See +.BR sane\-scsi (5) +on details of what constitutes a valid +device name. + +.SH FILES +.TP +.I /etc/sane.d/snapscan.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-snapscan.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-snapscan.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_SNAPSCAN +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 255 requests all debug output to be printed. Smaller +levels reduce verbosity. + + +.SH BUGS +Man page doesn't provide much information yet. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.br +.I http://sourceforge.net/projects/snapscan/ +(new development website) + +.SH AUTHOR +Kevin Charter, Franck Schneider, Michel Roelofs, Emmanuel Blot, +Mikko Tyolajarvi, David Mosberger-Tang, Wolfgang Goeller, +Petter Reinholdtsen, Gary Plewa, Sebastien Sable, Oliver Schwartz +and Mikael Magnusson. +.br +Man page by Henning Meier-Geinitz (mostly based on the web pages and +source code). diff --git a/upstream/fedora-40/man5/sane-sp15c.5 b/upstream/fedora-40/man5/sane-sp15c.5 new file mode 100644 index 00000000..63c30071 --- /dev/null +++ b/upstream/fedora-40/man5/sane-sp15c.5 @@ -0,0 +1,83 @@ +.TH sane\-sp15c 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" + +.SH NAME +sane\-sp15c \- SANE backend for Fujitsu ScanPartner 15C flatbed scanner + +.SH DESCRIPTION +The +.B sane\-sp15c +library implements a SANE (Scanner Access Now Easy) backend which +provides access to the Fujitsu flatbed scanners. +At present, the following +scanner is known to work with these backend: +.PP +.RS +.ft CR +.nf +Vendor: Model: Rev: +-------- ---------------- ----- +FCPA ScanPartner 15C 1.01 +.fi +.ft R +.RE +.P + +The ScanPartner 15C driver supports +lineart (1-bit), halftone (1-bit), +grayscale (4-bit and 8-bit), +and color (3 x 8-bit) scanning. + +Other scanners in these families may work. +The ScanPartner 15C seems to be a repackaging +of the ScanPartner 600C. +People are encouraged to try these driver with the other scanners +and to contact the author with test results. + +.SH CONFIGURATION +A modest effort has been made to expose the standard options to the API. +This allows frontends such as +.BR xscanimage (1) +to set scanning region, +resolution, bit-depth (and color), and enable the automatic document feeder. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR sane\-fujitsu (5), +.BR xscanimage (1) +.br +Fujitsu ScanPartner 15C OEM Manual, Doc. No. 250-0081-0 +.br +Fujitsu M3096G OEM Manual, part number 50FH5028E-05 +.br +Fujitsu M3096GX/M3093GX/M3093DG OEM Manual, part number C150-E015...03 + +.SH AUTHOR +Randolph Bentson +.RI < bentson@holmsjoen.com >, +with credit to the unnamed author of the coolscan driver + +.SH LIMITATIONS +Testing limited to a Linux 2.2.5 kernel +.br +Can't quite get the scan page/minute performance in ADF modes. +This may be due to limited system buffer size. + +.SH BUGS +I'm sure there are plenty, and not too well hidden, +but I haven't seen them yet. +.br +Both scanners claim to have separate control +of resolution in X and Y directions. I confess I haven't tested this yet. +I have found that +.BR xsane (1) +doesn't even display this capability. +.br +Threshold settings on the SP15C don't seem to +affect the results of lineart mode scans. +.br +It might be possible to merge these two drivers without much effort +since the SP15C driver was derived from the M3096G driver. +They were split so as to keep the second driver development from breaking +the working first driver. +Watch this space for changes. diff --git a/upstream/fedora-40/man5/sane-st400.5 b/upstream/fedora-40/man5/sane-st400.5 new file mode 100644 index 00000000..a1ade5f1 --- /dev/null +++ b/upstream/fedora-40/man5/sane-st400.5 @@ -0,0 +1,162 @@ +.TH sane\-st400 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-st400 +.SH NAME +sane\-st400 \- SANE backend for Siemens ST/Highscan flatbed scanners +.SH DESCRIPTION +The +.B sane\-st400 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Siemens ST400 flatbed scanners and compatibles. +At present, the following scanners are supported by this backend: +.PP +.RS +Siemens ST400 (6 bit gray scale) +.br +Siemens ST800 (6 bit gray scale) +.br +.RE +.PP +The driver supports line art and gray scans up to 8bpp. +.PP +The Siemens ST/Highscan series includes several more models, e.g. the ST300 +and ST600. If you own one of these scanners, or a scanner other than the +ones listed above that works with this backend, please let us know by sending +the scanner's model name, SCSI ID, and firmware revision to +.IR sane\-devel@alioth-lists.debian.net . +Have a look at +.I http://www.sane\-project.org/mailing\-lists.html +concerning subscription to sane\-devel. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. For SCSI scanners, the special device name must be a +generic SCSI device or a symlink to such a device. Under Linux, such +a device name could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH CONFIGURATION +The contents of the +.I st400.conf +file is a list of device names that correspond to Siemens +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +/dev/scanner +.br +# this is a comment +.br +/dev/sge +.RE +.PP +The default configuration file that is distributed with SANE looks like +this: +.PP +.RS +scsi SIEMENS "ST 400" Scanner * * 3 0 +.RE +.PP +In this configuration, the driver can only access the ST400 model +at SCSI ID 3 LUN 0 (see section +.B BUGS +below for the reason). +To use the driver with other scanner models, add an appropriate line to +the configuration file. For example, to use it with an ST800 at SCSI +ID 3 LUN 0, add the line: +.PP +.RS +scsi SIEMENS "ST 800" Scanner * * 3 0 +.RE + +.SH FILES +.TP +.I /etc/sane.d/st400.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-st400.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-st400.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_ST400 +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. E.g., a value of 128 +requests all debug output to be printed. Smaller levels reduce verbosity. + +.SH MISSING FUNCTIONALITY + +Everything but the most basic stuff. + +.SH BUGS +Currently, the backend does not check if the attached device really is +a ST400. It will happily accept everything that matches the configuration +entries. This makes it easy to test the backend with other scanners: +Just add an appropriate line to the configuration file. The configuration +file as distributed (see above) only works with the ST400. Be careful: +If there is no config file at all, the backend defaults to +.IR /dev/scanner . +.PP +The ST400 answers on all eight SCSI LUNs. Normally this is not a problem, +as LUN support is usually disabled in SCSI drivers, but if you are seeing +multiple instances of the scanner in a device list, either disable LUNs in +your SCSI setup or change the entry in the configuration file to match +LUN 0 only. + +.SH DEBUG +If you encounter a bug please set the environment variable +.B SANE_DEBUG_ST400 +to 128 and try to regenerate the problem. Then send me a report with the +log attached. +.PP +If you encounter a SCSI bus error or trimmed and/or displaced images please +also set the environment variable +.B SANE_DEBUG_SANEI_SCSI +to 128 before sending me the report. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5) +.br +.I http://www.informatik.uni-oldenburg.de/~ingo/sane/ + +.SH AUTHOR +Ingo Wilken +.RI < Ingo.Wilken@informatik.uni-oldenburg.de > diff --git a/upstream/fedora-40/man5/sane-stv680.5 b/upstream/fedora-40/man5/sane-stv680.5 new file mode 100644 index 00000000..060db32f --- /dev/null +++ b/upstream/fedora-40/man5/sane-stv680.5 @@ -0,0 +1,180 @@ +.TH sane\-stv680 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-stv680 +.SH NAME +sane\-stv680 \- SANE backend for STV680 camera's +.SH DESCRIPTION +The +.B sane\-stv680 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some STV680 cameras. This backend +should be considered +.B beta-quality +software! STV680 cameras are sold under +various brands like Aiptek. +This backend may or may not support yours. +.PP +The cameras that should work with this backend are: +.PP +.ft CR +.nf +Vendor Model USB vendor id USB product id status +------------------------ ------------- -------------- -------- +AIPTEK stv680 0x0553 0x0202 basic +Konica e-mini 0x04c8 0x0722 untested +DigitalDream l'espion XS 0x1183 0x0001 untested +Creative WebCam Go mini 0x041e 0x4007 untested +.fi +.ft R + +For all these cameras, see the backend home page (under AUTHOR) +for the exact status of each camera. + +For startup of this backend check that if present the stv680 kernel module is +removed or disabled. +.br +Also before using, enable the backend by editing the +.I /etc/sane.d/dll.conf +file, change #stv680 to stv680. + +For problems with the untested cameras, you should contact the author for that. + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI elements in +.BR xcam (1). +For both programs use the +.B \-B +option needed for size buffer. + +Some frontends examples: + +.br +.BR xcam (1) +.RS +xcam \-B +.RE + +.BR scanimage (1): +for writing in batch mode to a file or to a new file each time: + +.RS +scanimage \-B \-d stv680:libusb:001:002 \-\-batch=out.ppm \-\-batch-count 5 \-\-mode "Color RGB" +.RE +.RS +scanimage \-B \-d stv680:libusb:001:002 \-\-batch=out%d.ppm \-\-batch-count 5 \-\-mode "Color RGB" +.RE + +.br +If you have any success with a camera not listed here, or if you observe +any strange behavior, please report to the backend maintainer or to +the SANE mailing list. + +Valid command line options and their syntax can be listed by using: + +.RS +scanimage \-\-help \-d stv680 +.RE + + +.TP +.B Scan Mode + +.TP +.B \-\-mode +selects the basic mode of operation of the webcams valid choices. + +The read resolution mode is 8 bits, output resolution is 24 bits. +Selects the resolution for a scan. +The camera can do only the resolutions listed. +.TP +.B \-\-Raw +In this mode raw data is displayed +.TP +.B \-\-Color +In this mode the bayer unshuffle is done but no color correction +.TP +.B \-\-Color_RGB +Bayer unshuffle, color correction +.TP +.B \-\-Color_RGB_TXT +Bayer unshuffle, color correction, textline with date and time is added + + +.TP +.B Enhancement options + +.TP +.B \-\-white\-level\-r \-32..+32 +Selects what red radiance level should be +considered "white", when scanning some sheets by changing the calibration +value loaded into the scanner. Scale \-32 .. 0 .. +32 in steps of 1. + +.TP +.B \-\-white\-level\-g \-32..+32 +Selects what green radiance level should be +considered "white", when scanning some sheets by changing the calibration i +value loaded into the scanner. Scale \-32 .. 0 .. +32 in steps of 1. + +.TP +.B \-\-white\-level\-b \-32..+32 +Selects what blue radiance level should be +considered "white", when scanning some sheets by changing the calibration +value loaded into the scanner. Scale \-32 .. 0 .. +32 in steps of 1. + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/stv680.conf +supports only one item: the device name to use (eg usb 0x.... 0x....). + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-stv680.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-stv680.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_STV680 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller levels +reduce verbosity. + +.SH LIMITATIONS +The windows TWAIN driver has many more options than this SANE +backend. However they are only software adjustments. This backend only +implements what the webcam can support. + +.SH BUGS +.TP +Plenty. Parts of this backend are still under development. +1. Some untested cameras. +.br +2. Video streaming slow and stops sometimes (scanimage). +.br +3. Sometimes 1/3 of image is NOK (xcam). + + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR scanimage (1), +.BR xcam (1) + +.SH AUTHORS +Gerard Klaver +.I http://gkall.hobby.nl/stv680-aiptek.html + +.SH CREDITS +.TP +Thanks to developers of the other stv680 programs: +STV680 kernel module +.br +pencam2 program +.br +.BR libghoto2 (3) +program (camlib stv0680) diff --git a/upstream/fedora-40/man5/sane-tamarack.5 b/upstream/fedora-40/man5/sane-tamarack.5 new file mode 100644 index 00000000..2a0b4049 --- /dev/null +++ b/upstream/fedora-40/man5/sane-tamarack.5 @@ -0,0 +1,91 @@ +.TH sane\-tamarack 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-tamarack +.SH NAME +sane\-tamarack \- SANE backend for Tamarack flatbed scanners +.SH DESCRIPTION +The +.B sane\-tamarack +library implements a SANE (Scanner Access Now Easy) backend that +provides access to the following Tamarack flatbed scanners: +.PP +.RS +Artiscan 6000C +.br +Artiscan 8000C +.br +Artiscan 12000C +.br +.RE +.PP +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the path-name for the special device that corresponds to a +SCSI scanner. The special device name must be a generic SCSI device or a +symlink to such a device. The program +.BR sane\-find\-scanner (1) +helps to find out the correct device. Under Linux, such a device name +could be +.I /dev/sga +or +.IR /dev/sge , +for example. See +.BR sane\-scsi (5) +for details. + +.SH FILES +.TP +.I /etc/sane.d/tamarack.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-tamarack.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-tamarack.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR "tmp/config" , +.IR "." , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_TAMARACK +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_TAMARACK=4 + +.SH "SEE ALSO" +.BR sane (7) , +.BR sane\-find\-scanner (1), +.BR sane\-scsi (5) + +.SH AUTHOR +Roger Wolff diff --git a/upstream/fedora-40/man5/sane-teco1.5 b/upstream/fedora-40/man5/sane-teco1.5 new file mode 100644 index 00000000..0761fbe2 --- /dev/null +++ b/upstream/fedora-40/man5/sane-teco1.5 @@ -0,0 +1,201 @@ +.TH sane\-teco1 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-teco1 +.SH NAME +sane\-teco1 \- SANE backend for TECO / RELISYS scanners +.SH DESCRIPTION +The +.B sane\-teco1 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some TECO SCSI flatbed scanners. This backend +should be considered +.B beta-quality +software! TECO scanners are sold under +various brands like RELISYS, PIOTECH, TRUST. This backend may or +may not support yours. +.PP +The scanners that should work with this backend are: +.PP +.RS +.ft CR +.nf + Vendor Model TECO model status +---------------------- -------------- ----------- + Relisys AVEC 2400 VM3520 tested + Relisys AVEC 2412 VM3520+ tested + Relisys AVEC 4800 VM4530 untested + Relisys AVEC 4816 VM4530+ untested + Relisys RELI 2400 VM3530 untested + Relisys RELI 2412 VM3530+ tested + Relisys RELI 2412 VM3530+ untested + Relisys RELI 4816 VM4540 tested + Relisys RELI 4830 VM4542 tested + Relisys RELI 9600 VM6530 untested + Relisys RELI 9612 VM6530* untested + Relisys RELI 9624 VM6530+ untested + Relisys RELI 9630 VM6540 untested + Relisys RELI DS15 VM3440 untested + Relisys RELI DS6 VM3420 untested + Dextra DF-600P VM3510 tested + Dextra DF-4830T VM4542 untested + Dextra DF-1200T+ VM3530+ untested + Dextra DF-9624 VM6530+ untested +.fi +.ft R +.RE + +Note that the untested scanner will not be directly supported. You +should contact the author for that. + +The TECO VM number can usually be found at the back of the scanner. It +is also part of the FCC ID. +.I sane\-find\-scanner \-v +will also show the +SCSI inquiry, and if it is a TECO scanner, the name will be there too. + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI +elements in +.BR xscanimage (1) +or +.BR xsane (1). + +.br +If you have any success with a scanner not listed here, or if you notice +any strange behavior, please report to the backend maintainer or to +the SANE mailing list. + +Valid command line options and their syntax can be listed by using: + +.RS +scanimage \-\-help \-d teco1 +.RE + +.TP +.B Scan Mode + +.TP +.B \-\-mode Black & White|Grayscale|Color +Selects the basic mode of operation of the scanner. Valid choices are +.IR "Black & White" , +.I "Grayscale" +and +.IR Color . + +The +.I Black & White +mode is for black and white only (1 bit). +.I Grayscale +will produce 256 levels of gray (8 bits). +.I Color +will produce a 24 bit color image. + +.TP +.B \-\-resolution 1..600 +Selects the resolution for a scan. The scanner can do all resolutions +between 1 and 600, in increments of 1. + + +.TP +.B Geometry options + +.TP +.B \-l \-t \-x \-y +Controls the scan area: +.B \-l +sets the top left x coordinate, +.B \-t +the top left y coordinate, +.B \-x +selects the width and +.B \-y +the height of the scan area. All parameters are specified in millimeters by default. + + +.TP +.B Enhancement options + +.TP +.B \-\-custom\-gamma +(color mode only) allows the user to specify a gamma table (see the +next 3 parameters). + +.TP +.B \-\-red\-gamma\-table +Can be used to download a user defined gamma table for the red channel. +The table must be 256 bytes long. Color mode only. + +.TP +.B \-\-green\-gamma\-table +Can be used to download a user defined gamma table for the green channel. +The table must be 256 bytes long. Color mode only. + +.TP +.B \-\-blue\-gamma\-table +Can be used to download a user defined gamma table for the blue channel. +The table must be 256 bytes long. Color mode only. + +.TP +.B \-\-dither Line art|2x2|3x3|4x4 bayer|4x4 smooth|8x8 bayer|8x8 smooth|8x8 horizontal|8x8 vertical +Select the dither mask to use. Black & White only. + + +.TP +.B \-\-preview +Requests a preview scan. The resolution used is 22 dpi +and the scan area is the maximum allowed. The scan mode is user +selected. The default is "no". + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/teco1.conf +supports only one item: the device name to use (eg +.IR /dev/scanner ). + + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-teco1.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-teco1.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_TECO1 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller levels +reduce verbosity. + + +.SH LIMITATIONS +The windows TWAIN driver has many more options than this SANE +backend. However they are only software adjustments. This backend only +implements what the scanner can support. + + +.SH BUGS +None known. + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + +.SH AUTHOR +.TP +The package is actively maintained by Frank Zago. +.I http://www.zago.net/sane/#teco + +.SH CREDITS + +Thanks to Gerard Delafond for the VM4542 support. +Thanks to Jean-Yves Simon for the VM3510 support. diff --git a/upstream/fedora-40/man5/sane-teco2.5 b/upstream/fedora-40/man5/sane-teco2.5 new file mode 100644 index 00000000..5574f097 --- /dev/null +++ b/upstream/fedora-40/man5/sane-teco2.5 @@ -0,0 +1,257 @@ +.TH sane\-teco2 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-teco2 +.SH NAME +sane\-teco2 \- SANE backend for TECO / RELISYS scanners +.SH DESCRIPTION +The +.B sane\-teco2 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some TECO SCSI flatbed scanners. This backend +should be considered +.B beta-quality +software! TECO scanners are sold under +various brands like Mustek, Relisys, Piotech, Primax, TRUST. +This backend may or may not support yours. +.PP +The scanners that should work with this backend are: +.PP +.RS +.ft CR +.nf + Vendor Model TECO model status +--------------------------- -------------- ----------- + Mustek ScanMagic 4830S VM3575 untested + Primax Jewel 4800 VM356A good + Primax Profi 9600 VM6575 basic + Primax Profi 19200 VM6586 good + Relisys APOLLO Express 3 VM356A basic + Relisys APOLLO Express 6 VM6565 good + Relisys APOLLO Express 12 ? untested + Relisys AVEC II S3 VM3564 good + Relisys AVEC Super 3 VM3575 basic + Relisys SCORPIO Pro VM6575 good + Relisys SCORPIO Pro-S VM6586 untested + Relisys SCORPIO Super 3 VM3575 good +.fi +.ft R +.RE + +For all these scanners, lineart and gray mode work +well. However, most of them do not support more than a handful of +resolutions in color mode. See the backend home page (under AUTHOR) +for the exact status of each scanner. + +Note that the untested scanner will not be directly supported. You +should contact the author for that. + +The TECO VM number can usually be found at the back of the +scanner. It is also part of the FCC ID. + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI +elements in +.BR xscanimage (1), +.BR xsane (1), +.BR quiteinsane (1) +or +.BR kooka (1). + +.br +If you have any success with a scanner not listed here, or if you notice +any strange behavior, please report to the backend maintainer or to +the SANE mailing list. + +.SH OPTIONS +Valid command line options and their syntax can be listed by using: + +.RS +scanimage \-\-help \-d teco2 +.RE + +.TP +.B Scan Mode + +.TP +.B \-\-mode Lineart|Gray|Color +selects the basic mode of operation of the scanner. +The +.I Lineart +mode is black and white only (1 bit). +.I Gray +mode will produce 256 levels of gray (8 bits). +.I Color +will produce a 24 bits color image. + +.TP +.B \-\-resolution 1..600 +Selects the resolution for a scan. The scanner can do all resolutions +between 1 and 600, in increments of 1, for +.IR Lineart " and " Gray . +For +.IR Color , +a restricted set of resolutions are available. + +.B Note: +All values with ydpi > 300 (300 x 600) or 600 (600 x 1200) result in +a wrong proportion for the scan. The proportion can be adjusted with +the following +.BR convert (1) +command from imagemagick: +.br +.I convert \-geometry (dpi/max_xdpi * 100%)x100% +.br +max_xdpi is for the vm3575 constant with 300 dpi +e.g. 600dpi adjust with: convert \-geometry 200%x100% + +.TP +.B \-\-preview +requests a preview scan. The resolution used for that scan is 50 dpi +(for VM356A and VM6575 75 dpi) and the scan area is the maximum allowed. +The scan mode is user selected. The default is "no". + +.TP +.B Geometry options + +.TP +.B \-l, \-t, \-x, " \-y +Control the scan area: +.B \-l +sets the top left x coordinate, +.B \-t +the top left y coordinate, +.B \-x +selects the width and +.B \-y +the height of the scan area. All parameters are specified in millimeters by default. + + +.TP +.B Enhancement options + +.TP +.B \-\-custom\-gamma (no custom gamma option for the VM3564 and VM356A) +(color mode only) allows the user to specify a gamma table (see the +next 3 parameters). + +.SH OPTIONS FOR COLOR MODE +These options are valid for scan mode +.I Color +only. + +.TP +.B \-\-red\-gamma\-table +Can be used to download a user defined +gamma table for the red channel. The table must be 256 bytes long. + +.TP +.B \-\-green\-gamma\-table +Can be used to download a user defined +gamma table for the green channel. The table must be 256 bytes long. + +.TP +.B \-\-blue\-gamma\-table +Can be used to download a user defined gamma table +for the blue channel. The table must be 256 bytes long. + +.SH OPTIONS ONLY FOR VM3564, VM356A, VM3575 and VM6575 +These options are only available for VM3564, VM356A, VM3575 and VM6575 models. +.TP +.B \-\-white\-level\-r 0..64 +Selects what red radiance level should be +considered "white", when scanning some sheets by changing the calibration +value loaded into the scanner. Scale 0..64 in steps of 1. + +.TP +.B \-\-white\-level\-g 0..64 +Selects what green radiance level should be +considered "white", when scanning some sheets by changing the calibration +value loaded into the scanner. Scale 0..64 in steps of 1. + +.TP +.B \-\-white\-level\-b 0..64 +Selects what blue radiance level should be +considered "white", when scanning some sheets by changing the calibration +value loaded into the scanner. Scale 0..64 in steps of 1. + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/teco2.conf +supports only one item: the device name to use (eg +.IR /dev/scanner ). + + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-teco2.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-teco2.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_TECO2 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller levels +reduce verbosity. +.TP +.B SANE_TECO2_CAL_ALGO +Either 0 or 1. Selects the algorithm for the calibration. A +value of 1 seems to give better scans on the VM356A, VM3575. +Feedback on it is welcome. +For VM3564, VM356A, VM3575, VM6575 default 1. +For other supported types default 0. + + +.SH LIMITATIONS +The windows TWAIN driver has many more options than this SANE +backend. However they are only software adjustments. This backend only +implements what the scanner can support. + + +.SH BUGS +Plenty. Parts of this backend are still under development. + + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1) + + +.SH AUTHORS +.TP +Frank Zago +.I http://www.zago.net/sane/#teco2 +.TP +The package is actively maintained by Gerard Klaver. +.I http://gkall.hobby.nl/teco2.html + + + + +.SH CREDITS + +Thanks to: +.TP +Gerard Klaver for his relentless VM3575 testings and contributed a patch to support the VM3564 and VM356A. +.TP +Mark Plowman for providing the first SCSI traces from a VM3575. +.TP +Andreas Klaedtke for providing the first SCSI traces from a VM6586 and for his testing, and to Stefan von Dombrowski for his testing. +.TP +Nicolas Peyresaubes for providing the first SCSI traces from a VM656A and for his testing. +.TP +Dave Parker for testing the support for the VM6575. +.TP +Michael Hoeller for testing the support for the VM356A. +.TP +Christoph Hoeffner for testing the support for the VM3564 (Relisys AVEC II S3 firmware 1.09). diff --git a/upstream/fedora-40/man5/sane-teco3.5 b/upstream/fedora-40/man5/sane-teco3.5 new file mode 100644 index 00000000..44264b4a --- /dev/null +++ b/upstream/fedora-40/man5/sane-teco3.5 @@ -0,0 +1,168 @@ +.TH sane\-teco3 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-teco3 +.SH NAME +sane\-teco3 \- SANE backend for TECO / RELISYS scanners +.SH DESCRIPTION +The +.B sane\-teco3 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to some TECO SCSI flatbed scanners. This backend +should be considered +.B alpha-quality +software! TECO scanners are sold under +various brands like RELYSIS, PIOTECH, TRUST. This backend may or +may not support yours. +.PP +The scanners that should work with this backend are: +.PP +.RS +.ft CR +.nf + Vendor Model TECO model status + --------------------------- ---------- ---------- + Relisys Scorpio VM3552 tested + Plustek OpticPro 2400SP VM3552 untested + PIOTECH Splendeur 3024 VM3552 tested + Trust Imagery 2400 SP VM3552 tested + Trust Imagery 4800 SP+ VM3552 tested + Trust Imagery 9600 SP VM3552 untested +.fi +.ft R +.RE + +The TECO VM number can usually be found at the back of the +scanner. It is also part of the FCC ID. + +The options the backend supports can either be selected through +command line options to programs like +.BR scanimage (1) +or through GUI +elements in +.BR xscanimage (1) +or +.BR xsane (1). + +.br +If you have any success with a scanner not listed here, or if you notice +any strange behavior, please report to the backend maintainer or to +the SANE mailing list. + +.SH OPTIONS +Valid command line options and their syntax can be listed by using: + +.RS +scanimage \-\-help \-d teco3 +.RE + +.TP +.B Scan Mode + +.TP +.B \-\-mode Black & White|Grayscale|Color +Selects the basic mode of operation of the scanner. +The +.I Black & White +mode is black and white only (1 bit). +.I Grayscale +will produce 256 levels of gray (8 bits). +.I Color +will produce a 24-bit color image. + +.TP +.B \-\-resolution 1..1200 +Selects the resolution for a scan. The scanner can do all resolutions +between 1 and 1200, in increments of 1. + +.TP +.B \-\-preview +Requests a preview scan. The resolution used for that scan is 22 dpi +and the scan area is the maximum allowed. The scan mode is user +selected. The default is "no". + +.TP +.B Geometry options + +.TP +.B \-l \-t \-x \-y +Control the scan area: +.B \-l +sets the top left x coordinate, +.B \-t +the top left y coordinate, +.B \-x +selects the width and +.B \-y +the height of the scan area. +All parameters are specified in millimeters by default. + +.SH OPTIONS FOR COLOR MODE ONLY + +.TP +.B \-\-custom\-gamma +Allows the user to specify a gamma table (see the +next 3 parameters). + +.TP +.B \-\-red\-gamma\-table +Can be used to download a user defined +gamma table for the red channel. The table must be 1024 bytes long. + +.TP +.B \-\-green\-gamma\-table +Can be used to download a user defined +gamma table for the green channel. The table must be 1024 bytes long. + +.TP +.B \-\-blue\-gamma\-table +Can be used to download a user defined gamma table +for the blue channel. The table must be 1024 bytes long. + + +.SH CONFIGURATION FILE +The configuration file +.I /etc/sane.d/teco3.conf +supports only one item: the device name to use (eg +.IR /dev/scanner ). + + +.SH FILES +.TP +.I /usr/lib64/sane/libsane\-teco3.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-teco3.so +The shared library implementing this backend (present on systems that +support dynamic loading). + + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_TECO3 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller levels +reduce verbosity. + + +.SH LIMITATIONS +The windows TWAIN driver has many more options than this SANE +backend. However they are only software adjustments. This backend only +implements what the scanner can support. + + +.SH BUGS +Not much. + + +.SH "SEE ALSO" +.BR sane\-scsi (5), +.BR scanimage (1), +.BR xscanimage (1), +.BR xsane (1), +.BR sane (7) + + +.SH AUTHOR +.TP +The package is actively maintained by Frank Zago. +.I http://www.zago.net/sane/#teco3 diff --git a/upstream/fedora-40/man5/sane-test.5 b/upstream/fedora-40/man5/sane-test.5 new file mode 100644 index 00000000..c78f346d --- /dev/null +++ b/upstream/fedora-40/man5/sane-test.5 @@ -0,0 +1,351 @@ +.TH sane\-test 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-test +.SH NAME +sane\-test \- SANE backend for testing frontends +.SH DESCRIPTION +The +.B sane\-test +library implements a SANE (Scanner Access Now Easy) backend that allows +testing the SANE installation and SANE frontends. It provides access to a +(nearly) unlimited number of virtual devices. There is no support for real +scanners or cameras. However, the backend simulates scanning and setting +options. +.PP +The idea is not only to find bugs in frontends but also to show all +capabilities of SANE. Therefore +.B sane\-test +implements functions and options that are not (or seldom) found in other +backends. +.PP +The backend is commented out in +.IR /etc/sane.d/dll.conf , +so either the comment +character must be removed or the backend must be called explicitly. E.g. +.I scanimage \-d test +or +.IR "xscanimage test" . + + +.SH SCAN MODE OPTIONS +Option +.B mode +selects the scan mode (Gray or Color). +.PP +Option +.B depth +determines the number of bits per sample (1. 8, or 16). Keep in mind, that +this value refers to the sample, not the pixel. So depth=16 results in 48 +bits per pixel in color mode. The most usual combinations are mode=Gray, +depth=1 for lineart, mode=Gray, depth=8 for gray and mode=Color, depth=8 for +color mode. The combination of color and 1-bit mode is quite obscure (8 +colors) but allowed in the SANE standard. However, the meaning of bits is not +defined. Currently 1 = high intensity and 0 = low intensity is used. +.PP +Setting option +.B hand\-scanner +results in the test-backend behaving like a hand-scanner. Hand-scanners do +not know the image height a priori. Instead, they return a height of \-1. +Setting this option allows one to test whether a frontend can handle this +correctly. This option also enables a fixed width of 11 cm. +.PP +Setting option +.B three\-pass +simulates a three-pass scanner. Older color scanners needed to scan the image +once per color (red/green/blue) to get the full image. Therefore, in this mode +three single frames are transmitted in color mode. +.PP +Option +.B three\-pass\-order +provides support for changing the order of the three frames (see option +three-pass above). A frontend should support all orders. +.PP +Option +.B resolution +sets the resolution of the image in dots per inch. +.PP +.PP +Option +.B source +can be used to simulate an Automatic Document Feeder (ADF). After 10 scans, the +ADF will be "empty". +.PP + +.SH SPECIAL OPTIONS +Option +.B test\-picture +allows one to set the image that's returned to the frontend. While "Solid white" +and "Solid black" are quite obvious, the other options need some more +explanation. Color patterns are used to determine if all modes and their +colors are represented correctly by the frontend. The grid should look like the +same in every mode and resolution. A table of all the test pictures can be +found at: +.IR http://www.meier\-geinitz.de/sane/test\-backend/test\-pictures.html . +.PP +If option +.B invert\-endianness +is set, the upper and lower bytes of image data in 16 bit modes are exchanged. +This option can be used to test the 16 bit modes of frontends, e.g. if the +frontend uses the correct endianness. +.PP +If option +.B read\-limit +is set, the maximum amount of data transferred with each call to +.BR sane_read () +is limited. +.PP +Option +.B read\-limit\-size +sets the limit for option read-limit. A low limit slows down scanning. It +can be used to detect errors in frontend that occur because of wrong +assumptions on the size of the buffer or timing problems. +.PP +Option +.B read\-delay +enables delaying data to the frontend. +.PP +Option +.B read\-delay\-duration +selects the number of microseconds the backends waits after each transfer of a +buffer. This option is useful to find timing-related bugs, especially if +used over the network. +.PP +If option +.B read\-return\-value +is different from "Default", the selected status will be returned by every +call to +.BR sane_read (). +This is useful to test the frontend's handling of the SANE statuses. +.PP +If option +.B ppl\-loss +is different from 0, it determines the number of pixels that are "lost" at the +end of each line. That means, lines are padded with unused data. +.PP +Option +.B fuzzy\-parameters +selects that fuzzy (inexact) parameters are returned as long as the scan +hasn't been started. This option can be used to test if the frontend uses the +parameters it got before the start of the scan (which it shouldn't). +.PP +Option +.B non\-blocking +determines if non-blocking IO for +.BR sane_read () +should be used if supported by the frontend. +.PP +If option +.B select\-fd +is set, the backend offers a select filedescriptor for detecting if +.BR sane_read() +will return data. +.PP +If option +.B enable\-test\-options +is set, a fairly big list of options for testing the various SANE option +types is enabled. +.PP +Option +.B print\-options +can be used to print a list of all options to standard error. +.PP + +.SH GEOMETRY OPTIONS +Option +.B tl\-x +determines the top-left x position of the scan area. +.PP +Option +.B tl\-y +determines the top-left y position of the scan area. +.PP +Option +.B br\-x +determines the bottom-right x position of the scan area. +.PP +Option +.B br\-y +determines the bottom-right y position of the scan area. +.PP + +.SH BOOL TEST OPTIONS +There are 6 bool test options in total. Each option is numbered. (3/6) +means: this is option 3 of 6. The numbering scheme is intended for easier +detection of options not displayed by the frontend (because of missing support +or bugs). +.PP +Option +.B bool\-soft\-select\-soft\-detect +(1/6) is a bool test option that has soft select and soft detect (and +advanced) capabilities. That's just a normal bool option. +.PP +Option +.B bool\-hard\-select\-soft\-detect +(2/6) is a bool test option that has hard select and soft detect (and +advanced) capabilities. That means the option can't be set by the frontend +but by the user (e.g. by pressing a button at the device). +.PP +Option +.B bool\-hard\-select +(3/6) is a bool test option that has hard select (and advanced) capabilities. +That means the option can't be set by the frontend but by the user (e.g. by +pressing a button at the device) and can't be read by the frontend. +.PP +Option +.B bool\-soft\-detect +(4/6) is a bool test option that has soft detect (and advanced) +capabilities. That means the option is read-only. +.PP +Option +.B bool\-soft\-select\-soft\-detect\-emulated +(5/6) is a Bool test option that has soft select, soft detect, and emulated +(and advanced) capabilities. +.PP +Option +.B bool\-soft\-select\-soft\-detect\-auto +(6/6) is a Bool test option that has soft select, soft detect, and automatic +(and advanced) capabilities. This option can be automatically set by the +backend. +.PP + +.SH INT TEST OPTIONS +There are 7 int test options in total. +.PP +Option +.B int +(1/7) is an int test option with no unit and no constraint set. +.PP +Option +.B int\-constraint\-range +(2/7) is an int test option with unit pixel and constraint range set. Minimum +is 4, maximum 192, and quant is 2. +.PP +Option +.B int\-constraint\-word\-list +(3/7) is an int test option with unit bits and constraint word list set. +.PP +Option +.B int\-constraint\-array +(4/7) is an int test option with unit mm and using an array without +constraints. +.PP +Option +.B int\-constraint\-array\-constraint\-range +(5/7) is an int test option with unit mm and using an array with a range +constraint. Minimum is 4, maximum 192, and quant is 2. +.PP +Option +.B int\-constraint\-array\-constraint\-word\-list +(6/7) is an int test option with unit percent and using an array a word list +constraint. +.PP +Option +.B int\-inexact +(7/7) is an int test option that increments the requested value and returns +flag SANE_INFO_INEXACT. + + +.SH FIXED TEST OPTIONS +There are 3 fixed test options in total. +.PP +Option +.B fixed +(1/3) is a fixed test option with no unit and no constraint set. +.PP +Option +.B fixed\-constraint\-range +(2/3) is a fixed test option with unit microsecond and constraint range +set. Minimum is \-42.17, maximum 32767.9999, and quant is 2.0. +.PP +Option +.B fixed\-constraint\-word\-list +(3/3) is a Fixed test option with no unit and constraint word list set. +.PP + +.SH STRING TEST OPTIONS +There are 3 string test options in total. +.PP +Option +.B string +(1/3) is a string test option without constraint. +.PP +Option +.B string\-constraint\-string\-list +(2/3) is a string test option with string list constraint. +.PP +Option +.B string\-constraint\-long\-string\-list +(3/3) is a string test option with string list constraint. Contains some more +entries... +.PP + +.SH BUTTON TEST OPTION +Option +.B button +(1/1) is a Button test option. Prints some text... +.PP + +.SH FILES +.TP +.I /etc/sane.d/test.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). The initial values of most of the basic SANE options can be configured +in this file. A template containing all the default values is provided +together with this backend. One of the more interesting values may be +.BR number_of_devices . +It can be used to check the frontend's ability to show a long list of devices. +The config values concerning resolution and geometry can be useful to test +the handling of big file sizes. + +.TP +.I /usr/lib64/sane/libsane\-test.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-test.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I "/etc/sane.d" +being searched (in this order). +.TP +.B SANE_DEBUG_TEST +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_TEST=4 + +.SH "SEE ALSO" +.BR sane (7), +.BR scanimage (1), +.BR xscanimage (1) +.br +.IR http://www.meier\-geinitz.de/sane/test\-backend/ + + +.SH AUTHOR +Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > + +.SH BUGS +\- config file values aren't tested for correctness diff --git a/upstream/fedora-40/man5/sane-u12.5 b/upstream/fedora-40/man5/sane-u12.5 new file mode 100644 index 00000000..fa66b59a --- /dev/null +++ b/upstream/fedora-40/man5/sane-u12.5 @@ -0,0 +1,192 @@ +.TH sane\-u12 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-u12 +.SH NAME +sane\-u12 \- SANE backend for Plustek USB flatbed scanners, +based on older parport designs +.SH DESCRIPTION +The +.B sane\-u12 +library implements a SANE (Scanner Access Now Easy) backend that +provides access to USB flatbed scanners based on Plusteks' ASIC +98003 (parallel-port ASIC) and a GeneSys Logics' USB-parport +bridge chip. + +.SH "SUPPORTED DEVICES" +The backend is able to support some early Plustek USB scanners that based +their old parport design around the ASIC 98003 and other rebadged +Plustek devices. The following tables will give you a short overview. + +If your Plustek scanner has another Product ID, then the device is +.B NOT +supported by this backend. +.br + +Vendor Plustek \- ID: 0x07B3 +.br +.ft CR +.nf +---------------------------------------------------------- +Model: Vendor-ID: Product-ID: +---------------------------------------------------------- +OpticPro U12 0x07B3 0x0001 +OpticPro U1212 0x07B3 0x0001 +OpticPro UT12 0x07B3 0x0001 +.fi +.ft R +.PP + +Vendor KYE/Genius +.br +.ft CR +.nf +-------------------------------------------------------- +USB Model: Vendor-ID: Product-ID: +-------------------------------------------------------- +ColorPage Vivid III USB 0x07B3 0x0001 +ColorPage HR6 V1 0x0458 0x2004 +.fi +.ft R +.PP + +.SH "CONFIGURATION" +To use your scanner with this backend, you need at least two +entries in the configuration file +.I /etc/sane.d/u12.conf + +.RS +.I [usb] vendor-id product-id +.br +.I device /dev/usbscanner +.RE +.PP +.I [usb] +tells the backend, that the following devicename (here +.IR /dev/usbscanner ) +has to be interpreted as USB scanner device. If vendor- and +product-id has not been specified, the backend tries to +detect this by its own. If device is set to +.I auto +then the next matching device is used. +.PP +.B +The Options: +.PP +option warmup t +.RS +.I t +specifies the warmup period in seconds +.RE +.PP +option lampOff t +.RS +.I t +is the time in seconds for switching off the lamps in +standby mode +.RE +.PP +option lOffonEnd b +.RS +.I b +specifies the behaviour when closing the backend, 1 --> switch +lamps off, 0 --> do not change lamp status +.RE + +.PP +See the +.I u12.conf +file for examples. +.PP +.B Note: +You have to make sure, that the USB subsystem is loaded +correctly and you have access to the device-node. For +more details see +.BR sane\-usb (5) +manpage. You might use +.BR sane\-find\-scanner (1) +to check that you have access to your device. +.PP +.B Note: +.br +If there's no configuration file, the backend defaults to +.B device auto + +.SH FILES +.TP +.I /etc/sane.d/u12.conf +The backend configuration file +.TP +.I /usr/lib64/sane/libsane\-u12.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-u12.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_U12 +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_U12=10 + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5), +.BR sane\-plustek (5), +.BR sane\-find\-scanner (1), +.BR xscanimage (1), +.BR scanimage (1) +.br +.I /usr/share/doc/sane-backends/u12/U12.changes + +.SH "CONTACT AND BUG-REPORTS" +Please send any information and bug-reports to: +.br +.B SANE Mailing List +.PP +Additional info and hints can be obtained from our +.br +Mailing-List archive at: +.br +.I http://www.sane\-project.org/mailing\-lists.html +.PP +To obtain debug messages from the backend, please set the +environment-variable +.B SANE_DEBUG_U12 +before calling your favorite scan-frontend (i.e. +.BR xscanimage (1)), +i.e.: + +.br +.I export SANE_DEBUG_U12=20 ; xscanimage +.PP +The value controls the verbosity of the backend. + +.SH "KNOWN BUGS & RESTRICTIONS" +* The driver is in alpha state, so please don't expect too much!!! +.PP +* When using libusb, it might be, that the backend hangs. +In that case, reconnect the scanner. diff --git a/upstream/fedora-40/man5/sane-umax.5 b/upstream/fedora-40/man5/sane-umax.5 new file mode 100644 index 00000000..bc9b8364 --- /dev/null +++ b/upstream/fedora-40/man5/sane-umax.5 @@ -0,0 +1,284 @@ +.TH sane\-umax 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-umax + +.SH NAME +sane\-umax \- SANE backend for UMAX scanners + +.SH ABOUT THIS FILE + +This file is only a brief description of the +.B sane\-umax +backend for SANE! For detailed information take a look at +sane\-umax\-doc.html (it is included in the sane source directory and in the +.BR xsane (1) +online help)! + +.SH DESCRIPTION + +The +.B sane\-umax +library implements a SANE backend that provides access to several UMAX-SCSI-scanners and some Linotype Hell SCSI-scanners, +parallel- and USB-scanners are not (and probably will never be) supported! + +.B I suggest you hold one hand on the power-button of the scanner while you try the first scans! + +.SH CONFIGURATION + +The configuration file for this backend resides in +.IR /etc/sane.d/umax.conf . + +Its contents is a list of device names that correspond to UMAX and UMAX compatible scanners. Empty lines +and lines starting with a hash mark (#) are ignored. A sample configuration file is +shown below: + +.nf + # this is a comment + # + option scsi\-maxqueue 4 + option scsi\-buffer\-size\-min 65536 + option scsi\-buffer\-size\-max 131072 + option scan\-lines 40 + option preview\-lines 10 + option scsi\-maxqueue 2 + option execute\-request\-sense 0 + option force\-preview\-bit\-rgb 0 + option slow\-speed \-1 + option care\-about\-smearing \-1 + option calibration\-full\-ccd \-1 + option calibration\-width\-offset \-1 + option calibration\-bytes\-pixel \-1 + option exposure\-time\-rgb\-bind \-1 + option invert\-shading\-data \-1 + option lamp\-control\-available 0 + option gamma\-lsb\-padded 0 + /dev/sge +\ + #scsi Vendor Model Type Bus Channel ID LUN + # The following scanner supports lamp control + option lamp\-control\-available 1 + scsi UMAX * Scanner * * * * * +\ + # scanner on /dev/scanner does not support lamp control + option lamp\-control\-available 0 + /dev/scanner +.fi + +.TP +execute\-request\-sense: +values: 0 = disabled, 1 = enabled +.br +default = 0 +.br +If set to 1, +.BR umax_do_request_sense () +is called in +.BR umax_do_calibration (). +This can hang the system, but has been enabled until this version. +.TP +scsi\-buffer\-size\-min, scsi\-buffer\-size\-max: +values: 4096-1048576 +.br +default min = 32768, max = 131072 +.br +Especially the minimum value is very important. +If this value is set too small the backend is not +able to send gamma tables to the scanner or to +do a correct color calibration. This may result in +strange color effects. If the minimum value is set +too large then the backend is not able to allocate +the requested SCSI buffer size and aborts with +out of memory error. The default is 32KB, for +some scanners it should be increased to 64KB. +.TP +scan\-lines, preview\-lines: +values: 1-65535 +.br +default: scan\-lines = 40, preview\-lines = 10 +.br +define the maximum number of lines that are scanned +into one buffer +.TP +force\-preview\-bit\-rgb: +values: +0 = disabled, +1 = enabled +.br +default = 0 +.br +set preview bit in rgb real scan +.TP +slow\-speed, care\-about\-smearing: +values: +\-1 = auto, +0 = disabled, +1 = enabled +.br +default = \-1 +.br +Dangerous options, needed for some scanners. +.br +Do not change these options unless you really know +what you are doing otherwise you may destroy your scanner +with invalid values. +.TP +calibration\-full\-ccd: +values: +\-1 = auto, +0 = disabled, +1 = enabled +.br +default = \-1 +.br +do calibration for each pixel of ccd instead of +selected image +.TP +calibration\-width\-offset: +values: \-99999 = auto, > \-99999 set value +.br +add an offset to the calculated width for image/ccd +.TP +calibration\-bytes\-pixel: +values: +\-1 = disabled, +0 = not set, +1 = 1 byte/pixel, +2 = 2 bytes/pixel +.br +use # bytes per pixel for calibration +.TP +exposure\-time\-rgb\-bind: +values: +\-1 = automatically set by driver \- if known, +0 = disabled (own selection for red, green and blue), +1 = enabled (same values for red, green and blue) +.TP +invert\-shading\-data: +values: +\-1 = automatically set by driver \- if known, +0 = disabled, +1 = enabled +.br +default = \-1 +.br +invert shading data before sending it back to the scanner +.TP +lamp\-control\-available: +values: +0 = automatically set by driver \- if known, +1 = available +.br +default = 0 +.TP +gamma\-lsb\-padded: +values: +\-1 = automatically set by driver \- if known, +0 = gamma data is msb padded, +1 = gamma data is lsb padded +.br +default = \-1 +.TP +handle\-bad\-sense\-error: +values: +0 = handle as device busy, +1 = handle as ok, +2 = handle as i/o error, +3 = ignore bad error code \- continue sense handler +.br +default = 0 +.TP +scsi\-maxqueue: +values: +1..# (maximum defined at compile time) +.br +default = 2 +.br +most SCSI drivers allow internal command queueing with a depth +of 2 commands. In most cases it does not improve anything when you +increase this value. When your SCSI driver does not support any +command queueing you can try to set this value to 1. + +.PP +The special device name must be a generic SCSI device or a symlink to such a device. +To find out to which device your scanner is assigned and how you have to set the +permissions of that device, have a look at +.BR sane\-scsi (5). + +.SH SCSI ADAPTER TIPS + +The ISA-SCSI-adapters that are shipped with some UMAX-scanners are not supported very +well by Linux (I suggest not to use it), the PCI-SCSI-adapters that come with some +UMAX-scanners are not supported at all (as far as I know). On other platforms these +SCSI-adapters are not supported. So you typically need to purchase another SCSI-adapter +that is supported by your platform. See the relevant hardware FAQs and HOWTOs for your +platform for more information. + +The UMAX-scanners do block the SCSI-bus for a few seconds while scanning. It is not +necessary to connect the scanner to its own SCSI-adapter. But if you need short +response time for your SCSI-harddisk (e.g. if your computer is a file-server) or +other SCSI devices, I suggest you use an own SCSI-adapter for your UMAX-scanner. + +If you have any problems with your UMAX scanner, check your SCSI chain +(cable length, termination, ...). + +See also: +.BR sane\-scsi (5) + +.SH FILES + +.TP +The backend configuration file: +.I /etc/sane.d/umax.conf +.TP +The static library implementing this backend: +.I /usr/lib64/sane/libsane\-umax.a +.TP +The shared library implementing this backend: +.I /usr/lib64/sane/libsane\-umax.so +(present on systems that support dynamic loading) + +.SH ENVIRONMENT + +.TP +.B SANE_DEBUG_UMAX +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. E.g., a value of 128 +requests all debug output to be printed. Smaller levels reduce verbosity. +.B SANE_DEBUG_UMAX +values: + +.ft CR +.nf +Number Remark +\ + 0 print important errors (printed each time) + 1 print errors + 2 print sense + 3 print warnings + 4 print scanner-inquiry + 5 print information + 6 print less important information + 7 print called procedures + 8 print reader_process messages + 10 print called sane\-init-routines + 11 print called sane\-procedures + 12 print sane infos + 13 print sane option-control messages +.fi +.ft R + +.TP +Example: +export SANE_DEBUG_UMAX=8 + +.SH BUGS +X-resolutions greater than 600 dpi sometimes cause problems. + +.SH SEE ALSO +.BR sane (7), +.BR sane\-scsi (5) + +.SH AUTHOR +Oliver Rauch + +.SH EMAIL-CONTACT +.I Oliver.Rauch@Rauch-Domain.DE diff --git a/upstream/fedora-40/man5/sane-umax1220u.5 b/upstream/fedora-40/man5/sane-umax1220u.5 new file mode 100644 index 00000000..52445727 --- /dev/null +++ b/upstream/fedora-40/man5/sane-umax1220u.5 @@ -0,0 +1,120 @@ +.TH sane\-umax1220u 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-umax +.SH NAME +sane\-umax1220u \- SANE backend for the UMAX Astra 1220U and similar scanners + +.SH DESCRIPTION + +The +.B sane\-umax1220 +library implements a SANE (Scanner Access Now Easy) backend for the +the UMAX Astra 1220U and similar scanners. + +For more information on this backend, please visit +.IR http://umax1220u\-sane.sourceforge.net/ . + +.SH UMAX ASTRA 1600U/2000U/2100U SUPPORT + +This backend is also able to drive the UMAX Astra 1600U/2000U/2100U. The +2100U is confirmed to work. For the other scanners no reports have been received +yet. Please contact us and tell us if your scanner works +.RI ( sane\-devel@alioth-lists.debian.net ). + +.SH CONFIGURATION + +Usually, no manual configuration is necessary. The configuration file for this backend resides in +.IR /etc/sane.d/umax1220u.conf . + +Its content is a list of device names that correspond to UMAX Astra scanners. +Empty lines and lines starting with a hash mark (#) are ignored. A sample +configuration file is shown below: + +.nf + #usb vendor product + usb 0x1606 0x0010 + # Device list for non-linux systems + /dev/scanner + /dev/usb/scanner0 +.fi + +See +.BR sane\-usb (5) +for information on how to set the access permissions on the usb device files. + +.SH FILES + +.TP +The backend configuration file: +.I /etc/sane.d/umax1220u.conf +.TP +The static library implementing this backend: +.I /usr/lib64/sane/libsane\-umax1220u.a +.TP +The shared library implementing this backend: +.I /usr/lib64/sane/libsane\-umax1220u.so +(present on systems that support dynamic loading) + +.SH ENVIRONMENT + +.TP +.B SANE_DEBUG_UMAX1220U +If the library was compiled with debug support enabled, this environment +variable controls the debug level for this backend. E.g., a value of 128 +requests all debug output to be printed. Smaller levels reduce verbosity: + +.B SANE_DEBUG_UMAX1220U +values: + +.ft CR +.nf +Number Remark +\ + 1 print failures + 2 print information + 3 print high-level function calls + 4 print high-level function checkpoints + 9 print mid-level function calls + 10 print mid-level function checkpoints + 80 print protocol-level function entry + 90 print protocol-level function exit +.fi +.ft R + +.TP +Example: +export SANE_DEBUG_UMAX1220U=10 + +.SH KNOWN BUGS + +600 dpi scanning may fail for large image sizes. + +If you keep getting I/O errors, try cycling the power on your scanner to reset it. + +There is no way to cancel a scan, since the driver ignores +.BR sane_cancel (). + +If you try scanning an image which is too small, you will get I/O errors. Be +sure to adjust the scan area before doing a scan, since by default, the scan +area is zero. + +.SH SEE ALSO +.BR sane (7), +.BR sane\-usb (5) + +.TP +(Old) homepage: +.I http://umax1220u\-sane.sourceforge.net/ + +.SH AUTHOR +Marcio Luis Teixeira +.RI < marciot@users.sourceforge.net > + +.SH EMAIL-CONTACT +.I sane\-devel@alioth-lists.debian.net + +.SH REPORTING BUGS +This backend isn't actively maintained. Nevertheless, bug reports and comments +should be sent to the sane\-devel mailing list. When reporting bugs, please run +the backend with +.B SANE_DEBUG_UMAX1220U +set to 10 and attach a copy of the log messages. diff --git a/upstream/fedora-40/man5/sane-umax_pp.5 b/upstream/fedora-40/man5/sane-umax_pp.5 new file mode 100644 index 00000000..c49d4199 --- /dev/null +++ b/upstream/fedora-40/man5/sane-umax_pp.5 @@ -0,0 +1,332 @@ +.TH "sane\-umax_pp" "5" "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-umax_pp +.SH "NAME" +sane\-umax_pp \- SANE backend for Umax Astra parallel port flatbed scanners +.SH "DESCRIPTION" +The +.B sane\-umax_pp +library implements a SANE (Scanner Access Now Easy) backend that +provides access to Umax parallel port flatbed scanners. The +following scanners work with this backend: +.PP +.RS +Model: +.br +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.br +Astra 610P +.br +Astra 1220P +.br +HP3200C +.br +Astra 1600P +.br +Astra 2000P +.br +Genius ColorPage-Life Pro +.br +.RE +.PP +This backend handles 75x75, 150x150, 300x300, 600x600 and 600x1200 for 1220P/1600P/2000P +dpi scan resolutions, and 75x75, 150x150, 300x300 and 300x600 for 610P. In color and gray +levels, there is a software lineart mode. +.PP +The new generation models share a newer version of the 610P ASIC embedded in an EPAT chip. +Only parts such as CCD and ADC change from +one to another. They even all reports being UMAX Astra 1220P via IEEE1284. +There isn't a software method to recognize them properly. Under windows, model is +set by the driver installed, regardless of the hardware. +.PP +.TP +.B EPP/ECP MODES ONLY +The current version of the backend uses only EPP or ECP mode to communicate +with the scanner. PS/2 mode isn't implemented. The 610P only use SPP. It is +recommended that you set your parallel port to EPP in BIOS with the current +version of this +backend. You can leave it to ECP or ECP+EPP, but in this case you may not use +ppdev but only direct hardware access if you have to use ECP. ECPEPP will only +work if you use a 2.4 or 2.6 kernel with ppdev character device support. +.PP +This backend does support parport sharing only +.I +if you have a kernel with ppdev support. +.I +.PP +Note that if you don't use the ppdev character device, the backend +needs to run as root. To allow user access to the scanner +run the backend through the network interface (See +.BR saned (8) +and +.BR sane\-net (5)). +A more relaxed solution (security wise) is to add suid bit to the frontend +(See +.BR chmod (1)). +The backend drop root privileges as soon as it can, right after gaining direct +access to IO ports, which lessen risks when being root. + +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I port value +.RE +.PP +Where +\fBvalue\fR is : + +.RS +.TP +auto +autodetect all parallel ports and probe +them for scanner +.TP +safe\-auto +autodetect all parallel ports and probe +them for scanner, but does not try direct +hardware access +.TP +.I /dev/ppi0 +uses *BSD ppi device, depending on the +number of available parallel port, you +have to use +.IR /dev/ppi1 , +.IR /dev/ppi2 ", ..." +.TP +.I /dev/parport0 +uses Linux ppdev device, depending on the +number of available parallel port, you +have to use +.IR /dev/parport1 , +.IR /dev/parport2 ", ..." +.TP +0x378 +does direct hardware access on the given +address. Usual values are 0x378, 0x278, 0x3BC +In this case, you have to run the scanner as +root (*BSD and Linux), or with 'IOPL=yes' on +OS/2 +.PP +.RE +\fBNOTE:\fR in all cases, you must have sufficient privileges +to get access to the chosen device or address. Depending on the +security settings, devices may not be available for all users. +You have to change permissions on the +.I /dev/ppi* +or +.I /dev/parport* +devices. +.PP +.RE +You can rename any device using the +.PP +.RS +.I name devname +.br +.I model model +.br +.I vendor vendor +.RE +.PP +options. These options apply to the last port option. + +.SH "CONFIGURATION" +Please make sure to edit +.I umax_pp.conf +.B before +you use the backend. +.PP +The contents of the +.I umax_pp.conf +file is a list of options and device names that correspond to Umax +scanners. Empty lines and lines starting with a hash mark (#) are +ignored. +.PP +The eight options supported are +.BR red\-gain , +.BR green\-gain , +.BR blue\-gain , +.BR red\-offset , +.BR green\-offset , +.BR blue\-offset , +.BR astra , +and +.BR buffer . + +Options +.BR red\-gain , +.B green\-gain +and +.B blue\-gain +allow you to adjust the sensitivity of your scanner for the given color. Values +range from 0 (lowest gain) to 15 (highest). If the advanced option "Gain" isn't +checked in the frontend, the backend does automatic gain calibration, and do not use +user provided values. + +.PP + +Options +.B red\-offset +, +.B green\-offset +and +.B blue\-offset +allow you to adjust the offset of your scanner for the given color. Values +range from 0 (lowest offset) to 15 (highest). +.PP + +Option +.B astra +allows you to change the model of your scanner. Current auto detection is based +on side effects on scanning when using 1220P command set on other models, so +it may fail on unknown hardware combination. Valid values are 610, 1220, 1600 +and 2000. It is useful only when autodetection fails to detect properly +your scanner model. If your scanner work properly but is reported wrongly, +let it be that way. +The only valid case to change the model is when your scanner produces "black" or +"inverted" scans. In this case you can put the model. Be aware that it will +prevent scanner model autodetection. +.PP + +Option +.B buffer +allows you to change the size of the scan buffer. The size must be specified in +bytes. The default value is 2 megabytes. Decreasing this value will improve the +smoothness of progress bar in the frontend, but will stall the +scan more often. + +.PP + + + +.SH "FILES" +.TP +.I /etc/sane.d/umax_pp.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-umax_pp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-umax_pp.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH "ENVIRONMENT" +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_UMAX_PP +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. + +.PP +.RS +.ft CR +.nf +level debug output +\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0 nothing + 1 errors + 2 warnings & minor errors + 3 additional information + 4 debug information + 5 code flow (not supported yet) + 6 special debug information +.fi +.ft R +.RE +.PP +.TP +.B SANE_DEBUG_UMAX_PP_LOW +This variable sets the debug level for the SANE interface for the Umax +ASIC. Note that enabling this will spam your terminal with some +million lines of debug output. + +.PP +.RS +.ft CR +.nf +level debug output +\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0 nothing + 1 errors + 8 command blocks + 16 detailed code flow + 32 dump datafiles + 255 everything +.fi +.ft R +.RE +.PP + +.PP +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-net (5), +.BR saned (8) + +.TP +For latest bug fixes and information see +.I http://umax1220p.sourceforge.net/ + +.SH "AUTHOR" +St\['e]phane Voltz +.RI < stef.dev@free.fr > + +.SH "CREDITS" +Support for the 610P has been made possible thank to an hardware donation +by William Stuart. + +.SH "BUG REPORTS" +If something doesn't work, please contact me. But I need some information about +your scanner to be able to help you... + +.TP +.I SANE version +Run +.I "scanimage \-V" +to determine this +.TP +.I the backend version and your scanner hardware +Run +.I "SANE_DEBUG_UMAX_PP=255 scanimage \-L 2>log" +as root. If you don't get any output +from the +.B sane\-umax_pp +backend, make sure a line "umax_pp" is included into your +.I /etc/sane.d/dll.conf +file. +If your scanner isn't detected, make sure you've defined the right port address, or the +correct device +in your +.I umax_pp.conf +file. +.TP +.I the name of your scanner/vendor +also a worthy information. Please also include the optical resolution and lamp type of your scanner, both can be found in the manual of your scanner. +.TP +.I any further comments +if you have comments about the documentation (what could be done better), or you +think I should know something, please include it. diff --git a/upstream/fedora-40/man5/sane-usb.5 b/upstream/fedora-40/man5/sane-usb.5 new file mode 100644 index 00000000..ca2eecb7 --- /dev/null +++ b/upstream/fedora-40/man5/sane-usb.5 @@ -0,0 +1,186 @@ +.TH sane\-usb 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-usb +.SH NAME +sane\-usb \- USB configuration tips for SANE +.SH DESCRIPTION +This manual page contains information on how to access scanners with a USB +interface. It focuses on two main topics: getting the scanner detected by the +operating system kernel and using it with SANE. +.PP +This page applies to USB most backends and scanners, as they use the generic +sanei_usb interface. However, there is one exception: USB Scanners +supported by the +.BR sane\-microtek2 (5) +backend need a special USB kernel driver. + +.SH "QUICK START" +This is a short HOWTO-like section. For the full details, read the following +sections. The goal of this section is to get the scanner detected by +.BR sane\-find\-scanner (1). +.PP +Run +.BR sane\-find\-scanner (1). +If it lists your scanner with the correct vendor and +product ids, you are done. See section +.B "SANE ISSUES" +for details on how to go on. +.PP +.BR sane\-find\-scanner (1) +doesn't list your scanner? Does it work as root? If yes, there is a permission issue. +See the +.B LIBUSB +section for details. +.PP +Nothing is found even as root? Check that your kernel supports USB and that +libusb is installed (see section +.BR LIBUSB ). + +.SH "USB ACCESS METHODS" +For accessing USB devices, the USB library libusb is used. There used to exist +another method to access USB devices: the kernel scanner driver. The kernel +scanner driver method is deprecated and shouldn't be used anymore. It may be +removed from SANE at any time. In Linux, the kernel scanner driver has been +removed in the 2.6.* kernel series. Only libusb access is documented in this +manual page. + +.SH LIBUSB +SANE can only use libusb 0.1.6 or newer. It needs to be installed at +build-time. Modern Linux distributions and other operating systems come with +libusb. +.PP +Libusb can only access your scanner if it's not claimed by the kernel scanner +driver. If you want to use libusb, unload the kernel driver (e.g. rmmod +scanner under Linux) or disable the driver when compiling a new kernel. For +Linux, your kernel needs support for the USB filesystem (usbfs). For kernels +older than 2.4.19, replace "usbfs" with "usbdevfs" because the name has +changed. This filesystem must be mounted. That's done automatically at boot +time, if /etc/fstab contains a line like this: +.PP +.RS +none /proc/bus/usb usbfs defaults 0 0 +.RE +.PP +The permissions for the device files used by libusb must be adjusted for user +access. Otherwise only root can use SANE devices. For +.IR Linux , +the devices are located in +.I /proc/bus/usb/ +or in +.IR /dev/bus/usb , +if you use +udev. There are directories named e.g. "001" (the bus name) containing files +"001", "002" etc. (the device files). The right device files can be found out by +running: +.I "scanimage \-L: +as root. Setting permissions with +.BR chmod (1) +is not permanent, however. They will be reset after reboot or replugging the scanner. +.PP +Usually +.BR udev (7) +or for older distributions the hotplug utilities are used, which +support dynamic setting of access permissions. SANE comes with udev and hotplug +scripts in the directory +.I tools/udev +and +.IR tools/hotplug . +They can be used for setting permissions, see +.IR /usr/share/doc/sane-backends/README.linux , +.IR tools/README +and the +.I README +in the +.I tools/hotplug +directory for more details. +.PP +For the +.BR BSDs , +the device files used by libusb are named +.IR /dev/ugen* . +Use chmod to apply appropriate permissions. + +.SH "SANE ISSUES" +.PP +This section assumes that your scanner is detected by +.BR sane\-find\-scanner (1). +It doesn't make sense to go on, if this is not the case. While +.BR sane\-find\-scanner (1) +is able to detect any USB scanner, actual scanning will only work if the +scanner is supported by a SANE backend. Information on the level of support +can be found on the SANE webpage +.RI ( http://www.sane\-project.org/ ), +and the individual backend manpages. +.PP +Most backends can detect USB scanners automatically using "usb" configuration +file lines. This method allows one to identify scanners by the USB vendor and +product numbers. The syntax for specifying a scanner this way is: +.PP +.RS +usb +.I VENDOR PRODUCT +.RE +.PP +where +.I VENDOR +is the USB vendor id, and +.I PRODUCT +is the USB product id of the scanner. Both ids are non-negative integer numbers +in decimal or hexadecimal format. The correct values for these fields can be +found by running +.BR sane\-find\-scanner (1), +looking into the syslog (e.g., +.IR /var/log/messages ) +or under Linux by issuing the command +.IR "cat /proc/bus/usb/devices" . +This is an example of a config file line: +.PP +.RS +usb 0x055f 0x0006 +.RE +.PP +would have the effect that all USB devices in the system with a vendor id of +0x55f and a product id of 0x0006 would be probed and recognized by the +backend. +.PP +If your scanner is not detected automatically, it may be necessary to edit the +appropriate backend configuration file before using SANE for the first time. +For a detailed description of each backend's configuration file, please refer to +the relevant backend manual page (e.g. +.BR sane\-mustek_usb (5) +for Mustek USB scanners). +.PP +Do +.B not +create a symlink from +.I /dev/scanner +to the USB device because this link is used by the SCSI backends. The scanner +may be confused if it receives SCSI commands. + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SANEI_USB +If the library was compiled with debug support enabled, this +environment variable controls the debug level for the USB I/O +subsystem. E.g., a value of 128 requests all debug output to be +printed. Smaller levels reduce verbosity. Values greater than 4 enable +libusb debugging (if available). Example: +.IR "export SANE_DEBUG_SANEI_USB=4" . +.PP +.TP +.B SANE_USB_WORKAROUND +If your scanner does not work when plugged into a USB3 port, try +setting the environment variable +.B SANE_USB_WORKAROUND +to 1. This may work around issues which happen with particular kernel +versions. Example: +.I export SANE_USB_WORKAROUND=1. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-find\-scanner (1), +.BR sane\-"backendname" (5), +.BR sane\-scsi (5) + +.SH AUTHOR +Henning Meier-Geinitz +.RI < henning@meier\-geinitz.de > diff --git a/upstream/fedora-40/man5/sane-v4l.5 b/upstream/fedora-40/man5/sane-v4l.5 new file mode 100644 index 00000000..a6629e5e --- /dev/null +++ b/upstream/fedora-40/man5/sane-v4l.5 @@ -0,0 +1,100 @@ +.TH sane\-v4l 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-v4l +.SH NAME +sane\-v4l \- SANE interface for Video for Linux API +.SH DESCRIPTION +The +.B sane\-v4l +library implements a SANE (Scanner Access Now Easy) backend that +provides generic access to video cameras and similar equipment using +the V4L (Video for Linux) API. +.PP +This is ALPHA software. Really! Important features are missing and there are +lots of bugs. The code is currently only tested on a Linux 2.4 system with a +Hauppauge WinTV video card. +.PP +.SH "DEVICE NAMES" +This backend expects device names of the form: +.PP +.RS +.I special +.RE +.PP +Where +.I special +is the UNIX path-name for the special device that corresponds to the +v4l device. The special device name must be a v4l device or a symlink +to such a device. For example, such a device name could be +.I /dev/video0 +or +.IR /dev/bttv0 . +.SH CONFIGURATION +The contents of the +.I v4l.conf +file is a list of device names that correspond to v4l +devices. Empty lines and lines starting with a hash mark (#) are +ignored. A sample configuration file is shown below: +.PP +.RS +/dev/bttv0 +.br +# this is a comment +.br +/dev/video3 +.RE +.SH FILES +.TP +.I /etc/sane.d/v4l.conf +The backend configuration file (see also description of +.B SANE_CONFIG_DIR +below). +.TP +.I /usr/lib64/sane/libsane\-v4l.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-v4l.so +The shared library implementing this backend (present on systems that +support dynamic loading). +.SH ENVIRONMENT +.TP +.B SANE_CONFIG_DIR +This environment variable specifies the list of directories that may +contain the configuration file. On *NIX systems, the directories are +separated by a colon (`:'), under OS/2, they are separated by a +semi-colon (`;'). If this variable is not set, the configuration file +is searched in two default directories: first, the current working +directory (".") and then in +.IR /etc/sane.d . +If the value of the +environment variable ends with the directory separator character, then +the default directories are searched after the explicitly specified +directories. For example, setting +.B SANE_CONFIG_DIR +to "/tmp/config:" would result in directories +.IR tmp/config , +.IR . , +and +.I /etc/sane.d +being searched (in this order). +.TP +.B SANE_DEBUG_V4L +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. E.g., +a value of 128 requests all debug output to be printed. Smaller +levels reduce verbosity. +.SH AUTHOR +Juergen G. Schimmer, Henning Meier-Geinitz + +.SH BUGS: +If more than one video card is present, a crash may occur. Frequency and geometry +selection is missing. +.br +Send bug reports to the SANE mailing list: +.IR sane\-devel@alioth-lists.debian.net . +You must be subscribed to the list to send mail. See +.I http://www.sane\-project.org/mailing\-lists.html +for details. + +.SH SEE ALSO +.BR sane (7), +.BR xcam (1) diff --git a/upstream/fedora-40/man5/sane-xerox_mfp.5 b/upstream/fedora-40/man5/sane-xerox_mfp.5 new file mode 100644 index 00000000..37891491 --- /dev/null +++ b/upstream/fedora-40/man5/sane-xerox_mfp.5 @@ -0,0 +1,76 @@ +.TH sane\-xerox_mfp 5 "15 Dec 2008" "" "SANE Scanner Access Now Easy" +.IX sane\-xerox_mfp +.SH NAME +sane\-xerox_mfp \- SANE backend for Xerox Phaser 3200MFP device et al. +.SH DESCRIPTION +The +.B sane\-xerox_mfp +library implements a SANE (Scanner Access Now Easy) backend that provides +access to several Samsung-based Samsung, Xerox, and Dell scanners. +Please see full list of supported devices at +.IR http://www.sane\-project.org/sane\-supported\-devices.html . + +.SH CONFIGURATION +.TP +.I /etc/sane.d/xerox_mfp.conf +USB scanners do not need any configuration. + +For SCX\-4500W in network mode you need to specify +.PP +.RS +.B tcp host_address [port] +.RE +.PP +The +.B host_address +is passed through resolver, thus can be a dotted quad or a name from +.I /etc/hosts +or resolvable through DNS. +.SH FILES +.TP +.I /etc/sane.d/xerox_mfp.conf +The backend configuration file. By default all scanner types/models are enabled, you +may want to comment out unwanted entries. +.TP +.I /usr/lib64/sane/libsane\-xerox_mfp.a +The static library implementing this backend. +.TP +.I /usr/lib64/sane/libsane\-xerox_mfp.so +The shared library implementing this backend (present on systems that +support dynamic loading). + +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_XEROX_MFP +If the library was compiled with debug support enabled, this +environment variable controls the debug level for this backend. Higher +debug levels increase the verbosity of the output. + +Example: +export SANE_DEBUG_XEROX_MFP=4 + +.SH LIMITATIONS +Multicast autoconfiguration for LAN scanners is not implemented yet. IPv6 addressing has never been tested. + +.SH BUGS AND SUPPORT +If you have found a bug or need support please follow open\-source way of acquiring support via +mail\-lists +.I http://www.sane\-project.org/mailing\-lists.html +or SANE bug tracker +.IR http://www.sane\-project.org/bugs.html . + +.SH AUTHORS +Alex Belkin +.RI < abc@telekom.ru >. +.br +Samsung SCX\-4500W scan over network support by +Alexander Kuznetsov +.RI < acca(at)cpan.org >. +.br +Color scanning on Samsung M2870 model and Xerox Cognac 3215 & 3225 models by +Laxmeesh Onkar Markod +.RI < m.laxmeesh@samsung.com >. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-usb (5) diff --git a/upstream/fedora-40/man5/scr_dump.5 b/upstream/fedora-40/man5/scr_dump.5 new file mode 100644 index 00000000..505fca52 --- /dev/null +++ b/upstream/fedora-40/man5/scr_dump.5 @@ -0,0 +1,476 @@ +.\"*************************************************************************** +.\" Copyright 2018-2021,2023 Thomas E. Dickey * +.\" Copyright 2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp $ +.TH scr_dump 5 2023-12-30 "ncurses 6.4" "File formats" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +scr_dump \- +\fIcurses\fR screen dump +.\"SH SYNOPSIS +.SH DESCRIPTION +The curses library provides applications with the ability to write the +contents of a window to an external file using \fBscr_dump\fP or \fBputwin\fP, +and read it back using \fBscr_restore\fP or \fBgetwin\fP. +.PP +The \fBputwin\fP and \fBgetwin\fP functions do the work; +while \fBscr_dump\fP and \fBscr_restore\fP conveniently save and restore +the whole screen, i.e., \fBstdscr\fP. +.SS ncurses6 +A longstanding implementation of screen-dump was +revised with ncurses6 to remedy problems with the earlier approach: +.IP \(bu 4 +A \*(``magic number\*('' is written to the beginning of the dump file, +allowing applications (such as \fBfile\fP(1)) to recognize curses dump files. +.IP +Because ncurses6 uses a new format, +that requires a new magic number +was unused by other applications. +This 16-bit number was unused: +.RS 4 +.PP +.RS 4 +.EX +0x8888 (octal \*(``\e210\e210\*('') +.EE +.RE +.PP +but to be more certain, this 32-bit number was chosen: +.PP +.RS 4 +.EX +0x88888888 (octal \*(``\e210\e210\e210\e210\*('') +.EE +.RE +.PP +This is the pattern submitted to the maintainers of the \fBfile\fP program: +.PP +.RS 4 +.EX +# +# ncurses5 (and before) did not use a magic number, +# making screen dumps "data". +# +# ncurses6 (2015) uses this format, ignoring byte-order +0 string \e210\e210\e210\e210ncurses ncurses6 screen image +# +.EE +.RE +.RE +.bP +The screen dumps are written in textual form, +so that internal data sizes are not directly related to the dump-format, and +enabling the library to read dumps from either narrow- or wide-character- +configurations. +.IP +The \fInarrow\fP library configuration holds characters and video attributes +in a 32-bit \fBchtype\fP, while the \fIwide-character\fP library stores +this information in the \fBcchar_t\fP structure, which is much larger than +32-bits. +.bP +It is possible to read a screen dump into a terminal with a different +screen-size, +because the library truncates or fills the screen as necessary. +.bP +The ncurses6 \fBgetwin\fP reads the legacy screen dumps from ncurses5. +.SS "ncurses5 (Legacy)" +The screen-dump feature was added to \fI\%ncurses\fP in June 1995. +While there were fixes and improvements in succeeding years, +the basic scheme was unchanged: +.bP +The \fI\%WINDOW\fP structure was written in binary form. +.bP +The \fI\%WINDOW\fP structure refers to lines of data, +which were written as an array of binary data following the \fI\%WINDOW\fP. +.bP +When \fBgetwin\fP restored the window, +it would keep track of offsets into the array of line-data +and adjust the \fI\%WINDOW\fP structure which was read back into memory. +.PP +This is similar to Unix System\ V, +but does not write a \*(``magic number\*('' to identify the file format. +.SH PORTABILITY +There is no standard format for +.I curses +screen dumps. +A brief survey of the existing implementations follows. +.SS "X/Open Curses" +X/Open Curses, Issue 7 specifies little. +It says +(boldface emphasis added) +.RS 3 +.PP +\*(``[t]he \fI\%getwin()\fP function reads window-related data stored in +the file by \fI\%putwin()\fP. +The function then creates and initializes a new window using that data. +.PP +The \fI\%putwin()\fP function writes all data associated with \fIwin\fP +into the \fI\%stdio\fP stream to which \fIfilep\fP points, +using an \fBunspecified format\fP. +This information can be retrieved later using \fI\%getwin()\fP.\*('' +.RE +.PP +In the mid-1990s when the X/Open Curses document was written, +there were still System\ V systems using older, +less capable +.I curses +libraries. +BSD +.I curses +was not relevant to X/Open because it did not meet the criteria +for base-level conformance; +see \fB\%ncurses\fP(3X). +.SS "System V" +System\ V +.I curses +identified the file format by writing a \*(``magic number\*('' at the +beginning of the dump. +The \fI\%WINDOW\fP data and the lines of text follow, all in binary form. +.PP +Solaris +.I curses +has the following definitions. +.PP +.RS 4 +.EX +/* terminfo magic number */ +#define MAGNUM 0432 + +/* curses screen dump magic number */ +#define SVR2_DUMP_MAGIC_NUMBER 0433 +#define SVR3_DUMP_MAGIC_NUMBER 0434 +.EE +.RE +.PP +That is, the feature was likely introduced in SVr2 (1984), +and improved in SVr3 (1987). +Solaris +.I curses +has no magic number for SVr4 (1989). +Other System\ V operating systems +(AIX and HP-UX) +use a magic number that would correspond to the following. +.PP +.RS 4 +.EX +/* curses screen dump magic number */ +#define SVR4_DUMP_MAGIC_NUMBER 0435 +.EE +.RE +.PP +That octal number in bytes is 001, 035. +Because most Unix vendors at the time used big-endian hardware, +the magic number is written with the high-order byte first. +.PP +.RS 4 +.EX +\e001\e035 +.EE +.RE +.PP +After the magic number, +the \fI\%WINDOW\fP structure and line data are written in binary format. +While the magic number used by these systems can be observed with +\fIod\fP(1), +none of them documents the format used for screen dumps. +.PP +Nor do they use an identical format, +even with the System\ V family. +The +.I \%ncurses +.I \%savescreen +test program was used to collect information for this manual page. +It produced dumps of different size +(all on 64-bit hardware, +on 40x80 screens): +.bP +AIX (51817 bytes) +.bP +HP-UX (90093 bytes) +.bP +Solaris 10 (13273 bytes) +.bP +\fI\%ncurses\fP5 (12888 bytes) +.SS Solaris +As noted above, +Solaris +.I curses +has no magic number corresponding to SVr4 +.I curses. +This is odd, +since Solaris was the first operating system to meet the SVr4 +guidelines. +Solaris furthermore supplies two versions of +.I curses. +.bP +The default +.I curses +library uses the SVr3 magic number. +.bP +An alternate +.I curses +library +(which we term +.I \%xcurses), +available in +.I /usr/xpg4, +uses a textual format with no magic number. +.IP +According to its copyright notice, +this +.I \%xcurses +library was developed by MKS +(Mortice Kern Systems) from 1990 to 1995. +.IP +Like ncurses6, +it includes a header with parameters. +Unlike ncurses6, +the contents of the window are written piecemeal, +with coordinates and attributes for each chunk of text rather than +writing the whole window from top to bottom. +.SS PDCurses +.I \%PDCurses +added support for screen dumps in version 2.7 (2005). +Like System\ V and ncurses5, +it writes the \fI\%WINDOW\fP structure in binary, +but begins the file with its three-byte identifier \*(``PDC\*('', +followed by a single-byte version number. +.PP +.RS 4 +.EX + \*(``PDC\e001\*('' +.EE +.RE +.SS NetBSD +As of April 2017, +NetBSD +.I curses +does not support \fB\%scr_dump\fP and \fB\%scr_restore\fP +(or \fB\%scr_init\fP, +\fB\%scr_set\fP), +although it has \fB\%putwin\fP and \fB\%getwin\fP. +.PP +Like ncurses5, +NetBSD \fB\%putwin\fP does not identify its dumps with a useful magic +number. +It writes +.bP +the +.I curses +shared library major and minor versions as the first two bytes +(for example, +7 and 1), +.bP +followed by a binary dump of the \fI\%WINDOW\fP, +.bP +some data for wide characters referenced by the \fI\%WINDOW\fP +structure, +and +.bP +finally, +lines as done by other implementations. +.SH EXAMPLES +Given a simple program which writes text to the screen +(and for the sake of example, limiting the screen-size to 10x20): +.PP +.RS 4 +.EX +#include + +int +main(void) +{ + putenv("LINES=10"); + putenv("COLUMNS=20"); + initscr(); + start_color(); + init_pair(1, COLOR_WHITE, COLOR_BLUE); + init_pair(2, COLOR_RED, COLOR_BLACK); + bkgd(COLOR_PAIR(1)); + move(4, 5); + attron(A_BOLD); + addstr("Hello"); + move(5, 5); + attroff(A_BOLD); + attrset(A_REVERSE | COLOR_PAIR(2)); + addstr("World!"); + refresh(); + scr_dump("foo.out"); + endwin(); + return 0; +} +.EE +.RE +.PP +When run using ncurses6, the output looks like this: +.PP +.RS 4 +.EX +\e210\e210\e210\e210ncurses 6.0.20170415 +_cury=5 +_curx=11 +_maxy=9 +_maxx=19 +_flags=14 +_attrs=\e{REVERSE|C2} +flag=_idcok +_delay=-1 +_regbottom=9 +_bkgrnd=\e{NORMAL|C1}\es +rows: +1:\e{NORMAL|C1}\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +2:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +3:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +4:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +5:\es\es\es\es\es\e{BOLD}Hello\e{NORMAL}\es\es\es\es\es\es\es\es\es\es +6:\es\es\es\es\es\e{REVERSE|C2}World!\e{NORMAL|C1}\es\es\es\es\es\es\es\es\es +7:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +8:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +9:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +10:\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es\es +.EE +.RE +.PP +The first four octal escapes are actually nonprinting characters, +while the remainder of the file is printable text. +You may notice: +.bP +The actual color pair values are not written to the file. +.bP +All characters are shown in printable form; spaces are \*(``\es\*('' to +ensure they are not overlooked. +.bP +Attributes are written in escaped curly braces, e.g., \*(``\e{BOLD}\*('', +and may include a color pair (C1 or C2 in this example). +.bP +The parameters in the header are written out only if they are nonzero. +When reading back, order does not matter. +.ne 10 +.PP +Running the same program with Solaris \fIxpg4\fP curses gives this dump: +.PP +.RS 4 +.EX +MAX=10,20 +BEG=0,0 +SCROLL=0,10 +VMIN=1 +VTIME=0 +FLAGS=0x1000 +FG=0,0 +BG=0,0, +0,0,0,1, +0,19,0,0, +1,0,0,1, +1,19,0,0, +2,0,0,1, +2,19,0,0, +3,0,0,1, +3,19,0,0, +4,0,0,1, +4,5,0x20,0,Hello +4,10,0,1, +4,19,0,0, +5,0,0,1, +5,5,0x4,2,World! +5,11,0,1, +5,19,0,0, +6,0,0,1, +6,19,0,0, +7,0,0,1, +7,19,0,0, +8,0,0,1, +8,19,0,0, +9,0,0,1, +9,19,0,0, +CUR=11,5 +.EE +.RE +.PP +Solaris \fBgetwin\fP requires that all parameters are present, and +in the same order. +The \fIxpg4\fP curses library does not know about the \fBbce\fP +(back color erase) capability, and does not color the window background. +.ne 10 +.PP +On the other hand, the SVr4 curses library does know about the background color. +However, its screen dumps are in binary. +Here is the corresponding dump (using \*(``od \-t x1\*(''): +.PP +.RS 4 +.EX +0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00 +0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 +0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00 +0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00 +0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00 +0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00 +* +0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04 +0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04 +0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00 +* +0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00 +0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00 +0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00 +0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00 +* +0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1 +0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07 +0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00 +0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +* +0002371 +.EE +.RE +.SH AUTHORS +Thomas E. Dickey +.br +extended screen-dump format for \fI\%ncurses\fP 6.0 (2015) +.sp +Eric S. Raymond +.br +screen dump feature in \fI\%ncurses\fP 1.9.2d (1995) +.SH SEE ALSO +\fB\%curs_scr_dump\fP(3X), +\fB\%curs_util\fP(3X) diff --git a/upstream/fedora-40/man5/securetty.5 b/upstream/fedora-40/man5/securetty.5 new file mode 100644 index 00000000..279a81d6 --- /dev/null +++ b/upstream/fedora-40/man5/securetty.5 @@ -0,0 +1,35 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:06:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH securetty 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +securetty \- list of terminals on which root is allowed to login +.SH DESCRIPTION +The file +.I /etc/securetty +contains the names of terminals +(one per line, without leading +.IR /dev/ ) +which are considered secure for the transmission of certain authentication +tokens. +.P +It is used by (some versions of) +.BR login (1) +to restrict the terminals +on which root is allowed to login. +See +.BR login.defs (5) +if you use the shadow suite. +.P +On PAM enabled systems, it is used for the same purpose by +.BR pam_securetty (8) +to restrict the terminals on which empty passwords are accepted. +.SH FILES +.I /etc/securetty +.SH SEE ALSO +.BR login (1), +.BR login.defs (5), +.BR pam_securetty (8) diff --git a/upstream/fedora-40/man5/services.5 b/upstream/fedora-40/man5/services.5 new file mode 100644 index 00000000..2442c6dc --- /dev/null +++ b/upstream/fedora-40/man5/services.5 @@ -0,0 +1,199 @@ +.\" This manpage is Copyright (C) 1996 Austin Donnelly , +.\" with additional material Copyright (c) 1995 Martin Schulze +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This manpage was made by merging two independently written manpages, +.\" one written by Martin Schulze (18 Oct 95), the other written by +.\" Austin Donnelly, (9 Jan 96). +.\" +.\" Thu Jan 11 12:14:41 1996 Austin Donnelly +.\" * Merged two services(5) manpages +.\" +.TH services 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +services \- Internet network services list +.SH DESCRIPTION +.B services +is a plain ASCII file providing a mapping between human-friendly textual +names for internet services, and their underlying assigned port +numbers and protocol types. +Every networking program should look into +this file to get the port number (and protocol) for its service. +The C library routines +.BR getservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR setservent (3), +and +.BR endservent (3) +support querying this file from programs. +.P +Port numbers are assigned by the IANA (Internet Assigned Numbers +Authority), and their current policy is to assign both TCP and UDP +protocols when assigning a port number. +Therefore, most entries will +have two entries, even for TCP-only services. +.P +Port numbers below 1024 (so-called "low numbered" ports) can be +bound to only by root (see +.BR bind (2), +.BR tcp (7), +and +.BR udp (7)). +This is so clients connecting to low numbered ports can trust +that the service running on the port is the standard implementation, +and not a rogue service run by a user of the machine. +Well-known port numbers specified by the IANA are normally +located in this root-only space. +.P +The presence of an entry for a service in the +.B services +file does not necessarily mean that the service is currently running +on the machine. +See +.BR inetd.conf (5) +for the configuration of Internet services offered. +Note that not all +networking services are started by +.BR inetd (8), +and so won't appear in +.BR inetd.conf (5). +In particular, news (NNTP) and mail (SMTP) servers are often +initialized from the system boot scripts. +.P +The location of the +.B services +file is defined by +.B _PATH_SERVICES +in +.IR "." +This is usually set to +.IR /etc/services "." +.P +Each line describes one service, and is of the form: +.IP +\f2service-name\ \ \ port\f3/\f2protocol\ \ \ \f1[\f2aliases ...\f1] +.TP +where: +.TP +.I service-name +is the friendly name the service is known by and looked up under. +It is case sensitive. +Often, the client program is named after the +.IR service-name "." +.TP +.I port +is the port number (in decimal) to use for this service. +.TP +.I protocol +is the type of protocol to be used. +This field should match an entry +in the +.BR protocols (5) +file. +Typical values include +.B tcp +and +.BR udp . +.TP +.I aliases +is an optional space or tab separated list of other names for this +service. +Again, the names are case +sensitive. +.P +Either spaces or tabs may be used to separate the fields. +.P +Comments are started by the hash sign (#) and continue until the end +of the line. +Blank lines are skipped. +.P +The +.I service-name +should begin in the first column of the file, since leading spaces are +not stripped. +.I service-names +can be any printable characters excluding space and tab. +However, a conservative choice of characters should be used to minimize +compatibility problems. +For example, a\-z, 0\-9, and hyphen (\-) would seem a +sensible choice. +.P +Lines not matching this format should not be present in the +file. +(Currently, they are silently skipped by +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +However, this behavior should not be relied on.) +.P +.\" The following is not true as at glibc 2.8 (a line with a comma is +.\" ignored by getservent()); it's not clear if/when it was ever true. +.\" As a backward compatibility feature, the slash (/) between the +.\" .I port +.\" number and +.\" .I protocol +.\" name can in fact be either a slash or a comma (,). +.\" Use of the comma in +.\" modern installations is deprecated. +.\" +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. +.P +A sample +.B services +file might look like this: +.P +.in +4n +.EX +netstat 15/tcp +qotd 17/tcp quote +msp 18/tcp # message send protocol +msp 18/udp # message send protocol +chargen 19/tcp ttytst source +chargen 19/udp ttytst source +ftp 21/tcp +# 22 \- unassigned +telnet 23/tcp +.EE +.in +.SH FILES +.TP +.I /etc/services +The Internet network services list +.TP +.I +Definition of +.B _PATH_SERVICES +.\" .SH BUGS +.\" It's not clear when/if the following was ever true; +.\" it isn't true for glibc 2.8: +.\" There is a maximum of 35 aliases, due to the way the +.\" .BR getservent (3) +.\" code is written. +.\" +.\" It's not clear when/if the following was ever true; +.\" it isn't true for glibc 2.8: +.\" Lines longer than +.\" .B BUFSIZ +.\" (currently 1024) characters will be ignored by +.\" .BR getservent (3), +.\" .BR getservbyname (3), +.\" and +.\" .BR getservbyport (3). +.\" However, this will also cause the next line to be mis-parsed. +.SH SEE ALSO +.BR listen (2), +.BR endservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR getservent (3), +.BR setservent (3), +.BR inetd.conf (5), +.BR protocols (5), +.BR inetd (8) +.P +Assigned Numbers RFC, most recently RFC\ 1700, (AKA STD0002). diff --git a/upstream/fedora-40/man5/shells.5 b/upstream/fedora-40/man5/shells.5 new file mode 100644 index 00000000..7a6c6297 --- /dev/null +++ b/upstream/fedora-40/man5/shells.5 @@ -0,0 +1,40 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Thu May 20 20:45:48 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt +.\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu) +.TH shells 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +shells \- pathnames of valid login shells +.SH DESCRIPTION +.I /etc/shells +is a text file which contains the full pathnames of valid login shells. +This file is consulted by +.BR chsh (1) +and available to be queried by other programs. +.P +Be aware that there are programs which consult this file to +find out if a user is a normal user; +for example, +FTP daemons traditionally +disallow access to users with shells not included in this file. +.SH FILES +.I /etc/shells +.SH EXAMPLES +.I /etc/shells +may contain the following paths: +.P +.in +4n +.EX +.I /bin/sh +.I /bin/bash +.I /bin/csh +.EE +.in +.SH SEE ALSO +.BR chsh (1), +.BR getusershell (3), +.BR pam_shells (8) diff --git a/upstream/fedora-40/man5/slabinfo.5 b/upstream/fedora-40/man5/slabinfo.5 new file mode 100644 index 00000000..51e02a48 --- /dev/null +++ b/upstream/fedora-40/man5/slabinfo.5 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2001 Andreas Dilger (adilger@turbolinux.com) +.\" and Copyright (c) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH slabinfo 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +slabinfo \- kernel slab allocator statistics +.SH SYNOPSIS +.nf +.B cat /proc/slabinfo +.fi +.SH DESCRIPTION +Frequently used objects in the Linux kernel +(buffer heads, inodes, dentries, etc.) +have their own cache. +The file +.I /proc/slabinfo +gives statistics on these caches. +The following (edited) output shows an example of the +contents of this file: +.P +.EX +$ \fBsudo cat /proc/slabinfo\fP +slabinfo \- version: 2.1 +# name ... +sigqueue 100 100 160 25 1 : tunables 0 0 0 : slabdata 4 4 0 +sighand_cache 355 405 2112 15 8 : tunables 0 0 0 : slabdata 27 27 0 +kmalloc\-8192 96 96 8192 4 8 : tunables 0 0 0 : slabdata 24 24 0 +\&... +.EE +.P +The first line of output includes a version number, +which allows an application that is reading the file to handle changes +in the file format. +(See VERSIONS, below.) +The next line lists the names of the columns in the remaining lines. +.P +Each of the remaining lines displays information about a specified cache. +Following the cache name, +the output shown in each line shows three components for each cache: +.IP \[bu] 3 +statistics +.IP \[bu] +tunables +.IP \[bu] +slabdata +.P +The statistics are as follows: +.TP +.I active_objs +The number of objects that are currently active (i.e., in use). +.TP +.I num_objs +The total number of allocated objects +(i.e., objects that are both in use and not in use). +.TP +.I objsize +The size of objects in this slab, in bytes. +.TP +.I objperslab +The number of objects stored in each slab. +.TP +.I pagesperslab +The number of pages allocated for each slab. +.P +The +.I tunables +entries in each line show tunable parameters for the corresponding cache. +When using the default SLUB allocator, there are no tunables, the +.I /proc/slabinfo +file is not writable, and the value 0 is shown in these fields. +When using the older SLAB allocator, +the tunables for a particular cache can be set by writing +lines of the following form to +.IR /proc/slabinfo : +.P +.in +4n +.EX +# \fBecho \[aq]name limit batchcount sharedfactor\[aq] > /proc/slabinfo\fP +.EE +.in +.P +Here, +.I name +is the cache name, and +.IR limit , +.IR batchcount , +and +.I sharedfactor +are integers defining new values for the corresponding tunables. +The +.I limit +value should be a positive value, +.I batchcount +should be a positive value that is less than or equal to +.IR limit , +and +.I sharedfactor +should be nonnegative. +If any of the specified values is invalid, +the cache settings are left unchanged. +.P +The +.I tunables +entries in each line contain the following fields: +.TP +.I limit +The maximum number of objects that will be cached. +.\" https://lwn.net/Articles/56360/ +.\" This is the limit on the number of free objects that can be stored +.\" in the per-CPU free list for this slab cache. +.TP +.I batchcount +On SMP systems, this specifies the number of objects to transfer at one time +when refilling the available object list. +.\" https://lwn.net/Articles/56360/ +.\" On SMP systems, when we refill the available object list, instead +.\" of doing one object at a time, we do batch-count objects at a time. +.TP +.I sharedfactor +[To be documented] +.\" +.P +The +.I slabdata +entries in each line contain the following fields: +.TP +.I active_slabs +The number of active slabs. +.TP +.I nums_slabs +The total number of slabs. +.TP +.I sharedavail +[To be documented] +.P +Note that because of object alignment and slab cache overhead, +objects are not normally packed tightly into pages. +Pages with even one in-use object are considered in-use and cannot be +freed. +.P +Kernels configured with +.B CONFIG_DEBUG_SLAB +will also have additional statistics fields in each line, +and the first line of the file will contain the string "(statistics)". +The statistics field include : the high water mark of active +objects; the number of times objects have been allocated; +the number of times the cache has grown (new pages added +to this cache); the number of times the cache has been +reaped (unused pages removed from this cache); and the +number of times there was an error allocating new pages +to this cache. +.\" +.\" SMP systems will also have "(SMP)" in the first line of +.\" output, and will have two additional columns for each slab, +.\" reporting the slab allocation policy for the CPU-local +.\" cache (to reduce the need for inter-CPU synchronization +.\" when allocating objects from the cache). +.\" The first column is the per-CPU limit: the maximum number of objects that +.\" will be cached for each CPU. +.\" The second column is the +.\" batchcount: the maximum number of free objects in the +.\" global cache that will be transferred to the per-CPU cache +.\" if it is empty, or the number of objects to be returned +.\" to the global cache if the per-CPU cache is full. +.\" +.\" If both slab cache statistics and SMP are defined, there +.\" will be four additional columns, reporting the per-CPU +.\" cache statistics. +.\" The first two are the per-CPU cache +.\" allocation hit and miss counts: the number of times an +.\" object was or was not available in the per-CPU cache +.\" for allocation. +.\" The next two are the per-CPU cache free +.\" hit and miss counts: the number of times a freed object +.\" could or could not fit within the per-CPU cache limit, +.\" before flushing objects to the global cache. +.SH VERSIONS +The +.I /proc/slabinfo +file first appeared in Linux 2.1.23. +The file is versioned, +and over time there have been a number of versions with different layouts: +.TP +1.0 +Present throughout the Linux 2.2.x kernel series. +.TP +1.1 +Present in the Linux 2.4.x kernel series. +.\" First appeared in Linux 2.4.0-test3 +.TP +1.2 +A format that was briefly present in the Linux 2.5 development series. +.\" from Linux 2.5.45 to Linux 2.5.70 +.TP +2.0 +Present in Linux 2.6.x kernels up to and including Linux 2.6.9. +.\" First appeared in Linux 2.5.71 +.TP +2.1 +The current format, which first appeared in Linux 2.6.10. +.SH NOTES +Only root can read and (if the kernel was configured with +.BR CONFIG_SLAB ) +write the +.I /proc/slabinfo +file. +.P +The total amount of memory allocated to the SLAB/SLUB cache is shown in the +.I Slab +field of +.IR /proc/meminfo . +.SH SEE ALSO +.BR slabtop (1) +.P +The kernel source file +.I Documentation/vm/slub.txt +and +.IR tools/vm/slabinfo.c . diff --git a/upstream/fedora-40/man5/smb.conf.5 b/upstream/fedora-40/man5/smb.conf.5 new file mode 100644 index 00000000..6de830fd --- /dev/null +++ b/upstream/fedora-40/man5/smb.conf.5 @@ -0,0 +1,14930 @@ +'\" t +.\" Title: smb.conf +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 02/26/2024 +.\" Manual: File Formats and Conventions +.\" Source: Samba 4.20.0rc3 +.\" Language: English +.\" +.TH "SMB\&.CONF" "5" "02/26/2024" "Samba 4\&.20\&.0rc3" "File Formats and Conventions" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +smb.conf \- The configuration file for the Samba suite +.SH "SYNOPSIS" +.PP +The +smb\&.conf +file is a configuration file for the Samba suite\&. +smb\&.conf +contains runtime configuration information for the Samba programs\&. The complete description of the file format and possible parameters held within are here for reference purposes\&. +.SH "HOW CONFIGURATION CHANGES ARE APPLIED" +.PP +The Samba suite includes a number of different programs\&. Some of them operate in a client mode, others are server daemons that provide various services to its clients\&. The +smb\&.conf +file is processed in the following way: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The Samba suite\*(Aqs client applications read their configuration only once\&. Any changes made after start aren\*(Aqt reflected in the context of already running client code\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The Samba suite\*(Aqs server daemons reload their configuration when requested\&. However, already active connections do not change their configuration\&. More detailed information can be found in +\fBsmbd\fR(8) +and +\fBwinbindd\fR(8) +manual pages\&. +.RE +.sp +.RE +.PP +To request Samba server daemons to refresh their configuration, please use +\fBsmbcontrol\fR(1) +utility\&. +.SH "FILE FORMAT" +.PP +The file consists of sections and parameters\&. A section begins with the name of the section in square brackets and continues until the next section begins\&. Sections contain parameters of the form: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIname\fR = \fIvalue \fR +.fi +.if n \{\ +.RE +.\} +.PP +The file is line\-based \- that is, each newline\-terminated line represents either a comment, a section name or a parameter\&. +.PP +Section and parameter names are not case sensitive\&. +.PP +Only the first equals sign in a parameter is significant\&. Whitespace before or after the first equals sign is discarded\&. Leading, trailing and internal whitespace in section and parameter names is irrelevant\&. Leading and trailing whitespace in a parameter value is discarded\&. Internal whitespace within a parameter value is retained verbatim\&. +.PP +Any line beginning with a semicolon (\(lq;\(rq) or a hash (\(lq#\(rq) character is ignored, as are lines containing only whitespace\&. +.PP +Any line ending in a +\(lq\e\(rq +is continued on the next line in the customary UNIX fashion\&. +.PP +The values following the equals sign in parameters are all either a string (no quotes needed) or a boolean, which may be given as yes/no, 1/0 or true/false\&. Case is not significant in boolean values, but is preserved in string values\&. Some items such as create masks are numeric\&. +.SH "SECTION DESCRIPTIONS" +.PP +Each section in the configuration file (except for the [global] section) describes a shared resource (known as a +\(lqshare\(rq)\&. The section name is the name of the shared resource and the parameters within the section define the shares attributes\&. +.PP +There are three special sections, [global], [homes] and [printers], which are described under +\fIspecial sections\fR\&. The following notes apply to ordinary section descriptions\&. +.PP +A share consists of a directory to which access is being given plus a description of the access rights which are granted to the user of the service\&. Some housekeeping options are also specifiable\&. +.PP +Sections are either file share services (used by the client as an extension of their native file systems) or printable services (used by the client to access print services on the host running the server)\&. +.PP +Sections may be designated +\fIguest\fR +services, in which case no password is required to access them\&. A specified UNIX +\fIguest account\fR +is used to define access privileges in this case\&. +.PP +Sections other than guest services will require a password to access them\&. The client provides the username\&. As older clients only provide passwords and not usernames, you may specify a list of usernames to check against the password using the +user = +option in the share definition\&. For modern clients such as Windows 95/98/ME/NT/2000, this should not be necessary\&. +.PP +The access rights granted by the server are masked by the access rights granted to the specified or guest UNIX user by the host system\&. The server does not grant more access than the host system grants\&. +.PP +The following sample section defines a file space share\&. The user has write access to the path +/home/bar\&. The share is accessed via the share name +foo: +.sp +.if n \{\ +.RS 4 +.\} +.nf + \fI[foo]\fR + \m[blue]\fBpath = /home/bar\fR\m[] + \m[blue]\fBread only = no\fR\m[] +.fi +.if n \{\ +.RE +.\} +.PP +The following sample section defines a printable share\&. The share is read\-only, but printable\&. That is, the only write access permitted is via calls to open, write to and close a spool file\&. The +\fIguest ok\fR +parameter means access will be permitted as the default guest user (specified elsewhere): +.sp +.if n \{\ +.RS 4 +.\} +.nf + \fI[aprinter]\fR + \m[blue]\fBpath = /var/tmp\fR\m[] + \m[blue]\fBread only = yes\fR\m[] + \m[blue]\fBprintable = yes\fR\m[] + \m[blue]\fBguest ok = yes\fR\m[] +.fi +.if n \{\ +.RE +.\} +.sp +.SH "SPECIAL SECTIONS" +.SS "The [global] section" +.PP +Parameters in this section apply to the server as a whole, or are defaults for sections that do not specifically define certain items\&. See the notes under PARAMETERS for more information\&. +.SS "The [homes] section" +.PP +If a section called [homes] is included in the configuration file, services connecting clients to their home directories can be created on the fly by the server\&. +.PP +When the connection request is made, the existing sections are scanned\&. If a match is found, it is used\&. If no match is found, the requested section name is treated as a username and looked up in the local password file\&. If the name exists and the correct password has been given, a share is created by cloning the [homes] section\&. +.PP +Some modifications are then made to the newly created share: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The share name is changed from homes to the located username\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If no path was given, the path is set to the user\*(Aqs home directory\&. +.RE +.sp +.RE +.PP +If you decide to use a +\fIpath =\fR +line in your [homes] section, it may be useful to use the %S macro\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBpath = /data/pchome/%S\fR +.fi +.if n \{\ +.RE +.\} +.sp +is useful if you have different home directories for your PCs than for UNIX access\&. +.PP +This is a fast and simple way to give a large number of clients access to their home directories with a minimum of fuss\&. +.PP +A similar process occurs if the requested section name is +\(lqhomes\(rq, except that the share name is not changed to that of the requesting user\&. This method of using the [homes] section works well if different users share a client PC\&. +.PP +The [homes] section can specify all the parameters a normal service section can specify, though some make more sense than others\&. The following is a typical and suitable [homes] section: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fI[homes]\fR +\m[blue]\fBread only = no\fR\m[] +.fi +.if n \{\ +.RE +.\} +.PP +An important point is that if guest access is specified in the [homes] section, all home directories will be visible to all clients +\fIwithout a password\fR\&. In the very unlikely event that this is actually desirable, it is wise to also specify +\fIread only access\fR\&. +.PP +The +\fIbrowseable\fR +flag for auto home directories will be inherited from the global browseable flag, not the [homes] browseable flag\&. This is useful as it means setting +\fIbrowseable = no\fR +in the [homes] section will hide the [homes] share but make any auto home directories visible\&. +.SS "The [printers] section" +.PP +This section works like [homes], but for printers\&. +.PP +If a [printers] section occurs in the configuration file, users are able to connect to any printer specified in the local host\*(Aqs printcap file\&. +.PP +When a connection request is made, the existing sections are scanned\&. If a match is found, it is used\&. If no match is found, but a [homes] section exists, it is used as described above\&. Otherwise, the requested section name is treated as a printer name and the appropriate printcap file is scanned to see if the requested section name is a valid printer share name\&. If a match is found, a new printer share is created by cloning the [printers] section\&. +.PP +A few modifications are then made to the newly created share: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The share name is set to the located printer name +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If no printer name was given, the printer name is set to the located printer name +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the share does not permit guest access and no username was given, the username is set to the located printer name\&. +.RE +.sp +.RE +.PP +The [printers] service MUST be printable \- if you specify otherwise, the server will refuse to load the configuration file\&. +.PP +Typically the path specified is that of a world\-writeable spool directory with the sticky bit set on it\&. A typical [printers] entry looks like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fI[printers]\fR +\m[blue]\fBpath = /var/tmp\fR\m[] +\m[blue]\fBguest ok = yes\fR\m[] +\m[blue]\fBprintable = yes\fR\m[] +.fi +.if n \{\ +.RE +.\} +.PP +All aliases given for a printer in the printcap file are legitimate printer names as far as the server is concerned\&. If your printing subsystem doesn\*(Aqt work like that, you will have to set up a pseudo\-printcap\&. This is a file consisting of one or more lines like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +alias|alias|alias|alias\&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.PP +Each alias should be an acceptable printer name for your printing subsystem\&. In the [global] section, specify the new file as your printcap\&. The server will only recognize names found in your pseudo\-printcap, which of course can contain whatever aliases you like\&. The same technique could be used simply to limit access to a subset of your local printers\&. +.PP +An alias, by the way, is defined as any component of the first entry of a printcap record\&. Records are separated by newlines, components (if there are more than one) are separated by vertical bar symbols (|)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +On SYSV systems which use lpstat to determine what printers are defined on the system you may be able to use +printcap name = lpstat +to automatically obtain a list of printers\&. See the +printcap name +option for more details\&. +.sp .5v +.RE +.SH "USERSHARES" +.PP +Starting with Samba version 3\&.0\&.23 the capability for non\-root users to add, modify, and delete their own share definitions has been added\&. This capability is called +\fIusershares\fR +and is controlled by a set of parameters in the [global] section of the smb\&.conf\&. The relevant parameters are : +.PP +usershare allow guests +.RS 4 +Controls if usershares can permit guest access\&. +.RE +.PP +usershare max shares +.RS 4 +Maximum number of user defined shares allowed\&. +.RE +.PP +usershare owner only +.RS 4 +If set only directories owned by the sharing user can be shared\&. +.RE +.PP +usershare path +.RS 4 +Points to the directory containing the user defined share definitions\&. The filesystem permissions on this directory control who can create user defined shares\&. +.RE +.PP +usershare prefix allow list +.RS 4 +Comma\-separated list of absolute pathnames restricting what directories can be shared\&. Only directories below the pathnames in this list are permitted\&. +.RE +.PP +usershare prefix deny list +.RS 4 +Comma\-separated list of absolute pathnames restricting what directories can be shared\&. Directories below the pathnames in this list are prohibited\&. +.RE +.PP +usershare template share +.RS 4 +Names a pre\-existing share used as a template for creating new usershares\&. All other share parameters not specified in the user defined share definition are copied from this named share\&. +.RE +.PP +To allow members of the UNIX group +foo +to create user defined shares, create the directory to contain the share definitions as follows: +.PP +Become root: +.sp +.if n \{\ +.RS 4 +.\} +.nf +mkdir /usr/local/samba/lib/usershares +chgrp foo /usr/local/samba/lib/usershares +chmod 1770 /usr/local/samba/lib/usershares +.fi +.if n \{\ +.RE +.\} +.PP +Then add the parameters +.sp +.if n \{\ +.RS 4 +.\} +.nf + \m[blue]\fBusershare path = /usr/local/samba/lib/usershares\fR\m[] + \m[blue]\fBusershare max shares = 10\fR\m[] # (or the desired number of shares) +.fi +.if n \{\ +.RE +.\} +.sp +to the global section of your +smb\&.conf\&. Members of the group foo may then manipulate the user defined shares using the following commands\&. +.PP +net usershare add sharename path [comment] [acl] [guest_ok=[y|n]] +.RS 4 +To create or modify (overwrite) a user defined share\&. +.RE +.PP +net usershare delete sharename +.RS 4 +To delete a user defined share\&. +.RE +.PP +net usershare list wildcard\-sharename +.RS 4 +To list user defined shares\&. +.RE +.PP +net usershare info wildcard\-sharename +.RS 4 +To print information about user defined shares\&. +.RE +.SH "PARAMETERS" +.PP +Parameters define the specific attributes of sections\&. +.PP +Some parameters are specific to the [global] section (e\&.g\&., +\fIsecurity\fR)\&. Some parameters are usable in all sections (e\&.g\&., +\fIcreate mask\fR)\&. All others are permissible only in normal sections\&. For the purposes of the following descriptions the [homes] and [printers] sections will be considered normal\&. The letter +\fIG\fR +in parentheses indicates that a parameter is specific to the [global] section\&. The letter +\fIS\fR +indicates that a parameter can be specified in a service specific section\&. All +\fIS\fR +parameters can also be specified in the [global] section \- in which case they will define the default behavior for all services\&. +.PP +Parameters are arranged here in alphabetical order \- this may not create best bedfellows, but at least you can find them! Where there are synonyms, the preferred synonym is described, others refer to the preferred synonym\&. +.SH "VARIABLE SUBSTITUTIONS" +.PP +Many of the strings that are settable in the config file can take substitutions\&. For example the option +\(lqpath = /tmp/%u\(rq +is interpreted as +\(lqpath = /tmp/john\(rq +if the user connected with the username john\&. +.PP +These substitutions are mostly noted in the descriptions below, but there are some general substitutions which apply whenever they might be relevant\&. These are: +.PP +%U +.RS 4 +session username (the username that the client wanted, not necessarily the same as the one they got)\&. +.RE +.PP +%G +.RS 4 +primary group name of %U\&. +.RE +.PP +%h +.RS 4 +the Internet hostname that Samba is running on\&. +.RE +.PP +%m +.RS 4 +the NetBIOS name of the client machine (very useful)\&. +.sp +This parameter is not available when Samba listens on port 445, as clients no longer send this information\&. If you use this macro in an include statement on a domain that has a Samba domain controller be sure to set in the [global] section +\fIsmb ports = 139\fR\&. This will cause Samba to not listen on port 445 and will permit include functionality to function as it did with Samba 2\&.x\&. +.RE +.PP +%L +.RS 4 +the NetBIOS name of the server\&. This allows you to change your config based on what the client calls you\&. Your server can have a +\(lqdual personality\(rq\&. +.RE +.PP +%M +.RS 4 +the Internet name of the client machine\&. +.RE +.PP +%R +.RS 4 +the selected protocol level after protocol negotiation\&. It can be one of CORE, COREPLUS, LANMAN1, LANMAN2, NT1, SMB2_02, SMB2_10, SMB3_00, SMB3_02, SMB3_11 or SMB2_FF\&. +.RE +.PP +%d +.RS 4 +the process id of the current server process\&. +.RE +.PP +%a +.RS 4 +The architecture of the remote machine\&. It currently recognizes Samba (\fBSamba\fR), the Linux CIFS file system (\fBCIFSFS\fR), OS/2, (\fBOS2\fR), Mac OS X (\fBOSX\fR), Windows for Workgroups (\fBWfWg\fR), Windows 9x/ME (\fBWin95\fR), Windows NT (\fBWinNT\fR), Windows 2000 (\fBWin2K\fR), Windows XP (\fBWinXP\fR), Windows XP 64\-bit(\fBWinXP64\fR), Windows 2003 including 2003R2 (\fBWin2K3\fR), and Windows Vista (\fBVista\fR)\&. Anything else will be known as +\fBUNKNOWN\fR\&. +.RE +.PP +%I +.RS 4 +the IP address of the client machine\&. +.sp +Before 4\&.0\&.0 it could contain IPv4 mapped IPv6 addresses, now it only contains IPv4 or IPv6 addresses\&. +.RE +.PP +%J +.RS 4 +the IP address of the client machine, colons/dots replaced by underscores\&. +.RE +.PP +%i +.RS 4 +the local IP address to which a client connected\&. +.sp +Before 4\&.0\&.0 it could contain IPv4 mapped IPv6 addresses, now it only contains IPv4 or IPv6 addresses\&. +.RE +.PP +%j +.RS 4 +the local IP address to which a client connected, colons/dots replaced by underscores\&. +.RE +.PP +%T +.RS 4 +the current date and time\&. +.RE +.PP +%t +.RS 4 +the current date and time in a minimal format without colons (YYYYYmmdd_HHMMSS)\&. +.RE +.PP +%D +.RS 4 +name of the domain or workgroup of the current user\&. +.RE +.PP +%w +.RS 4 +the winbind separator\&. +.RE +.PP +%$(\fIenvvar\fR) +.RS 4 +the value of the environment variable +\fIenvar\fR\&. +.RE +.PP +The following substitutes apply only to some configuration options (only those that are used when a connection has been established): +.PP +%S +.RS 4 +the name of the current service, if any\&. +.RE +.PP +%P +.RS 4 +the root directory of the current service, if any\&. +.RE +.PP +%u +.RS 4 +username of the current service, if any\&. +.RE +.PP +%g +.RS 4 +primary group name of %u\&. +.RE +.PP +%H +.RS 4 +the home directory of the user given by %u\&. +.RE +.PP +%N +.RS 4 +This value is the same as %L\&. +.RE +.PP +There are some quite creative things that can be done with these substitutions and other +smb\&.conf +options\&. +.SH "NAME MANGLING" +.PP +Samba supports +name mangling +so that DOS and Windows clients can use files that don\*(Aqt conform to the 8\&.3 format\&. It can also be set to adjust the case of 8\&.3 format filenames\&. +.PP +There are several options that control the way mangling is performed, and they are grouped here rather than listed separately\&. For the defaults look at the output of the testparm program\&. +.PP +These options can be set separately for each service\&. +.PP +The options are: +.PP +case sensitive = yes/no/auto +.RS 4 +controls whether filenames are case sensitive\&. If they aren\*(Aqt, Samba must do a filename search and match on passed names\&. The default setting of auto allows clients that support case sensitive filenames (Linux CIFSVFS and smbclient 3\&.0\&.5 and above currently) to tell the Samba server on a per\-packet basis that they wish to access the file system in a case\-sensitive manner (to support UNIX case sensitive semantics)\&. No Windows or DOS system supports case\-sensitive filename so setting this option to auto is the same as setting it to no for them\&. Default +\fIauto\fR\&. +.RE +.PP +default case = upper/lower +.RS 4 +controls what the default case is for new filenames (ie\&. files that don\*(Aqt currently exist in the filesystem)\&. Default +\fIlower\fR\&. IMPORTANT NOTE: As part of the optimizations for directories containing large numbers of files, the following special case applies\&. If the options +\m[blue]\fBcase sensitive = yes\fR\m[], +\m[blue]\fBpreserve case = No\fR\m[], and +\m[blue]\fBshort preserve case = No\fR\m[] +are set, then the case of +\fIall\fR +incoming client filenames, not just new filenames, will be modified\&. See additional notes below\&. +.RE +.PP +preserve case = yes/no +.RS 4 +controls whether new files (ie\&. files that don\*(Aqt currently exist in the filesystem) are created with the case that the client passes, or if they are forced to be the +default +case\&. Default +\fIyes\fR\&. +.RE +.PP +short preserve case = yes/no +.RS 4 +controls if new files (ie\&. files that don\*(Aqt currently exist in the filesystem) which conform to 8\&.3 syntax, that is all in upper case and of suitable length, are created upper case, or if they are forced to be the +default +case\&. This option can be used with +preserve case = yes +to permit long filenames to retain their case, while short names are lowercased\&. Default +\fIyes\fR\&. +.RE +.PP +By default, Samba 3\&.0 has the same semantics as a Windows NT server, in that it is case insensitive but case preserving\&. As a special case for directories with large numbers of files, if the case options are set as follows, "case sensitive = yes", "case preserve = no", "short preserve case = no" then the "default case" option will be applied and will modify all filenames sent from the client when accessing this share\&. +.SH "REGISTRY\-BASED CONFIGURATION" +.PP +Starting with Samba version 3\&.2\&.0, the capability to store Samba configuration in the registry is available\&. The configuration is stored in the registry key +\fIHKLM\eSoftware\eSamba\esmbconf\fR\&. There are two levels of registry configuration: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Share definitions stored in registry are used\&. This is triggered by setting the global parameter +\fIregistry shares\fR +to +\(lqyes\(rq +in +\fIsmb\&.conf\fR\&. +.sp +The registry shares are loaded not at startup but on demand at runtime by +\fIsmbd\fR\&. Shares defined in +\fIsmb\&.conf\fR +take priority over shares of the same name defined in registry\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Global +\fIsmb\&.conf\fR +options stored in registry are used\&. This can be activated in two different ways: +.sp +Firstly, a registry only configuration is triggered by setting +\m[blue]\fBconfig backend = registry\fR\m[] +in the [global] section of +\fIsmb\&.conf\fR\&. This resets everything that has been read from config files to this point and reads the content of the global configuration section from the registry\&. This is the recommended method of using registry based configuration\&. +.sp +Secondly, a mixed configuration can be activated by a special new meaning of the parameter +\m[blue]\fBinclude = registry\fR\m[] +in the [global] section of +\fIsmb\&.conf\fR\&. This reads the global options from registry with the same priorities as for an include of a text file\&. This may be especially useful in cases where an initial configuration is needed to access the registry\&. +.sp +Activation of global registry options automatically activates registry shares\&. So in the registry only case, shares are loaded on demand only\&. +.RE +.sp +.RE +.PP +Note: To make registry\-based configurations foolproof at least to a certain extent, the use of +\fIlock directory\fR +and +\fIconfig backend\fR +inside the registry configuration has been disabled: Especially by changing the +\fIlock directory\fR +inside the registry configuration, one would create a broken setup where the daemons do not see the configuration they loaded once it is active\&. +.PP +The registry configuration can be accessed with tools like +\fIregedit\fR +or +\fInet (rpc) registry\fR +in the key +\fIHKLM\eSoftware\eSamba\esmbconf\fR\&. More conveniently, the +\fIconf\fR +subcommand of the +\fBnet\fR(8) +utility offers a dedicated interface to read and write the registry based configuration locally, i\&.e\&. directly accessing the database file, circumventing the server\&. +.SH "IDENTITY MAPPING CONSIDERATIONS" +.PP +In the SMB protocol, users, groups, and machines are represented by their security identifiers (SIDs)\&. On POSIX system Samba processes need to run under corresponding POSIX user identities and with supplemental POSIX groups to allow access to the files owned by those users and groups\&. The process of mapping SIDs to POSIX users and groups is called +\fIIDENTITY MAPPING\fR +or, in short, +\fIID MAPPING\fR\&. +.PP +Samba supports multiple ways to map SIDs to POSIX users and groups\&. The configuration is driven by the +\m[blue]\fBidmap config DOMAIN : OPTION\fR\m[] +option which allows one to specify identity mapping (idmap) options for each domain separately\&. +.PP +Identity mapping modules implement different strategies for mapping of SIDs to POSIX user and group identities\&. They are applicable to different use cases and scenarios\&. It is advised to read the documentation of the individual identity mapping modules before choosing a specific scenario to use\&. Each identity management module is documented in a separate manual page\&. The standard idmap backends are tdb (\fBidmap_tdb\fR(8)), tdb2 (\fBidmap_tdb2\fR(8)), ldap (\fBidmap_ldap\fR(8)), rid (\fBidmap_rid\fR(8)), hash (\fBidmap_hash\fR(8)), autorid (\fBidmap_autorid\fR(8)), ad (\fBidmap_ad\fR(8)), nss (\fBidmap_nss\fR(8)), and rfc2307 (\fBidmap_rfc2307\fR(8))\&. +.PP +Overall, ID mapping configuration should be decided carefully\&. Changes to the already deployed ID mapping configuration may create the risk of losing access to the data or disclosing the data to the wrong parties\&. +.PP +This example shows how to configure two domains with +\fBidmap_rid\fR(8), the principal domain and a trusted domain, leaving the default id mapping scheme at tdb\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + [global] + security = domain + workgroup = MAIN + + idmap config * : backend = tdb + idmap config * : range = 1000000\-1999999 + + idmap config MAIN : backend = rid + idmap config MAIN : range = 5000000\-5999999 + + idmap config TRUSTED : backend = rid + idmap config TRUSTED : range = 6000000\-6999999 + +.fi +.if n \{\ +.RE +.\} +.SH "EXPLANATION OF EACH PARAMETER" + + +abort shutdown script (G) +.PP +.RS 4 +This a full path name to a script called by +\fBsmbd\fR(8) +that should stop a shutdown procedure issued by the +\m[blue]\fBshutdown script\fR\m[]\&. +.sp +If the connected user possesses the +\fBSeRemoteShutdownPrivilege\fR, right, this command will be run as root\&. +.sp +Default: +\fI\fIabort shutdown script\fR\fR\fI = \fR\fI""\fR\fI \fR +.sp +Example: +\fI\fIabort shutdown script\fR\fR\fI = \fR\fI/sbin/shutdown \-c\fR\fI \fR +.RE + +access based share enum (S) +.PP +.RS 4 +If this parameter is +\fByes\fR +for a service, then the share hosted by the service will only be visible to users who have read or write access to the share during share enumeration (for example net view \e\esambaserver)\&. The share ACLs which allow or deny the access to the share can be modified using for example the +sharesec +command or using the appropriate Windows tools\&. This has parallels to access based enumeration, the main difference being that only share permissions are evaluated, and security descriptors on files contained on the share are not used in computing enumeration access rights\&. +.sp +Default: +\fI\fIaccess based share enum\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +acl allow execute always (S) +.PP +.RS 4 +This boolean parameter controls the behaviour of +\fBsmbd\fR(8) +when receiving a protocol request of "open for execution" from a Windows client\&. With Samba 3\&.6 and older, the execution right in the ACL was not checked, so a client could execute a file even if it did not have execute rights on the file\&. In Samba 4\&.0, this has been fixed, so that by default, i\&.e\&. when this parameter is set to "False", "open for execution" is now denied when execution permissions are not present\&. +.sp +If this parameter is set to "True", Samba does not check execute permissions on "open for execution", thus re\-establishing the behaviour of Samba 3\&.6\&. This can be useful to smoothen upgrades from older Samba versions to 4\&.0 and newer\&. This setting is not meant to be used as a permanent setting, but as a temporary relief: It is recommended to fix the permissions in the ACLs and reset this parameter to the default after a certain transition period\&. +.sp +Default: +\fI\fIacl allow execute always\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +acl check permissions (S) +.PP +.RS 4 +Please note this parameter is now deprecated in Samba 3\&.6\&.2 and will be removed in a future version of Samba\&. +.sp +This boolean parameter controls what +\fBsmbd\fR(8) +does on receiving a protocol request of "open for delete" from a Windows client\&. If a Windows client doesn\*(Aqt have permissions to delete a file then they expect this to be denied at open time\&. POSIX systems normally only detect restrictions on delete by actually attempting to delete the file or directory\&. As Windows clients can (and do) "back out" a delete request by unsetting the "delete on close" bit Samba cannot delete the file immediately on "open for delete" request as we cannot restore such a deleted file\&. With this parameter set to true (the default) then smbd checks the file system permissions directly on "open for delete" and denies the request without actually deleting the file if the file system permissions would seem to deny it\&. This is not perfect, as it\*(Aqs possible a user could have deleted a file without Samba being able to check the permissions correctly, but it is close enough to Windows semantics for mostly correct behaviour\&. Samba will correctly check POSIX ACL semantics in this case\&. +.sp +If this parameter is set to "false" Samba doesn\*(Aqt check permissions on "open for delete" and allows the open\&. If the user doesn\*(Aqt have permission to delete the file this will only be discovered at close time, which is too late for the Windows user tools to display an error message to the user\&. The symptom of this is files that appear to have been deleted "magically" re\-appearing on a Windows explorer refresh\&. This is an extremely advanced protocol option which should not need to be changed\&. This parameter was introduced in its final form in 3\&.0\&.21, an earlier version with slightly different semantics was introduced in 3\&.0\&.20\&. That older version is not documented here\&. +.sp +Default: +\fI\fIacl check permissions\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +acl claims evaluation (G) +.PP +.RS 4 +This option controls the way Samba handles evaluation of security descriptors in Samba, with regards to Active Directory Claims\&. AD Claims, introduced with Windows 2012, are essentially administrator\-defined key\-value pairs that can be set both in Active Directory (communicated via the Kerberos PAC) and in the security descriptor themselves\&. +.sp +Active Directory claims are new with Samba 4\&.20\&. Because the claims are evaluated against a very flexible expression language within the security descriptor, this option provides a mechanism to disable this logic if required by the administrator\&. +.sp +This default behaviour is that claims evaluation is enabled in the AD DC only\&. Additionally, claims evaluation on the AD DC is only enabled if the DC functional level is 2012 or later\&. See +\m[blue]\fBad dc functional level\fR\m[]\&. +.sp +Possible values are : +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBAD DC only\fR: Enabled for the Samba AD DC (for DC functional level 2012 or higher)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBnever\fR: Disabled in all cases\&. This option disables some but not all of the Authentication Policies and Authentication Policy Silos features of the Windows 2012R2 functional level in the AD DC\&. +.RE +.sp +.RE +Default: +\fI\fIacl claims evaluation\fR\fR\fI = \fR\fIAD DC only\fR\fI \fR +.RE + +acl flag inherited canonicalization (S) +.PP +.RS 4 +This option controls the way Samba handles client requests setting the Security Descriptor of files and directories and the effect the operation has on the Security Descriptor flag "DACL auto\-inherited" (DI)\&. Generally, this flag is set on a file (or directory) upon creation if the parent directory has DI set and also has inheritable ACEs\&. +.sp +On the other hand when a Security Descriptor is explicitly set on a file, the DI flag is cleared, unless the flag "DACL Inheritance Required" (DR) is also set in the new Security Descriptor (fwiw, DR is never stored on disk)\&. +.sp +This is the default behaviour when this option is enabled (the default)\&. When setting this option to +no, the resulting value of the DI flag on\-disk is directly taken from the DI value of the to\-be\-set Security Descriptor\&. This can be used so dump tools like rsync that copy data blobs from xattrs that represent ACLs created by the acl_xattr VFS module will result in copies of the ACL that are identical to the source\&. Without this option, the copied ACLs would all lose the DI flag if set on the source\&. +.sp +Default: +\fI\fIacl flag inherited canonicalization\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +acl group control (S) +.PP +.RS 4 +In a POSIX filesystem, only the owner of a file or directory and the superuser can modify the permissions and ACLs on a file\&. If this parameter is set, then Samba overrides this restriction, and also allows the +\fIprimary group owner\fR +of a file or directory to modify the permissions and ACLs on that file\&. +.sp +On a Windows server, groups may be the owner of a file or directory \- thus allowing anyone in that group to modify the permissions on it\&. This allows the delegation of security controls on a point in the filesystem to the group owner of a directory and anything below it also owned by that group\&. This means there are multiple people with permissions to modify ACLs on a file or directory, easing manageability\&. +.sp +This parameter allows Samba to also permit delegation of the control over a point in the exported directory hierarchy in much the same way as Windows\&. This allows all members of a UNIX group to control the permissions on a file or directory they have group ownership on\&. +.sp +This parameter is best used with the +\m[blue]\fBinherit owner\fR\m[] +option and also on a share containing directories with the UNIX +\fIsetgid bit\fR +set on them, which causes new files and directories created within it to inherit the group ownership from the containing directory\&. +.sp +This parameter was deprecated in Samba 3\&.0\&.23, but re\-activated in Samba 3\&.0\&.31 and above, as it now only controls permission changes if the user is in the owning primary group\&. It is now no longer equivalent to the +\fIdos filemode\fR +option\&. +.sp +Default: +\fI\fIacl group control\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +acl map full control (S) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +maps a POSIX ACE entry of "rwx" (read/write/execute), the maximum allowed POSIX permission set, into a Windows ACL of "FULL CONTROL"\&. If this parameter is set to true any POSIX ACE entry of "rwx" will be returned in a Windows ACL as "FULL CONTROL", is this parameter is set to false any POSIX ACE entry of "rwx" will be returned as the specific Windows ACL bits representing read, write and execute\&. +.sp +Default: +\fI\fIacl map full control\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ad dc functional level (G) +.PP +.RS 4 +The value of the parameter (a string) is the Active Directory functional level that this Domain Controller will claim to support\&. +.sp +Possible values are : +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB2008_R2\fR: Similar to Windows 2008 R2 Functional Level +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB2012\fR: Similar to Windows 2012 Functional Level +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB2012_R2\fR: Similar to Windows 2012 R2 Functional Level +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB2016\fR: Similar to Windows 2016 Functional Level +.RE +.sp +.RE +Normally this option should not be set as Samba will operate per the released functionality of the Samba Active Directory Domain Controller\&. +.sp +However to access incomplete features in domain functional level 2016 it may be useful to set this value, prior to upgrading the domain functional level\&. +.sp +If this is set manually, the protection against mismatching features between domain controllers is reduced, so all domain controllers should be running the same version of Samba, to ensure that behaviour as seen by the client is the same no matter which DC is contacted\&. +.sp +Setting this to +\fB2016\fR +will allow raising the domain functional level with +samba\-tool domain level raise \-\-domain\-level=2016 +and provide access to Samba\*(Aqs Kerberos Claims and Dynamic Access Control feature\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +The Samba\*(Aqs Kerberos Claims and Dynamic Access Control features enabled with +\fB2016\fR +are incomplete in Samba 4\&.19\&. +.sp .5v +.RE +Default: +\fI\fIad dc functional level\fR\fR\fI = \fR\fI2008_R2\fR\fI \fR +.sp +Example: +\fI\fIad dc functional level\fR\fR\fI = \fR\fI2016\fR\fI \fR +.RE + +add group script (G) +.PP +.RS 4 +This is the full pathname to a script that will be run +\fIAS ROOT\fR +by +\fBsmbd\fR(8) +when a new group is requested\&. It will expand any +\fI%g\fR +to the group name passed\&. This script is only useful for installations using the Windows NT domain administration tools\&. The script is free to create a group with an arbitrary name to circumvent unix group name restrictions\&. In that case the script must print the numeric gid of the created group on stdout\&. +.sp +Default: +\fI\fIadd group script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIadd group script\fR\fR\fI = \fR\fI/usr/sbin/groupadd %g\fR\fI \fR +.RE + +additional dns hostnames (G) +.PP +.RS 4 +A list of additional DNS names by which this host can be identified +.sp +Default: +\fI\fIadditional dns hostnames\fR\fR\fI = \fR\fI # empty string (no additional dns names)\fR\fI \fR +.sp +Example: +\fI\fIadditional dns hostnames\fR\fR\fI = \fR\fI host2\&.example\&.com host3\&.other\&.com \fR\fI \fR +.RE + +add machine script (G) +.PP +.RS 4 +This is the full pathname to a script that will be run by +\fBsmbd\fR(8) +when a machine is added to Samba\*(Aqs domain and a Unix account matching the machine\*(Aqs name appended with a "$" does not already exist\&. +.sp +This option is very similar to the +\m[blue]\fBadd user script\fR\m[], and likewise uses the %u substitution for the account name\&. Do not use the %m substitution\&. +.sp +Default: +\fI\fIadd machine script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIadd machine script\fR\fR\fI = \fR\fI/usr/sbin/adduser \-n \-g machines \-c Machine \-d /var/lib/nobody \-s /bin/false %u\fR\fI \fR +.RE + +addport command (G) +.PP +.RS 4 +Samba 3\&.0\&.23 introduced support for adding printer ports remotely using the Windows "Add Standard TCP/IP Port Wizard"\&. This option defines an external program to be executed when smbd receives a request to add a new Port to the system\&. The script is passed two parameters: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIport name\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdevice URI\fR +.RE +.sp +.RE +The deviceURI is in the format of socket://[:] or lpd:///\&. +.sp +Default: +\fI\fIaddport command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIaddport command\fR\fR\fI = \fR\fI/etc/samba/scripts/addport\&.sh\fR\fI \fR +.RE + +addprinter command (G) +.PP +.RS 4 +With the introduction of MS\-RPC based printing support for Windows NT/2000 clients in Samba 2\&.2, The MS Add Printer Wizard (APW) icon is now also available in the "Printers\&.\&.\&." folder displayed a share listing\&. The APW allows for printers to be add remotely to a Samba or Windows NT/2000 print server\&. +.sp +For a Samba host this means that the printer must be physically added to the underlying printing system\&. The +\fIaddprinter command\fR +defines a script to be run which will perform the necessary operations for adding the printer to the print system and to add the appropriate service definition to the +smb\&.conf +file in order that it can be shared by +\fBsmbd\fR(8)\&. +.sp +The +\fIaddprinter command\fR +is automatically invoked with the following parameter (in order): +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIprinter name\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshare name\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIport name\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdriver name\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIlocation\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIWindows 9x driver location\fR +.RE +.sp +.RE +All parameters are filled in from the PRINTER_INFO_2 structure sent by the Windows NT/2000 client with one exception\&. The "Windows 9x driver location" parameter is included for backwards compatibility only\&. The remaining fields in the structure are generated from answers to the APW questions\&. +.sp +Once the +\fIaddprinter command\fR +has been executed, +smbd +will reparse the +smb\&.conf +to determine if the share defined by the APW exists\&. If the sharename is still invalid, then +smbd +will return an ACCESS_DENIED error to the client\&. +.sp +The +\fIaddprinter command\fR +program can output a single line of text, which Samba will set as the port the new printer is connected to\&. If this line isn\*(Aqt output, Samba won\*(Aqt reload its printer shares\&. +.sp +Default: +\fI\fIaddprinter command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIaddprinter command\fR\fR\fI = \fR\fI/usr/bin/addprinter\fR\fI \fR +.RE + +add share command (G) +.PP +.RS 4 +Samba 2\&.2\&.0 introduced the ability to dynamically add and delete shares via the Windows NT 4\&.0 Server Manager\&. The +\fIadd share command\fR +is used to define an external program or script which will add a new service definition to +smb\&.conf\&. +.sp +In order to successfully execute the +\fIadd share command\fR, +smbd +requires that the administrator connects using a root account (i\&.e\&. uid == 0) or has the +SeDiskOperatorPrivilege\&. Scripts defined in the +\fIadd share command\fR +parameter are executed as root\&. +.sp +When executed, +smbd +will automatically invoke the +\fIadd share command\fR +with five parameters\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIconfigFile\fR +\- the location of the global +smb\&.conf +file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshareName\fR +\- the name of the new share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIpathName\fR +\- path to an **existing** directory on disk\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIcomment\fR +\- comment string to associate with the new share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fImax connections\fR +Number of maximum simultaneous connections to this share\&. +.RE +.sp +.RE +This parameter is only used to add file shares\&. To add printer shares, see the +\m[blue]\fBaddprinter command\fR\m[]\&. +.sp +Default: +\fI\fIadd share command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIadd share command\fR\fR\fI = \fR\fI/usr/local/bin/addshare\fR\fI \fR +.RE + +add user script (G) +.PP +.RS 4 +This is the full pathname to a script that will be run +\fIAS ROOT\fR +by +\fBsmbd\fR(8) +under special circumstances described below\&. +.sp +Normally, a Samba server requires that UNIX users are created for all users accessing files on this server\&. For sites that use Windows NT account databases as their primary user database creating these users and keeping the user list in sync with the Windows NT PDC is an onerous task\&. This option allows smbd to create the required UNIX users +\fION DEMAND\fR +when a user accesses the Samba server\&. +.sp +When the Windows user attempts to access the Samba server, at login (session setup in the SMB protocol) time, +\fBsmbd\fR(8) +contacts the +\m[blue]\fBpassword server\fR\m[] +and attempts to authenticate the given user with the given password\&. If the authentication succeeds then +smbd +attempts to find a UNIX user in the UNIX password database to map the Windows user into\&. If this lookup fails, and +\m[blue]\fBadd user script\fR\m[] +is set then +smbd +will call the specified script +\fIAS ROOT\fR, expanding any +\fI%u\fR +argument to be the user name to create\&. +.sp +If this script successfully creates the user then +smbd +will continue on as though the UNIX user already existed\&. In this way, UNIX users are dynamically created to match existing Windows NT accounts\&. +.sp +See also +\m[blue]\fBsecurity\fR\m[], +\m[blue]\fBpassword server\fR\m[], +\m[blue]\fBdelete user script\fR\m[]\&. +.sp +Default: +\fI\fIadd user script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIadd user script\fR\fR\fI = \fR\fI/usr/local/samba/bin/add_user %u\fR\fI \fR +.RE + +add user to group script (G) +.PP +.RS 4 +Full path to the script that will be called when a user is added to a group using the Windows NT domain administration tools\&. It will be run by +\fBsmbd\fR(8) +\fIAS ROOT\fR\&. Any +\fI%g\fR +will be replaced with the group name and any +\fI%u\fR +will be replaced with the user name\&. +.sp +Note that the +adduser +command used in the example below does not support the used syntax on all systems\&. +.sp +Default: +\fI\fIadd user to group script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIadd user to group script\fR\fR\fI = \fR\fI/usr/sbin/adduser %u %g\fR\fI \fR +.RE + +administrative share (S) +.PP +.RS 4 +If this parameter is set to +\fByes\fR +for a share, then the share will be an administrative share\&. The Administrative Shares are the default network shares created by all Windows NT\-based operating systems\&. These are shares like C$, D$ or ADMIN$\&. The type of these shares is STYPE_DISKTREE_HIDDEN\&. +.sp +See the section below on +\m[blue]\fBsecurity\fR\m[] +for more information about this option\&. +.sp +Default: +\fI\fIadministrative share\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +admin users (S) +.PP +.RS 4 +This is a list of users who will be granted administrative privileges on the share\&. This means that they will do all file operations as the super\-user (root)\&. +.sp +You should use this option very carefully, as any user in this list will be able to do anything they like on the share, irrespective of file permissions\&. +.sp +Default: +\fI\fIadmin users\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIadmin users\fR\fR\fI = \fR\fIjason\fR\fI \fR +.RE + +afs share (S) +.PP +.RS 4 +This parameter controls whether special AFS features are enabled for this share\&. If enabled, it assumes that the directory exported via the +\fIpath\fR +parameter is a local AFS import\&. The special AFS features include the attempt to hand\-craft an AFS token if you enabled \-\-with\-fake\-kaserver in configure\&. +.sp +Default: +\fI\fIafs share\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +afs token lifetime (G) +.PP +.RS 4 +This parameter controls the lifetime of tokens that the AFS fake\-kaserver claims\&. In reality these never expire but this lifetime controls when the afs client will forget the token\&. +.sp +Set this parameter to 0 to get +\fBNEVERDATE\fR\&. +.sp +Default: +\fI\fIafs token lifetime\fR\fR\fI = \fR\fI604800\fR\fI \fR +.RE + +afs username map (G) +.PP +.RS 4 +If you are using the fake kaserver AFS feature, you might want to hand\-craft the usernames you are creating tokens for\&. For example this is necessary if you have users from several domain in your AFS Protection Database\&. One possible scheme to code users as DOMAIN+User as it is done by winbind with the + as a separator\&. +.sp +The mapped user name must contain the cell name to log into, so without setting this parameter there will be no token\&. +.sp +Default: +\fI\fIafs username map\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIafs username map\fR\fR\fI = \fR\fI%u@afs\&.samba\&.org\fR\fI \fR +.RE + +aio max threads (G) +.PP +.RS 4 +The integer parameter specifies the maximum number of threads each smbd process will create when doing parallel asynchronous IO calls\&. If the number of outstanding calls is greater than this number the requests will not be refused but go onto a queue and will be scheduled in turn as outstanding requests complete\&. +.sp +Related command: +\m[blue]\fBaio read size\fR\m[] +.sp +Related command: +\m[blue]\fBaio write size\fR\m[] +.sp +Default: +\fI\fIaio max threads\fR\fR\fI = \fR\fI100\fR\fI \fR +.RE + +aio read size (S) +.PP +.RS 4 +If this integer parameter is set to a non\-zero value, Samba will read from files asynchronously when the request size is bigger than this value\&. Note that it happens only for non\-chained and non\-chaining reads\&. +.sp +The only reasonable values for this parameter are 0 (no async I/O) and 1 (always do async I/O)\&. +.sp +Related command: +\m[blue]\fBaio write size\fR\m[] +.sp +Default: +\fI\fIaio read size\fR\fR\fI = \fR\fI1\fR\fI \fR +.sp +Example: +\fI\fIaio read size\fR\fR\fI = \fR\fI0 # Always do reads synchronously \fR\fI \fR +.RE + +aio write behind (S) +.PP +.RS 4 +If Samba has been built with asynchronous I/O support, Samba will not wait until write requests are finished before returning the result to the client for files listed in this parameter\&. Instead, Samba will immediately return that the write request has been finished successfully, no matter if the operation will succeed or not\&. This might speed up clients without aio support, but is really dangerous, because data could be lost and files could be damaged\&. +.sp +The syntax is identical to the +\m[blue]\fBveto files\fR\m[] +parameter\&. +.sp +Default: +\fI\fIaio write behind\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIaio write behind\fR\fR\fI = \fR\fI/*\&.tmp/\fR\fI \fR +.RE + +aio write size (S) +.PP +.RS 4 +If this integer parameter is set to a non\-zero value, Samba will write to files asynchronously when the request size is bigger than this value\&. Note that it happens only for non\-chained and non\-chaining writes\&. +.sp +The only reasonable values for this parameter are 0 (no async I/O) and 1 (always do async I/O)\&. +.sp +Compared to +\m[blue]\fBaio read size\fR\m[] +this parameter has a smaller effect, most writes should end up in the file system cache\&. Writes that require space allocation might benefit most from going asynchronous\&. +.sp +Related command: +\m[blue]\fBaio read size\fR\m[] +.sp +Default: +\fI\fIaio write size\fR\fR\fI = \fR\fI1\fR\fI \fR +.sp +Example: +\fI\fIaio write size\fR\fR\fI = \fR\fI0 # Always do writes synchronously \fR\fI \fR +.RE + +algorithmic rid base (G) +.PP +.RS 4 +This determines how Samba will use its algorithmic mapping from uids/gid to the RIDs needed to construct NT Security Identifiers\&. +.sp +Setting this option to a larger value could be useful to sites transitioning from WinNT and Win2k, as existing user and group rids would otherwise clash with system users etc\&. +.sp +All UIDs and GIDs must be able to be resolved into SIDs for the correct operation of ACLs on the server\&. As such the algorithmic mapping can\*(Aqt be \*(Aqturned off\*(Aq, but pushing it \*(Aqout of the way\*(Aq should resolve the issues\&. Users and groups can then be assigned \*(Aqlow\*(Aq RIDs in arbitrary\-rid supporting backends\&. +.sp +Default: +\fI\fIalgorithmic rid base\fR\fR\fI = \fR\fI1000\fR\fI \fR +.sp +Example: +\fI\fIalgorithmic rid base\fR\fR\fI = \fR\fI100000\fR\fI \fR +.RE + +allocation roundup size (S) +.PP +.RS 4 +This parameter allows an administrator to tune the allocation size reported to Windows clients\&. This is only useful for old SMB1 clients because modern SMB dialects eliminated that bottleneck and have better performance by default\&. Using this parameter may cause difficulties for some applications, e\&.g\&. MS Visual Studio\&. If the MS Visual Studio compiler starts to crash with an internal error, set this parameter to zero for this share\&. Settings this parameter to a large value can also cause small files to allocate more space on the disk than needed\&. +.sp +This parameter is deprecated and will be removed in one of the next Samba releases\&. +.sp +The integer parameter specifies the roundup size in bytes\&. +.sp +Default: +\fI\fIallocation roundup size\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fIallocation roundup size\fR\fR\fI = \fR\fI1048576 # (to set it to the former default of 1 MiB)\fR\fI \fR +.RE + +allow dcerpc auth level connect (G) +.PP +.RS 4 +This option controls whether DCERPC services are allowed to be used with DCERPC_AUTH_LEVEL_CONNECT, which provides authentication, but no per message integrity nor privacy protection\&. +.sp +Some interfaces like samr, lsarpc and netlogon have a hard\-coded default of +\fBno\fR +and epmapper, mgmt and rpcecho have a hard\-coded default of +\fByes\fR\&. +.sp +The behavior can be overwritten per interface name (e\&.g\&. lsarpc, netlogon, samr, srvsvc, winreg, wkssvc \&.\&.\&.) by using \*(Aqallow dcerpc auth level connect:interface = yes\*(Aq as option\&. +.sp +This option is over\-ridden by the implementation specific restrictions\&. E\&.g\&. the drsuapi and backupkey protocols require DCERPC_AUTH_LEVEL_PRIVACY\&. The dnsserver protocol requires DCERPC_AUTH_LEVEL_INTEGRITY\&. +.sp +Default: +\fI\fIallow dcerpc auth level connect\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIallow dcerpc auth level connect\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +allow dns updates (G) +.PP +.RS 4 +This option determines what kind of updates to the DNS are allowed\&. +.sp +DNS updates can either be disallowed completely by setting it to +\fBdisabled\fR, enabled over secure connections only by setting it to +\fBsecure only\fR +or allowed in all cases by setting it to +\fBnonsecure\fR\&. +.sp +Default: +\fI\fIallow dns updates\fR\fR\fI = \fR\fIsecure only\fR\fI \fR +.sp +Example: +\fI\fIallow dns updates\fR\fR\fI = \fR\fIdisabled\fR\fI \fR +.RE + +allow insecure wide links (G) +.PP +.RS 4 +In normal operation the option +\m[blue]\fBwide links\fR\m[] +which allows the server to follow symlinks outside of a share path is automatically disabled when +\m[blue]\fBunix extensions\fR\m[] +are enabled on a Samba server\&. This is done for security purposes to prevent UNIX clients creating symlinks to areas of the server file system that the administrator does not wish to export\&. +.sp +Setting +\m[blue]\fBallow insecure wide links\fR\m[] +to true disables the link between these two parameters, removing this protection and allowing a site to configure the server to follow symlinks (by setting +\m[blue]\fBwide links\fR\m[] +to "true") even when +\m[blue]\fBunix extensions\fR\m[] +is turned on\&. +.sp +It is not recommended to enable this option unless you fully understand the implications of allowing the server to follow symbolic links created by UNIX clients\&. For most normal Samba configurations this would be considered a security hole and setting this parameter is not recommended\&. +.sp +This option was added at the request of sites who had deliberately set Samba up in this way and needed to continue supporting this functionality without having to patch the Samba code\&. +.sp +Default: +\fI\fIallow insecure wide links\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +allow nt4 crypto (G) +.PP +.RS 4 +This option is deprecated and will be removed in future, as it is a security problem if not set to "no" (which will be the hardcoded behavior in future)\&. +.sp +This option controls whether the netlogon server (currently only in \*(Aqactive directory domain controller\*(Aq mode), will reject clients which do not support NETLOGON_NEG_STRONG_KEYS nor NETLOGON_NEG_SUPPORTS_AES\&. +.sp +This option was added with Samba 4\&.2\&.0\&. It may lock out clients which worked fine with Samba versions up to 4\&.1\&.x\&. as the effective default was "yes" there, while it is "no" now\&. +.sp +If you have clients without RequireStrongKey = 1 in the registry, you may need to set "allow nt4 crypto = yes", until you have fixed all clients\&. +.sp +"allow nt4 crypto = yes" allows weak crypto to be negotiated, maybe via downgrade attacks\&. +.sp +\fIAvoid using this option!\fR +Use explicit \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = yes\fR\m[]\*(Aq instead! Which is available with the patches for +CVE\-2022\-38023 +see +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240 +.sp +Samba will log an error in the log files at log level 0 if legacy a client is rejected or allowed without an explicit, \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = yes\fR\m[]\*(Aq option for the client\&. The message will indicate the explicit \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = yes\fR\m[]\*(Aq line to be added, if the legacy client software requires it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2022_38023:error_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +This allows admins to use "yes" only for a short grace period, in order to collect the explicit \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = yes\fR\m[]\*(Aq options\&. +.sp +This option is over\-ridden by the effective value of \*(Aqyes\*(Aq from the \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT\fR\m[]\*(Aq and/or \*(Aq\m[blue]\fBreject md5 clients\fR\m[]\*(Aq options\&. +.sp +Default: +\fI\fIallow nt4 crypto\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +allow nt4 crypto:COMPUTERACCOUNT (G) +.PP +.RS 4 +If you still have legacy domain members which required \*(Aqallow nt4 crypto = yes\*(Aq, it is possible to specify an explicit exception per computer account by using \*(Aqallow nt4 crypto:COMPUTERACCOUNT = yes\*(Aq as option\&. Note that COMPUTERACCOUNT has to be the sAMAccountName value of the computer account (including the trailing \*(Aq$\*(Aq sign)\&. +.sp +Samba will log a complaint in the log files at log level 0 about the security problem if the option is set to "yes", but the related computer does not require it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2022_38023:warn_about_unused_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +Samba will log a warning in the log files at log level 5, if a setting is still needed for the specified computer account\&. +.sp +See +CVE\-2022\-38023, +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240\&. +.sp +This option overrides the +\m[blue]\fBallow nt4 crypto\fR\m[] +option\&. +.sp +This option is over\-ridden by the effective value of \*(Aqyes\*(Aq from the \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT\fR\m[]\*(Aq and/or \*(Aq\m[blue]\fBreject md5 clients\fR\m[]\*(Aq options\&. +.sp +Which means \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = yes\fR\m[]\*(Aq is only useful in combination with \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq +.sp +.if n \{\ +.RS 4 +.\} +.nf + allow nt4 crypto:LEGACYCOMPUTER1$ = yes + server reject md5 schannel:LEGACYCOMPUTER1$ = no + allow nt4 crypto:NASBOX$ = yes + server reject md5 schannel:NASBOX$ = no + allow nt4 crypto:LEGACYCOMPUTER2$ = yes + server reject md5 schannel:LEGACYCOMPUTER2$ = no + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +allow trusted domains (G) +.PP +.RS 4 +This option only takes effect when the +\m[blue]\fBsecurity\fR\m[] +option is set to +\fBserver\fR, +\fBdomain\fR +or +\fBads\fR\&. If it is set to no, then attempts to connect to a resource from a domain or workgroup other than the one which smbd is running in will fail, even if that domain is trusted by the remote server doing the authentication\&. +.sp +This is useful if you only want your Samba server to serve resources to users in the domain it is a member of\&. As an example, suppose that there are two domains DOMA and DOMB\&. DOMB is trusted by DOMA, which contains the Samba server\&. Under normal circumstances, a user with an account in DOMB can then access the resources of a UNIX account with the same account name on the Samba server even if they do not have an account in DOMA\&. This can make implementing a security boundary difficult\&. +.sp +Default: +\fI\fIallow trusted domains\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +allow unsafe cluster upgrade (G) +.PP +.RS 4 +If set to no (the default), smbd checks at startup if other smbd versions are running in the cluster and refuses to start if so\&. This is done to protect data corruption in internal data structures due to incompatible Samba versions running concurrently in the same cluster\&. Setting this parameter to +yes +disables this safety check\&. +.sp +Default: +\fI\fIallow unsafe cluster upgrade\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +apply group policies (G) +.PP +.RS 4 +This option controls whether winbind will execute the gpupdate command defined in +\m[blue]\fBgpo update command\fR\m[] +on the Group Policy update interval\&. The Group Policy update interval is defined as every 90 minutes, plus a random offset between 0 and 30 minutes\&. This applies Group Policy Machine polices to the client or KDC and machine policies to a server\&. +.sp +Default: +\fI\fIapply group policies\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIapply group policies\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +async dns timeout (G) +.PP +.RS 4 +The number of seconds the asynchronous DNS resolver code in Samba will wait for responses\&. Some of the Samba client library code uses internal asynchronous DNS resolution for A and AAAA records when trying to find Active Directory Domain controllers\&. This value prevents this name resolution code from waiting for DNS server timeouts\&. +.sp +The minimum value of this parameter is clamped at 1 second\&. +.sp +Default: +\fI\fIasync dns timeout\fR\fR\fI = \fR\fI10\fR\fI \fR +.sp +Example: +\fI\fIasync dns timeout\fR\fR\fI = \fR\fI20\fR\fI \fR +.RE + +async smb echo handler (G) +.PP +.RS 4 +This parameter specifies whether Samba should fork the async smb echo handler\&. It can be beneficial if your file system can block syscalls for a very long time\&. In some circumstances, it prolongs the timeout that Windows uses to determine whether a connection is dead\&. This parameter is only for SMB1\&. For SMB2 and above TCP keepalives can be used instead\&. +.sp +Default: +\fI\fIasync smb echo handler\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +auth event notification (G) +.PP +.RS 4 +When enabled, this option causes Samba (acting as an Active Directory Domain Controller) to stream authentication events across the internal message bus\&. Scripts built using Samba\*(Aqs python bindings can listen to these events by registering as the service +auth_event\&. +.sp +This is +\fInot\fR +needed for the audit logging described in +\m[blue]\fBlog level\fR\m[]\&. +.sp +Instead, this should instead be considered a developer option (it assists in the Samba testsuite) rather than a facility for external auditing, as message delivery is not guaranteed (a feature that the testsuite works around)\&. +.sp +The authentication events are also logged via the normal logging methods when the +\m[blue]\fBlog level\fR\m[] +is set appropriately, say to +auth_json_audit:3\&. +.sp +Default: +\fI\fIauth event notification\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +preload +.PP +.RS 4 +This parameter is a synonym for +auto services\&. +.RE + +auto services (G) +.PP +.RS 4 +This is a list of services that you want to be automatically added to the browse lists\&. This is most useful for homes and printers services that would otherwise not be visible\&. +.sp +Note that if you just want all printers in your printcap file loaded then the +\m[blue]\fBload printers\fR\m[] +option is easier\&. +.sp +Default: +\fI\fIauto services\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIauto services\fR\fR\fI = \fR\fIfred lp colorlp\fR\fI \fR +.RE + +available (S) +.PP +.RS 4 +This parameter lets you "turn off" a service\&. If +\fIavailable = no\fR, then +\fIALL\fR +attempts to connect to the service will fail\&. Such failures are logged\&. +.sp +Default: +\fI\fIavailable\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +bind dns directory +.PP +.RS 4 +This parameter is a synonym for +binddns dir\&. +.RE + +binddns dir (G) +.PP +.RS 4 +This parameters defines the directory samba will use to store the configuration files for bind, such as named\&.conf\&. NOTE: The bind dns directory needs to be on the same mount point as the private directory! +.sp +Default: +\fI\fIbinddns dir\fR\fR\fI = \fR\fI/var/lib/samba/bind\-dns\fR\fI \fR +.RE + +bind interfaces only (G) +.PP +.RS 4 +This global parameter allows the Samba admin to limit what interfaces on a machine will serve SMB requests\&. It affects file service +\fBsmbd\fR(8) +and name service +\fBnmbd\fR(8) +in a slightly different ways\&. +.sp +For name service it causes +nmbd +to bind to ports 137 and 138 on the interfaces listed in the +\m[blue]\fBinterfaces\fR\m[] +parameter\&. +nmbd +also binds to the "all addresses" interface (0\&.0\&.0\&.0) on ports 137 and 138 for the purposes of reading broadcast messages\&. If this option is not set then +nmbd +will service name requests on all of these sockets\&. If +\m[blue]\fBbind interfaces only\fR\m[] +is set then +nmbd +will check the source address of any packets coming in on the broadcast sockets and discard any that don\*(Aqt match the broadcast addresses of the interfaces in the +\m[blue]\fBinterfaces\fR\m[] +parameter list\&. As unicast packets are received on the other sockets it allows +nmbd +to refuse to serve names to machines that send packets that arrive through any interfaces not listed in the +\m[blue]\fBinterfaces\fR\m[] +list\&. IP Source address spoofing does defeat this simple check, however, so it must not be used seriously as a security feature for +nmbd\&. +.sp +For file service it causes +\fBsmbd\fR(8) +to bind only to the interface list given in the +\m[blue]\fBinterfaces\fR\m[] +parameter\&. This restricts the networks that +smbd +will serve, to packets coming in on those interfaces\&. Note that you should not use this parameter for machines that are serving PPP or other intermittent or non\-broadcast network interfaces as it will not cope with non\-permanent interfaces\&. +.sp +If +\m[blue]\fBbind interfaces only\fR\m[] +is set and the network address +\fI127\&.0\&.0\&.1\fR +is not added to the +\m[blue]\fBinterfaces\fR\m[] +parameter list +\fBsmbpasswd\fR(8) +may not work as expected due to the reasons covered below\&. +.sp +To change a users SMB password, the +smbpasswd +by default connects to the +\fIlocalhost \- 127\&.0\&.0\&.1\fR +address as an SMB client to issue the password change request\&. If +\m[blue]\fBbind interfaces only\fR\m[] +is set then unless the network address +\fI127\&.0\&.0\&.1\fR +is added to the +\m[blue]\fBinterfaces\fR\m[] +parameter list then +smbpasswd +will fail to connect in it\*(Aqs default mode\&. +smbpasswd +can be forced to use the primary IP interface of the local host by using its +\fBsmbpasswd\fR(8) +\fI\-r \fR\fI\fIremote machine\fR\fR +parameter, with +\fIremote machine\fR +set to the IP name of the primary interface of the local host\&. +.sp +Default: +\fI\fIbind interfaces only\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +blocking locks (S) +.PP +.RS 4 +This parameter controls the behavior of +\fBsmbd\fR(8) +when given a request by a client to obtain a byte range lock on a region of an open file, and the request has a time limit associated with it\&. +.sp +If this parameter is set and the lock range requested cannot be immediately satisfied, samba will internally queue the lock request, and periodically attempt to obtain the lock until the timeout period expires\&. +.sp +If this parameter is set to +\fBno\fR, then samba will behave as previous versions of Samba would and will fail the lock request immediately if the lock range cannot be obtained\&. +.sp +Default: +\fI\fIblocking locks\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +block size (S) +.PP +.RS 4 +This parameter controls the behavior of +\fBsmbd\fR(8) +when reporting disk free sizes\&. By default, this reports a disk block size of 1024 bytes\&. +.sp +Changing this parameter may have some effect on the efficiency of client writes, this is not yet confirmed\&. This parameter was added to allow advanced administrators to change it (usually to a higher value) and test the effect it has on client write performance without re\-compiling the code\&. As this is an experimental option it may be removed in a future release\&. +.sp +Changing this option does not change the disk free reporting size, just the block size unit reported to the client\&. +.sp +Default: +\fI\fIblock size\fR\fR\fI = \fR\fI1024\fR\fI \fR +.sp +Example: +\fI\fIblock size\fR\fR\fI = \fR\fI4096\fR\fI \fR +.RE + +browsable +.PP +.RS 4 +This parameter is a synonym for +browseable\&. +.RE + +browseable (S) +.PP +.RS 4 +This controls whether this share is seen in the list of available shares in a net view and in the browse list\&. +.sp +Default: +\fI\fIbrowseable\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +browse list (G) +.PP +.RS 4 +This controls whether +\fBsmbd\fR(8) +will serve a browse list to a client doing a +NetServerEnum +call\&. Normally set to +\fByes\fR\&. You should never need to change this\&. +.sp +Default: +\fI\fIbrowse list\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +cache directory (G) +.PP +.RS 4 +Usually, most of the TDB files are stored in the +\fIlock directory\fR\&. Since Samba 3\&.4\&.0, it is possible to differentiate between TDB files with persistent data and TDB files with non\-persistent data using the +\fIstate directory\fR +and the +\fIcache directory\fR +options\&. +.sp +This option specifies the directory for storing TDB files containing non\-persistent data that will be kept across service restarts\&. The directory should be placed on persistent storage, but the data can be safely deleted by an administrator\&. +.sp +Default: +\fI\fIcache directory\fR\fR\fI = \fR\fI/var/lib/samba\fR\fI \fR +.sp +Example: +\fI\fIcache directory\fR\fR\fI = \fR\fI/var/run/samba/locks/cache\fR\fI \fR +.RE + +casesignames +.PP +.RS 4 +This parameter is a synonym for +case sensitive\&. +.RE + +case sensitive (S) +.PP +.RS 4 +See the discussion in the section +name mangling\&. +.sp +Default: +\fI\fIcase sensitive\fR\fR\fI = \fR\fIauto\fR\fI \fR +.RE + +change notify (G) +.PP +.RS 4 +This parameter specifies whether Samba should reply to a client\*(Aqs file change notify requests\&. +.sp +You should never need to change this parameter +.sp +Default: +\fI\fIchange notify\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +change share command (G) +.PP +.RS 4 +Samba 2\&.2\&.0 introduced the ability to dynamically add and delete shares via the Windows NT 4\&.0 Server Manager\&. The +\fIchange share command\fR +is used to define an external program or script which will modify an existing service definition in +smb\&.conf\&. +.sp +In order to successfully execute the +\fIchange share command\fR, +smbd +requires that the administrator connects using a root account (i\&.e\&. uid == 0) or has the +SeDiskOperatorPrivilege\&. Scripts defined in the +\fIchange share command\fR +parameter are executed as root\&. +.sp +When executed, +smbd +will automatically invoke the +\fIchange share command\fR +with six parameters\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIconfigFile\fR +\- the location of the global +smb\&.conf +file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshareName\fR +\- the name of the new share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIpathName\fR +\- path to an **existing** directory on disk\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIcomment\fR +\- comment string to associate with the new share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fImax connections\fR +Number of maximum simultaneous connections to this share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fICSC policy\fR +\- client side caching policy in string form\&. Valid values are: manual, documents, programs, disable\&. +.RE +.sp +.RE +This parameter is only used to modify existing file share definitions\&. To modify printer shares, use the "Printers\&.\&.\&." folder as seen when browsing the Samba host\&. +.sp +Default: +\fI\fIchange share command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIchange share command\fR\fR\fI = \fR\fI/usr/local/bin/changeshare\fR\fI \fR +.RE + +check parent directory delete on close (S) +.PP +.RS 4 +A Windows SMB server prevents the client from creating files in a directory that has the delete\-on\-close flag set\&. By default Samba doesn\*(Aqt perform this check as this check is a quite expensive operation in Samba\&. +.sp +Default: +\fI\fIcheck parent directory delete on close\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +check password script (G) +.PP +.RS 4 +The name of a program that can be used to check password complexity\&. The password is sent to the program\*(Aqs standard input\&. +.sp +The program must return 0 on a good password, or any other value if the password is bad\&. In case the password is considered weak (the program does not return 0) the user will be notified and the password change will fail\&. +.sp +In Samba AD, this script will be run +\fIAS ROOT\fR +by +\fBsamba\fR(8) +without any substitutions\&. +.sp +Note that starting with Samba 4\&.11 the following environment variables are exported to the script: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SAMBA_CPS_ACCOUNT_NAME is always present and contains the sAMAccountName of user, the is the same as the %u substitutions in the none AD DC case\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SAMBA_CPS_USER_PRINCIPAL_NAME is optional in the AD DC case if the userPrincipalName is present\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SAMBA_CPS_FULL_NAME is optional if the displayName is present\&. +.RE +.sp +.RE +Note: In the example directory is a sample program called +crackcheck +that uses cracklib to check the password quality\&. +.sp +Default: +\fI\fIcheck password script\fR\fR\fI = \fR\fI # Disabled\fR\fI \fR +.sp +Example: +\fI\fIcheck password script\fR\fR\fI = \fR\fI/usr/local/sbin/crackcheck\fR\fI \fR +.RE + +cldap port (G) +.PP +.RS 4 +This option controls the port used by the CLDAP protocol\&. +.sp +Default: +\fI\fIcldap port\fR\fR\fI = \fR\fI389\fR\fI \fR +.sp +Example: +\fI\fIcldap port\fR\fR\fI = \fR\fI3389\fR\fI \fR +.RE + +client ipc max protocol (G) +.PP +.RS 4 +The value of the parameter (a string) is the highest protocol level that will be supported for IPC$ connections as DCERPC transport\&. +.sp +Normally this option should not be set as the automatic negotiation phase in the SMB protocol takes care of choosing the appropriate protocol\&. +.sp +The value +\fBdefault\fR +refers to the latest supported protocol, currently +\fBSMB3_11\fR\&. +.sp +See +\m[blue]\fBclient max protocol\fR\m[] +for a full list of available protocols\&. The values CORE, COREPLUS, LANMAN1, LANMAN2 are silently upgraded to NT1\&. +.sp +Default: +\fI\fIclient ipc max protocol\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.sp +Example: +\fI\fIclient ipc max protocol\fR\fR\fI = \fR\fISMB2_10\fR\fI \fR +.RE + +client ipc min protocol (G) +.PP +.RS 4 +This setting controls the minimum protocol version that the will be attempted to use for IPC$ connections as DCERPC transport\&. +.sp +Normally this option should not be set as the automatic negotiation phase in the SMB protocol takes care of choosing the appropriate protocol\&. +.sp +The value +\fBdefault\fR +refers to the higher value of +\fBNT1\fR +and the effective value of +\m[blue]\fBclient min protocol\fR\m[]\&. +.sp +See +\m[blue]\fBclient max protocol\fR\m[] +for a full list of available protocols\&. The values CORE, COREPLUS, LANMAN1, LANMAN2 are silently upgraded to NT1\&. +.sp +Default: +\fI\fIclient ipc min protocol\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.sp +Example: +\fI\fIclient ipc min protocol\fR\fR\fI = \fR\fISMB3_11\fR\fI \fR +.RE + +client ipc signing (G) +.PP +.RS 4 +This controls whether the client is allowed or required to use SMB signing for IPC$ connections as DCERPC transport\&. Possible values are +\fIdesired\fR, +\fIrequired\fR +and +\fIdisabled\fR\&. +.sp +When set to required or default, SMB signing is mandatory\&. +.sp +When set to desired, SMB signing is offered, but not enforced and if set to disabled, SMB signing is not offered either\&. +.sp +Connections from winbindd to Active Directory Domain Controllers always enforce signing\&. +.sp +Default: +\fI\fIclient ipc signing\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +client lanman auth (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.13 and support for LanMan (as distinct from NTLM, NTLMv2 or Kerberos) authentication as a client will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +client NTLMv2 auth = yes +will be the enforced behaviour\&. +.sp +This parameter determines whether or not +\fBsmbclient\fR(8) +and other samba client tools will attempt to authenticate itself to servers using the weaker LANMAN password hash\&. If disabled, only server which support NT password hashes (e\&.g\&. Windows NT/2000, Samba, etc\&.\&.\&. but not Windows 95/98) will be able to be connected from the Samba client\&. +.sp +The LANMAN encrypted response is easily broken, due to its case\-insensitive nature, and the choice of algorithm\&. Clients without Windows 95/98 servers are advised to disable this option\&. +.sp +Disabling this option will also disable the +client plaintext auth +option\&. +.sp +Likewise, if the +client ntlmv2 auth +parameter is enabled, then only NTLMv2 logins will be attempted\&. +.sp +Default: +\fI\fIclient lanman auth\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +client ldap sasl wrapping (G) +.PP +.RS 4 +The +\m[blue]\fBclient ldap sasl wrapping\fR\m[] +defines whether ldap traffic will be signed or signed and encrypted (sealed)\&. Possible values are +\fIplain\fR, +\fIsign\fR +and +\fIseal\fR\&. +.sp +The values +\fIsign\fR +and +\fIseal\fR +are only available if Samba has been compiled against a modern OpenLDAP version (2\&.3\&.x or higher)\&. +.sp +This option is needed firstly to secure the privacy of administrative connections from +samba\-tool, including in particular new or reset passwords for users\&. For this reason the default is +\fIseal\fR\&. +.sp +Additionally, +winbindd +and the +net +tool can use LDAP to communicate with Domain Controllers, so this option also controls the level of privacy for those connections\&. All supported AD DC versions will enforce the usage of at least signed LDAP connections by default, so a value of at least +\fIsign\fR +is required in practice\&. +.sp +The default value is +\fIseal\fR\&. That implies synchronizing the time with the KDC in the case of using +\fIKerberos\fR\&. +.sp +Default: +\fI\fIclient ldap sasl wrapping\fR\fR\fI = \fR\fIseal\fR\fI \fR +.RE + +client max protocol (G) +.PP +.RS 4 +The value of the parameter (a string) is the highest protocol level that will be supported by the client\&. +.sp +Possible values are : +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBCORE\fR: Earliest version\&. No concept of user names\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBCOREPLUS\fR: Slight improvements on CORE for efficiency\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBLANMAN1\fR: First +\fImodern\fR +version of the protocol\&. Long filename support\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBLANMAN2\fR: Updates to Lanman1 protocol\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBNT1\fR: Current up to date version of the protocol\&. Used by Windows NT\&. Known as CIFS\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB2\fR: Re\-implementation of the SMB protocol\&. Used by Windows Vista and later versions of Windows\&. SMB2 has sub protocols available\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB2_02\fR: The earliest SMB2 version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB2_10\fR: Windows 7 SMB2 version\&. +.RE +.sp +.RE +By default SMB2 selects the SMB2_10 variant\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3\fR: The same as SMB2\&. Used by Windows 8\&. SMB3 has sub protocols available\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3_00\fR: Windows 8 SMB3 version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3_02\fR: Windows 8\&.1 SMB3 version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3_11\fR: Windows 10 SMB3 version\&. +.RE +.sp +.RE +By default SMB3 selects the SMB3_11 variant\&. +.RE +.sp +.RE +Normally this option should not be set as the automatic negotiation phase in the SMB protocol takes care of choosing the appropriate protocol\&. +.sp +The value +\fBdefault\fR +refers to +\fBSMB3_11\fR\&. +.sp +IPC$ connections for DCERPC e\&.g\&. in winbindd, are handled by the +\m[blue]\fBclient ipc max protocol\fR\m[] +option\&. +.sp +Default: +\fI\fIclient max protocol\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.sp +Example: +\fI\fIclient max protocol\fR\fR\fI = \fR\fILANMAN1\fR\fI \fR +.RE + +client min protocol (G) +.PP +.RS 4 +This setting controls the minimum protocol version that the client will attempt to use\&. +.sp +Normally this option should not be set as the automatic negotiation phase in the SMB protocol takes care of choosing the appropriate protocol unless you connect to a legacy SMB1\-only server\&. +.sp +See +Related command: \m[blue]\fBclient max protocol\fR\m[] +for a full list of available protocols\&. +.sp +IPC$ connections for DCERPC e\&.g\&. in winbindd, are handled by the +\m[blue]\fBclient ipc min protocol\fR\m[] +option\&. +.sp +Note that most command line tools support \-\-option=\*(Aqclient min protocol=NT1\*(Aq, so it may not be required to enable SMB1 protocols globally in smb\&.conf\&. +.sp +Default: +\fI\fIclient min protocol\fR\fR\fI = \fR\fISMB2_02\fR\fI \fR +.sp +Example: +\fI\fIclient min protocol\fR\fR\fI = \fR\fINT1\fR\fI \fR +.RE + +client NTLMv2 auth (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.13 and support for NTLM and LanMan (as distinct from NTLMv2 or Kerberos authentication) will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +client NTLMv2 auth = yes +will be the enforced behaviour\&. +.sp +This parameter determines whether or not +\fBsmbclient\fR(8) +will attempt to authenticate itself to servers using the NTLMv2 encrypted password response\&. +.sp +If enabled, only an NTLMv2 and LMv2 response (both much more secure than earlier versions) will be sent\&. Older servers (including NT4 < SP4, Win9x and Samba 2\&.2) are not compatible with NTLMv2 when not in an NTLMv2 supporting domain +.sp +Similarly, if enabled, NTLMv1, +client lanman auth +and +client plaintext auth +authentication will be disabled\&. This also disables share\-level authentication\&. +.sp +If disabled, an NTLM response (and possibly a LANMAN response) will be sent by the client, depending on the value of +client lanman auth\&. +.sp +Note that Windows Vista and later versions already use NTLMv2 by default, and some sites (particularly those following \*(Aqbest practice\*(Aq security polices) only allow NTLMv2 responses, and not the weaker LM or NTLM\&. +.sp +When +\m[blue]\fBclient use spnego\fR\m[] +is also set to +\fByes\fR +extended security (SPNEGO) is required in order to use NTLMv2 only within NTLMSSP\&. This behavior was introduced with the patches for CVE\-2016\-2111\&. +.sp +Default: +\fI\fIclient NTLMv2 auth\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +client plaintext auth (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.13 and support for plaintext (as distinct from NTLM, NTLMv2 or Kerberos authentication) will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +client plaintext auth = no +will be the enforced behaviour\&. +.sp +Specifies whether a client should send a plaintext password if the server does not support encrypted passwords\&. +.sp +Default: +\fI\fIclient plaintext auth\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +client protection (G) +.PP +.RS 4 +This parameter defines which protection Samba client tools should use by default\&. +.sp +Possible client settings are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdefault\fR +\- Use the individual default values of the options: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIclient signing\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIclient smb encrypt\fR +.RE +.sp +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIplain\fR +\- This will send everything just as plaintext, signing or encryption are turned off\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsign\fR +\- This will enable integrity checking\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIencrypt\fR +\- This will enable integrity checks and force encryption for privacy\&. +.RE +.sp +.RE +Default: +\fI\fIclient protection\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +client schannel (G) +.PP +.RS 4 +This option is deprecated with Samba 4\&.8 and will be removed in future\&. At the same time the default changed to yes, which will be the hardcoded behavior in future\&. +.sp +This controls whether the client offers or even demands the use of the netlogon schannel\&. +\m[blue]\fBclient schannel = no\fR\m[] +does not offer the schannel, +\m[blue]\fBclient schannel = auto\fR\m[] +offers the schannel but does not enforce it, and +\m[blue]\fBclient schannel = yes\fR\m[] +denies access if the server is not able to speak netlogon schannel\&. +.sp +Note that for active directory domains this is hardcoded to +\m[blue]\fBclient schannel = yes\fR\m[]\&. +.sp +This option is over\-ridden by the +\m[blue]\fBrequire strong key\fR\m[] +option\&. +.sp +Default: +\fI\fIclient schannel\fR\fR\fI = \fR\fIyes\fR\fI \fR +.sp +Example: +\fI\fIclient schannel\fR\fR\fI = \fR\fIauto\fR\fI \fR +.RE + +client signing (G) +.PP +.RS 4 +This controls whether the client is allowed or required to use SMB signing\&. Possible values are +\fIdesired\fR, +\fIrequired\fR +and +\fIdisabled\fR\&. +.sp +When set to desired or default, SMB signing is offered, but not enforced\&. +.sp +When set to required, SMB signing is mandatory and if set to disabled, SMB signing is not offered either\&. +.sp +IPC$ connections for DCERPC e\&.g\&. in winbindd, are handled by the +\m[blue]\fBclient ipc signing\fR\m[] +option\&. +.sp +Default: +\fI\fIclient signing\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +client smb encrypt (G) +.PP +.RS 4 +This parameter controls whether a client should try or is required to use SMB encryption\&. It has different effects depending on whether the connection uses SMB1 or SMB3: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the connection uses SMB1, then this option controls the use of a Samba\-specific extension to the SMB protocol introduced in Samba 3\&.2 that makes use of the Unix extensions\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the connection uses SMB2 or newer, then this option controls the use of the SMB\-level encryption that is supported in SMB version 3\&.0 and above and available in Windows 8 and newer\&. +.RE +.sp +.RE +This parameter can be set globally\&. Possible values are +\fIoff\fR, +\fIif_required\fR, +\fIdesired\fR, and +\fIrequired\fR\&. A special value is +\fIdefault\fR +which is the implicit default setting of +\fIif_required\fR\&. +.PP +\fIEffects for SMB1\fR +.RS 4 +The Samba\-specific encryption of SMB1 connections is an extension to the SMB protocol negotiated as part of the UNIX extensions\&. SMB encryption uses the GSSAPI (SSPI on Windows) ability to encrypt and sign every request/response in a SMB protocol stream\&. When enabled it provides a secure method of SMB/CIFS communication, similar to an ssh protected session, but using SMB/CIFS authentication to negotiate encryption and signing keys\&. Currently this is only supported smbclient of by Samba 3\&.2 and newer\&. Windows does not support this feature\&. +.sp +When set to default, SMB encryption is probed, but not enforced\&. When set to required, SMB encryption is required and if set to disabled, SMB encryption can not be negotiated\&. +.RE +.PP +\fIEffects for SMB3 and newer\fR +.RS 4 +Native SMB transport encryption is available in SMB version 3\&.0 or newer\&. It is only used by Samba if +\fIclient max protocol\fR +is set to +\fISMB3\fR +or newer\&. +.sp +These features can be controlled with settings of +\fIclient smb encrypt\fR +as follows: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Leaving it as default, explicitly setting +\fIdefault\fR, or setting it to +\fIif_required\fR +globally will enable negotiation of encryption but will not turn on data encryption globally\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIdesired\fR +globally will enable negotiation and will turn on data encryption on sessions and share connections for those servers that support it\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIrequired\fR +globally will enable negotiation and turn on data encryption on sessions and share connections\&. Clients that do not support encryption will be denied access to the server\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIoff\fR +globally will completely disable the encryption feature for all connections\&. +.RE +.sp +.RE +.RE +.sp +Default: +\fI\fIclient smb encrypt\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +client smb3 encryption algorithms (G) +.PP +.RS 4 +This parameter specifies the availability and order of encryption algorithms which are available for negotiation in the SMB3_11 dialect\&. +.sp +It is also possible to remove individual algorithms from the default list, by prefixing them with \*(Aq\-\*(Aq\&. This can avoid having to specify a hardcoded list\&. +.sp +Note: that the removal of AES\-128\-CCM from the list will result in SMB3_00 and SMB3_02 being unavailable, as it is the default and only available algorithm for these dialects\&. +.sp +Default: +\fI\fIclient smb3 encryption algorithms\fR\fR\fI = \fR\fIAES\-128\-GCM, AES\-128\-CCM, AES\-256\-GCM, AES\-256\-CCM\fR\fI \fR +.sp +Example: +\fI\fIclient smb3 encryption algorithms\fR\fR\fI = \fR\fIAES\-256\-GCM\fR\fI \fR +.sp +Example: +\fI\fIclient smb3 encryption algorithms\fR\fR\fI = \fR\fI\-AES\-128\-GCM \-AES\-128\-CCM\fR\fI \fR +.RE + +client smb3 signing algorithms (G) +.PP +.RS 4 +This parameter specifies the availability and order of signing algorithms which are available for negotiation in the SMB3_11 dialect\&. +.sp +It is also possible to remove individual algorithms from the default list, by prefixing them with \*(Aq\-\*(Aq\&. This can avoid having to specify a hardcoded list\&. +.sp +Note: that the removal of AES\-128\-CMAC from the list will result in SMB3_00 and SMB3_02 being unavailable, and the removal of HMAC\-SHA256 will result in SMB2_02 and SMB2_10 being unavailable, as these are the default and only available algorithms for these dialects\&. +.sp +Default: +\fI\fIclient smb3 signing algorithms\fR\fR\fI = \fR\fIAES\-128\-GMAC, AES\-128\-CMAC, HMAC\-SHA256\fR\fI \fR +.sp +Example: +\fI\fIclient smb3 signing algorithms\fR\fR\fI = \fR\fIAES\-128\-CMAC, HMAC\-SHA256\fR\fI \fR +.sp +Example: +\fI\fIclient smb3 signing algorithms\fR\fR\fI = \fR\fI\-AES\-128\-CMAC\fR\fI \fR +.RE + +client use kerberos (G) +.PP +.RS 4 +This parameter determines whether Samba client tools will try to authenticate using Kerberos\&. For Kerberos authentication you need to use dns names instead of IP addresses when connecting to a service\&. +.sp +Possible option settings are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdesired\fR +\- Kerberos authentication will be tried first and if it fails it automatically fallback to NTLM\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIrequired\fR +\- Kerberos authentication will be required\&. There will be no fallback to NTLM or a different alternative\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIoff\fR +\- Don\*(Aqt use Kerberos, use NTLM instead or another alternative\&. +.RE +.sp +.RE +In case that weak cryptography is not allowed (e\&.g\&. FIPS mode) the default will be forced to +\fIrequired\fR\&. +.sp +Default: +\fI\fIclient use kerberos\fR\fR\fI = \fR\fIdesired\fR\fI \fR +.RE + +client use spnego principal (G) +.PP +.RS 4 +This parameter determines whether or not +\fBsmbclient\fR(8) +and other samba components acting as a client will attempt to use the server\-supplied principal sometimes given in the SPNEGO exchange\&. +.sp +If enabled, Samba can attempt to use Kerberos to contact servers known only by IP address\&. Kerberos relies on names, so ordinarily cannot function in this situation\&. +.sp +This is a VERY BAD IDEA for security reasons, and so this parameter SHOULD NOT BE USED\&. It will be removed in a future version of Samba\&. +.sp +If disabled, Samba will use the name used to look up the server when asking the KDC for a ticket\&. This avoids situations where a server may impersonate another, soliciting authentication as one principal while being known on the network as another\&. +.sp +Note that Windows XP SP2 and later versions already follow this behaviour, and Windows Vista and later servers no longer supply this \*(Aqrfc4178 hint\*(Aq principal on the server side\&. +.sp +This parameter is deprecated in Samba 4\&.2\&.1 and will be removed (along with the functionality) in a later release of Samba\&. +.sp +Default: +\fI\fIclient use spnego principal\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +client use spnego (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.13 and support for NTLMv2, NTLM and LanMan authentication outside NTLMSSP will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +client use spnego = yes +will be the enforced behaviour\&. +.sp +This variable controls whether Samba clients will try to use Simple and Protected NEGOtiation (as specified by rfc2478) with supporting servers (including WindowsXP, Windows2000 and Samba 3\&.0) to agree upon an authentication mechanism\&. This enables Kerberos authentication in particular\&. +.sp +When +\m[blue]\fBclient NTLMv2 auth\fR\m[] +is also set to +\fByes\fR +extended security (SPNEGO) is required in order to use NTLMv2 only within NTLMSSP\&. This behavior was introduced with the patches for CVE\-2016\-2111\&. +.sp +Default: +\fI\fIclient use spnego\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +cluster addresses (G) +.PP +.RS 4 +With this parameter you can add additional addresses that nmbd will register with a WINS server\&. Similarly, these addresses will be registered by default when +\fInet ads dns register\fR +is called with +\m[blue]\fBclustering = yes\fR\m[] +configured\&. +.sp +Default: +\fI\fIcluster addresses\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIcluster addresses\fR\fR\fI = \fR\fI10\&.0\&.0\&.1 10\&.0\&.0\&.2 10\&.0\&.0\&.3\fR\fI \fR +.RE + +clustering (G) +.PP +.RS 4 +This parameter specifies whether Samba should contact ctdb for accessing its tdb files and use ctdb as a backend for its messaging backend\&. +.sp +Set this parameter to +yes +only if you have a cluster setup with ctdb running\&. +.sp +Default: +\fI\fIclustering\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +comment (S) +.PP +.RS 4 +This is a text field that is seen next to a share when a client does a queries the server, either via the network neighborhood or via +net view +to list what shares are available\&. +.sp +If you want to set the string that is displayed next to the machine name then see the +\m[blue]\fBserver string\fR\m[] +parameter\&. +.sp +Default: +\fI\fIcomment\fR\fR\fI = \fR\fI # No comment\fR\fI \fR +.sp +Example: +\fI\fIcomment\fR\fR\fI = \fR\fIFred\*(Aqs Files\fR\fI \fR +.RE + +config backend (G) +.PP +.RS 4 +This controls the backend for storing the configuration\&. Possible values are +\fIfile\fR +(the default) and +\fIregistry\fR\&. When +\m[blue]\fBconfig backend = registry\fR\m[] +is encountered while loading +\fIsmb\&.conf\fR, the configuration read so far is dropped and the global options are read from registry instead\&. So this triggers a registry only configuration\&. Share definitions are not read immediately but instead +\fIregistry shares\fR +is set to +\fIyes\fR\&. +.sp +Note: This option can not be set inside the registry configuration itself\&. +.sp +Default: +\fI\fIconfig backend\fR\fR\fI = \fR\fIfile\fR\fI \fR +.sp +Example: +\fI\fIconfig backend\fR\fR\fI = \fR\fIregistry\fR\fI \fR +.RE + +config file (G) +.PP +.RS 4 +This allows you to override the config file to use, instead of the default (usually +smb\&.conf)\&. There is a chicken and egg problem here as this option is set in the config file! +.sp +For this reason, if the name of the config file has changed when the parameters are loaded then it will reload them from the new config file\&. +.sp +This option takes the usual substitutions, which can be very useful\&. +.sp +If the config file doesn\*(Aqt exist then it won\*(Aqt be loaded (allowing you to special case the config files of just a few clients)\&. +.sp +\fINo default\fR +.sp +Example: +\fI\fIconfig file\fR\fR\fI = \fR\fI/usr/local/samba/lib/smb\&.conf\&.%m\fR\fI \fR +.RE + +copy (S) +.PP +.RS 4 +This parameter allows you to "clone" service entries\&. The specified service is simply duplicated under the current service\*(Aqs name\&. Any parameters specified in the current section will override those in the section being copied\&. +.sp +This feature lets you set up a \*(Aqtemplate\*(Aq service and create similar services easily\&. Note that the service being copied must occur earlier in the configuration file than the service doing the copying\&. +.sp +Default: +\fI\fIcopy\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIcopy\fR\fR\fI = \fR\fIotherservice\fR\fI \fR +.RE + +create krb5 conf (G) +.PP +.RS 4 +Setting this parameter to +no +prevents winbind from creating custom krb5\&.conf files\&. Winbind normally does this because the krb5 libraries are not AD\-site\-aware and thus would pick any domain controller out of potentially very many\&. Winbind is site\-aware and makes the krb5 libraries use a local DC by creating its own krb5\&.conf files\&. +.sp +Preventing winbind from doing this might become necessary if you have to add special options into your system\-krb5\&.conf that winbind does not see\&. +.sp +Default: +\fI\fIcreate krb5 conf\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +create mode +.PP +.RS 4 +This parameter is a synonym for +create mask\&. +.RE + +create mask (S) +.PP +.RS 4 +When a file is created, the necessary permissions are calculated according to the mapping from DOS modes to UNIX permissions, and the resulting UNIX mode is then bit\-wise \*(AqAND\*(Aqed with this parameter\&. This parameter may be thought of as a bit\-wise MASK for the UNIX modes of a file\&. Any bit +\fInot\fR +set here will be removed from the modes set on a file when it is created\&. +.sp +The default value of this parameter removes the +group +and +other +write and execute bits from the UNIX modes\&. +.sp +Following this Samba will bit\-wise \*(AqOR\*(Aq the UNIX mode created from this parameter with the value of the +\m[blue]\fBforce create mode\fR\m[] +parameter which is set to 000 by default\&. +.sp +This parameter does not affect directory masks\&. See the parameter +\m[blue]\fBdirectory mask\fR\m[] +for details\&. +.sp +Default: +\fI\fIcreate mask\fR\fR\fI = \fR\fI0744\fR\fI \fR +.sp +Example: +\fI\fIcreate mask\fR\fR\fI = \fR\fI0775\fR\fI \fR +.RE + +csc policy (S) +.PP +.RS 4 +This stands for +\fIclient\-side caching policy\fR, and specifies how clients capable of offline caching will cache the files in the share\&. The valid values are: manual, documents, programs, disable\&. +.sp +These values correspond to those used on Windows servers\&. +.sp +For example, shares containing roaming profiles can have offline caching disabled using +\m[blue]\fBcsc policy = disable\fR\m[]\&. +.sp +Default: +\fI\fIcsc policy\fR\fR\fI = \fR\fImanual\fR\fI \fR +.sp +Example: +\fI\fIcsc policy\fR\fR\fI = \fR\fIprograms\fR\fI \fR +.RE + +ctdbd socket (G) +.PP +.RS 4 +If you set +clustering=yes, you need to tell Samba where ctdbd listens on its unix domain socket\&. The default path as of ctdb 1\&.0 is /tmp/ctdb\&.socket which you have to explicitly set for Samba in smb\&.conf\&. +.sp +Default: +\fI\fIctdbd socket\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIctdbd socket\fR\fR\fI = \fR\fI/tmp/ctdb\&.socket\fR\fI \fR +.RE + +ctdb locktime warn threshold (G) +.PP +.RS 4 +In a cluster environment using Samba and ctdb it is critical that locks on central ctdb\-hosted databases like locking\&.tdb are not held for long\&. With the current Samba architecture it happens that Samba takes a lock and while holding that lock makes file system calls into the shared cluster file system\&. This option makes Samba warn if it detects that it has held locks for the specified number of milliseconds\&. If this happens, +\fIsmbd\fR +will emit a debug level 0 message into its logs and potentially into syslog\&. The most likely reason for such a log message is that an operation of the cluster file system Samba exports is taking longer than expected\&. The messages are meant as a debugging aid for potential cluster problems\&. +.sp +The default value of 0 disables this logging\&. +.sp +Default: +\fI\fIctdb locktime warn threshold\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +ctdb timeout (G) +.PP +.RS 4 +This parameter specifies a timeout in milliseconds for the connection between Samba and ctdb\&. It is only valid if you have compiled Samba with clustering and if you have set +\fIclustering=yes\fR\&. +.sp +When something in the cluster blocks, it can happen that we wait indefinitely long for ctdb, just adding to the blocking condition\&. In a well\-running cluster this should never happen, but there are too many components in a cluster that might have hickups\&. Choosing the right balance for this value is very tricky, because on a busy cluster long service times to transfer something across the cluster might be valid\&. Setting it too short will degrade the service your cluster presents, setting it too long might make the cluster itself not recover from something severely broken for too long\&. +.sp +Be aware that if you set this parameter, this needs to be in the file smb\&.conf, it is not really helpful to put this into a registry configuration (typical on a cluster), because to access the registry contact to ctdb is required\&. +.sp +Setting +\fIctdb timeout\fR +to n makes any process waiting longer than n milliseconds for a reply by the cluster panic\&. Setting it to 0 (the default) makes Samba block forever, which is the highly recommended default\&. +.sp +Default: +\fI\fIctdb timeout\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +cups connection timeout (G) +.PP +.RS 4 +This parameter is only applicable if +\m[blue]\fBprinting\fR\m[] +is set to +\fBcups\fR\&. +.sp +If set, this option specifies the number of seconds that smbd will wait whilst trying to contact to the CUPS server\&. The connection will fail if it takes longer than this number of seconds\&. +.sp +Default: +\fI\fIcups connection timeout\fR\fR\fI = \fR\fI30\fR\fI \fR +.sp +Example: +\fI\fIcups connection timeout\fR\fR\fI = \fR\fI60\fR\fI \fR +.RE + +cups encrypt (G) +.PP +.RS 4 +This parameter is only applicable if +\m[blue]\fBprinting\fR\m[] +is set to +\fBcups\fR +and if you use CUPS newer than 1\&.0\&.x\&.It is used to define whether or not Samba should use encryption when talking to the CUPS server\&. Possible values are +\fIauto\fR, +\fIyes\fR +and +\fIno\fR +.sp +When set to auto we will try to do a TLS handshake on each CUPS connection setup\&. If that fails, we will fall back to unencrypted operation\&. +.sp +Default: +\fI\fIcups encrypt\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +cups options (S) +.PP +.RS 4 +This parameter is only applicable if +\m[blue]\fBprinting\fR\m[] +is set to +\fBcups\fR\&. Its value is a free form string of options passed directly to the cups library\&. +.sp +You can pass any generic print option known to CUPS (as listed in the CUPS "Software Users\*(Aq Manual")\&. You can also pass any printer specific option (as listed in "lpoptions \-d printername \-l") valid for the target queue\&. Multiple parameters should be space\-delimited name/value pairs according to the PAPI text option ABNF specification\&. Collection values ("name={a=\&.\&.\&. b=\&.\&.\&. c=\&.\&.\&.}") are stored with the curley brackets intact\&. +.sp +You should set this parameter to +\fBraw\fR +if your CUPS server +error_log +file contains messages such as "Unsupported format \*(Aqapplication/octet\-stream\*(Aq" when printing from a Windows client through Samba\&. It is no longer necessary to enable system wide raw printing in +/etc/cups/mime\&.{convs,types}\&. +.sp +Default: +\fI\fIcups options\fR\fR\fI = \fR\fI""\fR\fI \fR +.sp +Example: +\fI\fIcups options\fR\fR\fI = \fR\fI"raw media=a4"\fR\fI \fR +.RE + +cups server (G) +.PP +.RS 4 +This parameter is only applicable if +\m[blue]\fBprinting\fR\m[] +is set to +\fBcups\fR\&. +.sp +If set, this option overrides the ServerName option in the CUPS +client\&.conf\&. This is necessary if you have virtual samba servers that connect to different CUPS daemons\&. +.sp +Optionally, a port can be specified by separating the server name and port number with a colon\&. If no port was specified, the default port for IPP (631) will be used\&. +.sp +Default: +\fI\fIcups server\fR\fR\fI = \fR\fI""\fR\fI \fR +.sp +Example: +\fI\fIcups server\fR\fR\fI = \fR\fImycupsserver\fR\fI \fR +.sp +Example: +\fI\fIcups server\fR\fR\fI = \fR\fImycupsserver:1631\fR\fI \fR +.RE + +dcerpc endpoint servers (G) +.PP +.RS 4 +Specifies which DCE/RPC endpoint servers should be run\&. +.sp +Default: +\fI\fIdcerpc endpoint servers\fR\fR\fI = \fR\fIepmapper, wkssvc, samr, netlogon, lsarpc, drsuapi, dssetup, unixinfo, browser, eventlog6, backupkey, dnsserver\fR\fI \fR +.sp +Example: +\fI\fIdcerpc endpoint servers\fR\fR\fI = \fR\fIrpcecho\fR\fI \fR +.RE + +deadtime (G) +.PP +.RS 4 +The value of the parameter (a decimal integer) represents the number of minutes of inactivity before a connection is considered dead, and it is disconnected\&. The deadtime only takes effect if the number of open files is zero\&. +.sp +This is useful to stop a server\*(Aqs resources being exhausted by a large number of inactive connections\&. +.sp +Most clients have an auto\-reconnect feature when a connection is broken so in most cases this parameter should be transparent to users\&. +.sp +Using this parameter with a timeout of a few minutes is recommended for most systems\&. +.sp +A deadtime of zero indicates that no auto\-disconnection should be performed\&. +.sp +Default: +\fI\fIdeadtime\fR\fR\fI = \fR\fI10080\fR\fI \fR +.sp +Example: +\fI\fIdeadtime\fR\fR\fI = \fR\fI15\fR\fI \fR +.RE + +debug class (G) +.PP +.RS 4 +With this boolean parameter enabled, the debug class (DBGC_CLASS) will be displayed in the debug header\&. +.sp +For more information about currently available debug classes, see section about +\m[blue]\fBlog level\fR\m[]\&. +.sp +Default: +\fI\fIdebug class\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +debug encryption (G) +.PP +.RS 4 +This option will make the smbd server and client code using libsmb (smbclient, smbget, smbspool, \&.\&.\&.) dump the Session Id, the decrypted Session Key, the Signing Key, the Application Key, the Encryption Key and the Decryption Key every time an SMB3+ session is established\&. This information will be printed in logs at level 0\&. +.sp +Warning: access to these values enables the decryption of any encrypted traffic on the dumped sessions\&. This option should only be enabled for debugging purposes\&. +.sp +Default: +\fI\fIdebug encryption\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +debug hires timestamp (G) +.PP +.RS 4 +Sometimes the timestamps in the log messages are needed with a resolution of higher that seconds, this boolean parameter adds microsecond resolution to the timestamp message header when turned on\&. +.sp +Note that the parameter +\m[blue]\fBdebug timestamp\fR\m[] +or +\m[blue]\fBdebug syslog format\fR\m[] +must be on for this to have an effect\&. +.sp +Default: +\fI\fIdebug hires timestamp\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +debug pid (G) +.PP +.RS 4 +When using only one log file for more then one forked +\fBsmbd\fR(8)\-process there may be hard to follow which process outputs which message\&. This boolean parameter is adds the process\-id to the timestamp message headers in the logfile when turned on\&. +.sp +Note that the parameter +\m[blue]\fBdebug timestamp\fR\m[] +must be on for this to have an effect\&. +.sp +Default: +\fI\fIdebug pid\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +debug prefix timestamp (G) +.PP +.RS 4 +With this option enabled, the timestamp message header is prefixed to the debug message without the filename and function information that is included with the +\m[blue]\fBdebug timestamp\fR\m[] +parameter\&. This gives timestamps to the messages without adding an additional line\&. +.sp +Note that this parameter overrides the +\m[blue]\fBdebug timestamp\fR\m[] +parameter\&. +.sp +Default: +\fI\fIdebug prefix timestamp\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +debug syslog format (G) +.PP +.RS 4 +With this option enabled (\fByes\fR +(alias +\fBin_logs\fR) or +\fBalways\fR), debug messages are printed in a single\-line format like that traditionally produced by syslog\&. The timestamp consists of an abbreviated month, space\-padded date, and time including seconds\&. This is followed by the hostname and the program name, with the process\-ID in square brackets\&. +.sp +The value +\fBalways\fR +produces this log format even to +\fBSTDOUT\fR +or +\fBSTDERR\fR +.sp +The value +\fBno\fR +defers to other parameters and typically produces traditional two\-line Samba logs to log files\&. +.sp +If +\m[blue]\fBdebug hires timestamp\fR\m[] +is also enabled then an RFC5424 timestamp is used instead\&. +.sp +Default: +\fI\fIdebug syslog format\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winbind debug traceid (G) +.PP +.RS 4 +With this boolean parameter enabled, the per request unique traceid will be displayed in the debug header for winbind processes\&. +.sp +Default: +\fI\fIwinbind debug traceid\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +debug uid (G) +.PP +.RS 4 +Samba is sometimes run as root and sometime run as the connected user, this boolean parameter inserts the current euid, egid, uid and gid to the timestamp message headers in the log file if turned on\&. +.sp +Note that the parameter +\m[blue]\fBdebug timestamp\fR\m[] +must be on for this to have an effect\&. +.sp +Default: +\fI\fIdebug uid\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dedicated keytab file (G) +.PP +.RS 4 +Specifies the absolute path to the kerberos keytab file when +\m[blue]\fBkerberos method\fR\m[] +is set to "dedicated keytab"\&. +.sp +Default: +\fI\fIdedicated keytab file\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdedicated keytab file\fR\fR\fI = \fR\fI/usr/local/etc/krb5\&.keytab\fR\fI \fR +.RE + +default case (S) +.PP +.RS 4 +See the section on +name mangling\&. Also note the +\m[blue]\fBshort preserve case\fR\m[] +parameter\&. +.sp +Default: +\fI\fIdefault case\fR\fR\fI = \fR\fIlower\fR\fI \fR +.RE + +default devmode (S) +.PP +.RS 4 +This parameter is only applicable to +\m[blue]\fBprintable\fR\m[] +services\&. When smbd is serving Printer Drivers to Windows NT/2k/XP clients, each printer on the Samba server has a Device Mode which defines things such as paper size and orientation and duplex settings\&. The device mode can only correctly be generated by the printer driver itself (which can only be executed on a Win32 platform)\&. Because smbd is unable to execute the driver code to generate the device mode, the default behavior is to set this field to NULL\&. +.sp +Most problems with serving printer drivers to Windows NT/2k/XP clients can be traced to a problem with the generated device mode\&. Certain drivers will do things such as crashing the client\*(Aqs Explorer\&.exe with a NULL devmode\&. However, other printer drivers can cause the client\*(Aqs spooler service (spoolsv\&.exe) to die if the devmode was not created by the driver itself (i\&.e\&. smbd generates a default devmode)\&. +.sp +This parameter should be used with care and tested with the printer driver in question\&. It is better to leave the device mode to NULL and let the Windows client set the correct values\&. Because drivers do not do this all the time, setting +default devmode = yes +will instruct smbd to generate a default one\&. +.sp +For more information on Windows NT/2k printing and Device Modes, see the +MSDN documentation\&. +.sp +Default: +\fI\fIdefault devmode\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +default +.PP +.RS 4 +This parameter is a synonym for +default service\&. +.RE + +default service (G) +.PP +.RS 4 +This parameter specifies the name of a service which will be connected to if the service actually requested cannot be found\&. Note that the square brackets are +\fINOT\fR +given in the parameter value (see example below)\&. +.sp +There is no default value for this parameter\&. If this parameter is not given, attempting to connect to a nonexistent service results in an error\&. +.sp +Typically the default service would be a +\m[blue]\fBguest ok\fR\m[], +\m[blue]\fBread only\fR\m[] +service\&. +.sp +Also note that the apparent service name will be changed to equal that of the requested service, this is very useful as it allows you to use macros like +\fI%S\fR +to make a wildcard service\&. +.sp +Note also that any "_" characters in the name of the service used in the default service will get mapped to a "/"\&. This allows for interesting things\&. +.sp +Default: +\fI\fIdefault service\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdefault service\fR\fR\fI = \fR\fIpub\fR\fI \fR +.RE + +defer sharing violations (G) +.PP +.RS 4 +Windows allows specifying how a file will be shared with other processes when it is opened\&. Sharing violations occur when a file is opened by a different process using options that violate the share settings specified by other processes\&. This parameter causes smbd to act as a Windows server does, and defer returning a "sharing violation" error message for up to one second, allowing the client to close the file causing the violation in the meantime\&. +.sp +UNIX by default does not have this behaviour\&. +.sp +There should be no reason to turn off this parameter, as it is designed to enable Samba to more correctly emulate Windows\&. +.sp +Default: +\fI\fIdefer sharing violations\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +delete group script (G) +.PP +.RS 4 +This is the full pathname to a script that will be run +\fIAS ROOT\fR +by +\fBsmbd\fR(8) +when a group is requested to be deleted\&. It will expand any +\fI%g\fR +to the group name passed\&. This script is only useful for installations using the Windows NT domain administration tools\&. +.sp +Default: +\fI\fIdelete group script\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +deleteprinter command (G) +.PP +.RS 4 +With the introduction of MS\-RPC based printer support for Windows NT/2000 clients in Samba 2\&.2, it is now possible to delete a printer at run time by issuing the DeletePrinter() RPC call\&. +.sp +For a Samba host this means that the printer must be physically deleted from the underlying printing system\&. The +\m[blue]\fBdeleteprinter command\fR\m[] +defines a script to be run which will perform the necessary operations for removing the printer from the print system and from +smb\&.conf\&. +.sp +The +\m[blue]\fBdeleteprinter command\fR\m[] +is automatically called with only one parameter: +\m[blue]\fBprinter name\fR\m[]\&. +.sp +Once the +\m[blue]\fBdeleteprinter command\fR\m[] +has been executed, +smbd +will reparse the +smb\&.conf +to check that the associated printer no longer exists\&. If the sharename is still valid, then +smbd +will return an ACCESS_DENIED error to the client\&. +.sp +Default: +\fI\fIdeleteprinter command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdeleteprinter command\fR\fR\fI = \fR\fI/usr/bin/removeprinter\fR\fI \fR +.RE + +delete readonly (S) +.PP +.RS 4 +This parameter allows readonly files to be deleted\&. This is not normal DOS semantics, but is allowed by UNIX\&. +.sp +This option may be useful for running applications such as rcs, where UNIX file ownership prevents changing file permissions, and DOS semantics prevent deletion of a read only file\&. +.sp +Default: +\fI\fIdelete readonly\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +delete share command (G) +.PP +.RS 4 +Samba 2\&.2\&.0 introduced the ability to dynamically add and delete shares via the Windows NT 4\&.0 Server Manager\&. The +\fIdelete share command\fR +is used to define an external program or script which will remove an existing service definition from +smb\&.conf\&. +.sp +In order to successfully execute the +\fIdelete share command\fR, +smbd +requires that the administrator connects using a root account (i\&.e\&. uid == 0) or has the +SeDiskOperatorPrivilege\&. Scripts defined in the +\fIdelete share command\fR +parameter are executed as root\&. +.sp +When executed, +smbd +will automatically invoke the +\fIdelete share command\fR +with two parameters\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIconfigFile\fR +\- the location of the global +smb\&.conf +file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshareName\fR +\- the name of the existing service\&. +.RE +.sp +.RE +This parameter is only used to remove file shares\&. To delete printer shares, see the +\m[blue]\fBdeleteprinter command\fR\m[]\&. +.sp +Default: +\fI\fIdelete share command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdelete share command\fR\fR\fI = \fR\fI/usr/local/bin/delshare\fR\fI \fR +.RE + +delete user from group script (G) +.PP +.RS 4 +Full path to the script that will be called when a user is removed from a group using the Windows NT domain administration tools\&. It will be run by +\fBsmbd\fR(8) +\fIAS ROOT\fR\&. Any +\fI%g\fR +will be replaced with the group name and any +\fI%u\fR +will be replaced with the user name\&. +.sp +Default: +\fI\fIdelete user from group script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdelete user from group script\fR\fR\fI = \fR\fI/usr/sbin/deluser %u %g\fR\fI \fR +.RE + +delete user script (G) +.PP +.RS 4 +This is the full pathname to a script that will be run by +\fBsmbd\fR(8) +when managing users with remote RPC (NT) tools\&. +.sp +This script is called when a remote client removes a user from the server, normally using \*(AqUser Manager for Domains\*(Aq or +rpcclient\&. +.sp +This script should delete the given UNIX username\&. +.sp +Default: +\fI\fIdelete user script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdelete user script\fR\fR\fI = \fR\fI/usr/local/samba/bin/del_user %u\fR\fI \fR +.RE + +delete veto files (S) +.PP +.RS 4 +This option is used when Samba is attempting to delete a directory that contains one or more vetoed files or directories or non\-visible files or directories (such as dangling symlinks that point nowhere)\&. (see the +\m[blue]\fBveto files\fR\m[], +\m[blue]\fBhide special files\fR\m[], +\m[blue]\fBhide unreadable\fR\m[], +\m[blue]\fBhide unwriteable files\fR\m[] +options)\&. If this option is set to +\fBno\fR +(the default) then if a vetoed directory contains any non\-vetoed files or directories then the directory delete will fail\&. This is usually what you want\&. +.sp +If this option is set to +\fByes\fR, then Samba will attempt to recursively delete any files and directories within the vetoed directory\&. This can be useful for integration with file serving systems such as NetAtalk which create meta\-files within directories you might normally veto DOS/Windows users from seeing (e\&.g\&. +\&.AppleDouble) +.sp +Setting +\m[blue]\fBdelete veto files = yes\fR\m[] +allows these directories to be transparently deleted when the parent directory is deleted (so long as the user has permissions to do so)\&. +.sp +Default: +\fI\fIdelete veto files\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dfree cache time (S) +.PP +.RS 4 +The +\fIdfree cache time\fR +should only be used on systems where a problem occurs with the internal disk space calculations\&. This has been known to happen with Ultrix, but may occur with other operating systems\&. The symptom that was seen was an error of "Abort Retry Ignore" at the end of each directory listing\&. +.sp +This is a new parameter introduced in Samba version 3\&.0\&.21\&. It specifies in seconds the time that smbd will cache the output of a disk free query\&. If set to zero (the default) no caching is done\&. This allows a heavily loaded server to prevent rapid spawning of +\m[blue]\fBdfree command\fR\m[] +scripts increasing the load\&. +.sp +By default this parameter is zero, meaning no caching will be done\&. +.sp +\fINo default\fR +.sp +Example: +\fI\fIdfree cache time\fR\fR\fI = \fR\fI60\fR\fI \fR +.RE + +dfree command (S) +.PP +.RS 4 +The +\fIdfree command\fR +setting should only be used on systems where a problem occurs with the internal disk space calculations\&. This has been known to happen with Ultrix, but may occur with other operating systems\&. The symptom that was seen was an error of "Abort Retry Ignore" at the end of each directory listing\&. +.sp +This setting allows the replacement of the internal routines to calculate the total disk space and amount available with an external routine\&. The example below gives a possible script that might fulfill this function\&. +.sp +In Samba version 3\&.0\&.21 this parameter has been changed to be a per\-share parameter, and in addition the parameter +\m[blue]\fBdfree cache time\fR\m[] +was added to allow the output of this script to be cached for systems under heavy load\&. +.sp +The external program will be passed a single parameter indicating a directory in the filesystem being queried\&. This will typically consist of the string +\&./\&. The script should return two integers in ASCII\&. The first should be the total disk space in blocks, and the second should be the number of available blocks\&. An optional third return value can give the block size in bytes\&. The default blocksize is 1024 bytes\&. +.sp +Note: Your script should +\fINOT\fR +be setuid or setgid and should be owned by (and writeable only by) root! +.sp +Where the script dfree (which must be made executable) could be: +.sp +.if n \{\ +.RS 4 +.\} +.nf + +#!/bin/sh +df "$1" | tail \-1 | awk \*(Aq{print $(NF\-4),$(NF\-2)}\*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +or perhaps (on Sys V based systems): +.sp +.if n \{\ +.RS 4 +.\} +.nf + +#!/bin/sh +/usr/bin/df \-k "$1" | tail \-1 | awk \*(Aq{print $3" "$5}\*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +Note that you may have to replace the command names with full path names on some systems\&. Also note the arguments passed into the script should be quoted inside the script in case they contain special characters such as spaces or newlines\&. +.sp +By default internal routines for determining the disk capacity and remaining space will be used\&. +.sp +\fINo default\fR +.sp +Example: +\fI\fIdfree command\fR\fR\fI = \fR\fI/usr/local/samba/bin/dfree\fR\fI \fR +.RE + +dgram port (G) +.PP +.RS 4 +Specifies which ports the server should listen on for NetBIOS datagram traffic\&. +.sp +Default: +\fI\fIdgram port\fR\fR\fI = \fR\fI138\fR\fI \fR +.RE + +directory mode +.PP +.RS 4 +This parameter is a synonym for +directory mask\&. +.RE + +directory mask (S) +.PP +.RS 4 +This parameter is the octal modes which are used when converting DOS modes to UNIX modes when creating UNIX directories\&. +.sp +When a directory is created, the necessary permissions are calculated according to the mapping from DOS modes to UNIX permissions, and the resulting UNIX mode is then bit\-wise \*(AqAND\*(Aqed with this parameter\&. This parameter may be thought of as a bit\-wise MASK for the UNIX modes of a directory\&. Any bit +\fInot\fR +set here will be removed from the modes set on a directory when it is created\&. +.sp +The default value of this parameter removes the \*(Aqgroup\*(Aq and \*(Aqother\*(Aq write bits from the UNIX mode, allowing only the user who owns the directory to modify it\&. +.sp +Following this Samba will bit\-wise \*(AqOR\*(Aq the UNIX mode created from this parameter with the value of the +\m[blue]\fBforce directory mode\fR\m[] +parameter\&. This parameter is set to 000 by default (i\&.e\&. no extra mode bits are added)\&. +.sp +Default: +\fI\fIdirectory mask\fR\fR\fI = \fR\fI0755\fR\fI \fR +.sp +Example: +\fI\fIdirectory mask\fR\fR\fI = \fR\fI0775\fR\fI \fR +.RE + +directory security mask (S) +.PP +.RS 4 +This parameter has been removed for Samba 4\&.0\&.0\&. +.sp +\fINo default\fR +.RE + +disable netbios (G) +.PP +.RS 4 +Enabling this parameter will disable netbios support in Samba\&. Netbios is the only available form of browsing in Windows versions prior to Windows 2000\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Clients that only support netbios won\*(Aqt be able to see your samba server when netbios support is disabled\&. +.sp .5v +.RE +Default: +\fI\fIdisable netbios\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +disable spoolss (G) +.PP +.RS 4 +Enabling this parameter will disable Samba\*(Aqs support for the SPOOLSS set of MS\-RPC\*(Aqs and will yield identical behavior as Samba 2\&.0\&.x\&. Windows NT/2000 clients will downgrade to using Lanman style printing commands\&. Windows 9x/ME will be unaffected by the parameter\&. However, this will also disable the ability to upload printer drivers to a Samba server via the Windows NT Add Printer Wizard or by using the NT printer properties dialog window\&. It will also disable the capability of Windows NT/2000 clients to download print drivers from the Samba host upon demand\&. +\fIBe very careful about enabling this parameter\&.\fR +.sp +Default: +\fI\fIdisable spoolss\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dmapi support (S) +.PP +.RS 4 +This parameter specifies whether Samba should use DMAPI to determine whether a file is offline or not\&. This would typically be used in conjunction with a hierarchical storage system that automatically migrates files to tape\&. +.sp +Note that Samba infers the status of a file by examining the events that a DMAPI application has registered interest in\&. This heuristic is satisfactory for a number of hierarchical storage systems, but there may be system for which it will fail\&. In this case, Samba may erroneously report files to be offline\&. +.sp +This parameter is only available if a supported DMAPI implementation was found at compilation time\&. It will only be used if DMAPI is found to enabled on the system at run time\&. +.sp +Default: +\fI\fIdmapi support\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dns forwarder (G) +.PP +.RS 4 +This option specifies the list of DNS servers that DNS requests will be forwarded to if they can not be handled by Samba itself\&. +.sp +The DNS forwarder is only used if the internal DNS server in Samba is used\&. Port numbers can be appended by separating them from the address by using a colon (\*(Aq:\*(Aq)\&. When specifying a port, IPv6 addresses must be enclosed in square brackets (\*(Aq[\*(Aq and \*(Aq]\*(Aq)\&. IPv6 forwarder addresses with no port specified, don\*(Aqt need the square brackets, and default to port 53\&. +.sp +Default: +\fI\fIdns forwarder\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdns forwarder\fR\fR\fI = \fR\fI192\&.168\&.0\&.1 192\&.168\&.0\&.2 ::1 [2001:db8::1] [2001:db8:1:2::1]:54 \fR\fI \fR +.RE + +dns port (G) +.PP +.RS 4 +Specifies which ports the server should listen on for DNS traffic\&. +.sp +It makes possible to use another DNS server as a front and forward to Samba\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Dynamic DNS updates may not be proxied by the front DNS server when forwarding to Samba\&. Dynamic DNS update proxying depends on the features of the other DNS server used as a front\&. +.sp .5v +.RE +Default: +\fI\fIdns port\fR\fR\fI = \fR\fI53\fR\fI \fR +.RE + +dns proxy (G) +.PP +.RS 4 +Specifies that +\fBnmbd\fR(8) +when acting as a WINS server and finding that a NetBIOS name has not been registered, should treat the NetBIOS name word\-for\-word as a DNS name and do a lookup with the DNS server for that name on behalf of the name\-querying client\&. +.sp +Note that the maximum length for a NetBIOS name is 15 characters, so the DNS name (or DNS alias) can likewise only be 15 characters, maximum\&. +.sp +nmbd +spawns a second copy of itself to do the DNS name lookup requests, as doing a name lookup is a blocking action\&. +.sp +Default: +\fI\fIdns proxy\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +dns update command (G) +.PP +.RS 4 +This option sets the command that is called when there are DNS updates\&. It should update the local machines DNS names using TSIG\-GSS\&. +.sp +Default: +\fI\fIdns update command\fR\fR\fI = \fR\fI/builddir/build/BUILD/samba\-4\&.20\&.0rc3/source4/scripting/bin/samba_dnsupdate\fR\fI \fR +.sp +Example: +\fI\fIdns update command\fR\fR\fI = \fR\fI/usr/local/sbin/dnsupdate\fR\fI \fR +.RE + +dns zone scavenging (G) +.PP +.RS 4 +When enabled (the default is disabled) unused dynamic dns records are periodically removed\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +This option should not be enabled for installations created with versions of samba before 4\&.9\&. Doing this will result in the loss of static DNS entries\&. This is due to a bug in previous versions of samba (BUG 12451) which marked dynamic DNS records as static and static records as dynamic\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +If one record for a DNS name is static (non\-aging) then no other record for that DNS name will be scavenged\&. +.sp .5v +.RE +Default: +\fI\fIdns zone scavenging\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dns zone transfer clients allow (G) +.PP +.RS 4 +This option specifies the list of IPs authorized to ask for dns zone transfer from bind DLZ module\&. +.sp +The IP list is comma and space separated and specified in the same syntax as used in +\m[blue]\fBhosts allow\fR\m[], specifically including IP address, IP prefixes and IP address masks\&. +.sp +As this is a DNS server option, hostnames are naturally not permitted\&. +.sp +The default behaviour is to deny any request\&. A request will be authorized only if the emitting client is identified in this list, and not in +\m[blue]\fBdns zone transfer clients deny\fR\m[] +.sp +Default: +\fI\fIdns zone transfer clients allow\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdns zone transfer clients allow\fR\fR\fI = \fR\fI192\&.168\&.0\&.1\fR\fI \fR +.RE + +dns zone transfer clients deny (G) +.PP +.RS 4 +This option specifies the list of IPs denied to ask for dns zone transfer from bind DLZ module\&. +.sp +The IP list is comma and space separated and specified in the same syntax as used in +\m[blue]\fBhosts allow\fR\m[], specifically including IP address, IP prefixes and IP address masks\&. +.sp +As this is a DNS server option, hostnames are naturally not permitted\&. +.sp +If a client identified in this list sends a zone transfer request, it will always be denied, even if they are in +\m[blue]\fBdns zone transfer clients allow\fR\m[]\&. This allows the definition of specific denied clients within an authorized subnet\&. +.sp +Default: +\fI\fIdns zone transfer clients deny\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdns zone transfer clients deny\fR\fR\fI = \fR\fI192\&.168\&.0\&.1\fR\fI \fR +.RE + +domain logons (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.13 and support for NT4\-style domain logons(as distinct from the Samba AD DC) will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +domain logons = no +will be the enforced behaviour\&. +.sp +If set to +\fByes\fR, the Samba server will provide the netlogon service for Windows 9X network logons for the +\m[blue]\fBworkgroup\fR\m[] +it is in\&. This will also cause the Samba server to act as a domain controller for NT4 style domain services\&. For more details on setting up this feature see the Domain Control chapter of the Samba HOWTO Collection\&. +.sp +Default: +\fI\fIdomain logons\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +domain master (G) +.PP +.RS 4 +Tell +\fBsmbd\fR(8) +to enable WAN\-wide browse list collation\&. Setting this option causes +nmbd +to claim a special domain specific NetBIOS name that identifies it as a domain master browser for its given +\m[blue]\fBworkgroup\fR\m[]\&. Local master browsers in the same +\m[blue]\fBworkgroup\fR\m[] +on broadcast\-isolated subnets will give this +nmbd +their local browse lists, and then ask +\fBsmbd\fR(8) +for a complete copy of the browse list for the whole wide area network\&. Browser clients will then contact their local master browser, and will receive the domain\-wide browse list, instead of just the list for their broadcast\-isolated subnet\&. +.sp +Note that Windows NT Primary Domain Controllers expect to be able to claim this +\m[blue]\fBworkgroup\fR\m[] +specific special NetBIOS name that identifies them as domain master browsers for that +\m[blue]\fBworkgroup\fR\m[] +by default (i\&.e\&. there is no way to prevent a Windows NT PDC from attempting to do this)\&. This means that if this parameter is set and +nmbd +claims the special name for a +\m[blue]\fBworkgroup\fR\m[] +before a Windows NT PDC is able to do so then cross subnet browsing will behave strangely and may fail\&. +.sp +If +\m[blue]\fBdomain logons = yes\fR\m[], then the default behavior is to enable the +\m[blue]\fBdomain master\fR\m[] +parameter\&. If +\m[blue]\fBdomain logons\fR\m[] +is not enabled (the default setting), then neither will +\m[blue]\fBdomain master\fR\m[] +be enabled by default\&. +.sp +When +\m[blue]\fBdomain logons = Yes\fR\m[] +the default setting for this parameter is Yes, with the result that Samba will be a PDC\&. If +\m[blue]\fBdomain master = No\fR\m[], Samba will function as a BDC\&. In general, this parameter should be set to \*(AqNo\*(Aq only on a BDC\&. +.sp +Default: +\fI\fIdomain master\fR\fR\fI = \fR\fIauto\fR\fI \fR +.RE + +dont descend (S) +.PP +.RS 4 +There are certain directories on some systems (e\&.g\&., the +/proc +tree under Linux) that are either not of interest to clients or are infinitely deep (recursive)\&. This parameter allows you to specify a comma\-delimited list of directories that the server should always show as empty\&. +.sp +Note that Samba can be very fussy about the exact format of the "dont descend" entries\&. For example you may need +\&./proc +instead of just +/proc\&. Experimentation is the best policy :\-) +.sp +Default: +\fI\fIdont descend\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIdont descend\fR\fR\fI = \fR\fI/proc,/dev\fR\fI \fR +.RE + +dos charset (G) +.PP +.RS 4 +DOS SMB clients assume the server has the same charset as they do\&. This option specifies which charset Samba should use to talk to DOS clients\&. +.sp +The default depends on which charsets you have installed\&. Samba tries to use charset 850 but falls back to ASCII in case it is not available\&. Run +\fBtestparm\fR(1) +to check the default on your system\&. +.sp +\fINo default\fR +.RE + +dos filemode (S) +.PP +.RS 4 +The default behavior in Samba is to provide UNIX\-like behavior where only the owner of a file/directory is able to change the permissions on it\&. However, this behavior is often confusing to DOS/Windows users\&. Enabling this parameter allows a user who has write access to the file (by whatever means, including an ACL permission) to modify the permissions (including ACL) on it\&. Note that a user belonging to the group owning the file will not be allowed to change permissions if the group is only granted read access\&. Ownership of the file/directory may also be changed\&. Note that using the VFS modules acl_xattr or acl_tdb which store native Windows as meta\-data will automatically turn this option on for any share for which they are loaded, as they require this option to emulate Windows ACLs correctly\&. +.sp +Default: +\fI\fIdos filemode\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dos filetime resolution (S) +.PP +.RS 4 +Under the DOS and Windows FAT filesystem, the finest granularity on time resolution is two seconds\&. Setting this parameter for a share causes Samba to round the reported time down to the nearest two second boundary when a query call that requires one second resolution is made to +\fBsmbd\fR(8)\&. +.sp +This option is mainly used as a compatibility option for Visual C++ when used against Samba shares\&. If oplocks are enabled on a share, Visual C++ uses two different time reading calls to check if a file has changed since it was last read\&. One of these calls uses a one\-second granularity, the other uses a two second granularity\&. As the two second call rounds any odd second down, then if the file has a timestamp of an odd number of seconds then the two timestamps will not match and Visual C++ will keep reporting the file has changed\&. Setting this option causes the two timestamps to match, and Visual C++ is happy\&. +.sp +Default: +\fI\fIdos filetime resolution\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dos filetimes (S) +.PP +.RS 4 +Under DOS and Windows, if a user can write to a file they can change the timestamp on it\&. Under POSIX semantics, only the owner of the file or root may change the timestamp\&. By default, Samba emulates the DOS semantics and allows one to change the timestamp on a file if the user +smbd +is acting on behalf has write permissions\&. Due to changes in Microsoft Office 2000 and beyond, the default for this parameter has been changed from "no" to "yes" in Samba 3\&.0\&.14 and above\&. Microsoft Excel will display dialog box warnings about the file being changed by another user if this parameter is not set to "yes" and files are being shared between users\&. +.sp +Default: +\fI\fIdos filetimes\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +dsdb event notification (G) +.PP +.RS 4 +When enabled, this option causes Samba (acting as an Active Directory Domain Controller) to stream Samba database events across the internal message bus\&. Scripts built using Samba\*(Aqs python bindings can listen to these events by registering as the service +dsdb_event\&. +.sp +This is +\fInot\fR +needed for the audit logging described in +\m[blue]\fBlog level\fR\m[]\&. +.sp +Instead, this should instead be considered a developer option (it assists in the Samba testsuite) rather than a facility for external auditing, as message delivery is not guaranteed (a feature that the testsuite works around)\&. +.sp +The Samba database events are also logged via the normal logging methods when the +\m[blue]\fBlog level\fR\m[] +is set appropriately, say to +dsdb_json_audit:5\&. +.sp +Default: +\fI\fIdsdb event notification\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dsdb group change notification (G) +.PP +.RS 4 +When enabled, this option causes Samba (acting as an Active Directory Domain Controller) to stream group membership change events across the internal message bus\&. Scripts built using Samba\*(Aqs python bindings can listen to these events by registering as the service +dsdb_group_event\&. +.sp +This is +\fInot\fR +needed for the audit logging described in +\m[blue]\fBlog level\fR\m[]\&. +.sp +Instead, this should instead be considered a developer option (it assists in the Samba testsuite) rather than a facility for external auditing, as message delivery is not guaranteed (a feature that the testsuite works around)\&. +.sp +The Samba database events are also logged via the normal logging methods when the +\m[blue]\fBlog level\fR\m[] +is set appropriately, say to +dsdb_group_json_audit:5\&. +.sp +Default: +\fI\fIdsdb group change notification\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +dsdb password event notification (G) +.PP +.RS 4 +When enabled, this option causes Samba (acting as an Active Directory Domain Controller) to stream password change and reset events across the internal message bus\&. Scripts built using Samba\*(Aqs python bindings can listen to these events by registering as the service +password_event\&. +.sp +This is +\fInot\fR +needed for the audit logging described in +\m[blue]\fBlog level\fR\m[]\&. +.sp +Instead, this should instead be considered a developer option (it assists in the Samba testsuite) rather than a facility for external auditing, as message delivery is not guaranteed (a feature that the testsuite works around)\&. +.sp +The Samba database events are also logged via the normal logging methods when the +\m[blue]\fBlog level\fR\m[] +is set appropriately, say to +dsdb_password_json_audit:5\&. +.sp +Default: +\fI\fIdsdb password event notification\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +durable handles (S) +.PP +.RS 4 +This boolean parameter controls whether Samba can grant SMB2 durable file handles on a share\&. +.sp +Note that durable handles are only enabled if +\m[blue]\fBkernel oplocks = no\fR\m[], +\m[blue]\fBkernel share modes = no\fR\m[], and +\m[blue]\fBposix locking = no\fR\m[], i\&.e\&. if the share is configured for CIFS/SMB2 only access, not supporting interoperability features with local UNIX processes or NFS operations\&. +.sp +Also note that, for the time being, durability is not granted for a handle that has the delete on close flag set\&. +.sp +Default: +\fI\fIdurable handles\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ea support (S) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will allow clients to attempt to access extended attributes on a share\&. In order to enable this parameter on a setup with default VFS modules: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Samba must have been built with extended attributes support\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The underlying filesystem exposed by the share must support extended attributes (e\&.g\&. the getfattr(1) +/ setfattr(1) +utilities must work)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Access to extended user attributes must be allowed by the underlying filesystem (e\&.g\&. when mounted with a system\-dependent option like user_xattr on Linux)\&. +.RE +.sp +.RE +This option exposes the "user" attribute namespace from the underlying filesystem to clients\&. In order to match Windows conventions, the namespace prefix ("user\&.") is stripped from the attribute name on the client side\&. The handling of further attribute namespaces (like "security", "system", or "trusted") is not affected by this option\&. +.sp +Note that the SMB protocol allows setting attributes whose value is 64K bytes long, and that on NTFS, the maximum storage space for extended attributes per file is 64K\&. On some filesystem the limits may be lower\&. Filesystems with too limited EA space may experience unexpected weird effects\&. The default has changed to yes in Samba release 4\&.9\&.0 and above to allow better Windows fileserver compatibility in a default install\&. +.sp +Default: +\fI\fIea support\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +elasticsearch:address (S) +.PP +.RS 4 +Specifies the name of the Elasticsearch server to use for Spotlight queries when using the Elasticsearch backend\&. +.sp +Default: +\fI\fIelasticsearch:address\fR\fR\fI = \fR\fIlocalhost\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:address\fR\fR\fI = \fR\fIneedle\&.haystack\&.samba\&.org\fR\fI \fR +.RE + +elasticsearch:ignore unknown attribute (G) +.PP +.RS 4 +Ignore unknown Spotlight attributes in search queries\&. An example query using the unsupported attribute +"kMDItemTopic" +would be +kMDItemTopic=="hotstuff"\&. By default any query using such a type would completely fail\&. By enabling this option, if the type match is a subexpression of a larger expression, then this subexpression is just ignored\&. +.sp +Default: +\fI\fIelasticsearch:ignore unknown attribute\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:ignore unknown attribute\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +elasticsearch:ignore unknown type (G) +.PP +.RS 4 +Ignore unknown Spotlight types in search queries\&. An example query using the unsupported type +"public\&.calendar\-event" +would be +kMDItemContentType=="public\&.calendar\-event"\&. By default any query using such a type would completely fail\&. By enabling this option, if the type match is a subexpression of a larger expression, then this subexpression is just ignored\&. +.sp +Default: +\fI\fIelasticsearch:ignore unknown type\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:ignore unknown type\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +elasticsearch:index (S) +.PP +.RS 4 +Specifies the name of the Elasticsearch index to use for Spotlight queries when using the Elasticsearch backend\&. The default value of "_all" is a special Elasticsearch value that performs the search operation on all indices\&. +.sp +Default: +\fI\fIelasticsearch:index\fR\fR\fI = \fR\fI_all\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:index\fR\fR\fI = \fR\fIspotlight\fR\fI \fR +.RE + +elasticsearch:mappings (G) +.PP +.RS 4 +Path to a file specifying metadata attribute mappings in JSON format\&. Use by the Elasticsearch backend of the Spotlight RPC service\&. +.sp +Default: +\fI\fIelasticsearch:mappings\fR\fR\fI = \fR\fI/usr/share/samba/elasticsearch_mappings\&.json\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:mappings\fR\fR\fI = \fR\fI/usr/share/foo/mymappings\&.json\fR\fI \fR +.RE + +elasticsearch:max results (S) +.PP +.RS 4 +Path to a file specifying metadata attribute mappings in JSON format\&. Used by the Elasticsearch backend of the Spotlight RPC service\&. A value of 0 means no limit\&. +.sp +Default: +\fI\fIelasticsearch:max results\fR\fR\fI = \fR\fI100\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:max results\fR\fR\fI = \fR\fI10\fR\fI \fR +.RE + +elasticsearch:port (S) +.PP +.RS 4 +Specifies the TCP port of the Elasticsearch server to use for Spotlight queries when using the Elasticsearch backend\&. +.sp +Default: +\fI\fIelasticsearch:port\fR\fR\fI = \fR\fI9200\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:port\fR\fR\fI = \fR\fI9201\fR\fI \fR +.RE + +elasticsearch:use tls (S) +.PP +.RS 4 +Specifies whether to use HTTPS when talking to the Elasticsearch server used for Spotlight queries when using the Elasticsearch backend\&. +.sp +Default: +\fI\fIelasticsearch:use tls\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIelasticsearch:use tls\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +enable asu support (G) +.PP +.RS 4 +Hosts running the "Advanced Server for Unix (ASU)" product require some special accommodations such as creating a builtin [ADMIN$] share that only supports IPC connections\&. The has been the default behavior in smbd for many years\&. However, certain Microsoft applications such as the Print Migrator tool require that the remote server support an [ADMIN$] file share\&. Disabling this parameter allows for creating an [ADMIN$] file share in smb\&.conf\&. +.sp +Default: +\fI\fIenable asu support\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +enable core files (G) +.PP +.RS 4 +This parameter specifies whether core dumps should be written on internal exits\&. Normally set to +\fByes\fR\&. You should never need to change this\&. +.sp +Default: +\fI\fIenable core files\fR\fR\fI = \fR\fIyes\fR\fI \fR +.sp +Example: +\fI\fIenable core files\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +enable privileges (G) +.PP +.RS 4 +This deprecated parameter controls whether or not smbd will honor privileges assigned to specific SIDs via either +net rpc rights +or one of the Windows user and group manager tools\&. This parameter is enabled by default\&. It can be disabled to prevent members of the Domain Admins group from being able to assign privileges to users or groups which can then result in certain smbd operations running as root that would normally run under the context of the connected user\&. +.sp +An example of how privileges can be used is to assign the right to join clients to a Samba controlled domain without providing root access to the server via smbd\&. +.sp +Please read the extended description provided in the Samba HOWTO documentation\&. +.sp +Default: +\fI\fIenable privileges\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +enable spoolss (G) +.PP +.RS 4 +Inverted synonym for +\m[blue]\fBdisable spoolss\fR\m[]\&. +.sp +Default: +\fI\fIenable spoolss\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +encrypt passwords (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.11 and support for plaintext (as distinct from NTLM, NTLMv2 or Kerberos authentication) will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +encrypt passwords = yes +will be the enforced behaviour\&. +.sp +This boolean controls whether encrypted passwords will be negotiated with the client\&. Note that Windows NT 4\&.0 SP3 and above and also Windows 98 will by default expect encrypted passwords unless a registry entry is changed\&. To use encrypted passwords in Samba see the chapter "User Database" in the Samba HOWTO Collection\&. +.sp +MS Windows clients that expect Microsoft encrypted passwords and that do not have plain text password support enabled will be able to connect only to a Samba server that has encrypted password support enabled and for which the user accounts have a valid encrypted password\&. Refer to the smbpasswd command man page for information regarding the creation of encrypted passwords for user accounts\&. +.sp +The use of plain text passwords is NOT advised as support for this feature is no longer maintained in Microsoft Windows products\&. If you want to use plain text passwords you must set this parameter to no\&. +.sp +In order for encrypted passwords to work correctly +\fBsmbd\fR(8) +must either have access to a local +\fBsmbpasswd\fR(5) +file (see the +\fBsmbpasswd\fR(8) +program for information on how to set up and maintain this file), or set the +\m[blue]\fBsecurity = [domain|ads]\fR\m[] +parameter which causes +smbd +to authenticate against another server\&. +.sp +Default: +\fI\fIencrypt passwords\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +enhanced browsing (G) +.PP +.RS 4 +This option enables a couple of enhancements to cross\-subnet browse propagation that have been added in Samba but which are not standard in Microsoft implementations\&. +.sp +The first enhancement to browse propagation consists of a regular wildcard query to a Samba WINS server for all Domain Master Browsers, followed by a browse synchronization with each of the returned DMBs\&. The second enhancement consists of a regular randomised browse synchronization with all currently known DMBs\&. +.sp +You may wish to disable this option if you have a problem with empty workgroups not disappearing from browse lists\&. Due to the restrictions of the browse protocols, these enhancements can cause a empty workgroup to stay around forever which can be annoying\&. +.sp +In general you should leave this option enabled as it makes cross\-subnet browse propagation much more reliable\&. +.sp +Default: +\fI\fIenhanced browsing\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +enumports command (G) +.PP +.RS 4 +The concept of a "port" is fairly foreign to UNIX hosts\&. Under Windows NT/2000 print servers, a port is associated with a port monitor and generally takes the form of a local port (i\&.e\&. LPT1:, COM1:, FILE:) or a remote port (i\&.e\&. LPD Port Monitor, etc\&.\&.\&.)\&. By default, Samba has only one port defined\-\-\fB"Samba Printer Port"\fR\&. Under Windows NT/2000, all printers must have a valid port name\&. If you wish to have a list of ports displayed (smbd +does not use a port name for anything) other than the default +\fB"Samba Printer Port"\fR, you can define +\fIenumports command\fR +to point to a program which should generate a list of ports, one per line, to standard output\&. This listing will then be used in response to the level 1 and 2 EnumPorts() RPC\&. +.sp +Default: +\fI\fIenumports command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIenumports command\fR\fR\fI = \fR\fI/usr/bin/listports\fR\fI \fR +.RE + +eventlog list (G) +.PP +.RS 4 +This option defines a list of log names that Samba will report to the Microsoft EventViewer utility\&. The listed eventlogs will be associated with tdb file on disk in the +$(statedir)/eventlog\&. +.sp +The administrator must use an external process to parse the normal Unix logs such as +/var/log/messages +and write then entries to the eventlog tdb files\&. Refer to the eventlogadm(8) utility for how to write eventlog entries\&. +.sp +Default: +\fI\fIeventlog list\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIeventlog list\fR\fR\fI = \fR\fISecurity Application Syslog Apache\fR\fI \fR +.RE + +fake directory create times (S) +.PP +.RS 4 +NTFS and Windows VFAT file systems keep a create time for all files and directories\&. This is not the same as the ctime \- status change time \- that Unix keeps, so Samba by default reports the earliest of the various times Unix does keep\&. Setting this parameter for a share causes Samba to always report midnight 1\-1\-1980 as the create time for directories\&. +.sp +This option is mainly used as a compatibility option for Visual C++ when used against Samba shares\&. Visual C++ generated makefiles have the object directory as a dependency for each object file, and a make rule to create the directory\&. Also, when NMAKE compares timestamps it uses the creation time when examining a directory\&. Thus the object directory will be created if it does not exist, but once it does exist it will always have an earlier timestamp than the object files it contains\&. +.sp +However, Unix time semantics mean that the create time reported by Samba will be updated whenever a file is created or deleted in the directory\&. NMAKE finds all object files in the object directory\&. The timestamp of the last one built is then compared to the timestamp of the object directory\&. If the directory\*(Aqs timestamp if newer, then all object files will be rebuilt\&. Enabling this option ensures directories always predate their contents and an NMAKE build will proceed as expected\&. +.sp +Default: +\fI\fIfake directory create times\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +fake oplocks (S) +.PP +.RS 4 +Oplocks are the way that SMB clients get permission from a server to locally cache file operations\&. If a server grants an oplock (opportunistic lock) then the client is free to assume that it is the only one accessing the file and it will aggressively cache file data\&. With some oplock types the client may even cache file open/close operations\&. This can give enormous performance benefits\&. +.sp +When you set +fake oplocks = yes, +\fBsmbd\fR(8) +will always grant oplock requests no matter how many clients are using the file\&. +.sp +It is generally much better to use the real +\m[blue]\fBoplocks\fR\m[] +support rather than this parameter\&. +.sp +If you enable this option on all read\-only shares or shares that you know will only be accessed from one client at a time such as physically read\-only media like CDROMs, you will see a big performance improvement on many operations\&. If you enable this option on shares where multiple clients may be accessing the files read\-write at the same time you can get data corruption\&. Use this option carefully! +.sp +Default: +\fI\fIfake oplocks\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +follow symlinks (S) +.PP +.RS 4 +This parameter allows the Samba administrator to stop +\fBsmbd\fR(8) +from following symbolic links in a particular share\&. Setting this parameter to +\fBno\fR +prevents any file or directory that is a symbolic link from being followed (the user will get an error)\&. This option is very useful to stop users from adding a symbolic link to +/etc/passwd +in their home directory for instance\&. However it will slow filename lookups down slightly\&. +.sp +This option is enabled (i\&.e\&. +smbd +will follow symbolic links) by default\&. +.sp +Default: +\fI\fIfollow symlinks\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smbd force process locks (S) +.PP +.RS 4 +This boolean option tells +smbd +whether to forcefully disable the use of Open File Description locks on Linux\&. +.sp +This option should not be changed from the default unless you know what you\*(Aqre doing\&. +.sp +Default: +\fI\fIsmbd force process locks\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +force create mode (S) +.PP +.RS 4 +This parameter specifies a set of UNIX mode bit permissions that will +\fIalways\fR +be set on a file created by Samba\&. This is done by bitwise \*(AqOR\*(Aqing these bits onto the mode bits of a file that is being created\&. The default for this parameter is (in octal) 000\&. The modes in this parameter are bitwise \*(AqOR\*(Aqed onto the file mode after the mask set in the +\fIcreate mask\fR +parameter is applied\&. +.sp +The example below would force all newly created files to have read and execute permissions set for \*(Aqgroup\*(Aq and \*(Aqother\*(Aq as well as the read/write/execute bits set for the \*(Aquser\*(Aq\&. +.sp +Default: +\fI\fIforce create mode\fR\fR\fI = \fR\fI0000\fR\fI \fR +.sp +Example: +\fI\fIforce create mode\fR\fR\fI = \fR\fI0755\fR\fI \fR +.RE + +force directory mode (S) +.PP +.RS 4 +This parameter specifies a set of UNIX mode bit permissions that will +\fIalways\fR +be set on a directory created by Samba\&. This is done by bitwise \*(AqOR\*(Aqing these bits onto the mode bits of a directory that is being created\&. The default for this parameter is (in octal) 0000 which will not add any extra permission bits to a created directory\&. This operation is done after the mode mask in the parameter +\fIdirectory mask\fR +is applied\&. +.sp +The example below would force all created directories to have read and execute permissions set for \*(Aqgroup\*(Aq and \*(Aqother\*(Aq as well as the read/write/execute bits set for the \*(Aquser\*(Aq\&. +.sp +Default: +\fI\fIforce directory mode\fR\fR\fI = \fR\fI0000\fR\fI \fR +.sp +Example: +\fI\fIforce directory mode\fR\fR\fI = \fR\fI0755\fR\fI \fR +.RE + +force directory security mode (S) +.PP +.RS 4 +This parameter has been removed for Samba 4\&.0\&.0\&. +.sp +\fINo default\fR +.RE + +group +.PP +.RS 4 +This parameter is a synonym for +force group\&. +.RE + +force group (S) +.PP +.RS 4 +This specifies a UNIX group name that will be assigned as the default primary group for all users connecting to this service\&. This is useful for sharing files by ensuring that all access to files on service will use the named group for their permissions checking\&. Thus, by assigning permissions for this group to the files and directories within this service the Samba administrator can restrict or allow sharing of these files\&. +.sp +In Samba 2\&.0\&.5 and above this parameter has extended functionality in the following way\&. If the group name listed here has a \*(Aq+\*(Aq character prepended to it then the current user accessing the share only has the primary group default assigned to this group if they are already assigned as a member of that group\&. This allows an administrator to decide that only users who are already in a particular group will create files with group ownership set to that group\&. This gives a finer granularity of ownership assignment\&. For example, the setting +force group = +sys +means that only users who are already in group sys will have their default primary group assigned to sys when accessing this Samba share\&. All other users will retain their ordinary primary group\&. +.sp +If the +\m[blue]\fBforce user\fR\m[] +parameter is also set the group specified in +\fIforce group\fR +will override the primary group set in +\fIforce user\fR\&. +.sp +Default: +\fI\fIforce group\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIforce group\fR\fR\fI = \fR\fIagroup\fR\fI \fR +.RE + +force printername (S) +.PP +.RS 4 +When printing from Windows NT (or later), each printer in +smb\&.conf +has two associated names which can be used by the client\&. The first is the sharename (or shortname) defined in smb\&.conf\&. This is the only printername available for use by Windows 9x clients\&. The second name associated with a printer can be seen when browsing to the "Printers" (or "Printers and Faxes") folder on the Samba server\&. This is referred to simply as the printername (not to be confused with the +\fIprinter name\fR +option)\&. +.sp +When assigning a new driver to a printer on a remote Windows compatible print server such as Samba, the Windows client will rename the printer to match the driver name just uploaded\&. This can result in confusion for users when multiple printers are bound to the same driver\&. To prevent Samba from allowing the printer\*(Aqs printername to differ from the sharename defined in smb\&.conf, set +\fIforce printername = yes\fR\&. +.sp +Be aware that enabling this parameter may affect migrating printers from a Windows server to Samba since Windows has no way to force the sharename and printername to match\&. +.sp +It is recommended that this parameter\*(Aqs value not be changed once the printer is in use by clients as this could cause a user not be able to delete printer connections from their local Printers folder\&. +.sp +Default: +\fI\fIforce printername\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +force security mode (S) +.PP +.RS 4 +This parameter has been removed for Samba 4\&.0\&.0\&. +.sp +\fINo default\fR +.RE + +force unknown acl user (S) +.PP +.RS 4 +If this parameter is set, a Windows NT ACL that contains an unknown SID (security descriptor, or representation of a user or group id) as the owner or group owner of the file will be silently mapped into the current UNIX uid or gid of the currently connected user\&. +.sp +This is designed to allow Windows NT clients to copy files and folders containing ACLs that were created locally on the client machine and contain users local to that machine only (no domain users) to be copied to a Samba server (usually with XCOPY /O) and have the unknown userid and groupid of the file owner map to the current connected user\&. This can only be fixed correctly when winbindd allows arbitrary mapping from any Windows NT SID to a UNIX uid or gid\&. +.sp +Try using this parameter when XCOPY /O gives an ACCESS_DENIED error\&. +.sp +Default: +\fI\fIforce unknown acl user\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +force user (S) +.PP +.RS 4 +This specifies a UNIX user name that will be assigned as the default user for all users connecting to this service\&. This is useful for sharing files\&. You should also use it carefully as using it incorrectly can cause security problems\&. +.sp +This user name only gets used once a connection is established\&. Thus clients still need to connect as a valid user and supply a valid password\&. Once connected, all file operations will be performed as the "forced user", no matter what username the client connected as\&. This can be very useful\&. +.sp +In Samba 2\&.0\&.5 and above this parameter also causes the primary group of the forced user to be used as the primary group for all file activity\&. Prior to 2\&.0\&.5 the primary group was left as the primary group of the connecting user (this was a bug)\&. +.sp +Default: +\fI\fIforce user\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIforce user\fR\fR\fI = \fR\fIauser\fR\fI \fR +.RE + +fss: prune stale (G) +.PP +.RS 4 +When enabled, Samba\*(Aqs File Server Remote VSS Protocol (FSRVP) server checks all FSRVP initiated snapshots on startup, and removes any corresponding state (including share definitions) for nonexistent snapshot paths\&. +.sp +Default: +\fI\fIfss: prune stale\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIfss: prune stale\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +fss: sequence timeout (G) +.PP +.RS 4 +The File Server Remote VSS Protocol (FSRVP) server includes a message sequence timer to ensure cleanup on unexpected client disconnect\&. This parameter overrides the default timeout between FSRVP operations\&. FSRVP timeouts can be completely disabled via a value of 0\&. +.sp +Default: +\fI\fIfss: sequence timeout\fR\fR\fI = \fR\fI180 or 1800, depending on operation\fR\fI \fR +.sp +Example: +\fI\fIfss: sequence timeout\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +fstype (S) +.PP +.RS 4 +This parameter allows the administrator to configure the string that specifies the type of filesystem a share is using that is reported by +\fBsmbd\fR(8) +when a client queries the filesystem type for a share\&. The default type is +\fBNTFS\fR +for compatibility with Windows NT but this can be changed to other strings such as +\fBSamba\fR +or +\fBFAT\fR +if required\&. +.sp +Default: +\fI\fIfstype\fR\fR\fI = \fR\fINTFS\fR\fI \fR +.sp +Example: +\fI\fIfstype\fR\fR\fI = \fR\fISamba\fR\fI \fR +.RE + +get quota command (G) +.PP +.RS 4 +The +get quota command +should only be used whenever there is no operating system API available from the OS that samba can use\&. +.sp +This option is only available Samba was compiled with quotas support\&. +.sp +This parameter should specify the path to a script that queries the quota information for the specified user/group for the partition that the specified directory is on\&. +.sp +Such a script is being given 3 arguments: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +directory +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +type of query +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +uid of user or gid of group +.RE +.sp +.RE +The directory is actually mostly just "\&." \- It needs to be treated relatively to the current working directory that the script can also query\&. +.sp +The type of query can be one of: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +1 \- user quotas +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +2 \- user default quotas (uid = \-1) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +3 \- group quotas +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +4 \- group default quotas (gid = \-1) +.RE +.sp +.RE +This script should print one line as output with spaces between the columns\&. The printed columns should be: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +1 \- quota flags (0 = no quotas, 1 = quotas enabled, 2 = quotas enabled and enforced) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +2 \- number of currently used blocks +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +3 \- the softlimit number of blocks +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +4 \- the hardlimit number of blocks +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5 \- currently used number of inodes +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +6 \- the softlimit number of inodes +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +7 \- the hardlimit number of inodes +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +8 (optional) \- the number of bytes in a block(default is 1024) +.RE +.sp +.RE +Default: +\fI\fIget quota command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIget quota command\fR\fR\fI = \fR\fI/usr/local/sbin/query_quota\fR\fI \fR +.RE + +getwd cache (G) +.PP +.RS 4 +This is a tuning option\&. When this is enabled a caching algorithm will be used to reduce the time taken for getwd() calls\&. This can have a significant impact on performance, especially when the +\m[blue]\fBwide links\fR\m[] +parameter is set to +\fBno\fR\&. +.sp +Default: +\fI\fIgetwd cache\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +gpo update command (G) +.PP +.RS 4 +This option sets the command that is called to apply GPO policies\&. The samba\-gpupdate script applies System Access and Kerberos Policies to the KDC\&. System Access policies set minPwdAge, maxPwdAge, minPwdLength, and pwdProperties in the samdb\&. Kerberos Policies set kdc:service ticket lifetime, kdc:user ticket lifetime, and kdc:renewal lifetime in smb\&.conf\&. +.sp +Default: +\fI\fIgpo update command\fR\fR\fI = \fR\fI/builddir/build/BUILD/samba\-4\&.20\&.0rc3/source4/scripting/bin/samba\-gpupdate\fR\fI \fR +.sp +Example: +\fI\fIgpo update command\fR\fR\fI = \fR\fI/usr/local/sbin/gpoupdate\fR\fI \fR +.RE + +guest account (G) +.PP +.RS 4 +This is a username which will be used for access to services which are specified as +\m[blue]\fBguest ok\fR\m[] +(see below)\&. Whatever privileges this user has will be available to any client connecting to the guest service\&. This user must exist in the password file, but does not require a valid login\&. The user account "ftp" is often a good choice for this parameter\&. +.sp +On some systems the default guest account "nobody" may not be able to print\&. Use another account in this case\&. You should test this by trying to log in as your guest user (perhaps by using the +su \- +command) and trying to print using the system print command such as +lpr(1) +or +lp(1)\&. +.sp +This parameter does not accept % macros, because many parts of the system require this value to be constant for correct operation\&. +.sp +Default: +\fI\fIguest account\fR\fR\fI = \fR\fInobody # default can be changed at compile\-time\fR\fI \fR +.sp +Example: +\fI\fIguest account\fR\fR\fI = \fR\fIftp\fR\fI \fR +.RE + +public +.PP +.RS 4 +This parameter is a synonym for +guest ok\&. +.RE + +guest ok (S) +.PP +.RS 4 +If this parameter is +\fByes\fR +for a service, then no password is required to connect to the service\&. Privileges will be those of the +\m[blue]\fBguest account\fR\m[]\&. +.sp +This parameter nullifies the benefits of setting +\m[blue]\fBrestrict anonymous = 2\fR\m[] +.sp +See the section below on +\m[blue]\fBsecurity\fR\m[] +for more information about this option\&. +.sp +Default: +\fI\fIguest ok\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +only guest +.PP +.RS 4 +This parameter is a synonym for +guest only\&. +.RE + +guest only (S) +.PP +.RS 4 +If this parameter is +\fByes\fR +for a service, then only guest connections to the service are permitted\&. This parameter will have no effect if +\m[blue]\fBguest ok\fR\m[] +is not set for the service\&. +.sp +See the section below on +\m[blue]\fBsecurity\fR\m[] +for more information about this option\&. +.sp +Default: +\fI\fIguest only\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +hide dot files (S) +.PP +.RS 4 +This is a boolean parameter that controls whether files starting with a dot appear as hidden files\&. +.sp +Default: +\fI\fIhide dot files\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +hide files (S) +.PP +.RS 4 +This is a list of files or directories that are not visible but are accessible\&. The DOS \*(Aqhidden\*(Aq attribute is applied to any files or directories that match\&. +.sp +Each entry in the list must be separated by a \*(Aq/\*(Aq, which allows spaces to be included in the entry\&. \*(Aq*\*(Aq and \*(Aq?\*(Aq can be used to specify multiple files or directories as in DOS wildcards\&. +.sp +Each entry must be a Unix path, not a DOS path and must not include the Unix directory separator \*(Aq/\*(Aq\&. +.sp +Note that the case sensitivity option is applicable in hiding files\&. +.sp +Setting this parameter will affect the performance of Samba, as it will be forced to check all files and directories for a match as they are scanned\&. +.sp +The example shown above is based on files that the Macintosh SMB client (DAVE) available from +Thursby +creates for internal use, and also still hides all files beginning with a dot\&. +.sp +An example of us of this parameter is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +hide files = /\&.*/DesktopFolderDB/TrashFor%m/resource\&.frk/ +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIhide files\fR\fR\fI = \fR\fI # no file are hidden\fR\fI \fR +.RE + +hide new files timeout (S) +.PP +.RS 4 +Setting this parameter to something but 0 hides files that have been modified less than N seconds ago\&. +.sp +It can be used for ingest/process queue style workloads\&. A processing application should only see files that are definitely finished\&. As many applications do not have proper external workflow control, this can be a way to make sure processing does not interfere with file ingest\&. +.sp +Default: +\fI\fIhide new files timeout\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +hide special files (S) +.PP +.RS 4 +This parameter prevents clients from seeing special files such as sockets, devices and fifo\*(Aqs in directory listings\&. +.sp +Default: +\fI\fIhide special files\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +hide unreadable (S) +.PP +.RS 4 +This parameter prevents clients from seeing the existence of files that cannot be read\&. Defaults to off\&. +.sp +Please note that enabling this can slow down listing large directories significantly\&. Samba has to evaluate the ACLs of all directory members, which can be a lot of effort\&. +.sp +Default: +\fI\fIhide unreadable\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +hide unwriteable files (S) +.PP +.RS 4 +This parameter prevents clients from seeing the existence of files that cannot be written to\&. Defaults to off\&. Note that unwriteable directories are shown as usual\&. +.sp +Please note that enabling this can slow down listing large directories significantly\&. Samba has to evaluate the ACLs of all directory members, which can be a lot of effort\&. +.sp +Default: +\fI\fIhide unwriteable files\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +honor change notify privilege (S) +.PP +.RS 4 +This option can be used to make use of the change notify privilege\&. By default notify results are not checked against the file system permissions\&. +.sp +If "honor change notify privilege" is enabled, a user will only receive notify results, if he has change notify privilege or sufficient file system permissions\&. If a user has the change notify privilege, he will receive all requested notify results, even if the user does not have the permissions on the file system\&. +.sp +Default: +\fI\fIhonor change notify privilege\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +host msdfs (G) +.PP +.RS 4 +If set to +\fByes\fR, Samba will act as a Dfs server, and allow Dfs\-aware clients to browse Dfs trees hosted on the server\&. +.sp +See also the +\m[blue]\fBmsdfs root\fR\m[] +share level parameter\&. For more information on setting up a Dfs tree on Samba, refer to the MSFDS chapter in the book Samba3\-HOWTO\&. +.sp +Default: +\fI\fIhost msdfs\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +hostname lookups (G) +.PP +.RS 4 +Specifies whether samba should use (expensive) hostname lookups or use the ip addresses instead\&. An example place where hostname lookups are currently used is when checking the +hosts deny +and +hosts allow\&. +.sp +Default: +\fI\fIhostname lookups\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIhostname lookups\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +allow hosts +.PP +.RS 4 +This parameter is a synonym for +hosts allow\&. +.RE + +hosts allow (S) +.PP +.RS 4 +A synonym for this parameter is +\m[blue]\fBallow hosts\fR\m[]\&. +.sp +This parameter is a comma, space, or tab delimited set of hosts which are permitted to access a service\&. +.sp +If specified in the [global] section then it will apply to all services, regardless of whether the individual service has a different setting\&. +.sp +You can specify the hosts by name or IP number\&. For example, you could restrict access to only the hosts on a Class C subnet with something like +allow hosts = 150\&.203\&.5\&.\&. The full syntax of the list is described in the man page +hosts_access(5)\&. Note that this man page may not be present on your system, so a brief description will be given here also\&. +.sp +Note that the localhost address 127\&.0\&.0\&.1 will always be allowed access unless specifically denied by a +\m[blue]\fBhosts deny\fR\m[] +option\&. +.sp +You can also specify hosts by network/netmask pairs and by netgroup names if your system supports netgroups\&. The +\fIEXCEPT\fR +keyword can also be used to limit a wildcard list\&. The following examples may provide some help: +.sp +Example 1: allow all IPs in 150\&.203\&.*\&.*; except one +.sp +hosts allow = 150\&.203\&. EXCEPT 150\&.203\&.6\&.66 +.sp +Example 2: allow hosts that match the given network/netmask +.sp +hosts allow = 150\&.203\&.15\&.0/255\&.255\&.255\&.0 +.sp +Example 3: allow a couple of hosts +.sp +hosts allow = lapland, arvidsjaur +.sp +Example 4: allow only hosts in NIS netgroup "foonet", but deny access from one particular host +.sp +hosts allow = @foonet +.sp +hosts deny = pirate +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Note that access still requires suitable user\-level passwords\&. +.sp .5v +.RE +See +\fBtestparm\fR(1) +for a way of testing your host access to see if it does what you expect\&. +.sp +Default: +\fI\fIhosts allow\fR\fR\fI = \fR\fI # none (i\&.e\&., all hosts permitted access)\fR\fI \fR +.sp +Example: +\fI\fIhosts allow\fR\fR\fI = \fR\fI150\&.203\&.5\&. myhost\&.mynet\&.edu\&.au\fR\fI \fR +.RE + +deny hosts +.PP +.RS 4 +This parameter is a synonym for +hosts deny\&. +.RE + +hosts deny (S) +.PP +.RS 4 +The opposite of +\fIhosts allow\fR +\- hosts listed here are +\fINOT\fR +permitted access to services unless the specific services have their own lists to override this one\&. Where the lists conflict, the +\fIallow\fR +list takes precedence\&. +.sp +In the event that it is necessary to deny all by default, use the keyword ALL (or the netmask +0\&.0\&.0\&.0/0) and then explicitly specify to the +\m[blue]\fBhosts allow = hosts allow\fR\m[] +parameter those hosts that should be permitted access\&. +.sp +Default: +\fI\fIhosts deny\fR\fR\fI = \fR\fI # none (i\&.e\&., no hosts specifically excluded)\fR\fI \fR +.sp +Example: +\fI\fIhosts deny\fR\fR\fI = \fR\fI150\&.203\&.4\&. badhost\&.mynet\&.edu\&.au\fR\fI \fR +.RE + +idmap backend (G) +.PP +.RS 4 +The idmap backend provides a plugin interface for Winbind to use varying backends to store SID/uid/gid mapping tables\&. +.sp +This option specifies the default backend that is used when no special configuration set, but it is now deprecated in favour of the new spelling +\m[blue]\fBidmap config * : backend\fR\m[]\&. +.sp +Default: +\fI\fIidmap backend\fR\fR\fI = \fR\fItdb\fR\fI \fR +.RE + +idmap cache time (G) +.PP +.RS 4 +This parameter specifies the number of seconds that Winbind\*(Aqs idmap interface will cache positive SID/uid/gid query results\&. By default, Samba will cache these results for one week\&. +.sp +Default: +\fI\fIidmap cache time\fR\fR\fI = \fR\fI604800\fR\fI \fR +.RE + +idmap config DOMAIN : OPTION (G) +.PP +.RS 4 +ID mapping in Samba is the mapping between Windows SIDs and Unix user and group IDs\&. This is performed by Winbindd with a configurable plugin interface\&. Samba\*(Aqs ID mapping is configured by options starting with the +\m[blue]\fBidmap config\fR\m[] +prefix\&. An idmap option consists of the +\m[blue]\fBidmap config\fR\m[] +prefix, followed by a domain name or the asterisk character (*), a colon, and the name of an idmap setting for the chosen domain\&. +.sp +The idmap configuration is hence divided into groups, one group for each domain to be configured, and one group with the asterisk instead of a proper domain name, which specifies the default configuration that is used to catch all domains that do not have an explicit idmap configuration of their own\&. +.sp +There are three general options available: +.PP +backend = backend_name +.RS 4 +This specifies the name of the idmap plugin to use as the SID/uid/gid backend for this domain\&. The standard backends are tdb (\fBidmap_tdb\fR(8)), tdb2 (\fBidmap_tdb2\fR(8)), ldap (\fBidmap_ldap\fR(8)), rid (\fBidmap_rid\fR(8)), hash (\fBidmap_hash\fR(8)), autorid (\fBidmap_autorid\fR(8)), ad (\fBidmap_ad\fR(8)) and nss (\fBidmap_nss\fR(8))\&. The corresponding manual pages contain the details, but here is a summary\&. +.sp +The first three of these create mappings of their own using internal unixid counters and store the mappings in a database\&. These are suitable for use in the default idmap configuration\&. The rid and hash backends use a pure algorithmic calculation to determine the unixid for a SID\&. The autorid module is a mixture of the tdb and rid backend\&. It creates ranges for each domain encountered and then uses the rid algorithm for each of these automatically configured domains individually\&. The ad backend uses unix ids stored in Active Directory via the standard schema extensions\&. The nss backend reverses the standard winbindd setup and gets the unix ids via names from nsswitch which can be useful in an ldap setup\&. +.RE +.PP +range = low \- high +.RS 4 +Defines the available matching uid and gid range for which the backend is authoritative\&. For allocating backends, this also defines the start and the end of the range for allocating new unique IDs\&. +.sp +winbind uses this parameter to find the backend that is authoritative for a unix ID to SID mapping, so it must be set for each individually configured domain and for the default configuration\&. The configured ranges must be mutually disjoint\&. +.sp +Note that the low value interacts with the +\m[blue]\fBmin domain uid\fR\m[] +option! +.RE +.PP +read only = yes|no +.RS 4 +This option can be used to turn the writing backends tdb, tdb2, and ldap into read only mode\&. This can be useful e\&.g\&. in cases where a pre\-filled database exists that should not be extended automatically\&. +.RE +.sp +The following example illustrates how to configure the +\fBidmap_ad\fR(8) +backend for the CORP domain and the +\fBidmap_tdb\fR(8) +backend for all other domains\&. This configuration assumes that the admin of CORP assigns unix ids below 1000000 via the SFU extensions, and winbind is supposed to use the next million entries for its own mappings from trusted domains and for local groups for example\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + idmap config * : backend = tdb + idmap config * : range = 1000000\-1999999 + + idmap config CORP : backend = ad + idmap config CORP : range = 1000\-999999 + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +winbind gid +.PP +.RS 4 +This parameter is a synonym for +idmap gid\&. +.RE + +idmap gid (G) +.PP +.RS 4 +The idmap gid parameter specifies the range of group ids for the default idmap configuration\&. It is now deprecated in favour of +\m[blue]\fBidmap config * : range\fR\m[]\&. +.sp +See the +\m[blue]\fBidmap config\fR\m[] +option\&. +.sp +Default: +\fI\fIidmap gid\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIidmap gid\fR\fR\fI = \fR\fI10000\-20000\fR\fI \fR +.RE + +idmap negative cache time (G) +.PP +.RS 4 +This parameter specifies the number of seconds that Winbind\*(Aqs idmap interface will cache negative SID/uid/gid query results\&. +.sp +Default: +\fI\fIidmap negative cache time\fR\fR\fI = \fR\fI120\fR\fI \fR +.RE + +winbind uid +.PP +.RS 4 +This parameter is a synonym for +idmap uid\&. +.RE + +idmap uid (G) +.PP +.RS 4 +The idmap uid parameter specifies the range of user ids for the default idmap configuration\&. It is now deprecated in favour of +\m[blue]\fBidmap config * : range\fR\m[]\&. +.sp +See the +\m[blue]\fBidmap config\fR\m[] +option\&. +.sp +Default: +\fI\fIidmap uid\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIidmap uid\fR\fR\fI = \fR\fI10000\-20000\fR\fI \fR +.RE + +include (S) +.PP +.RS 4 +This allows you to include one config file inside another\&. The file is included literally, as though typed in place\&. +.sp +It takes the standard substitutions, except +\fI%u\fR, +\fI%P\fR +and +\fI%S\fR\&. +.sp +The parameter +\fIinclude = registry\fR +has a special meaning: It does +\fInot\fR +include a file named +\fIregistry\fR +from the current working directory, but instead reads the global configuration options from the registry\&. See the section on registry\-based configuration for details\&. Note that this option automatically activates registry shares\&. +.sp +Default: +\fI\fIinclude\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIinclude\fR\fR\fI = \fR\fI/usr/local/samba/lib/admin_smb\&.conf\fR\fI \fR +.RE + +include system krb5 conf (G) +.PP +.RS 4 +Setting this parameter to +no +will prevent winbind to include the system /etc/krb5\&.conf file into the krb5\&.conf file it creates\&. See also +\m[blue]\fBcreate krb5 conf\fR\m[]\&. This option only applies to Samba built with MIT Kerberos\&. +.sp +Default: +\fI\fIinclude system krb5 conf\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +inherit acls (S) +.PP +.RS 4 +This parameter is only relevant for filesystems that do not support standardized NFS4 ACLs but only a POSIX draft ACL implementation and which implements default ACLs like most filesystems on Linux\&. It can be used to ensure that if default ACLs exist on parent directories, they are always honored when creating a new file or subdirectory in these parent directories\&. The default behavior is to use the unix mode specified when creating the directory\&. Enabling this option sets the unix mode to 0777, thus guaranteeing that the default directory ACLs are propagated\&. Note that using the VFS modules acl_xattr or acl_tdb which store native Windows as meta\-data will automatically turn this option on for any share for which they are loaded, as they require this option to emulate Windows ACLs correctly\&. +.sp +Default: +\fI\fIinherit acls\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +inherit owner (S) +.PP +.RS 4 +The ownership of new files and directories is normally governed by effective uid of the connected user\&. This option allows the Samba administrator to specify that the ownership for new files and directories should be controlled by the ownership of the parent directory\&. +.sp +Valid options are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBno\fR +\- Both the Windows (SID) owner and the UNIX (uid) owner of the file are governed by the identity of the user that created the file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBwindows and unix\fR +\- The Windows (SID) owner and the UNIX (uid) owner of new files and directories are set to the respective owner of the parent directory\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fByes\fR +\- a synonym for +\fBwindows and unix\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBunix only\fR +\- Only the UNIX owner is set to the UNIX owner of the parent directory\&. +.RE +.sp +.RE +Common scenarios where this behavior is useful is in implementing drop\-boxes, where users can create and edit files but not delete them and ensuring that newly created files in a user\*(Aqs roaming profile directory are actually owned by the user\&. +.sp +The +\fBunix only\fR +option effectively breaks the tie between the Windows owner of a file and the UNIX owner\&. As a logical consequence, in this mode, setting the Windows owner of a file does not modify the UNIX owner\&. Using this mode should typically be combined with a backing store that can emulate the full NT ACL model without affecting the POSIX permissions, such as the acl_xattr VFS module, coupled with +\m[blue]\fBacl_xattr:ignore system acls = yes\fR\m[]\&. This can be used to emulate folder quotas, when files are exposed only via SMB (without UNIX extensions)\&. The UNIX owner of a directory is locally set and inherited by all subdirectories and files, and they all consume the same quota\&. +.sp +Default: +\fI\fIinherit owner\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +inherit permissions (S) +.PP +.RS 4 +The permissions on new files and directories are normally governed by +\m[blue]\fBcreate mask\fR\m[], +\m[blue]\fBdirectory mask\fR\m[], +\m[blue]\fBforce create mode\fR\m[] +and +\m[blue]\fBforce directory mode\fR\m[] +but the boolean inherit permissions parameter overrides this\&. +.sp +New directories inherit the mode of the parent directory, including bits such as setgid\&. +.sp +New files inherit their read/write bits from the parent directory\&. Their execute bits continue to be determined by +\m[blue]\fBmap archive\fR\m[], +\m[blue]\fBmap hidden\fR\m[] +and +\m[blue]\fBmap system\fR\m[] +as usual\&. +.sp +Note that the setuid bit is +\fInever\fR +set via inheritance (the code explicitly prohibits this)\&. +.sp +This can be particularly useful on large systems with many users, perhaps several thousand, to allow a single [homes] share to be used flexibly by each user\&. +.sp +Default: +\fI\fIinherit permissions\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +init logon delay (G) +.PP +.RS 4 +This parameter specifies a delay in milliseconds for the hosts configured for delayed initial samlogon with +\m[blue]\fBinit logon delayed hosts\fR\m[]\&. +.sp +Default: +\fI\fIinit logon delay\fR\fR\fI = \fR\fI100\fR\fI \fR +.RE + +init logon delayed hosts (G) +.PP +.RS 4 +This parameter takes a list of host names, addresses or networks for which the initial samlogon reply should be delayed (so other DCs get preferred by XP workstations if there are any)\&. +.sp +The length of the delay can be specified with the +\m[blue]\fBinit logon delay\fR\m[] +parameter\&. +.sp +Default: +\fI\fIinit logon delayed hosts\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIinit logon delayed hosts\fR\fR\fI = \fR\fI150\&.203\&.5\&. myhost\&.mynet\&.de\fR\fI \fR +.RE + +interfaces (G) +.PP +.RS 4 +This option allows you to override the default network interfaces list that Samba will use for browsing, name registration and other NetBIOS over TCP/IP (NBT) traffic\&. By default Samba will query the kernel for the list of all active interfaces and use any interfaces except 127\&.0\&.0\&.1 that are broadcast capable\&. +.sp +The option takes a list of interface strings\&. Each string can be in any of the following forms: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a network interface name (such as eth0)\&. This may include shell\-like wildcards so eth* will match any interface starting with the substring "eth" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +an IP address\&. In this case the netmask is determined from the list of interfaces obtained from the kernel +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +an IP/mask pair\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a broadcast/mask pair\&. +.RE +.sp +.RE +The "mask" parameters can either be a bit length (such as 24 for a C class network) or a full netmask in dotted decimal form\&. +.sp +The "IP" parameters above can either be a full dotted decimal IP address or a hostname which will be looked up via the OS\*(Aqs normal hostname resolution mechanisms\&. +.sp +By default Samba enables all active interfaces that are broadcast capable except the loopback adaptor (IP address 127\&.0\&.0\&.1)\&. +.sp +In order to support SMB3 multi\-channel configurations, smbd understands some extra parameters which can be appended after the actual interface with this extended syntax (note that the quoting is important in order to handle the ; and , characters): +.sp +"interface[;key1=value1[,key2=value2[\&.\&.\&.]]]" +.sp +Known keys are speed, capability, and if_index\&. Speed is specified in bits per second\&. Known capabilities are RSS and RDMA\&. The if_index should be used with care: the values must not coincide with indexes used by the kernel\&. Note that these options are mainly intended for testing and development rather than for production use\&. At least on Linux systems, these values should be auto\-detected, but the settings can serve as last a resort when autodetection is not working or is not available\&. The specified values overwrite the auto\-detected values\&. +.sp +The first two example below configures three network interfaces corresponding to the eth0 device and IP addresses 192\&.168\&.2\&.10 and 192\&.168\&.3\&.10\&. The netmasks of the latter two interfaces would be set to 255\&.255\&.255\&.0\&. +.sp +The other examples show how per interface extra parameters can be specified\&. Notice the possible usage of "," and ";", which makes the double quoting necessary\&. +.sp +Default: +\fI\fIinterfaces\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIinterfaces\fR\fR\fI = \fR\fIeth0 192\&.168\&.2\&.10/24 192\&.168\&.3\&.10/255\&.255\&.255\&.0\fR\fI \fR +.sp +Example: +\fI\fIinterfaces\fR\fR\fI = \fR\fIeth0, 192\&.168\&.2\&.10/24; 192\&.168\&.3\&.10/255\&.255\&.255\&.0\fR\fI \fR +.sp +Example: +\fI\fIinterfaces\fR\fR\fI = \fR\fI"eth0;if_index=65,speed=1000000000,capability=RSS"\fR\fI \fR +.sp +Example: +\fI\fIinterfaces\fR\fR\fI = \fR\fI"lo;speed=1000000000" "eth0;capability=RSS"\fR\fI \fR +.sp +Example: +\fI\fIinterfaces\fR\fR\fI = \fR\fI"lo;speed=1000000000" , "eth0;capability=RSS"\fR\fI \fR +.sp +Example: +\fI\fIinterfaces\fR\fR\fI = \fR\fI"eth0;capability=RSS" , "rdma1;capability=RDMA" ; "rdma2;capability=RSS,capability=RDMA"\fR\fI \fR +.RE + +invalid users (S) +.PP +.RS 4 +This is a list of users that should not be allowed to login to this service\&. This is really a +\fIparanoid\fR +check to absolutely ensure an improper setting does not breach your security\&. +.sp +A name starting with a \*(Aq@\*(Aq is interpreted as an NIS netgroup first (if your system supports NIS), and then as a UNIX group if the name was not found in the NIS netgroup database\&. +.sp +A name starting with \*(Aq+\*(Aq is interpreted only by looking in the UNIX group database via the NSS getgrnam() interface\&. A name starting with \*(Aq&\*(Aq is interpreted only by looking in the NIS netgroup database (this requires NIS to be working on your system)\&. The characters \*(Aq+\*(Aq and \*(Aq&\*(Aq may be used at the start of the name in either order so the value +\fI+&group\fR +means check the UNIX group database, followed by the NIS netgroup database, and the value +\fI&+group\fR +means check the NIS netgroup database, followed by the UNIX group database (the same as the \*(Aq@\*(Aq prefix)\&. +.sp +The current servicename is substituted for +\fI%S\fR\&. This is useful in the [homes] section\&. +.sp +Default: +\fI\fIinvalid users\fR\fR\fI = \fR\fI # no invalid users\fR\fI \fR +.sp +Example: +\fI\fIinvalid users\fR\fR\fI = \fR\fIroot fred admin @wheel\fR\fI \fR +.RE + +iprint server (G) +.PP +.RS 4 +This parameter is only applicable if +\m[blue]\fBprinting\fR\m[] +is set to +\fBiprint\fR\&. +.sp +If set, this option overrides the ServerName option in the CUPS +client\&.conf\&. This is necessary if you have virtual samba servers that connect to different CUPS daemons\&. +.sp +Default: +\fI\fIiprint server\fR\fR\fI = \fR\fI""\fR\fI \fR +.sp +Example: +\fI\fIiprint server\fR\fR\fI = \fR\fIMYCUPSSERVER\fR\fI \fR +.RE + +kdc default domain supported enctypes (G) +.PP +.RS 4 +Set the default value of +\fBmsDS\-SupportedEncryptionTypes\fR +for service accounts in Active Directory that are missing this value or where +\fBmsDS\-SupportedEncryptionTypes\fR +is set to 0\&. +.sp +This allows Samba administrators to match the configuration flexibility provided by the +\fBHKEY_LOCAL_MACHINE\eSystem\eCurrentControlSet\eservices\eKDC\eDefaultDomainSupportedEncTypes\fR +Registry Value on Windows\&. +.sp +Unlike the Windows registry key (which only takes an base\-10 number), in Samba this may also be expressed in hexadecimal or as a list of Kerberos encryption type names\&. +.sp +Specified values are ORed together bitwise, and those currently supported consist of: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBarcfour\-hmac\-md5\fR, +\fBrc4\-hmac\fR, +\fB0x4\fR, or +\fB4\fR +.sp +Known on Windows as Kerberos RC4 encryption +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBaes128\-cts\-hmac\-sha1\-96\fR, +\fBaes128\-cts\fR, +\fB0x8\fR, or +\fB8\fR +.sp +Known on Windows as Kerberos AES 128 bit encryption +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBaes256\-cts\-hmac\-sha1\-96\fR, +\fBaes256\-cts\fR, +\fB0x10\fR, or +\fB16\fR +.sp +Known on Windows as Kerberos AES 256 bit encryption +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBaes256\-cts\-hmac\-sha1\-96\-sk\fR, +\fBaes256\-cts\-sk\fR, +\fB0x20\fR, or +\fB32\fR +.sp +Allow AES session keys\&. When this is set, it indicates to the KDC that AES session keys can be used, even when +\fBaes256\-cts\fR +and +\fBaes128\-cts\fR +are not set\&. This allows use of AES keys against hosts otherwise only configured with RC4 for ticket keys (which is the default)\&. +.RE +.sp +.RE +Default: +\fI\fIkdc default domain supported enctypes\fR\fR\fI = \fR\fI0 # maps to what the software supports currently: arcfour\-hmac\-md5 aes256\-cts\-hmac\-sha1\-96\-sk\fR\fI \fR +.RE + +kdc enable fast (G) +.PP +.RS 4 +With the Samba 4\&.16 the embedded Heimdal KDC brings support for RFC6113 FAST, which wasn\*(Aqt available in older Samba versions\&. +.sp +This option is mostly for testing and currently only applies if the embedded Heimdal KDC is used\&. +.sp +Default: +\fI\fIkdc enable fast\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +kdc force enable rc4 weak session keys (G) +.PP +.RS 4 +\fBRFC8429\fR +declares that +\fBrc4\-hmac\fR +Kerberos ciphers are weak and there are known attacks on Active Directory use of this cipher suite\&. +.sp +However for compatibility with Microsoft Windows this option allows the KDC to assume that regardless of the value set in a service account\*(Aqs +\fBmsDS\-SupportedEncryptionTypes\fR +attribute that a +\fBrc4\-hmac\fR +Kerberos session key (as distinct from the ticket key, as found in a service keytab) can be used if the potentially older client requests it\&. +.sp +Default: +\fI\fIkdc force enable rc4 weak session keys\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +kdc supported enctypes (G) +.PP +.RS 4 +On an active directory domain controller, this is the list of supported encryption types for local running kdc\&. +.sp +This allows Samba administrators to remove support for weak/unused encryption types, similar the configuration flexibility provided by the +\fBNetwork security: Configure encryption types allowed for Kerberos\fR +GPO/Local Policies/Security Options Value, which results in the +\fBHKEY_LOCAL_MACHINE\eSOFTWARE\eMicrosoft\eWindows\eCurrentVersion\ePolicies\eSystem\eKerberos\eParameters\eSupportedEncryptionTypes\fR +Registry Value on Windows\&. +.sp +Unlike the Windows registry key (which only takes an base\-10 number), in Samba this may also be expressed as hexadecimal or a list of Kerberos encryption type names\&. +.sp +Specified values are ORed together bitwise, and those currently supported consist of: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBarcfour\-hmac\-md5\fR, +\fBrc4\-hmac\fR, +\fB0x4\fR, or +\fB4\fR +.sp +Known on Windows as Kerberos RC4 encryption +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBaes128\-cts\-hmac\-sha1\-96\fR, +\fBaes128\-cts\fR, +\fB0x8\fR, or +\fB8\fR +.sp +Known on Windows as Kerberos AES 128 bit encryption +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBaes256\-cts\-hmac\-sha1\-96\fR, +\fBaes256\-cts\fR, +\fB0x10\fR, or +\fB16\fR +.sp +Known on Windows as Kerberos AES 256 bit encryption +.RE +.sp +.RE +Default: +\fI\fIkdc supported enctypes\fR\fR\fI = \fR\fI0 # maps to what the software supports currently: arcfour\-hmac\-md5 aes128\-cts\-hmac\-sha1\-96 aes256\-cts\-hmac\-sha1\-96\fR\fI \fR +.RE + +keepalive (G) +.PP +.RS 4 +The value of the parameter (an integer) represents the number of seconds between +\fIkeepalive\fR +packets\&. If this parameter is zero, no keepalive packets will be sent\&. Keepalive packets, if sent, allow the server to tell whether a client is still present and responding\&. +.sp +Keepalives should, in general, not be needed if the socket has the SO_KEEPALIVE attribute set on it by default\&. (see +\m[blue]\fBsocket options\fR\m[])\&. Basically you should only use this option if you strike difficulties\&. +.sp +Please note this option only applies to SMB1 client connections, and has no effect on SMB2 clients\&. +.sp +Default: +\fI\fIkeepalive\fR\fR\fI = \fR\fI300\fR\fI \fR +.sp +Example: +\fI\fIkeepalive\fR\fR\fI = \fR\fI600\fR\fI \fR +.RE + +kerberos encryption types (G) +.PP +.RS 4 +This parameter determines the encryption types to use when operating as a Kerberos client\&. Possible values are +\fIall\fR, +\fIstrong\fR, and +\fIlegacy\fR\&. +.sp +Samba uses a Kerberos library (MIT or Heimdal) to obtain Kerberos tickets\&. This library is normally configured outside of Samba, using the krb5\&.conf file\&. This file may also include directives to configure the encryption types to be used\&. However, Samba implements Active Directory protocols and algorithms to locate a domain controller\&. In order to force the Kerberos library into using the correct domain controller, some Samba processes, such as +\fBwinbindd\fR(8) +and +\fBnet\fR(8), build a private krb5\&.conf file for use by the Kerberos library while being invoked from Samba\&. This private file controls all aspects of the Kerberos library operation, and this parameter controls how the encryption types are configured within this generated file, and therefore also controls the encryption types negotiable by Samba\&. +.sp +When set to +\fBall\fR, all active directory encryption types are allowed\&. +.sp +When set to +\fBstrong\fR, only AES\-based encryption types are offered\&. This can be used in hardened environments to prevent downgrade attacks\&. +.sp +When set to +\fBlegacy\fR, only RC4\-HMAC\-MD5 is allowed\&. AVOID using this option, because of +CVE\-2022\-37966 +see +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15237\&. +.sp +Default: +\fI\fIkerberos encryption types\fR\fR\fI = \fR\fIall\fR\fI \fR +.RE + +kerberos method (G) +.PP +.RS 4 +Controls how kerberos tickets are verified\&. +.sp +Valid options are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secrets only \- use only the secrets\&.tdb for ticket verification (default) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +system keytab \- use only the system keytab for ticket verification +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +dedicated keytab \- use a dedicated keytab for ticket verification +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secrets and keytab \- use the secrets\&.tdb first, then the system keytab +.RE +.sp +.RE +The major difference between "system keytab" and "dedicated keytab" is that the latter method relies on kerberos to find the correct keytab entry instead of filtering based on expected principals\&. +.sp +When the kerberos method is in "dedicated keytab" mode, +\m[blue]\fBdedicated keytab file\fR\m[] +must be set to specify the location of the keytab file\&. +.sp +Default: +\fI\fIkerberos method\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +kernel change notify (G) +.PP +.RS 4 +This parameter specifies whether Samba should ask the kernel for change notifications in directories so that SMB clients can refresh whenever the data on the server changes\&. +.sp +This parameter is only used when your kernel supports change notification to user programs using the inotify interface\&. +.sp +Default: +\fI\fIkernel change notify\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +kernel oplocks (S) +.PP +.RS 4 +For UNIXes that support kernel based +\m[blue]\fBoplocks\fR\m[] +(currently only Linux), this parameter allows the use of them to be turned on or off\&. However, this disables Level II oplocks for clients as the Linux kernel does not support them properly\&. +.sp +Kernel oplocks support allows Samba +\fIoplocks \fR +to be broken whenever a local UNIX process or NFS operation accesses a file that +\fBsmbd\fR(8) +has oplocked\&. This allows complete data consistency between SMB/CIFS, NFS and local file access (and is a +\fIvery\fR +cool feature :\-)\&. +.sp +If you do not need this interaction, you should disable the parameter on Linux to get Level II oplocks and the associated performance benefit\&. +.sp +This parameter defaults to +\fBno\fR +and is translated to a no\-op on systems that do not have the necessary kernel support\&. +.sp +Default: +\fI\fIkernel oplocks\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +kernel share modes (S) +.PP +.RS 4 +This parameter controls whether SMB share modes are translated into file system specific sharemode calls\&. +.sp +Kernel share modes provide a minimal level of interoperability with local UNIX processes and NFS operations by preventing access corresponding to the SMB share modes\&. This requires a file system specific VFS module with proper support\&. +.sp +Note that in order to use SMB2 durable file handles on a share, you have to turn kernel share modes off\&. +.sp +This parameter defaults to +\fBno\fR\&. Setting it to +\fByes\fR +requires a file system module that supports file system sharemodes, otherwise attempts to access files will fail with a sharing violation\&. +.sp +Default: +\fI\fIkernel share modes\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +kpasswd port (G) +.PP +.RS 4 +Specifies which ports the Kerberos server should listen on for password changes\&. +.sp +Default: +\fI\fIkpasswd port\fR\fR\fI = \fR\fI464\fR\fI \fR +.RE + +krb5 port (G) +.PP +.RS 4 +Specifies which port the KDC should listen on for Kerberos traffic\&. +.sp +Default: +\fI\fIkrb5 port\fR\fR\fI = \fR\fI88\fR\fI \fR +.RE + +lanman auth (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.11 and support for LanMan (as distinct from NTLM, NTLMv2 or Kerberos authentication) will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +lanman auth = no +will be the enforced behaviour\&. +.sp +This parameter determines whether or not +\fBsmbd\fR(8) +will attempt to authenticate users or permit password changes using the LANMAN password hash\&. If disabled, only clients which support NT password hashes (e\&.g\&. Windows NT/2000 clients, smbclient, but not Windows 95/98 or the MS DOS network client) will be able to connect to the Samba host\&. +.sp +The LANMAN encrypted response is easily broken, due to its case\-insensitive nature, and the choice of algorithm\&. Servers without Windows 95/98/ME or MS DOS clients are advised to disable this option\&. +.sp +When this parameter is set to +no +this will also result in sambaLMPassword in Samba\*(Aqs passdb being blanked after the next password change\&. As a result of that lanman clients won\*(Aqt be able to authenticate, even if lanman auth is re\-enabled later on\&. +.sp +Unlike the +\fIencrypt passwords\fR +option, this parameter cannot alter client behaviour, and the LANMAN response will still be sent over the network\&. See the +client lanman auth +to disable this for Samba\*(Aqs clients (such as smbclient) +.sp +This parameter is overridden by +\fIntlm auth\fR, so unless that it is also set to +\fBntlmv1\-permitted\fR +or +\fByes\fR, then only NTLMv2 logins will be permitted and no LM hash will be stored\&. All modern clients support NTLMv2, and but some older clients require special configuration to use it\&. +.sp +\fIThis parameter has no impact on the Samba AD DC, LM authentication is always disabled and no LM password is ever stored\&.\fR +.sp +Default: +\fI\fIlanman auth\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +large readwrite (G) +.PP +.RS 4 +This parameter determines whether or not +\fBsmbd\fR(8) +supports the new 64k streaming read and write variant SMB requests introduced with Windows 2000\&. Note that due to Windows 2000 client redirector bugs this requires Samba to be running on a 64\-bit capable operating system such as IRIX, Solaris or a Linux 2\&.4 kernel\&. Can improve performance by 10% with Windows 2000 clients\&. Defaults to on\&. Not as tested as some other Samba code paths\&. +.sp +Default: +\fI\fIlarge readwrite\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ldap admin dn (G) +.PP +.RS 4 +The +\m[blue]\fBldap admin dn\fR\m[] +defines the Distinguished Name (DN) name used by Samba to contact the ldap server when retrieving user account information\&. The +\m[blue]\fBldap admin dn\fR\m[] +is used in conjunction with the admin dn password stored in the +private/secrets\&.tdb +file\&. See the +\fBsmbpasswd\fR(8) +man page for more information on how to accomplish this\&. +.sp +The +\m[blue]\fBldap admin dn\fR\m[] +requires a fully specified DN\&. The +\m[blue]\fBldap suffix\fR\m[] +is not appended to the +\m[blue]\fBldap admin dn\fR\m[]\&. +.sp +\fINo default\fR +.RE + +ldap connection timeout (G) +.PP +.RS 4 +This parameter tells the LDAP library calls which timeout in seconds they should honor during initial connection establishments to LDAP servers\&. It is very useful in failover scenarios in particular\&. If one or more LDAP servers are not reachable at all, we do not have to wait until TCP timeouts are over\&. This feature must be supported by your LDAP library\&. +.sp +This parameter is different from +\m[blue]\fBldap timeout\fR\m[] +which affects operations on LDAP servers using an existing connection and not establishing an initial connection\&. +.sp +Default: +\fI\fIldap connection timeout\fR\fR\fI = \fR\fI2\fR\fI \fR +.RE + +ldap debug level (G) +.PP +.RS 4 +This parameter controls the debug level of the LDAP library calls\&. In the case of OpenLDAP, it is the same bit\-field as understood by the server and documented in the +\fBslapd.conf\fR(5) +manpage\&. A typical useful value will be +\fI1\fR +for tracing function calls\&. +.sp +The debug output from the LDAP libraries appears with the prefix [LDAP] in Samba\*(Aqs logging output\&. The level at which LDAP logging is printed is controlled by the parameter +\fIldap debug threshold\fR\&. +.sp +Default: +\fI\fIldap debug level\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fIldap debug level\fR\fR\fI = \fR\fI1\fR\fI \fR +.RE + +ldap debug threshold (G) +.PP +.RS 4 +This parameter controls the Samba debug level at which the ldap library debug output is printed in the Samba logs\&. See the description of +\fIldap debug level\fR +for details\&. +.sp +Default: +\fI\fIldap debug threshold\fR\fR\fI = \fR\fI10\fR\fI \fR +.sp +Example: +\fI\fIldap debug threshold\fR\fR\fI = \fR\fI5\fR\fI \fR +.RE + +ldap delete dn (G) +.PP +.RS 4 +This parameter specifies whether a delete operation in the ldapsam deletes the complete entry or only the attributes specific to Samba\&. +.sp +Default: +\fI\fIldap delete dn\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +ldap deref (G) +.PP +.RS 4 +This option controls whether Samba should tell the LDAP library to use a certain alias dereferencing method\&. The default is +\fIauto\fR, which means that the default setting of the ldap client library will be kept\&. Other possible values are +\fInever\fR, +\fIfinding\fR, +\fIsearching\fR +and +\fIalways\fR\&. Grab your LDAP manual for more information\&. +.sp +Default: +\fI\fIldap deref\fR\fR\fI = \fR\fIauto\fR\fI \fR +.sp +Example: +\fI\fIldap deref\fR\fR\fI = \fR\fIsearching\fR\fI \fR +.RE + +ldap follow referral (G) +.PP +.RS 4 +This option controls whether to follow LDAP referrals or not when searching for entries in the LDAP database\&. Possible values are +\fIon\fR +to enable following referrals, +\fIoff\fR +to disable this, and +\fIauto\fR, to use the libldap default settings\&. libldap\*(Aqs choice of following referrals or not is set in /etc/openldap/ldap\&.conf with the REFERRALS parameter as documented in ldap\&.conf(5)\&. +.sp +Default: +\fI\fIldap follow referral\fR\fR\fI = \fR\fIauto\fR\fI \fR +.sp +Example: +\fI\fIldap follow referral\fR\fR\fI = \fR\fIoff\fR\fI \fR +.RE + +ldap group suffix (G) +.PP +.RS 4 +This parameter specifies the suffix that is used for groups when these are added to the LDAP directory\&. If this parameter is unset, the value of +\m[blue]\fBldap suffix\fR\m[] +will be used instead\&. The suffix string is prepended to the +\m[blue]\fBldap suffix\fR\m[] +string so use a partial DN\&. +.sp +Default: +\fI\fIldap group suffix\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIldap group suffix\fR\fR\fI = \fR\fIou=Groups\fR\fI \fR +.RE + +ldap idmap suffix (G) +.PP +.RS 4 +This parameters specifies the suffix that is used when storing idmap mappings\&. If this parameter is unset, the value of +\m[blue]\fBldap suffix\fR\m[] +will be used instead\&. The suffix string is prepended to the +\m[blue]\fBldap suffix\fR\m[] +string so use a partial DN\&. +.sp +Default: +\fI\fIldap idmap suffix\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIldap idmap suffix\fR\fR\fI = \fR\fIou=Idmap\fR\fI \fR +.RE + +ldap machine suffix (G) +.PP +.RS 4 +It specifies where machines should be added to the ldap tree\&. If this parameter is unset, the value of +\m[blue]\fBldap suffix\fR\m[] +will be used instead\&. The suffix string is prepended to the +\m[blue]\fBldap suffix\fR\m[] +string so use a partial DN\&. +.sp +Default: +\fI\fIldap machine suffix\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIldap machine suffix\fR\fR\fI = \fR\fIou=Computers\fR\fI \fR +.RE + +ldap max anonymous request size (G) +.PP +.RS 4 +This parameter specifies the maximum permitted size (in bytes) for an LDAP request received on an anonymous connection\&. +.sp +If the request size exceeds this limit the request will be rejected\&. +.sp +Default: +\fI\fIldap max anonymous request size\fR\fR\fI = \fR\fI256000\fR\fI \fR +.sp +Example: +\fI\fIldap max anonymous request size\fR\fR\fI = \fR\fI500000\fR\fI \fR +.RE + +ldap max authenticated request size (G) +.PP +.RS 4 +This parameter specifies the maximum permitted size (in bytes) for an LDAP request received on an authenticated connection\&. +.sp +If the request size exceeds this limit the request will be rejected\&. +.sp +Default: +\fI\fIldap max authenticated request size\fR\fR\fI = \fR\fI16777216\fR\fI \fR +.sp +Example: +\fI\fIldap max authenticated request size\fR\fR\fI = \fR\fI4194304\fR\fI \fR +.RE + +ldap max search request size (G) +.PP +.RS 4 +This parameter specifies the maximum permitted size (in bytes) for an LDAP search request\&. +.sp +If the request size exceeds this limit the request will be rejected\&. +.sp +Default: +\fI\fIldap max search request size\fR\fR\fI = \fR\fI256000\fR\fI \fR +.sp +Example: +\fI\fIldap max search request size\fR\fR\fI = \fR\fI4194304\fR\fI \fR +.RE + +ldap page size (G) +.PP +.RS 4 +This parameter specifies the number of entries per page\&. +.sp +If the LDAP server supports paged results, clients can request subsets of search results (pages) instead of the entire list\&. This parameter specifies the size of these pages\&. +.sp +Default: +\fI\fIldap page size\fR\fR\fI = \fR\fI1000\fR\fI \fR +.sp +Example: +\fI\fIldap page size\fR\fR\fI = \fR\fI512\fR\fI \fR +.RE + +ldap password sync +.PP +.RS 4 +This parameter is a synonym for +ldap passwd sync\&. +.RE + +ldap passwd sync (G) +.PP +.RS 4 +This option is used to define whether or not Samba should sync the LDAP password with the NT and LM hashes for normal accounts (NOT for workstation, server or domain trusts) on a password change via SAMBA\&. +.sp +The +\m[blue]\fBldap passwd sync\fR\m[] +can be set to one of three values: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIYes\fR += Try to update the LDAP, NT and LM passwords and update the pwdLastSet time\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINo\fR += Update NT and LM passwords and update the pwdLastSet time\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIOnly\fR += Only update the LDAP password and let the LDAP server do the rest\&. +.RE +.sp +.RE +Default: +\fI\fIldap passwd sync\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +ldap replication sleep (G) +.PP +.RS 4 +When Samba is asked to write to a read\-only LDAP replica, we are redirected to talk to the read\-write master server\&. This server then replicates our changes back to the \*(Aqlocal\*(Aq server, however the replication might take some seconds, especially over slow links\&. Certain client activities, particularly domain joins, can become confused by the \*(Aqsuccess\*(Aq that does not immediately change the LDAP back\-end\*(Aqs data\&. +.sp +This option simply causes Samba to wait a short time, to allow the LDAP server to catch up\&. If you have a particularly high\-latency network, you may wish to time the LDAP replication with a network sniffer, and increase this value accordingly\&. Be aware that no checking is performed that the data has actually replicated\&. +.sp +The value is specified in milliseconds, the maximum value is 5000 (5 seconds)\&. +.sp +Default: +\fI\fIldap replication sleep\fR\fR\fI = \fR\fI1000\fR\fI \fR +.RE + +ldapsam:editposix (G) +.PP +.RS 4 +Editposix is an option that leverages ldapsam:trusted to make it simpler to manage a domain controller eliminating the need to set up custom scripts to add and manage the posix users and groups\&. This option will instead directly manipulate the ldap tree to create, remove and modify user and group entries\&. This option also requires a running winbindd as it is used to allocate new uids/gids on user/group creation\&. The allocation range must be therefore configured\&. +.sp +To use this option, a basic ldap tree must be provided and the ldap suffix parameters must be properly configured\&. On virgin servers the default users and groups (Administrator, Guest, Domain Users, Domain Admins, Domain Guests) can be precreated with the command +net sam provision\&. To run this command the ldap server must be running, Winbindd must be running and the smb\&.conf ldap options must be properly configured\&. The typical ldap setup used with the +\m[blue]\fBldapsam:trusted = yes\fR\m[] +option is usually sufficient to use +\m[blue]\fBldapsam:editposix = yes\fR\m[] +as well\&. +.sp +An example configuration can be the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf + encrypt passwords = true + passdb backend = ldapsam + + ldapsam:trusted=yes + ldapsam:editposix=yes + + ldap admin dn = cn=admin,dc=samba,dc=org + ldap delete dn = yes + ldap group suffix = ou=groups + ldap idmap suffix = ou=idmap + ldap machine suffix = ou=computers + ldap user suffix = ou=users + ldap suffix = dc=samba,dc=org + + idmap backend = ldap:"ldap://localhost" + + idmap uid = 5000\-50000 + idmap gid = 5000\-50000 + +.fi +.if n \{\ +.RE +.\} +.sp +This configuration assumes a directory layout like described in the following ldif: +.sp +.if n \{\ +.RS 4 +.\} +.nf + dn: dc=samba,dc=org + objectClass: top + objectClass: dcObject + objectClass: organization + o: samba\&.org + dc: samba + + dn: cn=admin,dc=samba,dc=org + objectClass: simpleSecurityObject + objectClass: organizationalRole + cn: admin + description: LDAP administrator + userPassword: secret + + dn: ou=users,dc=samba,dc=org + objectClass: top + objectClass: organizationalUnit + ou: users + + dn: ou=groups,dc=samba,dc=org + objectClass: top + objectClass: organizationalUnit + ou: groups + + dn: ou=idmap,dc=samba,dc=org + objectClass: top + objectClass: organizationalUnit + ou: idmap + + dn: ou=computers,dc=samba,dc=org + objectClass: top + objectClass: organizationalUnit + ou: computers + +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIldapsam:editposix\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +ldapsam:trusted (G) +.PP +.RS 4 +By default, Samba as a Domain Controller with an LDAP backend needs to use the Unix\-style NSS subsystem to access user and group information\&. Due to the way Unix stores user information in /etc/passwd and /etc/group this inevitably leads to inefficiencies\&. One important question a user needs to know is the list of groups he is member of\&. The plain UNIX model involves a complete enumeration of the file /etc/group and its NSS counterparts in LDAP\&. UNIX has optimized functions to enumerate group membership\&. Sadly, other functions that are used to deal with user and group attributes lack such optimization\&. +.sp +To make Samba scale well in large environments, the +\m[blue]\fBldapsam:trusted = yes\fR\m[] +option assumes that the complete user and group database that is relevant to Samba is stored in LDAP with the standard posixAccount/posixGroup attributes\&. It further assumes that the Samba auxiliary object classes are stored together with the POSIX data in the same LDAP object\&. If these assumptions are met, +\m[blue]\fBldapsam:trusted = yes\fR\m[] +can be activated and Samba can bypass the NSS system to query user group memberships\&. Optimized LDAP queries can greatly speed up domain logon and administration tasks\&. Depending on the size of the LDAP database a factor of 100 or more for common queries is easily achieved\&. +.sp +Default: +\fI\fIldapsam:trusted\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +ldap server require strong auth (G) +.PP +.RS 4 +The +\m[blue]\fBldap server require strong auth\fR\m[] +defines whether the ldap server requires ldap traffic to be signed or signed and encrypted (sealed)\&. Possible values are +\fIno\fR, +\fIallow_sasl_over_tls\fR +and +\fIyes\fR\&. +.sp +A value of +\fIno\fR +allows simple and sasl binds over all transports\&. +.sp +A value of +\fIallow_sasl_over_tls\fR +allows simple and sasl binds (without sign or seal) over TLS encrypted connections\&. Unencrypted connections only allow sasl binds with sign or seal\&. +.sp +A value of +\fIyes\fR +allows only simple binds over TLS encrypted connections\&. Unencrypted connections only allow sasl binds with sign or seal\&. +.sp +Default: +\fI\fIldap server require strong auth\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ldap ssl (G) +.PP +.RS 4 +This option is used to define whether or not Samba should use SSL when connecting to the ldap server This is +\fINOT\fR +related to Samba\*(Aqs previous SSL support which was enabled by specifying the +\-\-with\-ssl +option to the +configure +script\&. +.sp +LDAP connections should be secured where possible\&. This may be done setting +\fIeither\fR +this parameter to +\fIstart tls\fR +\fIor\fR +by specifying +\fIldaps://\fR +in the URL argument of +\m[blue]\fBpassdb backend\fR\m[]\&. +.sp +The +\m[blue]\fBldap ssl\fR\m[] +can be set to one of two values: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIOff\fR += Never use SSL when querying the directory\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIstart tls\fR += Use the LDAPv3 StartTLS extended operation (RFC2830) for communicating with the directory server\&. +.RE +.sp +.RE +Please note that this parameter does only affect +\fIrpc\fR +methods\&. +.sp +Default: +\fI\fIldap ssl\fR\fR\fI = \fR\fIstart tls\fR\fI \fR +.RE + +ldap suffix (G) +.PP +.RS 4 +Specifies the base for all ldap suffixes and for storing the sambaDomain object\&. +.sp +The ldap suffix will be appended to the values specified for the +\m[blue]\fBldap user suffix\fR\m[], +\m[blue]\fBldap group suffix\fR\m[], +\m[blue]\fBldap machine suffix\fR\m[], and the +\m[blue]\fBldap idmap suffix\fR\m[]\&. Each of these should be given only a DN relative to the +\m[blue]\fBldap suffix\fR\m[]\&. +.sp +Default: +\fI\fIldap suffix\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIldap suffix\fR\fR\fI = \fR\fIdc=samba,dc=org\fR\fI \fR +.RE + +ldap timeout (G) +.PP +.RS 4 +This parameter defines the number of seconds that Samba should use as timeout for LDAP operations\&. +.sp +Default: +\fI\fIldap timeout\fR\fR\fI = \fR\fI15\fR\fI \fR +.RE + +ldap user suffix (G) +.PP +.RS 4 +This parameter specifies where users are added to the tree\&. If this parameter is unset, the value of +\m[blue]\fBldap suffix\fR\m[] +will be used instead\&. The suffix string is prepended to the +\m[blue]\fBldap suffix\fR\m[] +string so use a partial DN\&. +.sp +Default: +\fI\fIldap user suffix\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIldap user suffix\fR\fR\fI = \fR\fIou=people\fR\fI \fR +.RE + +level2 oplocks (S) +.PP +.RS 4 +This parameter controls whether Samba supports level2 (read\-only) oplocks on a share\&. +.sp +Level2, or read\-only oplocks allow Windows NT clients that have an oplock on a file to downgrade from a read\-write oplock to a read\-only oplock once a second client opens the file (instead of releasing all oplocks on a second open, as in traditional, exclusive oplocks)\&. This allows all openers of the file that support level2 oplocks to cache the file for read\-ahead only (ie\&. they may not cache writes or lock requests) and increases performance for many accesses of files that are not commonly written (such as application \&.EXE files)\&. +.sp +Once one of the clients which have a read\-only oplock writes to the file all clients are notified (no reply is needed or waited for) and told to break their oplocks to "none" and delete any read\-ahead caches\&. +.sp +It is recommended that this parameter be turned on to speed access to shared executables\&. +.sp +For more discussions on level2 oplocks see the CIFS spec\&. +.sp +Currently, if +\m[blue]\fBkernel oplocks\fR\m[] +are supported then level2 oplocks are not granted (even if this parameter is set to +\fByes\fR)\&. Note also, the +\m[blue]\fBoplocks\fR\m[] +parameter must be set to +\fByes\fR +on this share in order for this parameter to have any effect\&. +.sp +Default: +\fI\fIlevel2 oplocks\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +lm announce (G) +.PP +.RS 4 +This parameter determines if +\fBnmbd\fR(8) +will produce Lanman announce broadcasts that are needed by OS/2 clients in order for them to see the Samba server in their browse list\&. This parameter can have three values, +\fByes\fR, +\fBno\fR, or +\fBauto\fR\&. The default is +\fBauto\fR\&. If set to +\fBno\fR +Samba will never produce these broadcasts\&. If set to +\fByes\fR +Samba will produce Lanman announce broadcasts at a frequency set by the parameter +\m[blue]\fBlm interval\fR\m[]\&. If set to +\fBauto\fR +Samba will not send Lanman announce broadcasts by default but will listen for them\&. If it hears such a broadcast on the wire it will then start sending them at a frequency set by the parameter +\m[blue]\fBlm interval\fR\m[]\&. +.sp +Default: +\fI\fIlm announce\fR\fR\fI = \fR\fIauto\fR\fI \fR +.sp +Example: +\fI\fIlm announce\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +lm interval (G) +.PP +.RS 4 +If Samba is set to produce Lanman announce broadcasts needed by OS/2 clients (see the +\m[blue]\fBlm announce\fR\m[] +parameter) then this parameter defines the frequency in seconds with which they will be made\&. If this is set to zero then no Lanman announcements will be made despite the setting of the +\m[blue]\fBlm announce\fR\m[] +parameter\&. +.sp +Default: +\fI\fIlm interval\fR\fR\fI = \fR\fI60\fR\fI \fR +.sp +Example: +\fI\fIlm interval\fR\fR\fI = \fR\fI120\fR\fI \fR +.RE + +load printers (G) +.PP +.RS 4 +A boolean variable that controls whether all printers in the printcap will be loaded for browsing by default\&. See the +printers +section for more details\&. +.sp +Default: +\fI\fIload printers\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +local master (G) +.PP +.RS 4 +This option allows +\fBnmbd\fR(8) +to try and become a local master browser on a subnet\&. If set to +\fBno\fR +then +nmbd +will not attempt to become a local master browser on a subnet and will also lose in all browsing elections\&. By default this value is set to +\fByes\fR\&. Setting this value to +\fByes\fR +doesn\*(Aqt mean that Samba will +\fIbecome\fR +the local master browser on a subnet, just that +nmbd +will +\fIparticipate\fR +in elections for local master browser\&. +.sp +Setting this value to +\fBno\fR +will cause +nmbd +\fInever\fR +to become a local master browser\&. +.sp +Default: +\fI\fIlocal master\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +lock dir +.PP +.RS 4 +This parameter is a synonym for +lock directory\&. +.RE + +lock directory (G) +.PP +.RS 4 +This option specifies the directory where lock files will be placed\&. The lock files are used to implement the +\m[blue]\fBmax connections\fR\m[] +option\&. +.sp +Note: This option can not be set inside registry configurations\&. +.sp +The files placed in this directory are not required across service restarts and can be safely placed on volatile storage (e\&.g\&. tmpfs in Linux) +.sp +Default: +\fI\fIlock directory\fR\fR\fI = \fR\fI/var/lib/samba/lock\fR\fI \fR +.sp +Example: +\fI\fIlock directory\fR\fR\fI = \fR\fI/var/run/samba/locks\fR\fI \fR +.RE + +locking (S) +.PP +.RS 4 +This controls whether or not locking will be performed by the server in response to lock requests from the client\&. +.sp +If +locking = no, all lock and unlock requests will appear to succeed and all lock queries will report that the file in question is available for locking\&. +.sp +If +locking = yes, real locking will be performed by the server\&. +.sp +This option +\fImay\fR +be useful for read\-only filesystems which +\fImay\fR +not need locking (such as CDROM drives), although setting this parameter of +\fBno\fR +is not really recommended even in this case\&. +.sp +Be careful about disabling locking either globally or in a specific service, as lack of locking may result in data corruption\&. You should never need to set this parameter\&. +.sp +Default: +\fI\fIlocking\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +lock spin time (G) +.PP +.RS 4 +The time in milliseconds that smbd should keep waiting to see if a failed lock request can be granted\&. This parameter has changed in default value from Samba 3\&.0\&.23 from 10 to 200\&. The associated +lock spin count +parameter is no longer used in Samba 3\&.0\&.24\&. You should not need to change the value of this parameter\&. +.sp +Default: +\fI\fIlock spin time\fR\fR\fI = \fR\fI200\fR\fI \fR +.RE + +log file (G) +.PP +.RS 4 +This option allows you to override the name of the Samba log file (also known as the debug file)\&. +.sp +This option takes the standard substitutions, allowing you to have separate log files for each user or machine\&. +.sp +\fINo default\fR +.sp +Example: +\fI\fIlog file\fR\fR\fI = \fR\fI/usr/local/samba/var/log\&.%m\fR\fI \fR +.RE + +logging (G) +.PP +.RS 4 +This parameter configures logging backends\&. Multiple backends can be specified at the same time, with different log levels for each backend\&. The parameter is a list of backends, where each backend is specified as backend[:option][@loglevel]\&. +.sp +The \*(Aqoption\*(Aq parameter can be used to pass backend\-specific options\&. +.sp +The log level for a backend is optional, if it is not set for a backend, all messages are sent to this backend\&. The parameter +\m[blue]\fBlog level\fR\m[] +determines overall log levels, while the log levels specified here define what is sent to the individual backends\&. +.sp +When +\m[blue]\fBlogging\fR\m[] +is set, it overrides the +\m[blue]\fBsyslog\fR\m[] +and +\m[blue]\fBsyslog only\fR\m[] +parameters\&. +.sp +Some backends are only available when Samba has been compiled with the additional libraries\&. The overall list of logging backends: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsyslog\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIfile\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsystemd\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIlttng\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIgpfs\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIringbuf\fR +.RE +.sp +.RE +The +\fIringbuf\fR +backend supports an optional size argument to change the buffer size used, the default is 1 MB: +\fIringbuf:size=NBYTES\fR +.sp +Default: +\fI\fIlogging\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIlogging\fR\fR\fI = \fR\fIsyslog@1 file\fR\fI \fR +.RE + +debuglevel +.PP +.RS 4 +This parameter is a synonym for +log level\&. +.RE + +log level (G) +.PP +.RS 4 +The value of the parameter (a string) allows the debug level (logging level) to be specified in the +smb\&.conf +file\&. +.sp +This parameter has been extended since the 2\&.2\&.x series, now it allows one to specify the debug level for multiple debug classes and distinct logfiles for debug classes\&. This is to give greater flexibility in the configuration of the system\&. The following debug classes are currently implemented: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIall\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fItdb\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIprintdrivers\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIlanman\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsmb\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIrpc_parse\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIrpc_srv\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIrpc_cli\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIpassdb\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsam\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIauth\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIwinbind\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIvfs\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIidmap\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIquota\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIacls\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIlocking\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fImsdfs\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdmapi\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIregistry\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIscavenger\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdns\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIldb\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fItevent\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIauth_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIauth_json_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIkerberos\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdrs_repl\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsmb2\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsmb2_credits\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_json_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_password_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_password_json_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_transaction_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_transaction_json_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_group_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdsdb_group_json_audit\fR +.RE +.sp +.RE +Various modules register dynamic debug classes at first usage: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIcatia\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdfs_samba4\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIextd_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIfileid\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIfruit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIfull_audit\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fImedia_harmony\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIpreopen\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIrecycle\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshadow_copy\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshadow_copy\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIunityed_media\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIvirusfilter\fR +.RE +.sp +.RE +To configure the logging for specific classes to go into a different file then +\m[blue]\fBlog file\fR\m[], you can append +\fI@PATH\fR +to the class, eg +\fIlog level = 1 full_audit:1@/var/log/audit\&.log\fR\&. +.sp +Authentication and authorization audit information is logged under the +\fIauth_audit\fR, and if Samba was not compiled with \-\-without\-json, a JSON representation is logged under +\fIauth_json_audit\fR\&. +.sp +Support is comprehensive for all authentication and authorisation of user accounts in the Samba Active Directory Domain Controller, as well as the implicit authentication in password changes\&. In the file server, NTLM authentication, SMB and RPC authorization is covered\&. +.sp +Log levels for +\fIauth_audit\fR +and +\fIauth_audit_json\fR +are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +2: Authentication Failure +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +3: Authentication Success +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +4: Authorization Success +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5: Anonymous Authentication and Authorization Success +.RE +.sp +.RE +Changes to the AD DC +sam\&.ldb +database are logged under the +\fIdsdb_audit\fR +and a JSON representation is logged under +\fIdsdb_json_audit\fR\&. +.sp +Group membership changes to the AD DC +sam\&.ldb +database are logged under the +\fIdsdb_group_audit\fR +and a JSON representation is logged under +\fIdsdb_group_json_audit\fR\&. +.sp +Log levels for +\fIdsdb_audit\fR, +\fIdsdb_json_audit\fR, +\fIdsdb_group_audit\fR, +\fIdsdb_group_json_audit\fR +and +\fIdsdb_json_audit\fR +are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5: Database modifications +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5: Replicated updates from another DC +.RE +.sp +.RE +Password changes and Password resets in the AD DC are logged under +\fIdsdb_password_audit\fR +and a JSON representation is logged under the +\fIdsdb_password_json_audit\fR\&. Password changes will also appears as authentication events via +\fIauth_audit\fR +and +\fIauth_audit_json\fR\&. +.sp +Log levels for +\fIdsdb_password_audit\fR +and +\fIdsdb_password_json_audit\fR +are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5: Successful password changes and resets +.RE +.sp +.RE +Transaction rollbacks and prepare commit failures are logged under the +\fIdsdb_transaction_audit\fR +and a JSON representation is logged under the +\fIdsdb_transaction_json_audit\fR\&. +.sp +Log levels for +\fIdsdb_transaction_audit\fR +and +\fIdsdb_transaction_json\fR +are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5: Transaction failure (rollback) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +10: Transaction success (commit) +.RE +.sp +.RE +Transaction roll\-backs are possible in Samba, and whilst they rarely reflect anything more than the failure of an individual operation (say due to the add of a conflicting record), they are possible\&. Audit logs are already generated and sent to the system logs before the transaction is complete\&. Logging the transaction details allows the identification of password and +sam\&.ldb +operations that have been rolled back, and so have not actually persisted\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Changes to +sam\&.ldb +made locally by the +root +user with direct access to the database are not logged to the system logs, but to the administrator\*(Aqs own console\&. While less than ideal, any user able to make such modifications could disable the audit logging in any case\&. +.sp .5v +.RE +Default: +\fI\fIlog level\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fIlog level\fR\fR\fI = \fR\fI3 passdb:5 auth:10 winbind:2\fR\fI \fR +.sp +Example: +\fI\fIlog level\fR\fR\fI = \fR\fI1 full_audit:1@/var/log/audit\&.log winbind:2\fR\fI \fR +.RE + +log nt token command (G) +.PP +.RS 4 +This option can be set to a command that will be called when new nt tokens are created\&. +.sp +This is only useful for development purposes\&. +.sp +Default: +\fI\fIlog nt token command\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +logon drive (G) +.PP +.RS 4 +This parameter specifies the local path to which the home directory will be connected (see +\m[blue]\fBlogon home\fR\m[]) and is only used by NT Workstations\&. +.sp +Note that this option is only useful if Samba is set up as a logon server\&. +.sp +Default: +\fI\fIlogon drive\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIlogon drive\fR\fR\fI = \fR\fIh:\fR\fI \fR +.RE + +logon home (G) +.PP +.RS 4 +This parameter specifies the home directory location when a Win95/98 or NT Workstation logs into a Samba PDC\&. It allows you to do +.sp +C:\e>\fBNET USE H: /HOME\fR +.sp +from a command prompt, for example\&. +.sp +This option takes the standard substitutions, allowing you to have separate logon scripts for each user or machine\&. +.sp +This parameter can be used with Win9X workstations to ensure that roaming profiles are stored in a subdirectory of the user\*(Aqs home directory\&. This is done in the following way: +.sp +logon home = \e\e%N\e%U\eprofile +.sp +This tells Samba to return the above string, with substitutions made when a client requests the info, generally in a NetUserGetInfo request\&. Win9X clients truncate the info to \e\eserver\eshare when a user does +net use /home +but use the whole string when dealing with profiles\&. +.sp +Note that in prior versions of Samba, the +\m[blue]\fBlogon path\fR\m[] +was returned rather than +\fIlogon home\fR\&. This broke +net use /home +but allowed profiles outside the home directory\&. The current implementation is correct, and can be used for profiles if you use the above trick\&. +.sp +Disable this feature by setting +\m[blue]\fBlogon home = ""\fR\m[] +\- using the empty string\&. +.sp +This option is only useful if Samba is set up as a logon server\&. +.sp +Default: +\fI\fIlogon home\fR\fR\fI = \fR\fI\e\e%N\e%U\fR\fI \fR +.sp +Example: +\fI\fIlogon home\fR\fR\fI = \fR\fI\e\eremote_smb_server\e%U\fR\fI \fR +.RE + +logon path (G) +.PP +.RS 4 +This parameter specifies the directory where roaming profiles (Desktop, NTuser\&.dat, etc) are stored\&. Contrary to previous versions of these manual pages, it has nothing to do with Win 9X roaming profiles\&. To find out how to handle roaming profiles for Win 9X system, see the +\m[blue]\fBlogon home\fR\m[] +parameter\&. +.sp +This option takes the standard substitutions, allowing you to have separate logon scripts for each user or machine\&. It also specifies the directory from which the "Application Data", +desktop, +start menu, +network neighborhood, +programs +and other folders, and their contents, are loaded and displayed on your Windows NT client\&. +.sp +The share and the path must be readable by the user for the preferences and directories to be loaded onto the Windows NT client\&. The share must be writeable when the user logs in for the first time, in order that the Windows NT client can create the NTuser\&.dat and other directories\&. Thereafter, the directories and any of the contents can, if required, be made read\-only\&. It is not advisable that the NTuser\&.dat file be made read\-only \- rename it to NTuser\&.man to achieve the desired effect (a +\fIMAN\fRdatory profile)\&. +.sp +Windows clients can sometimes maintain a connection to the [homes] share, even though there is no user logged in\&. Therefore, it is vital that the logon path does not include a reference to the homes share (i\&.e\&. setting this parameter to \e\e%N\ehomes\eprofile_path will cause problems)\&. +.sp +This option takes the standard substitutions, allowing you to have separate logon scripts for each user or machine\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Do not quote the value\&. Setting this as +\(lq\e\e%N\eprofile\e%U\(rq +will break profile handling\&. Where the tdbsam or ldapsam passdb backend is used, at the time the user account is created the value configured for this parameter is written to the passdb backend and that value will over\-ride the parameter value present in the smb\&.conf file\&. Any error present in the passdb backend account record must be edited using the appropriate tool (pdbedit on the command\-line, or any other locally provided system tool)\&. +.sp .5v +.RE +Note that this option is only useful if Samba is set up as a domain controller\&. +.sp +Disable the use of roaming profiles by setting the value of this parameter to the empty string\&. For example, +\m[blue]\fBlogon path = ""\fR\m[]\&. Take note that even if the default setting in the smb\&.conf file is the empty string, any value specified in the user account settings in the passdb backend will over\-ride the effect of setting this parameter to null\&. Disabling of all roaming profile use requires that the user account settings must also be blank\&. +.sp +An example of use is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +logon path = \e\ePROFILESERVER\ePROFILE\e%U +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIlogon path\fR\fR\fI = \fR\fI\e\e%N\e%U\eprofile\fR\fI \fR +.RE + +logon script (G) +.PP +.RS 4 +This parameter specifies the batch file (\&.bat) or NT command file (\&.cmd) to be downloaded and run on a machine when a user successfully logs in\&. The file must contain the DOS style CR/LF line endings\&. Using a DOS\-style editor to create the file is recommended\&. +.sp +The script must be a relative path to the +\fI[netlogon]\fR +service\&. If the [netlogon] service specifies a +\m[blue]\fBpath\fR\m[] +of +/usr/local/samba/netlogon, and +\m[blue]\fBlogon script = STARTUP\&.BAT\fR\m[], then the file that will be downloaded is: +.sp +.if n \{\ +.RS 4 +.\} +.nf + /usr/local/samba/netlogon/STARTUP\&.BAT +.fi +.if n \{\ +.RE +.\} +.sp +The contents of the batch file are entirely your choice\&. A suggested command would be to add +NET TIME \e\eSERVER /SET /YES, to force every machine to synchronize clocks with the same time server\&. Another use would be to add +NET USE U: \e\eSERVER\eUTILS +for commonly used utilities, or +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBNET USE Q: \e\eSERVER\eISO9001_QA\fR +.fi +.if n \{\ +.RE +.\} +.sp +for example\&. +.sp +Note that it is particularly important not to allow write access to the [netlogon] share, or to grant users write permission on the batch files in a secure environment, as this would allow the batch files to be arbitrarily modified and security to be breached\&. +.sp +This option takes the standard substitutions, allowing you to have separate logon scripts for each user or machine\&. +.sp +This option is only useful if Samba is set up as a logon server in a classic domain controller role\&. If Samba is set up as an Active Directory domain controller, LDAP attribute +scriptPath +is used instead\&. For configurations where +\m[blue]\fBpassdb backend = ldapsam\fR\m[] +is in use, this option only defines a default value in case LDAP attribute +sambaLogonScript +is missing\&. +.sp +Default: +\fI\fIlogon script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIlogon script\fR\fR\fI = \fR\fIscripts\e%U\&.bat\fR\fI \fR +.RE + +log writeable files on exit (G) +.PP +.RS 4 +When the network connection between a CIFS client and Samba dies, Samba has no option but to simply shut down the server side of the network connection\&. If this happens, there is a risk of data corruption because the Windows client did not complete all write operations that the Windows application requested\&. Setting this option to "yes" makes smbd log with a level 0 message a list of all files that have been opened for writing when the network connection died\&. Those are the files that are potentially corrupted\&. It is meant as an aid for the administrator to give him a list of files to do consistency checks on\&. +.sp +Default: +\fI\fIlog writeable files on exit\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +lppause command (S) +.PP +.RS 4 +This parameter specifies the command to be executed on the server host in order to stop printing or spooling a specific print job\&. +.sp +This command should be a program or script which takes a printer name and job number to pause the print job\&. One way of implementing this is by using job priorities, where jobs having a too low priority won\*(Aqt be sent to the printer\&. +.sp +If a +\fI%p\fR +is given then the printer name is put in its place\&. A +\fI%j\fR +is replaced with the job number (an integer)\&. On HPUX (see +\fIprinting=hpux \fR), if the +\fI\-p%p\fR +option is added to the lpq command, the job will show up with the correct status, i\&.e\&. if the job priority is lower than the set fence priority it will have the PAUSED status, whereas if the priority is equal or higher it will have the SPOOLED or PRINTING status\&. +.sp +Note that it is good practice to include the absolute path in the lppause command as the PATH may not be available to the server\&. +.sp +Currently no default value is given to this string, unless the value of the +\m[blue]\fBprinting\fR\m[] +parameter is +\fBSYSV\fR, in which case the default is : +lp \-i %p\-%j \-H hold +or if the value of the +\fIprinting\fR +parameter is +\fBSOFTQ\fR, then the default is: +qstat \-s \-j%j \-h\&. +.sp +Default: +\fI\fIlppause command\fR\fR\fI = \fR\fI # determined by printing parameter\fR\fI \fR +.sp +Example: +\fI\fIlppause command\fR\fR\fI = \fR\fI/usr/bin/lpalt %p\-%j \-p0\fR\fI \fR +.RE + +lpq cache time (G) +.PP +.RS 4 +This controls how long lpq info will be cached for to prevent the +lpq +command being called too often\&. A separate cache is kept for each variation of the +lpq +command used by the system, so if you use different +lpq +commands for different users then they won\*(Aqt share cache information\&. +.sp +The cache files are stored in +/tmp/lpq\&.xxxx +where xxxx is a hash of the +lpq +command in use\&. +.sp +The default is 30 seconds, meaning that the cached results of a previous identical +lpq +command will be used if the cached data is less than 30 seconds old\&. A large value may be advisable if your +lpq +command is very slow\&. +.sp +A value of 0 will disable caching completely\&. +.sp +Default: +\fI\fIlpq cache time\fR\fR\fI = \fR\fI30\fR\fI \fR +.sp +Example: +\fI\fIlpq cache time\fR\fR\fI = \fR\fI10\fR\fI \fR +.RE + +lpq command (S) +.PP +.RS 4 +This parameter specifies the command to be executed on the server host in order to obtain +lpq\-style printer status information\&. +.sp +This command should be a program or script which takes a printer name as its only parameter and outputs printer status information\&. +.sp +Currently nine styles of printer status information are supported; BSD, AIX, LPRNG, PLP, SYSV, HPUX, QNX, CUPS, and SOFTQ\&. This covers most UNIX systems\&. You control which type is expected using the +\fIprinting =\fR +option\&. +.sp +Some clients (notably Windows for Workgroups) may not correctly send the connection number for the printer they are requesting status information about\&. To get around this, the server reports on the first printer service connected to by the client\&. This only happens if the connection number sent is invalid\&. +.sp +If a +\fI%p\fR +is given then the printer name is put in its place\&. Otherwise it is placed at the end of the command\&. +.sp +Note that it is good practice to include the absolute path in the +\fIlpq command\fR +as the +\fB$PATH \fR +may not be available to the server\&. When compiled with the CUPS libraries, no +\fIlpq command\fR +is needed because smbd will make a library call to obtain the print queue listing\&. +.sp +Default: +\fI\fIlpq command\fR\fR\fI = \fR\fI # determined by printing parameter\fR\fI \fR +.sp +Example: +\fI\fIlpq command\fR\fR\fI = \fR\fI/usr/bin/lpq \-P%p\fR\fI \fR +.RE + +lpresume command (S) +.PP +.RS 4 +This parameter specifies the command to be executed on the server host in order to restart or continue printing or spooling a specific print job\&. +.sp +This command should be a program or script which takes a printer name and job number to resume the print job\&. See also the +\m[blue]\fBlppause command\fR\m[] +parameter\&. +.sp +If a +\fI%p\fR +is given then the printer name is put in its place\&. A +\fI%j\fR +is replaced with the job number (an integer)\&. +.sp +Note that it is good practice to include the absolute path in the +\fIlpresume command\fR +as the PATH may not be available to the server\&. +.sp +See also the +\m[blue]\fBprinting\fR\m[] +parameter\&. +.sp +Default: Currently no default value is given to this string, unless the value of the +\fIprinting\fR +parameter is +\fBSYSV\fR, in which case the default is: +.sp +lp \-i %p\-%j \-H resume +.sp +or if the value of the +\fIprinting\fR +parameter is +\fBSOFTQ\fR, then the default is: +.sp +qstat \-s \-j%j \-r +.sp +Default: +\fI\fIlpresume command\fR\fR\fI = \fR\fI # determined by printing parameter\fR\fI \fR +.sp +Example: +\fI\fIlpresume command\fR\fR\fI = \fR\fI/usr/bin/lpalt %p\-%j \-p2\fR\fI \fR +.RE + +lprm command (S) +.PP +.RS 4 +This parameter specifies the command to be executed on the server host in order to delete a print job\&. +.sp +This command should be a program or script which takes a printer name and job number, and deletes the print job\&. +.sp +If a +\fI%p\fR +is given then the printer name is put in its place\&. A +\fI%j\fR +is replaced with the job number (an integer)\&. +.sp +Note that it is good practice to include the absolute path in the +\fIlprm command\fR +as the PATH may not be available to the server\&. +.sp +Examples of use are: +.sp +.if n \{\ +.RS 4 +.\} +.nf +lprm command = /usr/bin/lprm \-P%p %j + +or + +lprm command = /usr/bin/cancel %p\-%j +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIlprm command\fR\fR\fI = \fR\fI # determined by printing parameter\fR\fI \fR +.RE + +lsa over netlogon (G) +.PP +.RS 4 +Setting this deprecated option will allow the RPC server in the AD DC to answer the LSARPC interface on the +\epipe\enetlogon +IPC pipe\&. +.sp +When enabled, this matches the behaviour of Microsoft\*(Aqs Windows, due to their internal implementation choices\&. +.sp +If it is disabled (the default), the AD DC can offer improved performance, as the netlogon server is decoupled and can run as multiple processes\&. +.sp +Default: +\fI\fIlsa over netlogon\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +machine password timeout (G) +.PP +.RS 4 +If a Samba server is a member of a Windows NT or Active Directory Domain (see the +\m[blue]\fBsecurity = domain\fR\m[] +and +\m[blue]\fBsecurity = ads\fR\m[] +parameters), then periodically a running winbindd process will try and change the MACHINE ACCOUNT PASSWORD stored in the TDB called +secrets\&.tdb\&. This parameter specifies how often this password will be changed, in seconds\&. The default is one week (expressed in seconds), the same as a Windows NT Domain member server\&. +.sp +See also +\fBsmbpasswd\fR(8), and the +\m[blue]\fBsecurity = domain\fR\m[] +and +\m[blue]\fBsecurity = ads\fR\m[] +parameters\&. +.sp +Default: +\fI\fImachine password timeout\fR\fR\fI = \fR\fI604800\fR\fI \fR +.RE + +magic output (S) +.PP +.RS 4 +This parameter specifies the name of a file which will contain output created by a magic script (see the +\m[blue]\fBmagic script\fR\m[] +parameter below)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +If two clients use the same +\fImagic script \fR +in the same directory the output file content is undefined\&. +.sp .5v +.RE +Default: +\fI\fImagic output\fR\fR\fI = \fR\fI # \&.out\fR\fI \fR +.sp +Example: +\fI\fImagic output\fR\fR\fI = \fR\fImyfile\&.txt\fR\fI \fR +.RE + +magic script (S) +.PP +.RS 4 +This parameter specifies the name of a file which, if opened, will be executed by the server when the file is closed\&. This allows a UNIX script to be sent to the Samba host and executed on behalf of the connected user\&. +.sp +Scripts executed in this way will be deleted upon completion assuming that the user has the appropriate level of privilege and the file permissions allow the deletion\&. +.sp +If the script generates output, output will be sent to the file specified by the +\m[blue]\fBmagic output\fR\m[] +parameter (see above)\&. +.sp +Note that some shells are unable to interpret scripts containing CR/LF instead of CR as the end\-of\-line marker\&. Magic scripts must be executable +\fIas is\fR +on the host, which for some hosts and some shells will require filtering at the DOS end\&. +.sp +Magic scripts are +\fIEXPERIMENTAL\fR +and should +\fINOT\fR +be relied upon\&. +.sp +Default: +\fI\fImagic script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fImagic script\fR\fR\fI = \fR\fIuser\&.csh\fR\fI \fR +.RE + +mangled names (S) +.PP +.RS 4 +This controls whether non\-DOS names under UNIX should be mapped to DOS\-compatible names ("mangled") and made visible, or whether non\-DOS names should simply be ignored\&. +.sp +See the section on +name mangling +for details on how to control the mangling process\&. +.sp +Possible option settings are +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIyes\fR +\- enables name mangling for all not DOS 8\&.3 conforming names\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIno\fR +\- disables any name mangling\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIillegal (default)\fR +\- does mangling for names with illegal NTFS characters\&. This is the most sensible setting for modern clients that don\*(Aqt use the shortname anymore\&. +.RE +.sp +.RE +If mangling is used then the mangling method is as follows: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The first (up to) five alphanumeric characters before the rightmost dot of the filename are preserved, forced to upper case, and appear as the first (up to) five characters of the mangled name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A tilde "~" is appended to the first part of the mangled name, followed by a two\-character unique sequence, based on the original root name (i\&.e\&., the original filename minus its final extension)\&. The final extension is included in the hash calculation only if it contains any upper case characters or is longer than three characters\&. +.sp +Note that the character to use may be specified using the +\m[blue]\fBmangling char\fR\m[] +option, if you don\*(Aqt like \*(Aq~\*(Aq\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Files whose UNIX name begins with a dot will be presented as DOS hidden files\&. The mangled name will be created as for other filenames, but with the leading dot removed and "___" as its extension regardless of actual original extension (that\*(Aqs three underscores)\&. +.RE +.sp +.RE +The two\-digit hash value consists of upper case alphanumeric characters\&. +.sp +This algorithm can cause name collisions only if files in a directory share the same first five alphanumeric characters\&. The probability of such a clash is 1/1300\&. +.sp +The name mangling (if enabled) allows a file to be copied between UNIX directories from Windows/DOS while retaining the long UNIX filename\&. UNIX files can be renamed to a new extension from Windows/DOS and will retain the same basename\&. Mangled names do not change between sessions\&. +.sp +Default: +\fI\fImangled names\fR\fR\fI = \fR\fIillegal\fR\fI \fR +.sp +Example: +\fI\fImangled names\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +mangle prefix (G) +.PP +.RS 4 +controls the number of prefix characters from the original name used when generating the mangled names\&. A larger value will give a weaker hash and therefore more name collisions\&. The minimum value is 1 and the maximum value is 6\&. +.sp +mangle prefix is effective only when mangling method is hash2\&. +.sp +Default: +\fI\fImangle prefix\fR\fR\fI = \fR\fI1\fR\fI \fR +.sp +Example: +\fI\fImangle prefix\fR\fR\fI = \fR\fI4\fR\fI \fR +.RE + +mangling char (S) +.PP +.RS 4 +This controls what character is used as the +\fImagic\fR +character in +name mangling\&. The default is a \*(Aq~\*(Aq but this may interfere with some software\&. Use this option to set it to whatever you prefer\&. This is effective only when mangling method is hash\&. +.sp +Default: +\fI\fImangling char\fR\fR\fI = \fR\fI~\fR\fI \fR +.sp +Example: +\fI\fImangling char\fR\fR\fI = \fR\fI^\fR\fI \fR +.RE + +mangling method (G) +.PP +.RS 4 +controls the algorithm used for the generating the mangled names\&. Can take two different values, "hash" and "hash2"\&. "hash" is the algorithm that was used in Samba for many years and was the default in Samba 2\&.2\&.x "hash2" is now the default and is newer and considered a better algorithm (generates less collisions) in the names\&. Many Win32 applications store the mangled names and so changing to algorithms must not be done lightly as these applications may break unless reinstalled\&. +.sp +Default: +\fI\fImangling method\fR\fR\fI = \fR\fIhash2\fR\fI \fR +.sp +Example: +\fI\fImangling method\fR\fR\fI = \fR\fIhash\fR\fI \fR +.RE + +map acl inherit (S) +.PP +.RS 4 +This boolean parameter is only relevant for systems that do not support standardized NFS4 ACLs but only a POSIX draft implementation of ACLs\&. Linux is the only common UNIX system which does still not offer standardized NFS4 ACLs actually\&. On such systems this parameter controls whether +\fBsmbd\fR(8) +will attempt to map the \*(Aqprotected\*(Aq (don\*(Aqt inherit) flags of the Windows ACLs into an extended attribute called user\&.SAMBA_PAI (POSIX draft ACL Inheritance)\&. This parameter requires support for extended attributes on the filesystem and allows the Windows ACL editor to store (non\-)inheritance information while NT ACLs are mapped best\-effort to the POSIX draft ACLs that the OS and filesystem implements\&. +.sp +Default: +\fI\fImap acl inherit\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +map archive (S) +.PP +.RS 4 +This controls whether the DOS archive attribute should be mapped to the UNIX owner execute bit\&. The DOS archive bit is set when a file has been modified since its last backup\&. One motivation for this option is to keep Samba/your PC from making any file it touches from becoming executable under UNIX\&. This can be quite annoying for shared source code, documents, etc\&.\&.\&. +.sp +Note that this parameter will be ignored if the +\m[blue]\fBstore dos attributes\fR\m[] +parameter is set, as the DOS archive attribute will then be stored inside a UNIX extended attribute\&. +.sp +Note that this requires the +\m[blue]\fBcreate mask\fR\m[] +parameter to be set such that owner execute bit is not masked out (i\&.e\&. it must include 100)\&. See the parameter +\m[blue]\fBcreate mask\fR\m[] +for details\&. +.sp +Default: +\fI\fImap archive\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +map hidden (S) +.PP +.RS 4 +This controls whether DOS style hidden files should be mapped to the UNIX world execute bit\&. +.sp +Note that this parameter will be ignored if the +\m[blue]\fBstore dos attributes\fR\m[] +parameter is set, as the DOS hidden attribute will then be stored inside a UNIX extended attribute\&. +.sp +Note that this requires the +\m[blue]\fBcreate mask\fR\m[] +to be set such that the world execute bit is not masked out (i\&.e\&. it must include 001)\&. See the parameter +\m[blue]\fBcreate mask\fR\m[] +for details\&. +.sp +Default: +\fI\fImap hidden\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +map readonly (S) +.PP +.RS 4 +This controls how the DOS read only attribute should be mapped from a UNIX filesystem\&. +.sp +This parameter can take three different values, which tell +\fBsmbd\fR(8) +how to display the read only attribute on files, where either +\m[blue]\fBstore dos attributes\fR\m[] +is set to +\fBNo\fR, or no extended attribute is present\&. If +\m[blue]\fBstore dos attributes\fR\m[] +is set to +\fByes\fR +then this parameter is +\fIignored\fR\&. This is a new parameter introduced in Samba version 3\&.0\&.21\&. +.sp +The three settings are : +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBYes\fR +\- The read only DOS attribute is mapped to the inverse of the user or owner write bit in the unix permission mode set\&. If the owner write bit is not set, the read only attribute is reported as being set on the file\&. If the read only DOS attribute is set, Samba sets the owner, group and others write bits to zero\&. Write bits set in an ACL are ignored by Samba\&. If the read only DOS attribute is unset, Samba simply sets the write bit of the owner to one\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBPermissions\fR +\- The read only DOS attribute is mapped to the effective permissions of the connecting user, as evaluated by +\fBsmbd\fR(8) +by reading the unix permissions and filesystem ACL (if present)\&. If the connecting user does not have permission to modify the file, the read only attribute is reported as being set on the file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBNo\fR +\- The read only DOS attribute is unaffected by permissions, and can only be set by the +\m[blue]\fBstore dos attributes\fR\m[] +method\&. This may be useful for exporting mounted CDs\&. +.RE +.sp +.RE +Note that this parameter will be ignored if the +\m[blue]\fBstore dos attributes\fR\m[] +parameter is set, as the DOS \*(Aqread\-only\*(Aq attribute will then be stored inside a UNIX extended attribute\&. +.sp +The default has changed to no in Samba release 4\&.9\&.0 and above to allow better Windows fileserver compatibility in a default install\&. In addition the default setting of +\m[blue]\fBstore dos attributes\fR\m[] +has been changed to +\fBYes\fR +in Samba release 4\&.9\&.0 and above\&. +.sp +Default: +\fI\fImap readonly\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +map system (S) +.PP +.RS 4 +This controls whether DOS style system files should be mapped to the UNIX group execute bit\&. +.sp +Note that this parameter will be ignored if the +\m[blue]\fBstore dos attributes\fR\m[] +parameter is set, as the DOS system attribute will then be stored inside a UNIX extended attribute\&. +.sp +Note that this requires the +\m[blue]\fBcreate mask\fR\m[] +to be set such that the group execute bit is not masked out (i\&.e\&. it must include 010)\&. See the parameter +\m[blue]\fBcreate mask\fR\m[] +for details\&. +.sp +Default: +\fI\fImap system\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +map to guest (G) +.PP +.RS 4 +This parameter can take four different values, which tell +\fBsmbd\fR(8) +what to do with user login requests that don\*(Aqt match a valid UNIX user in some way\&. +.sp +The four settings are : +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBNever\fR +\- Means user login requests with an invalid password are rejected\&. This is the default\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBBad User\fR +\- Means user logins with an invalid password are rejected, unless the username does not exist, in which case it is treated as a guest login and mapped into the +\m[blue]\fBguest account\fR\m[]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBBad Password\fR +\- Means user logins with an invalid password are treated as a guest login and mapped into the +\m[blue]\fBguest account\fR\m[]\&. Note that this can cause problems as it means that any user incorrectly typing their password will be silently logged on as "guest" \- and will not know the reason they cannot access files they think they should \- there will have been no message given to them that they got their password wrong\&. Helpdesk services will +\fIhate\fR +you if you set the +\fImap to guest\fR +parameter this way :\-)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBBad Uid\fR +\- Is only applicable when Samba is configured in some type of domain mode security (security = {domain|ads}) and means that user logins which are successfully authenticated but which have no valid Unix user account (and smbd is unable to create one) should be mapped to the defined guest account\&. This was the default behavior of Samba 2\&.x releases\&. Note that if a member server is running winbindd, this option should never be required because the nss_winbind library will export the Windows domain users and groups to the underlying OS via the Name Service Switch interface\&. +.RE +.sp +.RE +Note that this parameter is needed to set up "Guest" share services\&. This is because in these modes the name of the resource being requested is +\fInot\fR +sent to the server until after the server has successfully authenticated the client so the server cannot make authentication decisions at the correct time (connection to the share) for "Guest" shares\&. +.sp +Default: +\fI\fImap to guest\fR\fR\fI = \fR\fINever\fR\fI \fR +.sp +Example: +\fI\fImap to guest\fR\fR\fI = \fR\fIBad User\fR\fI \fR +.RE + +max connections (S) +.PP +.RS 4 +This option allows the number of simultaneous connections to a service to be limited\&. If +\fImax connections\fR +is greater than 0 then connections will be refused if this number of connections to the service are already open\&. A value of zero mean an unlimited number of connections may be made\&. +.sp +Record lock files are used to implement this feature\&. The lock files will be stored in the directory specified by the +\m[blue]\fBlock directory\fR\m[] +option\&. +.sp +Default: +\fI\fImax connections\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fImax connections\fR\fR\fI = \fR\fI10\fR\fI \fR +.RE + +max disk size (G) +.PP +.RS 4 +This option allows you to put an upper limit on the apparent size of disks\&. If you set this option to 100 then all shares will appear to be not larger than 100 MB in size\&. +.sp +Note that this option does not limit the amount of data you can put on the disk\&. In the above case you could still store much more than 100 MB on the disk, but if a client ever asks for the amount of free disk space or the total disk size then the result will be bounded by the amount specified in +\fImax disk size\fR\&. +.sp +This option is primarily useful to work around bugs in some pieces of software that can\*(Aqt handle very large disks, particularly disks over 1GB in size\&. +.sp +A +\fImax disk size\fR +of 0 means no limit\&. +.sp +Default: +\fI\fImax disk size\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fImax disk size\fR\fR\fI = \fR\fI1000\fR\fI \fR +.RE + +max log size (G) +.PP +.RS 4 +This option (an integer in kilobytes) specifies the max size the log file should grow to\&. Samba periodically checks the size and if it is exceeded it will rename the file, adding a +\&.old +extension\&. +.sp +A size of 0 means no limit\&. +.sp +Default: +\fI\fImax log size\fR\fR\fI = \fR\fI5000\fR\fI \fR +.sp +Example: +\fI\fImax log size\fR\fR\fI = \fR\fI1000\fR\fI \fR +.RE + +max mux (G) +.PP +.RS 4 +This option controls the maximum number of outstanding simultaneous SMB operations that Samba tells the client it will allow\&. You should never need to set this parameter\&. +.sp +Default: +\fI\fImax mux\fR\fR\fI = \fR\fI50\fR\fI \fR +.RE + +max open files (G) +.PP +.RS 4 +This parameter limits the maximum number of open files that one +\fBsmbd\fR(8) +file serving process may have open for a client at any one time\&. This parameter can be set very high (16384) as Samba uses only one bit per unopened file\&. Setting this parameter lower than 16384 will cause Samba to complain and set this value back to the minimum of 16384, as Windows 7 depends on this number of open file handles being available\&. +.sp +The limit of the number of open files is usually set by the UNIX per\-process file descriptor limit rather than this parameter so you should never need to touch this parameter\&. +.sp +Default: +\fI\fImax open files\fR\fR\fI = \fR\fI16384\fR\fI \fR +.RE + +max print jobs (S) +.PP +.RS 4 +This parameter limits the maximum number of jobs allowable in a Samba printer queue at any given moment\&. If this number is exceeded, +\fBsmbd\fR(8) +will remote "Out of Space" to the client\&. +.sp +Default: +\fI\fImax print jobs\fR\fR\fI = \fR\fI1000\fR\fI \fR +.sp +Example: +\fI\fImax print jobs\fR\fR\fI = \fR\fI5000\fR\fI \fR +.RE + +max reported print jobs (S) +.PP +.RS 4 +This parameter limits the maximum number of jobs displayed in a port monitor for Samba printer queue at any given moment\&. If this number is exceeded, the excess jobs will not be shown\&. A value of zero means there is no limit on the number of print jobs reported\&. +.sp +Default: +\fI\fImax reported print jobs\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fImax reported print jobs\fR\fR\fI = \fR\fI1000\fR\fI \fR +.RE + +max smbd processes (G) +.PP +.RS 4 +This parameter limits the maximum number of +\fBsmbd\fR(8) +processes concurrently running on a system and is intended as a stopgap to prevent degrading service to clients in the event that the server has insufficient resources to handle more than this number of connections\&. Remember that under normal operating conditions, each user will have an +\fBsmbd\fR(8) +associated with him or her to handle connections to all shares from a given host\&. +.sp +For a Samba ADDC running the standard process model this option limits the number of processes forked to handle requests\&. Currently new processes are only forked for ldap and netlogon requests\&. +.sp +Default: +\fI\fImax smbd processes\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fImax smbd processes\fR\fR\fI = \fR\fI1000\fR\fI \fR +.RE + +max stat cache size (G) +.PP +.RS 4 +This parameter limits the size in memory of any +\fIstat cache\fR +being used to speed up case insensitive name mappings\&. It represents the number of kilobyte (1024) units the stat cache can use\&. A value of zero, meaning unlimited, is not advisable due to increased memory usage\&. You should not need to change this parameter\&. +.sp +Default: +\fI\fImax stat cache size\fR\fR\fI = \fR\fI512\fR\fI \fR +.sp +Example: +\fI\fImax stat cache size\fR\fR\fI = \fR\fI100\fR\fI \fR +.RE + +max ttl (G) +.PP +.RS 4 +This option tells +\fBnmbd\fR(8) +what the default \*(Aqtime to live\*(Aq of NetBIOS names should be (in seconds) when +nmbd +is requesting a name using either a broadcast packet or from a WINS server\&. You should never need to change this parameter\&. The default is 3 days\&. +.sp +Default: +\fI\fImax ttl\fR\fR\fI = \fR\fI259200\fR\fI \fR +.RE + +max wins ttl (G) +.PP +.RS 4 +This option tells +\fBsmbd\fR(8) +when acting as a WINS server (\m[blue]\fBwins support = yes\fR\m[]) what the maximum \*(Aqtime to live\*(Aq of NetBIOS names that +nmbd +will grant will be (in seconds)\&. You should never need to change this parameter\&. The default is 6 days (518400 seconds)\&. +.sp +Default: +\fI\fImax wins ttl\fR\fR\fI = \fR\fI518400\fR\fI \fR +.RE + +max xmit (G) +.PP +.RS 4 +This option controls the maximum packet size that will be negotiated by Samba\*(Aqs +\fBsmbd\fR(8) +for the SMB1 protocol\&. The default is 16644, which matches the behavior of Windows 2000\&. A value below 2048 is likely to cause problems\&. You should never need to change this parameter from its default value\&. +.sp +Default: +\fI\fImax xmit\fR\fR\fI = \fR\fI16644\fR\fI \fR +.sp +Example: +\fI\fImax xmit\fR\fR\fI = \fR\fI8192\fR\fI \fR +.RE + +mdns name (G) +.PP +.RS 4 +This parameter controls the name that multicast DNS support advertises as its\*(Aq hostname\&. +.sp +The default is to use the NETBIOS name which is typically the hostname in all capital letters\&. +.sp +A setting of mdns will defer the hostname configuration to the MDNS library that is used\&. +.sp +Default: +\fI\fImdns name\fR\fR\fI = \fR\fInetbios\fR\fI \fR +.RE + +message command (G) +.PP +.RS 4 +This specifies what command to run when the server receives a WinPopup style message\&. +.sp +This would normally be a command that would deliver the message somehow\&. How this is to be done is up to your imagination\&. +.sp +An example is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +message command = csh \-c \*(Aqxedit %s;rm %s\*(Aq & +.fi +.if n \{\ +.RE +.\} +.sp +This delivers the message using +xedit, then removes it afterwards\&. +\fINOTE THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN IMMEDIATELY\fR\&. That\*(Aqs why I have the \*(Aq&\*(Aq on the end\&. If it doesn\*(Aqt return immediately then your PCs may freeze when sending messages (they should recover after 30 seconds, hopefully)\&. +.sp +All messages are delivered as the global guest user\&. The command takes the standard substitutions, although +\fI %u\fR +won\*(Aqt work (\fI%U\fR +may be better in this case)\&. +.sp +Apart from the standard substitutions, some additional ones apply\&. In particular: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%s\fR += the filename containing the message\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%t\fR += the destination that the message was sent to (probably the server name)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%f\fR += who the message is from\&. +.RE +.sp +.RE +You could make this command send mail, or whatever else takes your fancy\&. Please let us know of any really interesting ideas you have\&. +.sp +Here\*(Aqs a way of sending the messages as mail to root: +.sp +.if n \{\ +.RS 4 +.\} +.nf +message command = /bin/mail \-s \*(Aqmessage from %f on %m\*(Aq root < %s; rm %s +.fi +.if n \{\ +.RE +.\} +.sp +If you don\*(Aqt have a message command then the message won\*(Aqt be delivered and Samba will tell the sender there was an error\&. Unfortunately WfWg totally ignores the error code and carries on regardless, saying that the message was delivered\&. +.sp +If you want to silently delete it then try: +.sp +.if n \{\ +.RS 4 +.\} +.nf +message command = rm %s +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fImessage command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fImessage command\fR\fR\fI = \fR\fIcsh \-c \*(Aqxedit %s; rm %s\*(Aq &\fR\fI \fR +.RE + +min domain uid (G) +.PP +.RS 4 +The integer parameter specifies the minimum uid allowed when mapping a local account to a domain account\&. +.sp +Note that this option interacts with the configured +\fIidmap ranges\fR! +.sp +Default: +\fI\fImin domain uid\fR\fR\fI = \fR\fI1000\fR\fI \fR +.RE + +min print space (S) +.PP +.RS 4 +This sets the minimum amount of free disk space that must be available before a user will be able to spool a print job\&. It is specified in kilobytes\&. The default is 0, which means a user can always spool a print job\&. +.sp +Default: +\fI\fImin print space\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fImin print space\fR\fR\fI = \fR\fI2000\fR\fI \fR +.RE + +min receivefile size (G) +.PP +.RS 4 +This option changes the behavior of +\fBsmbd\fR(8) +when processing SMBwriteX calls\&. Any incoming SMBwriteX call on a non\-signed SMB/CIFS connection greater than this value will not be processed in the normal way but will be passed to any underlying kernel recvfile or splice system call (if there is no such call Samba will emulate in user space)\&. This allows zero\-copy writes directly from network socket buffers into the filesystem buffer cache, if available\&. It may improve performance but user testing is recommended\&. If set to zero Samba processes SMBwriteX calls in the normal way\&. To enable POSIX large write support (SMB/CIFS writes up to 16Mb) this option must be nonzero\&. The maximum value is 128k\&. Values greater than 128k will be silently set to 128k\&. +.sp +Note this option will have NO EFFECT if set on a SMB signed connection\&. +.sp +The default is zero, which disables this option\&. +.sp +Default: +\fI\fImin receivefile size\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +min wins ttl (G) +.PP +.RS 4 +This option tells +\fBnmbd\fR(8) +when acting as a WINS server (\m[blue]\fBwins support = yes\fR\m[]) what the minimum \*(Aqtime to live\*(Aq of NetBIOS names that +nmbd +will grant will be (in seconds)\&. You should never need to change this parameter\&. The default is 6 hours (21600 seconds)\&. +.sp +Default: +\fI\fImin wins ttl\fR\fR\fI = \fR\fI21600\fR\fI \fR +.RE + +mit kdc command (G) +.PP +.RS 4 +This option specifies the path to the MIT kdc binary\&. +.sp +If the KDC is not installed in the default location and wasn\*(Aqt correctly detected during build then you should modify this variable and point it to the correct binary\&. +.sp +Default: +\fI\fImit kdc command\fR\fR\fI = \fR\fI/usr/sbin/krb5kdc\fR\fI \fR +.sp +Example: +\fI\fImit kdc command\fR\fR\fI = \fR\fI/opt/mit/sbin/krb5kdc\fR\fI \fR +.RE + +msdfs proxy (S) +.PP +.RS 4 +This parameter indicates that the share is a stand\-in for another CIFS share whose location is specified by the value of the parameter\&. When clients attempt to connect to this share, they are redirected to one or multiple, comma separated proxied shares using the SMB\-Dfs protocol\&. +.sp +Only Dfs roots can act as proxy shares\&. Take a look at the +\m[blue]\fBmsdfs root\fR\m[] +and +\m[blue]\fBhost msdfs\fR\m[] +options to find out how to set up a Dfs root share\&. +.sp +\fINo default\fR +.sp +Example: +\fI\fImsdfs proxy\fR\fR\fI = \fR\fI\eotherserver\esomeshare,\eotherserver2\esomeshare\fR\fI \fR +.RE + +msdfs root (S) +.PP +.RS 4 +If set to +\fByes\fR, Samba treats the share as a Dfs root and allows clients to browse the distributed file system tree rooted at the share directory\&. Dfs links are specified in the share directory by symbolic links of the form +msdfs:serverA\e\eshareA,serverB\e\eshareB +and so on\&. For more information on setting up a Dfs tree on Samba, refer to the MSDFS chapter in the Samba3\-HOWTO book\&. +.sp +Default: +\fI\fImsdfs root\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +msdfs shuffle referrals (S) +.PP +.RS 4 +If set to +\fByes\fR, Samba will shuffle Dfs referrals for a given Dfs link if multiple are available, allowing for load balancing across clients\&. For more information on setting up a Dfs tree on Samba, refer to the MSDFS chapter in the Samba3\-HOWTO book\&. +.sp +Default: +\fI\fImsdfs shuffle referrals\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +multicast dns register (G) +.PP +.RS 4 +If compiled with proper support for it, Samba will announce itself with multicast DNS services like for example provided by the Avahi daemon\&. +.sp +This parameter allows disabling Samba to register itself\&. +.sp +Default: +\fI\fImulticast dns register\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +name cache timeout (G) +.PP +.RS 4 +Specifies the number of seconds it takes before entries in samba\*(Aqs hostname resolve cache time out\&. If the timeout is set to 0\&. the caching is disabled\&. +.sp +Default: +\fI\fIname cache timeout\fR\fR\fI = \fR\fI660\fR\fI \fR +.sp +Example: +\fI\fIname cache timeout\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +name resolve order (G) +.PP +.RS 4 +This option is used by the programs in the Samba suite to determine what naming services to use and in what order to resolve host names to IP addresses\&. Its main purpose to is to control how netbios name resolution is performed\&. The option takes a space separated string of name resolution options\&. +.sp +The options are: "lmhosts", "host", "wins" and "bcast"\&. They cause names to be resolved as follows: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBlmhosts\fR +: Lookup an IP address in the Samba lmhosts file\&. If the line in lmhosts has no name type attached to the NetBIOS name (see the manpage for lmhosts for details) then any name type matches for lookup\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBhost\fR +: Do a standard host name to IP address resolution, using the system +/etc/hosts +or DNS lookups\&. This method of name resolution is operating system depended for instance on IRIX or Solaris this may be controlled by the +/etc/nsswitch\&.conf +file\&. Note that this method is used only if the NetBIOS name type being queried is the 0x20 (server) name type or 0x1c (domain controllers)\&. The latter case is only useful for active directory domains and results in a DNS query for the SRV RR entry matching _ldap\&._tcp\&.domain\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBwins\fR +: Query a name with the IP address listed in the +\m[blue]\fBWINSSERVER\fR\m[] +parameter\&. If no WINS server has been specified this method will be ignored\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBbcast\fR +: Do a broadcast on each of the known local interfaces listed in the +\m[blue]\fBinterfaces\fR\m[] +parameter\&. This is the least reliable of the name resolution methods as it depends on the target host being on a locally connected subnet\&. +.RE +.sp +.RE +The example below will cause the local lmhosts file to be examined first, followed by a broadcast attempt, followed by a normal system hostname lookup\&. +.sp +When Samba is functioning in ADS security mode (security = ads) it is advised to use following settings for +\fIname resolve order\fR: +.sp +name resolve order = wins bcast +.sp +DC lookups will still be done via DNS, but fallbacks to netbios names will not inundate your DNS servers with needless queries for DOMAIN<0x1c> lookups\&. +.sp +Default: +\fI\fIname resolve order\fR\fR\fI = \fR\fIlmhosts wins host bcast\fR\fI \fR +.sp +Example: +\fI\fIname resolve order\fR\fR\fI = \fR\fIlmhosts bcast host\fR\fI \fR +.RE + +socket address +.PP +.RS 4 +This parameter is a synonym for +nbt client socket address\&. +.RE + +nbt client socket address (G) +.PP +.RS 4 +This option allows you to control what address Samba will send NBT client packets from, and process replies using, including in nmbd\&. +.sp +Setting this option should never be necessary on usual Samba servers running only one nmbd\&. +.sp +By default Samba will send UDP packets from the OS default address for the destination, and accept replies on 0\&.0\&.0\&.0\&. +.sp +This parameter is deprecated\&. See +\m[blue]\fBbind interfaces only = Yes\fR\m[] +and +\m[blue]\fBinterfaces\fR\m[] +for the previous behaviour of controlling the normal listening sockets\&. +.sp +Default: +\fI\fInbt client socket address\fR\fR\fI = \fR\fI0\&.0\&.0\&.0\fR\fI \fR +.sp +Example: +\fI\fInbt client socket address\fR\fR\fI = \fR\fI192\&.168\&.2\&.20\fR\fI \fR +.RE + +nbtd:wins_prepend1Bto1Cqueries (G) +.PP +.RS 4 +Normally queries for 0x1C names (all logon servers for a domain) will return the first address of the 0x1B names (domain master browser and PDC) as first address in the result list\&. As many client only use the first address in the list by default, all clients will use the same server (the PDC)\&. Windows servers have an option to disable this behavior (since Windows 2000 Service Pack 2)\&. +.sp +Default: +\fI\fInbtd:wins_prepend1Bto1Cqueries\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +nbtd:wins_wins_randomize1Clist (G) +.PP +.RS 4 +Normally queries for 0x1C names will return the addresses in the same order as they\*(Aqre stored in the database, that means first all addresses which have been directly registered at the local wins server and then all addresses registered at other servers\&. Windows servers have an option to change this behavior and randomize the returned addresses\&. Set this parameter to "yes" and Samba will sort the address list depending on the client address and the matching bits of the addresses, the first address is randomized based on depending on the "nbtd:wins_randomize1Clist_mask" parameter\&. +.sp +Default: +\fI\fInbtd:wins_wins_randomize1Clist\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +nbtd:wins_randomize1Clist_mask (G) +.PP +.RS 4 +If the "nbtd:wins_randomize1Clist" parameter is set to "yes", then randomizing of the first returned address is based on the specified netmask\&. If there are addresses which are in the same subnet as the client address, the first returned address is randomly chosen out them\&. Otherwise the first returned address is randomly chosen out of all addresses\&. +.sp +Default: +\fI\fInbtd:wins_randomize1Clist_mask\fR\fR\fI = \fR\fI255\&.255\&.255\&.0\fR\fI \fR +.RE + +nbt port (G) +.PP +.RS 4 +Specifies which port the server should use for NetBIOS over IP name services traffic\&. +.sp +Default: +\fI\fInbt port\fR\fR\fI = \fR\fI137\fR\fI \fR +.RE + +ncalrpc dir (G) +.PP +.RS 4 +This directory will hold a series of named pipes to allow RPC over inter\-process communication\&. +.sp +This will allow Samba and other unix processes to interact over DCE/RPC without using TCP/IP\&. Additionally a sub\-directory \*(Aqnp\*(Aq has restricted permissions, and allows a trusted communication channel between Samba processes +.sp +Default: +\fI\fIncalrpc dir\fR\fR\fI = \fR\fI/run/samba/ncalrpc\fR\fI \fR +.sp +Example: +\fI\fIncalrpc dir\fR\fR\fI = \fR\fI/var/run/samba/ncalrpc\fR\fI \fR +.RE + +netbios aliases (G) +.PP +.RS 4 +This is a list of NetBIOS names that nmbd will advertise as additional names by which the Samba server is known\&. This allows one machine to appear in browse lists under multiple names\&. If a machine is acting as a browse server or logon server none of these names will be advertised as either browse server or logon servers, only the primary name of the machine will be advertised with these capabilities\&. +.sp +Default: +\fI\fInetbios aliases\fR\fR\fI = \fR\fI # empty string (no additional names)\fR\fI \fR +.sp +Example: +\fI\fInetbios aliases\fR\fR\fI = \fR\fITEST TEST1 TEST2\fR\fI \fR +.RE + +netbios name (G) +.PP +.RS 4 +This sets the NetBIOS name by which a Samba server is known\&. By default it is the same as the first component of the host\*(Aqs DNS name\&. If a machine is a browse server or logon server this name (or the first component of the hosts DNS name) will be the name that these services are advertised under\&. +.sp +Note that the maximum length for a NetBIOS name is 15 characters\&. +.sp +There is a bug in Samba that breaks operation of browsing and access to shares if the netbios name is set to the literal name +PIPE\&. To avoid this problem, do not name your Samba server +PIPE\&. +.sp +Default: +\fI\fInetbios name\fR\fR\fI = \fR\fI # machine DNS name\fR\fI \fR +.sp +Example: +\fI\fInetbios name\fR\fR\fI = \fR\fIMYNAME\fR\fI \fR +.RE + +netbios scope (G) +.PP +.RS 4 +This sets the NetBIOS scope that Samba will operate under\&. This should not be set unless every machine on your LAN also sets this value\&. +.sp +Default: +\fI\fInetbios scope\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +neutralize nt4 emulation (G) +.PP +.RS 4 +This option controls whether winbindd sends the NETLOGON_NEG_NEUTRALIZE_NT4_EMULATION flag in order to bypass the NT4 emulation of a domain controller\&. +.sp +Typically you should not need set this\&. It can be useful for upgrades from NT4 to AD domains\&. +.sp +The behavior can be controlled per netbios domain by using \*(Aqneutralize nt4 emulation:NETBIOSDOMAIN = yes\*(Aq as option\&. +.sp +Default: +\fI\fIneutralize nt4 emulation\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +nmbd bind explicit broadcast (G) +.PP +.RS 4 +This option causes +\fBnmbd\fR(8) +to explicitly bind to the broadcast address of the local subnets\&. This is needed to make nmbd work correctly in combination with the +\m[blue]\fBsocket address\fR\m[] +option\&. You should not need to unset this option\&. +.sp +Default: +\fI\fInmbd bind explicit broadcast\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +nsupdate command (G) +.PP +.RS 4 +This option sets the path to the +nsupdate +command which is used for GSS\-TSIG dynamic DNS updates\&. +.sp +Default: +\fI\fInsupdate command\fR\fR\fI = \fR\fI/usr/bin/nsupdate \-g\fR\fI \fR +.RE + +nt hash store (G) +.PP +.RS 4 +This parameter determines whether or not +\fBsamba\fR(8) +will, as an AD DC, attempt to store the NT password hash used in NTLM and NTLMv2 authentication for users in this domain\&. +.sp +If so configured, the Samba Active Directory Domain Controller, will, except for trust accounts (computers, domain controllers and inter\-domain trusts) the +\fINOT store the NT hash\fR +for new and changed accounts in the sam\&.ldb database\&. +.sp +This avoids the storage of an unsalted hash for these user\-created passwords\&. As a consequence the +\fBarcfour\-hmac\-md5\fR +Kerberos key type is also unavailable in the KDC for these users \- thankfully +\fImodern clients will select an AES based key instead\&.\fR +.sp +NOTE: As the password history in Active Directory is stored as an NT hash (and thus unavailable), a workaround is used, relying instead on Kerberos password hash values\&. This stores three passwords, the current, previous and second previous password\&. This allows some checking against reuse\&. +.sp +However as these values are salted, changing the sAMAccountName, userAccountControl or userPrincipalName of an account will cause the salt to change\&. After the rare combination of both a rename and a password change only the current password will be recognised for password history purposes\&. +.sp +The available settings are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBalways\fR +\- Always store the NT hash (as machine accounts will also always store an NT hash, a hash will be stored for all accounts)\&. +.sp +This setting may be useful if +\fIntlm auth\fR +is set to +\fBdisabled\fR +for a trial period +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBnever\fR +\- Never store the NT hash for user accounts, only for machine accounts +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBauto\fR +\- Store an NT hash if +\fIntlm auth\fR +is not set to +\fBdisabled\fR\&. +.RE +.sp +.RE +Default: +\fI\fInt hash store\fR\fR\fI = \fR\fIalways\fR\fI \fR +.RE + +nt acl support (S) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will attempt to map UNIX permissions into Windows NT access control lists\&. The UNIX permissions considered are the traditional UNIX owner and group permissions, as well as filesystem ACLs set on any files or directories\&. This parameter was formally a global parameter in releases prior to 2\&.2\&.2\&. +.sp +Default: +\fI\fInt acl support\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ntlm auth (G) +.PP +.RS 4 +This parameter determines whether or not +\fBsmbd\fR(8) +will attempt to authenticate users using the NTLM encrypted password response for this local passdb (SAM or account database)\&. +.sp +If disabled, both NTLM and LanMan authentication against the local passdb is disabled\&. +.sp +Note that these settings apply only to local users, authentication will still be forwarded to and NTLM authentication accepted against any domain we are joined to, and any trusted domain, even if disabled or if NTLMv2\-only is enforced here\&. To control NTLM authentication for domain users, this option must be configured on each DC\&. +.sp +By default with +ntlm auth +set to +\fBntlmv2\-only\fR +only NTLMv2 logins will be permitted\&. All modern clients support NTLMv2 by default, but some older clients will require special configuration to use it\&. +.sp +The primary user of NTLMv1 is MSCHAPv2 for VPNs and 802\&.1x\&. +.sp +The available settings are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBntlmv1\-permitted\fR +(alias +\fByes\fR) \- Allow NTLMv1 and above for all clients\&. +.sp +This is the required setting to enable the +\fIlanman auth\fR +parameter\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBntlmv2\-only\fR +(alias +\fBno\fR) \- Do not allow NTLMv1 to be used, but permit NTLMv2\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBmschapv2\-and\-ntlmv2\-only\fR +\- Only allow NTLMv1 when the client promises that it is providing MSCHAPv2 authentication (such as the +ntlm_auth +tool)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBdisabled\fR +\- Do not accept NTLM (or LanMan) authentication of any level, nor permit NTLM password changes\&. +.sp +\fIWARNING:\fR +Both Microsoft Windows and Samba +\fIRead Only Domain Controllers\fR +(RODCs) convert a plain\-text LDAP Simple Bind into an NTLMv2 authentication to forward to a full DC\&. Setting this option to +\fBdisabled\fR +will cause these forwarded authentications to fail\&. +.sp +Additionally, for Samba acting as an Active Directory Domain Controller, for user accounts, if +\fInt hash store\fR +is set to the default setting of +\fBauto\fR, the +\fINT hash will not be stored\fR +in the sam\&.ldb database for new users and after a password change\&. +.RE +.sp +.RE +The default changed from +\fByes\fR +to +\fBno\fR +with Samba 4\&.5\&. The default changed again to +\fBntlmv2\-only\fR +with Samba 4\&.7, however the behaviour is unchanged\&. +.sp +Default: +\fI\fIntlm auth\fR\fR\fI = \fR\fIntlmv2\-only\fR\fI \fR +.RE + +nt pipe support (G) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will allow Windows NT clients to connect to the NT SMB specific +\fBIPC$\fR +pipes\&. This is a developer debugging option and can be left alone\&. +.sp +Default: +\fI\fInt pipe support\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ntp signd socket directory (G) +.PP +.RS 4 +This setting controls the location of the socket that the NTP daemon uses to communicate with Samba for signing packets\&. +.sp +If a non\-default path is specified here, then it is also necessary to make NTP aware of the new path using the +\fBntpsigndsocket\fR +directive in +ntp\&.conf\&. +.sp +Default: +\fI\fIntp signd socket directory\fR\fR\fI = \fR\fI/var/lib/samba/ntp_signd\fR\fI \fR +.RE + +nt status support (G) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will negotiate NT specific status support with Windows NT/2k/XP clients\&. This is a developer debugging option and should be left alone\&. If this option is set to +\fBno\fR +then Samba offers exactly the same DOS error codes that versions prior to Samba 2\&.2\&.3 reported\&. +.sp +You should not need to ever disable this parameter\&. +.sp +Default: +\fI\fInt status support\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +ntvfs handler (S) +.PP +.RS 4 +This specifies the NTVFS handlers for this share\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +unixuid: Sets up user credentials based on POSIX gid/uid\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cifs: Proxies a remote CIFS FS\&. Mainly useful for testing\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +nbench: Filter module that saves data useful to the nbench benchmark suite\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipc: Allows using SMB for inter process communication\&. Only used for the IPC$ share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +posix: Maps POSIX FS semantics to NT semantics +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +print: Allows printing over SMB\&. This is LANMAN\-style printing, not the be confused with the spoolss DCE/RPC interface used by later versions of Windows\&. +.RE +.sp +.RE +Note that this option is only used when the NTVFS file server is in use\&. It is not used with the (default) s3fs file server\&. +.sp +Default: +\fI\fIntvfs handler\fR\fR\fI = \fR\fIunixuid, default\fR\fI \fR +.RE + +null passwords (G) +.PP +.RS 4 +Allow or disallow client access to accounts that have null passwords\&. +.sp +See also +\fBsmbpasswd\fR(5)\&. +.sp +Default: +\fI\fInull passwords\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +obey pam restrictions (G) +.PP +.RS 4 +When Samba 3\&.0 is configured to enable PAM support (i\&.e\&. \-\-with\-pam), this parameter will control whether or not Samba should obey PAM\*(Aqs account and session management directives\&. The default behavior is to use PAM for clear text authentication only and to ignore any account or session management\&. Note that Samba always ignores PAM for authentication in the case of +\m[blue]\fBencrypt passwords = yes\fR\m[]\&. The reason is that PAM modules cannot support the challenge/response authentication mechanism needed in the presence of SMB password encryption\&. +.sp +Default: +\fI\fIobey pam restrictions\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +old password allowed period (G) +.PP +.RS 4 +Number of minutes to permit an NTLM login after a password change or reset using the old password\&. This allows the user to re\-cache the new password on multiple clients without disrupting a network reconnection in the meantime\&. +.sp +This parameter only applies when +\m[blue]\fBserver role\fR\m[] +is set to Active Directory Domain Controller\&. +.sp +Default: +\fI\fIold password allowed period\fR\fR\fI = \fR\fI60\fR\fI \fR +.RE + +oplock break wait time (G) +.PP +.RS 4 +This is a tuning parameter added due to bugs in both Windows 9x and WinNT\&. If Samba responds to a client too quickly when that client issues an SMB that can cause an oplock break request, then the network client can fail and not respond to the break request\&. This tuning parameter (which is set in milliseconds) is the amount of time Samba will wait before sending an oplock break request to such (broken) clients\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE\&. +.sp .5v +.RE +Default: +\fI\fIoplock break wait time\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +oplocks (S) +.PP +.RS 4 +This boolean option tells +smbd +whether to issue oplocks (opportunistic locks) to file open requests on this share\&. The oplock code can dramatically (approx\&. 30% or more) improve the speed of access to files on Samba servers\&. It allows the clients to aggressively cache files locally and you may want to disable this option for unreliable network environments (it is turned on by default in Windows NT Servers)\&. +.sp +Oplocks may be selectively turned off on certain files with a share\&. See the +\m[blue]\fBveto oplock files\fR\m[] +parameter\&. On some systems oplocks are recognized by the underlying operating system\&. This allows data synchronization between all access to oplocked files, whether it be via Samba or NFS or a local UNIX process\&. See the +\m[blue]\fBkernel oplocks\fR\m[] +parameter for details\&. +.sp +Default: +\fI\fIoplocks\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +os2 driver map (G) +.PP +.RS 4 +The parameter is used to define the absolute path to a file containing a mapping of Windows NT printer driver names to OS/2 printer driver names\&. The format is: +.sp + = \&. +.sp +For example, a valid entry using the HP LaserJet 5 printer driver would appear as +HP LaserJet 5L = LASERJET\&.HP LaserJet 5L\&. +.sp +The need for the file is due to the printer driver namespace problem described in the chapter on Classical Printing in the Samba3\-HOWTO book\&. For more details on OS/2 clients, please refer to chapter on other clients in the Samba3\-HOWTO book\&. +.sp +Default: +\fI\fIos2 driver map\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +os level (G) +.PP +.RS 4 +This integer value controls what level Samba advertises itself as for browse elections\&. The value of this parameter determines whether +\fBnmbd\fR(8) +has a chance of becoming a local master browser for the +\m[blue]\fBworkgroup\fR\m[] +in the local broadcast area\&. +.sp +\fI Note:\fR +By default, Samba will win a local master browsing election over all Microsoft operating systems except a Windows NT 4\&.0/2000 Domain Controller\&. This means that a misconfigured Samba host can effectively isolate a subnet for browsing purposes\&. This parameter is largely auto\-configured in the Samba\-3 release series and it is seldom necessary to manually override the default setting\&. Please refer to the chapter on Network Browsing in the Samba\-3 HOWTO document for further information regarding the use of this parameter\&. +\fINote:\fR +The maximum value for this parameter is 255\&. If you use higher values, counting will start at 0! +.sp +Default: +\fI\fIos level\fR\fR\fI = \fR\fI20\fR\fI \fR +.sp +Example: +\fI\fIos level\fR\fR\fI = \fR\fI65\fR\fI \fR +.RE + +pam password change (G) +.PP +.RS 4 +With the addition of better PAM support in Samba 2\&.2, this parameter, it is possible to use PAM\*(Aqs password change control flag for Samba\&. If enabled, then PAM will be used for password changes when requested by an SMB client instead of the program listed in +\m[blue]\fBpasswd program\fR\m[]\&. It should be possible to enable this without changing your +\m[blue]\fBpasswd chat\fR\m[] +parameter for most setups\&. +.sp +Default: +\fI\fIpam password change\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +panic action (G) +.PP +.RS 4 +This is a Samba developer option that allows a system command to be called when either +\fBsmbd\fR(8) +or +\fBnmbd\fR(8) +crashes\&. This is usually used to draw attention to the fact that a problem occurred\&. +.sp +Default: +\fI\fIpanic action\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpanic action\fR\fR\fI = \fR\fI/bin/sleep 90000\fR\fI \fR +.RE + +passdb backend (G) +.PP +.RS 4 +This option allows the administrator to chose which backend will be used for storing user and possibly group information\&. This allows you to swap between different storage mechanisms without recompile\&. +.sp +The parameter value is divided into two parts, the backend\*(Aqs name, and a \*(Aqlocation\*(Aq string that has meaning only to that particular backed\&. These are separated by a : character\&. +.sp +Available backends can include: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +smbpasswd +\- The old plaintext passdb backend\&. Some Samba features will not work if this passdb backend is used\&. Takes a path to the smbpasswd file as an optional argument\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +tdbsam +\- The TDB based password storage backend\&. Takes a path to the TDB as an optional argument (defaults to passdb\&.tdb in the +\m[blue]\fBprivate dir\fR\m[] +directory\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ldapsam +\- The LDAP based passdb backend\&. Takes an LDAP URL as an optional argument (defaults to +ldap://localhost) +.sp +LDAP connections should be secured where possible\&. This may be done using either Start\-TLS (see +\m[blue]\fBldap ssl\fR\m[]) or by specifying +\fIldaps://\fR +in the URL argument\&. +.sp +Multiple servers may also be specified in double\-quotes\&. Whether multiple servers are supported or not and the exact syntax depends on the LDAP library you use\&. +.RE +.sp +.RE + + Examples of use are: +.sp +.if n \{\ +.RS 4 +.\} +.nf +passdb backend = tdbsam:/etc/samba/private/passdb\&.tdb + +or multi server LDAP URL with OpenLDAP library: + +passdb backend = ldapsam:"ldap://ldap\-1\&.example\&.com ldap://ldap\-2\&.example\&.com" + +or multi server LDAP URL with Netscape based LDAP library: + +passdb backend = ldapsam:"ldap://ldap\-1\&.example\&.com ldap\-2\&.example\&.com" +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIpassdb backend\fR\fR\fI = \fR\fItdbsam\fR\fI \fR +.RE + +passdb expand explicit (G) +.PP +.RS 4 +This parameter controls whether Samba substitutes %\-macros in the passdb fields if they are explicitly set\&. We used to expand macros here, but this turned out to be a bug because the Windows client can expand a variable %G_osver% in which %G would have been substituted by the user\*(Aqs primary group\&. +.sp +Default: +\fI\fIpassdb expand explicit\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +passwd chat (G) +.PP +.RS 4 +This string controls the +\fI"chat"\fR +conversation that takes places between +\fBsmbd\fR(8) +and the local password changing program to change the user\*(Aqs password\&. The string describes a sequence of response\-receive pairs that +\fBsmbd\fR(8) +uses to determine what to send to the +\m[blue]\fBpasswd program\fR\m[] +and what to expect back\&. If the expected output is not received then the password is not changed\&. +.sp +This chat sequence is often quite site specific, depending on what local methods are used for password control\&. +.sp +Note that this parameter only is used if the +\m[blue]\fBunix password sync\fR\m[] +parameter is set to +\fByes\fR\&. This sequence is then called +\fIAS ROOT\fR +when the SMB password in the smbpasswd file is being changed, without access to the old password cleartext\&. This means that root must be able to reset the user\*(Aqs password without knowing the text of the previous password\&. +.sp +The string can contain the macro +\fI%n\fR +which is substituted for the new password\&. The old password (\fI%o\fR) is only available when +\m[blue]\fBencrypt passwords\fR\m[] +has been disabled\&. The chat sequence can also contain the standard macros \en, \er, \et and \es to give line\-feed, carriage\-return, tab and space\&. The chat sequence string can also contain a \*(Aq*\*(Aq which matches any sequence of characters\&. Double quotes can be used to collect strings with spaces in them into a single string\&. +.sp +If the send string in any part of the chat sequence is a full stop "\&.", then no string is sent\&. Similarly, if the expect string is a full stop then no string is expected\&. +.sp +If the +\m[blue]\fBpam password change\fR\m[] +parameter is set to +\fByes\fR, the chat pairs may be matched in any order, and success is determined by the PAM result, not any particular output\&. The \en macro is ignored for PAM conversions\&. +.sp +Default: +\fI\fIpasswd chat\fR\fR\fI = \fR\fI*new*password* %n\en *new*password* %n\en *changed*\fR\fI \fR +.sp +Example: +\fI\fIpasswd chat\fR\fR\fI = \fR\fI"*Enter NEW password*" %n\en "*Reenter NEW password*" %n\en "*Password changed*"\fR\fI \fR +.RE + +passwd chat debug (G) +.PP +.RS 4 +This boolean specifies if the passwd chat script parameter is run in +\fIdebug\fR +mode\&. In this mode the strings passed to and received from the passwd chat are printed in the +\fBsmbd\fR(8) +log with a +\m[blue]\fBdebug level\fR\m[] +of 100\&. This is a dangerous option as it will allow plaintext passwords to be seen in the +smbd +log\&. It is available to help Samba admins debug their +\fIpasswd chat\fR +scripts when calling the +\fIpasswd program\fR +and should be turned off after this has been done\&. This option has no effect if the +\m[blue]\fBpam password change\fR\m[] +parameter is set\&. This parameter is off by default\&. +.sp +Default: +\fI\fIpasswd chat debug\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +passwd chat timeout (G) +.PP +.RS 4 +This integer specifies the number of seconds smbd will wait for an initial answer from a passwd chat script being run\&. Once the initial answer is received the subsequent answers must be received in one tenth of this time\&. The default it two seconds\&. +.sp +Default: +\fI\fIpasswd chat timeout\fR\fR\fI = \fR\fI2\fR\fI \fR +.RE + +passwd program (G) +.PP +.RS 4 +The name of a program that can be used to set UNIX user passwords\&. Any occurrences of +\fI%u\fR +will be replaced with the user name\&. The user name is checked for existence before calling the password changing program\&. +.sp +Also note that many passwd programs insist in +\fIreasonable \fR +passwords, such as a minimum length, or the inclusion of mixed case chars and digits\&. This can pose a problem as some clients (such as Windows for Workgroups) uppercase the password before sending it\&. +.sp +\fINote\fR +that if the +\fIunix password sync\fR +parameter is set to +\fByes \fR +then this program is called +\fIAS ROOT\fR +before the SMB password in the smbpasswd file is changed\&. If this UNIX password change fails, then +smbd +will fail to change the SMB password also (this is by design)\&. +.sp +If the +\fIunix password sync\fR +parameter is set this parameter +\fIMUST USE ABSOLUTE PATHS\fR +for +\fIALL\fR +programs called, and must be examined for security implications\&. Note that by default +\fIunix password sync\fR +is set to +\fBno\fR\&. +.sp +Default: +\fI\fIpasswd program\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpasswd program\fR\fR\fI = \fR\fI/bin/passwd %u\fR\fI \fR +.RE + +password hash gpg key ids (G) +.PP +.RS 4 +If +samba +is running as an active directory domain controller, it is possible to store the cleartext password of accounts in a PGP/OpenGPG encrypted form\&. +.sp +You can specify one or more recipients by key id or user id\&. Note that 32bit key ids are not allowed, specify at least 64bit\&. +.sp +The value is stored as \*(AqPrimary:SambaGPG\*(Aq in the +supplementalCredentials +attribute\&. +.sp +As password changes can occur on any domain controller, you should configure this on each of them\&. Note that this feature is currently available only on Samba domain controllers\&. +.sp +This option is only available if +samba +was compiled with +gpgme +support\&. +.sp +You may need to export the +GNUPGHOME +environment variable before starting +samba\&. +\fIIt is strongly recommended to only store the public key in this location\&. The private key is not used for encryption and should be only stored where decryption is required\&.\fR +.sp +Being able to restore the cleartext password helps, when they need to be imported into other authentication systems later (see +samba\-tool user getpassword) or you want to keep the passwords in sync with another system, e\&.g\&. an OpenLDAP server (see +samba\-tool user syncpasswords)\&. +.sp +While this option needs to be configured on all domain controllers, the +samba\-tool user syncpasswords +command should run on a single domain controller only (typically the PDC\-emulator)\&. +.sp +Default: +\fI\fIpassword hash gpg key ids\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpassword hash gpg key ids\fR\fR\fI = \fR\fI4952E40301FAB41A\fR\fI \fR +.sp +Example: +\fI\fIpassword hash gpg key ids\fR\fR\fI = \fR\fIselftest@samba\&.example\&.com\fR\fI \fR +.sp +Example: +\fI\fIpassword hash gpg key ids\fR\fR\fI = \fR\fIselftest@samba\&.example\&.com, 4952E40301FAB41A\fR\fI \fR +.RE + +password hash userPassword schemes (G) +.PP +.RS 4 +This parameter determines whether or not +\fBsamba\fR(8) +acting as an Active Directory Domain Controller will attempt to store additional passwords hash types for the user +.sp +The values are stored as \*(AqPrimary:userPassword\*(Aq in the +supplementalCredentials +attribute\&. The value of this option is a hash type\&. +.sp +The currently supported hash types are: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBCryptSHA256\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBCryptSHA512\fR +.RE +.sp +.RE +Multiple instances of a hash type may be computed and stored\&. The password hashes are calculated using the +\fBcrypt\fR(3) +call\&. The number of rounds used to compute the hash can be specified by adding \*(Aq:rounds=xxxx\*(Aq to the hash type, i\&.e\&. CryptSHA512:rounds=4500 would calculate an SHA512 hash using 4500 rounds\&. If not specified the Operating System defaults for +\fBcrypt\fR(3) +are used\&. +.sp +As password changes can occur on any domain controller, you should configure this on each of them\&. Note that this feature is currently available only on Samba domain controllers\&. +.sp +Currently the NT Hash of the password is recorded when these hashes are calculated and stored\&. When retrieving the hashes the current value of the NT Hash is checked against the stored NT Hash\&. This detects password changes that have not updated the password hashes\&. In this case +samba\-tool user +will ignore the stored hash values\&. +.sp +Being able to obtain the hashed password helps, when they need to be imported into other authentication systems later (see +samba\-tool user getpassword) or you want to keep the passwords in sync with another system, e\&.g\&. an OpenLDAP server (see +samba\-tool user syncpasswords)\&. +.sp +Related command: +\m[blue]\fBunix password sync\fR\m[] +.sp +Default: +\fI\fIpassword hash userPassword schemes\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpassword hash userPassword schemes\fR\fR\fI = \fR\fICryptSHA256\fR\fI \fR +.sp +Example: +\fI\fIpassword hash userPassword schemes\fR\fR\fI = \fR\fICryptSHA256 CryptSHA512\fR\fI \fR +.sp +Example: +\fI\fIpassword hash userPassword schemes\fR\fR\fI = \fR\fICryptSHA256:rounds=5000 CryptSHA512:rounds=7000\fR\fI \fR +.RE + +password server (G) +.PP +.RS 4 +By specifying the name of a domain controller with this option, and using +security = [ads|domain] +it is possible to get Samba to do all its username/password validation using a specific remote server\&. +.sp +Ideally, this option +\fIshould not\fR +be used, as the default \*(Aq*\*(Aq indicates to Samba to determine the best DC to contact dynamically, just as all other hosts in an AD domain do\&. This allows the domain to be maintained (addition and removal of domain controllers) without modification to the smb\&.conf file\&. The cryptographic protection on the authenticated RPC calls used to verify passwords ensures that this default is safe\&. +.sp +\fIIt is strongly recommended that you use the default of \*(Aq*\*(Aq\fR, however if in your particular environment you have reason to specify a particular DC list, then the list of machines in this option must be a list of names or IP addresses of Domain controllers for the Domain\&. If you use the default of \*(Aq*\*(Aq, or list several hosts in the +\fIpassword server\fR +option then +smbd +will try each in turn till it finds one that responds\&. This is useful in case your primary server goes down\&. +.sp +If the list of servers contains both names/IP\*(Aqs and the \*(Aq*\*(Aq character, the list is treated as a list of preferred domain controllers, but an auto lookup of all remaining DC\*(Aqs will be added to the list as well\&. Samba will not attempt to optimize this list by locating the closest DC\&. +.sp +If parameter is a name, it is looked up using the parameter +\m[blue]\fBname resolve order\fR\m[] +and so may resolved by any method and order described in that parameter\&. +.sp +Default: +\fI\fIpassword server\fR\fR\fI = \fR\fI*\fR\fI \fR +.sp +Example: +\fI\fIpassword server\fR\fR\fI = \fR\fINT\-PDC, NT\-BDC1, NT\-BDC2, *\fR\fI \fR +.sp +Example: +\fI\fIpassword server\fR\fR\fI = \fR\fIwindc\&.mydomain\&.com:389 192\&.168\&.1\&.101 *\fR\fI \fR +.RE + +directory +.PP +.RS 4 +This parameter is a synonym for +path\&. +.RE + +path (S) +.PP +.RS 4 +This parameter specifies a directory to which the user of the service is to be given access\&. In the case of printable services, this is where print data will spool prior to being submitted to the host for printing\&. +.sp +For a printable service offering guest access, the service should be readonly and the path should be world\-writeable and have the sticky bit set\&. This is not mandatory of course, but you probably won\*(Aqt get the results you expect if you do otherwise\&. +.sp +Any occurrences of +\fI%u\fR +in the path will be replaced with the UNIX username that the client is using on this connection\&. Any occurrences of +\fI%m\fR +will be replaced by the NetBIOS name of the machine they are connecting from\&. These replacements are very useful for setting up pseudo home directories for users\&. +.sp +Note that this path will be based on +\m[blue]\fBroot dir\fR\m[] +if one was specified\&. +.sp +Default: +\fI\fIpath\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpath\fR\fR\fI = \fR\fI/home/fred\fR\fI \fR +.RE + +perfcount module (G) +.PP +.RS 4 +This parameter specifies the perfcount backend to be used when monitoring SMB operations\&. Only one perfcount module may be used, and it must implement all of the apis contained in the smb_perfcount_handler structure defined in smb\&.h\&. +.sp +\fINo default\fR +.RE + +pid directory (G) +.PP +.RS 4 +This option specifies the directory where pid files will be placed\&. +.sp +Default: +\fI\fIpid directory\fR\fR\fI = \fR\fI/run\fR\fI \fR +.sp +Example: +\fI\fIpid directory\fR\fR\fI = \fR\fI/var/run/\fR\fI \fR +.RE + +posix locking (S) +.PP +.RS 4 +The +\fBsmbd\fR(8) +daemon maintains an database of file locks obtained by SMB clients\&. The default behavior is to map this internal database to POSIX locks\&. This means that file locks obtained by SMB clients are consistent with those seen by POSIX compliant applications accessing the files via a non\-SMB method (e\&.g\&. NFS or local file access)\&. It is very unlikely that you need to set this parameter to "no", unless you are sharing from an NFS mount, which is not a good idea in the first place\&. +.sp +Default: +\fI\fIposix locking\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +postexec (S) +.PP +.RS 4 +This option specifies a command to be run whenever the service is disconnected\&. It takes the usual substitutions\&. The command may be run as the root on some systems\&. +.sp +An interesting example may be to unmount server resources: +.sp +postexec = /etc/umount /cdrom +.sp +Default: +\fI\fIpostexec\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpostexec\fR\fR\fI = \fR\fIecho \e"%u disconnected from %S from %m (%I)\e" >> /tmp/log\fR\fI \fR +.RE + +exec +.PP +.RS 4 +This parameter is a synonym for +preexec\&. +.RE + +preexec (S) +.PP +.RS 4 +This option specifies a command to be run whenever the service is connected to\&. It takes the usual substitutions\&. +.sp +An interesting example is to send the users a welcome message every time they log in\&. Maybe a message of the day? Here is an example: +.sp +preexec = csh \-c \*(Aqecho \e"Welcome to %S!\e" | /usr/local/samba/bin/smbclient \-M %m \-I %I\*(Aq & +.sp +Of course, this could get annoying after a while :\-) +.sp +See also +\m[blue]\fBpreexec close\fR\m[] +and +\m[blue]\fBpostexec\fR\m[]\&. +.sp +Default: +\fI\fIpreexec\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpreexec\fR\fR\fI = \fR\fIecho \e"%u connected to %S from %m (%I)\e" >> /tmp/log\fR\fI \fR +.RE + +preexec close (S) +.PP +.RS 4 +This boolean option controls whether a non\-zero return code from +\m[blue]\fBpreexec\fR\m[] +should close the service being connected to\&. +.sp +Default: +\fI\fIpreexec close\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +prefered master +.PP +.RS 4 +This parameter is a synonym for +preferred master\&. +.RE + +preferred master (G) +.PP +.RS 4 +This boolean parameter controls if +\fBnmbd\fR(8) +is a preferred master browser for its workgroup\&. +.sp +If this is set to +\fByes\fR, on startup, +nmbd +will force an election, and it will have a slight advantage in winning the election\&. It is recommended that this parameter is used in conjunction with +\m[blue]\fBdomain master = yes\fR\m[], so that +nmbd +can guarantee becoming a domain master\&. +.sp +Use this option with caution, because if there are several hosts (whether Samba servers, Windows 95 or NT) that are preferred master browsers on the same subnet, they will each periodically and continuously attempt to become the local master browser\&. This will result in unnecessary broadcast traffic and reduced browsing capabilities\&. +.sp +Default: +\fI\fIpreferred master\fR\fR\fI = \fR\fIauto\fR\fI \fR +.RE + +prefork backoff increment (G) +.PP +.RS 4 +This option specifies the number of seconds added to the delay before a prefork master or worker process is restarted\&. The restart is initially zero, the prefork backoff increment is added to the delay on each restart up to the value specified by "prefork maximum backoff"\&. +.sp +Additionally set the backoff for an individual service by using "prefork backoff increment: service name" i\&.e\&. "prefork backoff increment:ldap = 2" to set the backoff increment to 2\&. +.sp +If the backoff increment is 2 and the maximum backoff is 5\&. There will be a zero second delay for the first restart\&. A two second delay for the second restart\&. A four second delay for the third and any subsequent restarts +.sp +Default: +\fI\fIprefork backoff increment\fR\fR\fI = \fR\fI10\fR\fI \fR +.RE + +prefork children (G) +.PP +.RS 4 +This option controls the number of worker processes that are started for each service when prefork process model is enabled (see +\fBsamba\fR(8) +\-M) The prefork children are only started for those services that support prefork (currently ldap, kdc and netlogon)\&. For processes that don\*(Aqt support preforking all requests are handled by a single process for that service\&. +.sp +This should be set to a small multiple of the number of CPU\*(Aqs available on the server +.sp +Additionally the number of prefork children can be specified for an individual service by using "prefork children: service name" i\&.e\&. "prefork children:ldap = 8" to set the number of ldap worker processes\&. +.sp +Default: +\fI\fIprefork children\fR\fR\fI = \fR\fI4\fR\fI \fR +.RE + +prefork maximum backoff (G) +.PP +.RS 4 +This option controls the maximum delay before a failed pre\-fork process is restarted\&. +.sp +Default: +\fI\fIprefork maximum backoff\fR\fR\fI = \fR\fI120\fR\fI \fR +.RE + +preload modules (G) +.PP +.RS 4 +This is a list of paths to modules that should be loaded into smbd before a client connects\&. This improves the speed of smbd when reacting to new connections somewhat\&. +.sp +Default: +\fI\fIpreload modules\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIpreload modules\fR\fR\fI = \fR\fI/usr/lib/samba/passdb/mysql\&.so\fR\fI \fR +.RE + +preserve case (S) +.PP +.RS 4 +This controls if new filenames are created with the case that the client passes, or if they are forced to be the +\m[blue]\fBdefault case\fR\m[]\&. +.sp +See the section on +NAME MANGLING +for a fuller discussion\&. +.sp +Default: +\fI\fIpreserve case\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +print ok +.PP +.RS 4 +This parameter is a synonym for +printable\&. +.RE + +printable (S) +.PP +.RS 4 +If this parameter is +\fByes\fR, then clients may open, write to and submit spool files on the directory specified for the service\&. +.sp +Note that a printable service will ALWAYS allow writing to the service path (user privileges permitting) via the spooling of print data\&. The +\m[blue]\fBread only\fR\m[] +parameter controls only non\-printing access to the resource\&. +.sp +Default: +\fI\fIprintable\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +printcap cache time (G) +.PP +.RS 4 +This option specifies the number of seconds before the printing subsystem is again asked for the known printers\&. +.sp +Setting this parameter to 0 disables any rescanning for new or removed printers after the initial startup\&. +.sp +Default: +\fI\fIprintcap cache time\fR\fR\fI = \fR\fI750\fR\fI \fR +.sp +Example: +\fI\fIprintcap cache time\fR\fR\fI = \fR\fI600\fR\fI \fR +.RE + +printcap +.PP +.RS 4 +This parameter is a synonym for +printcap name\&. +.RE + +printcap name (G) +.PP +.RS 4 +This parameter may be used to override the compiled\-in default printcap name used by the server (usually +/etc/printcap)\&. See the discussion of the +[printers] +section above for reasons why you might want to do this\&. +.sp +To use the CUPS printing interface set +printcap name = cups\&. This should be supplemented by an additional setting +\m[blue]\fBprinting = cups\fR\m[] +in the [global] section\&. +printcap name = cups +will use the "dummy" printcap created by CUPS, as specified in your CUPS configuration file\&. +.sp +On System V systems that use +lpstat +to list available printers you can use +printcap name = lpstat +to automatically obtain lists of available printers\&. This is the default for systems that define SYSV at configure time in Samba (this includes most System V based systems)\&. If +\fI printcap name\fR +is set to +lpstat +on these systems then Samba will launch +lpstat \-v +and attempt to parse the output to obtain a printer list\&. +.sp +A minimal printcap file would look something like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +print1|My Printer 1 +print2|My Printer 2 +print3|My Printer 3 +print4|My Printer 4 +print5|My Printer 5 +.fi +.if n \{\ +.RE +.\} +.sp +where the \*(Aq|\*(Aq separates aliases of a printer\&. The fact that the second alias has a space in it gives a hint to Samba that it\*(Aqs a comment\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Under AIX the default printcap name is +/etc/qconfig\&. Samba will assume the file is in AIX +qconfig +format if the string +qconfig +appears in the printcap filename\&. +.sp .5v +.RE +Default: +\fI\fIprintcap name\fR\fR\fI = \fR\fI/etc/printcap\fR\fI \fR +.sp +Example: +\fI\fIprintcap name\fR\fR\fI = \fR\fI/etc/myprintcap\fR\fI \fR +.RE + +print command (S) +.PP +.RS 4 +After a print job has finished spooling to a service, this command will be used via a +system() +call to process the spool file\&. Typically the command specified will submit the spool file to the host\*(Aqs printing subsystem, but there is no requirement that this be the case\&. The server will not remove the spool file, so whatever command you specify should remove the spool file when it has been processed, otherwise you will need to manually remove old spool files\&. +.sp +The print command is simply a text string\&. It will be used verbatim after macro substitutions have been made: +.sp +%s, %f \- the path to the spool file name +.sp +%p \- the appropriate printer name +.sp +%J \- the job name as transmitted by the client\&. +.sp +%c \- The number of printed pages of the spooled job (if known)\&. +.sp +%z \- the size of the spooled print job (in bytes) +.sp +The print command +\fIMUST\fR +contain at least one occurrence of +\fI%s\fR +or +\fI%f \fR +\- the +\fI%p\fR +is optional\&. At the time a job is submitted, if no printer name is supplied the +\fI%p \fR +will be silently removed from the printer command\&. +.sp +If specified in the [global] section, the print command given will be used for any printable service that does not have its own print command specified\&. +.sp +If there is neither a specified print command for a printable service nor a global print command, spool files will be created but not processed and (most importantly) not removed\&. +.sp +Note that printing may fail on some UNIXes from the +\fBnobody\fR +account\&. If this happens then create an alternative guest account that can print and set the +\m[blue]\fBguest account\fR\m[] +in the [global] section\&. +.sp +You can form quite complex print commands by realizing that they are just passed to a shell\&. For example the following will log a print job, print the file, then remove it\&. Note that \*(Aq;\*(Aq is the usual separator for command in shell scripts\&. +.sp +print command = echo Printing %s >> /tmp/print\&.log; lpr \-P %p %s; rm %s +.sp +You may have to vary this command considerably depending on how you normally print files on your system\&. The default for the parameter varies depending on the setting of the +\m[blue]\fBprinting\fR\m[] +parameter\&. +.sp +Default: For +printing = BSD, AIX, QNX, LPRNG or PLP : +.sp +print command = lpr \-r \-P%p %s +.sp +For +printing = SYSV or HPUX : +.sp +print command = lp \-c \-d%p %s; rm %s +.sp +For +printing = SOFTQ : +.sp +print command = lp \-d%p \-s %s; rm %s +.sp +For printing = CUPS : If SAMBA is compiled against libcups, then +\m[blue]\fBprintcap = cups\fR\m[] +uses the CUPS API to submit jobs, etc\&. Otherwise it maps to the System V commands with the \-oraw option for printing, i\&.e\&. it uses +lp \-c \-d%p \-oraw; rm %s\&. With +printing = cups, and if SAMBA is compiled against libcups, any manually set print command will be ignored\&. +.sp +\fINo default\fR +.sp +Example: +\fI\fIprint command\fR\fR\fI = \fR\fI/usr/local/samba/bin/myprintscript %p %s\fR\fI \fR +.RE + +printer +.PP +.RS 4 +This parameter is a synonym for +printer name\&. +.RE + +printer name (S) +.PP +.RS 4 +This parameter specifies the name of the printer to which print jobs spooled through a printable service will be sent\&. +.sp +If specified in the [global] section, the printer name given will be used for any printable service that does not have its own printer name specified\&. +.sp +The default value of the +\m[blue]\fBprinter name\fR\m[] +may be +lp +on many systems\&. +.sp +Default: +\fI\fIprinter name\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIprinter name\fR\fR\fI = \fR\fIlaserwriter\fR\fI \fR +.RE + +printing (S) +.PP +.RS 4 +This parameters controls how printer status information is interpreted on your system\&. It also affects the default values for the +\fIprint command\fR, +\fIlpq command\fR, +\fIlppause command \fR, +\fIlpresume command\fR, and +\fIlprm command\fR +if specified in the [global] section\&. +.sp +Currently nine printing styles are supported\&. They are +\fBBSD\fR, +\fBAIX\fR, +\fBLPRNG\fR, +\fBPLP\fR, +\fBSYSV\fR, +\fBHPUX\fR, +\fBQNX\fR, +\fBSOFTQ\fR, +\fBCUPS\fR +and +\fBIPRINT\fR\&. +.sp +Be aware that CUPS and IPRINT are only available if the CUPS development library was available at the time Samba was compiled or packaged\&. +.sp +To see what the defaults are for the other print commands when using the various options use the +\fBtestparm\fR(1) +program\&. +.sp +This option can be set on a per printer basis\&. Please be aware however, that you must place any of the various printing commands (e\&.g\&. print command, lpq command, etc\&.\&.\&.) after defining the value for the +\fIprinting\fR +option since it will reset the printing commands to default values\&. +.sp +See also the discussion in the +[printers] +section\&. +.sp +See +testparm \-v\&. +for the default value on your system +.sp +Default: +\fI\fIprinting\fR\fR\fI = \fR\fI # Depends on the operating system\fR\fI \fR +.RE + +printjob username (S) +.PP +.RS 4 +This parameter specifies which user information will be passed to the printing system\&. Usually, the username is sent, but in some cases, e\&.g\&. the domain prefix is useful, too\&. +.sp +Default: +\fI\fIprintjob username\fR\fR\fI = \fR\fI%U\fR\fI \fR +.sp +Example: +\fI\fIprintjob username\fR\fR\fI = \fR\fI%D\e%U\fR\fI \fR +.RE + +print notify backchannel (S) +.PP +.RS 4 +Windows print clients can update print queue status by expecting the server to open a backchannel SMB connection to them\&. Due to client firewall settings this can cause considerable timeouts and will often fail, as there is no guarantee the client is even running an SMB server\&. By default, the Samba print server will not try to connect back to clients, and will treat corresponding requests as if the connection back to the client failed\&. +.sp +Default: +\fI\fIprint notify backchannel\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +private directory +.PP +.RS 4 +This parameter is a synonym for +private dir\&. +.RE + +private dir (G) +.PP +.RS 4 +This parameters defines the directory smbd will use for storing such files as +smbpasswd +and +secrets\&.tdb\&. +.sp +Default: +\fI\fIprivate dir\fR\fR\fI = \fR\fI/var/lib/samba/private\fR\fI \fR +.RE + +queuepause command (S) +.PP +.RS 4 +This parameter specifies the command to be executed on the server host in order to pause the printer queue\&. +.sp +This command should be a program or script which takes a printer name as its only parameter and stops the printer queue, such that no longer jobs are submitted to the printer\&. +.sp +This command is not supported by Windows for Workgroups, but can be issued from the Printers window under Windows 95 and NT\&. +.sp +If a +\fI%p\fR +is given then the printer name is put in its place\&. Otherwise it is placed at the end of the command\&. +.sp +Note that it is good practice to include the absolute path in the command as the PATH may not be available to the server\&. +.sp +Default: +\fI\fIqueuepause command\fR\fR\fI = \fR\fI # determined by printing parameter\fR\fI \fR +.sp +Example: +\fI\fIqueuepause command\fR\fR\fI = \fR\fIdisable %p\fR\fI \fR +.RE + +queueresume command (S) +.PP +.RS 4 +This parameter specifies the command to be executed on the server host in order to resume the printer queue\&. It is the command to undo the behavior that is caused by the previous parameter (\m[blue]\fBqueuepause command\fR\m[])\&. +.sp +This command should be a program or script which takes a printer name as its only parameter and resumes the printer queue, such that queued jobs are resubmitted to the printer\&. +.sp +This command is not supported by Windows for Workgroups, but can be issued from the Printers window under Windows 95 and NT\&. +.sp +If a +\fI%p\fR +is given then the printer name is put in its place\&. Otherwise it is placed at the end of the command\&. +.sp +Note that it is good practice to include the absolute path in the command as the PATH may not be available to the server\&. +.sp +Default: +\fI\fIqueueresume command\fR\fR\fI = \fR\fI # determined by printing parameter\fR\fI \fR +.sp +Example: +\fI\fIqueueresume command\fR\fR\fI = \fR\fIenable %p\fR\fI \fR +.RE + +raw NTLMv2 auth (G) +.PP +.RS 4 +This parameter has been deprecated since Samba 4\&.13 and support for NTLMv2 authentication without NTLMSSP will be removed in a future Samba release\&. +.sp +That is, in the future, the current default of +raw NTLMv2 auth = no +will be the enforced behaviour\&. +.sp +This parameter determines whether or not +\fBsmbd\fR(8) +will allow SMB1 clients without extended security (without SPNEGO) to use NTLMv2 authentication\&. +.sp +If this option, +lanman auth +and +ntlm auth +are all disabled, then only clients with SPNEGO support will be permitted\&. That means NTLMv2 is only supported within NTLMSSP\&. +.sp +Default: +\fI\fIraw NTLMv2 auth\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +read list (S) +.PP +.RS 4 +This is a list of users that are given read\-only access to a service\&. If the connecting user is in this list then they will not be given write access, no matter what the +\m[blue]\fBread only\fR\m[] +option is set to\&. The list can include group names using the syntax described in the +\m[blue]\fBinvalid users\fR\m[] +parameter\&. +.sp +Default: +\fI\fIread list\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIread list\fR\fR\fI = \fR\fImary, @students\fR\fI \fR +.RE + +read only (S) +.PP +.RS 4 +An inverted synonym is +\m[blue]\fBwriteable\fR\m[]\&. +.sp +If this parameter is +\fByes\fR, then users of a service may not create or modify files in the service\*(Aqs directory\&. +.sp +Note that a printable service (printable = yes) will +\fIALWAYS\fR +allow writing to the directory (user privileges permitting), but only via spooling operations\&. +.sp +Default: +\fI\fIread only\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +read raw (G) +.PP +.RS 4 +This is ignored if +\m[blue]\fBasync smb echo handler\fR\m[] +is set, because this feature is incompatible with raw read SMB requests +.sp +If enabled, raw reads allow reads of 65535 bytes in one packet\&. This typically provides a major performance benefit for some very, very old clients\&. +.sp +However, some clients either negotiate the allowable block size incorrectly or are incapable of supporting larger block sizes, and for these clients you may need to disable raw reads\&. +.sp +In general this parameter should be viewed as a system tuning tool and left severely alone\&. +.sp +Default: +\fI\fIread raw\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +realm (G) +.PP +.RS 4 +This option specifies the kerberos realm to use\&. The realm is used as the ADS equivalent of the NT4 +domain\&. It is usually set to the DNS name of the kerberos server\&. +.sp +Default: +\fI\fIrealm\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIrealm\fR\fR\fI = \fR\fImysambabox\&.mycompany\&.com\fR\fI \fR +.RE + +registry shares (G) +.PP +.RS 4 +This turns on or off support for share definitions read from registry\&. Shares defined in +\fIsmb\&.conf\fR +take precedence over shares with the same name defined in registry\&. See the section on registry\-based configuration for details\&. +.sp +Note that this parameter defaults to +\fIno\fR, but it is set to +\fIyes\fR +when +\fIconfig backend\fR +is set to +\fIregistry\fR\&. +.sp +Default: +\fI\fIregistry shares\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIregistry shares\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +reject md5 clients (G) +.PP +.RS 4 +This option is deprecated and will be removed in a future release, as it is a security problem if not set to "yes" (which will be the hardcoded behavior in the future)\&. +.sp +This option controls whether the netlogon server (currently only in \*(Aqactive directory domain controller\*(Aq mode), will reject clients which does not support NETLOGON_NEG_SUPPORTS_AES\&. +.sp +Support for NETLOGON_NEG_SUPPORTS_AES was added in Windows starting with Server 2008R2 and Windows 7, it\*(Aqs available in Samba starting with 4\&.0, however third party domain members like NetApp ONTAP still uses RC4 (HMAC\-MD5), see +https://www\&.samba\&.org/samba/security/CVE\-2022\-38023\&.html +for more details\&. +.sp +The default changed from \*(Aqno\*(Aq to \*(Aqyes\*(Aq, with the patches for +CVE\-2022\-38023 +see +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240\&. +.sp +\fIAvoid using this option!\fR +Use an explicit per machine account \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT\fR\m[]\*(Aq instead! Which is available with the patches for +CVE\-2022\-38023 +see +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240\&. +.sp +Samba will log an error in the log files at log level 0 if legacy a client is rejected or allowed without an explicit, \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq option for the client\&. The message will indicate the explicit \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq line to be added, if the legacy client software requires it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2022_38023:error_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +This allows admins to use "no" only for a short grace period, in order to collect the explicit \*(Aq\m[blue]\fBserver reject md5 schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq options\&. +.sp +When set to \*(Aqyes\*(Aq this option overrides the \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT\fR\m[]\*(Aq and \*(Aq\m[blue]\fBallow nt4 crypto\fR\m[]\*(Aq options and implies \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = no\fR\m[]\*(Aq\&. +.sp +Default: +\fI\fIreject md5 clients\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +server reject md5 schannel:COMPUTERACCOUNT (G) +.PP +.RS 4 +If you still have legacy domain members or trusted domains, which required "reject md5 clients = no" before, it is possible to specify an explicit exception per computer account by setting \*(Aqserver reject md5 schannel:COMPUTERACCOUNT = no\*(Aq\&. Note that COMPUTERACCOUNT has to be the sAMAccountName value of the computer account (including the trailing \*(Aq$\*(Aq sign)\&. +.sp +Samba will log a complaint in the log files at log level 0 about the security problem if the option is set to "no", but the related computer does not require it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2022_38023:warn_about_unused_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +Samba will log a warning in the log files at log level 5 if a setting is still needed for the specified computer account\&. +.sp +See +CVE\-2022\-38023, +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240\&. +.sp +This option overrides the +\m[blue]\fBreject md5 clients\fR\m[] +option\&. +.sp +When set to \*(Aqyes\*(Aq this option overrides the \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT\fR\m[]\*(Aq and \*(Aq\m[blue]\fBallow nt4 crypto\fR\m[]\*(Aq options and implies \*(Aq\m[blue]\fBallow nt4 crypto:COMPUTERACCOUNT = no\fR\m[]\*(Aq\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + server reject md5 schannel:LEGACYCOMPUTER1$ = no + server reject md5 schannel:NASBOX$ = no + server reject md5 schannel:LEGACYCOMPUTER2$ = no + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +reject md5 servers (G) +.PP +.RS 4 +This option controls whether winbindd requires support for aes support for the netlogon secure channel\&. +.sp +The following flags will be required NETLOGON_NEG_ARCFOUR, NETLOGON_NEG_SUPPORTS_AES, NETLOGON_NEG_PASSWORD_SET2 and NETLOGON_NEG_AUTHENTICATED_RPC\&. +.sp +You can set this to yes if all domain controllers support aes\&. This will prevent downgrade attacks\&. +.sp +The behavior can be controlled per netbios domain by using \*(Aqreject md5 servers:NETBIOSDOMAIN = no\*(Aq as option\&. +.sp +The default changed from \*(Aqno\*(Aq to \*(Aqyes, with the patches for CVE\-2022\-38023, see https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240 +.sp +This option overrides the +\m[blue]\fBrequire strong key\fR\m[] +option\&. +.sp +Default: +\fI\fIreject md5 servers\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +remote announce (G) +.PP +.RS 4 +This option allows you to setup +\fBnmbd\fR(8) +to periodically announce itself to arbitrary IP addresses with an arbitrary workgroup name\&. +.sp +This is useful if you want your Samba server to appear in a remote workgroup for which the normal browse propagation rules don\*(Aqt work\&. The remote workgroup can be anywhere that you can send IP packets to\&. +.sp +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +remote announce = 192\&.168\&.2\&.255/SERVERS 192\&.168\&.4\&.255/STAFF +.fi +.if n \{\ +.RE +.\} +.sp +the above line would cause +nmbd +to announce itself to the two given IP addresses using the given workgroup names\&. If you leave out the workgroup name, then the one given in the +\m[blue]\fBworkgroup\fR\m[] +parameter is used instead\&. +.sp +The IP addresses you choose would normally be the broadcast addresses of the remote networks, but can also be the IP addresses of known browse masters if your network config is that stable\&. +.sp +See the chapter on Network Browsing in the Samba\-HOWTO book\&. +.sp +Default: +\fI\fIremote announce\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +remote browse sync (G) +.PP +.RS 4 +This option allows you to setup +\fBnmbd\fR(8) +to periodically request synchronization of browse lists with the master browser of a Samba server that is on a remote segment\&. This option will allow you to gain browse lists for multiple workgroups across routed networks\&. This is done in a manner that does not work with any non\-Samba servers\&. +.sp +This is useful if you want your Samba server and all local clients to appear in a remote workgroup for which the normal browse propagation rules don\*(Aqt work\&. The remote workgroup can be anywhere that you can send IP packets to\&. +.sp +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIremote browse sync = 192\&.168\&.2\&.255 192\&.168\&.4\&.255\fR +.fi +.if n \{\ +.RE +.\} +.sp +the above line would cause +nmbd +to request the master browser on the specified subnets or addresses to synchronize their browse lists with the local server\&. +.sp +The IP addresses you choose would normally be the broadcast addresses of the remote networks, but can also be the IP addresses of known browse masters if your network config is that stable\&. If a machine IP address is given Samba makes NO attempt to validate that the remote machine is available, is listening, nor that it is in fact the browse master on its segment\&. +.sp +The +\m[blue]\fBremote browse sync\fR\m[] +may be used on networks where there is no WINS server, and may be used on disjoint networks where each network has its own WINS server\&. +.sp +Default: +\fI\fIremote browse sync\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +rename user script (G) +.PP +.RS 4 +This is the full pathname to a script that will be run as root by +\fBsmbd\fR(8) +under special circumstances described below\&. +.sp +When a user with admin authority or SeAddUserPrivilege rights renames a user (e\&.g\&.: from the NT4 User Manager for Domains), this script will be run to rename the POSIX user\&. Two variables, +%uold +and +%unew, will be substituted with the old and new usernames, respectively\&. The script should return 0 upon successful completion, and nonzero otherwise\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +The script has all responsibility to rename all the necessary data that is accessible in this posix method\&. This can mean different requirements for different backends\&. The tdbsam and smbpasswd backends will take care of the contents of their respective files, so the script is responsible only for changing the POSIX username, and other data that may required for your circumstances, such as home directory\&. Please also consider whether or not you need to rename the actual home directories themselves\&. The ldapsam backend will not make any changes, because of the potential issues with renaming the LDAP naming attribute\&. In this case the script is responsible for changing the attribute that samba uses (uid) for locating users, as well as any data that needs to change for other applications using the same directory\&. +.sp .5v +.RE +Default: +\fI\fIrename user script\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +require strong key (G) +.PP +.RS 4 +This option controls whether winbindd requires support for md5 strong key support for the netlogon secure channel\&. +.sp +The following flags will be required NETLOGON_NEG_STRONG_KEYS, NETLOGON_NEG_ARCFOUR and NETLOGON_NEG_AUTHENTICATED_RPC\&. +.sp +You can set this to no if some domain controllers only support des\&. This might allows weak crypto to be negotiated, may via downgrade attacks\&. +.sp +The behavior can be controlled per netbios domain by using \*(Aqrequire strong key:NETBIOSDOMAIN = no\*(Aq as option\&. +.sp +Note for active directory domain this option is hardcoded to \*(Aqyes\*(Aq +.sp +This option is over\-ridden by the +\m[blue]\fBreject md5 servers\fR\m[] +option\&. +.sp +This option overrides the +\m[blue]\fBclient schannel\fR\m[] +option\&. +.sp +Default: +\fI\fIrequire strong key\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +reset on zero vc (G) +.PP +.RS 4 +This boolean option controls whether an incoming SMB1 session setup should kill other connections coming from the same IP\&. This matches the default Windows 2003 behaviour\&. Setting this parameter to yes becomes necessary when you have a flaky network and windows decides to reconnect while the old connection still has files with share modes open\&. These files become inaccessible over the new connection\&. The client sends a zero VC on the new connection, and Windows 2003 kills all other connections coming from the same IP\&. This way the locked files are accessible again\&. Please be aware that enabling this option will kill connections behind a masquerading router, and will not trigger for clients that only use SMB2 or SMB3\&. +.sp +Default: +\fI\fIreset on zero vc\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +restrict anonymous (G) +.PP +.RS 4 +The setting of this parameter determines whether SAMR and LSA DCERPC services can be accessed anonymously\&. This corresponds to the following Windows Server registry options: +.sp +.if n \{\ +.RS 4 +.\} +.nf + HKEY_LOCAL_MACHINE\eSYSTEM\eCurrentControlSet\eControl\eLsa\eRestrictAnonymous + +.fi +.if n \{\ +.RE +.\} +.sp +The option also affects the browse option which is required by legacy clients which rely on Netbios browsing\&. While modern Windows version should be fine with restricting the access there could still be applications relying on anonymous access\&. +.sp +Setting +\m[blue]\fBrestrict anonymous = 1\fR\m[] +will disable anonymous SAMR access\&. +.sp +Setting +\m[blue]\fBrestrict anonymous = 2\fR\m[] +will, in addition to restricting SAMR access, disallow anonymous connections to the IPC$ share in general\&. Setting +\m[blue]\fBguest ok = yes\fR\m[] +on any share will remove the security advantage\&. +.sp +Default: +\fI\fIrestrict anonymous\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +root +.PP +.RS 4 +This parameter is a synonym for +root directory\&. +.RE + +root dir +.PP +.RS 4 +This parameter is a synonym for +root directory\&. +.RE + +root directory (G) +.PP +.RS 4 +The server will +chroot() +(i\&.e\&. Change its root directory) to this directory on startup\&. This is not strictly necessary for secure operation\&. Even without it the server will deny access to files not in one of the service entries\&. It may also check for, and deny access to, soft links to other parts of the filesystem, or attempts to use "\&.\&." in file names to access other directories (depending on the setting of the +\m[blue]\fBwide links\fR\m[] +parameter)\&. +.sp +Adding a +\fIroot directory\fR +entry other than "/" adds an extra level of security, but at a price\&. It absolutely ensures that no access is given to files not in the sub\-tree specified in the +\fIroot directory\fR +option, +\fIincluding\fR +some files needed for complete operation of the server\&. To maintain full operability of the server you will need to mirror some system files into the +\fIroot directory\fR +tree\&. In particular you will need to mirror +/etc/passwd +(or a subset of it), and any binaries or configuration files needed for printing (if required)\&. The set of files that must be mirrored is operating system dependent\&. +.sp +Default: +\fI\fIroot directory\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIroot directory\fR\fR\fI = \fR\fI/homes/smb\fR\fI \fR +.RE + +root postexec (S) +.PP +.RS 4 +This is the same as the +\fIpostexec\fR +parameter except that the command is run as root\&. This is useful for unmounting filesystems (such as CDROMs) after a connection is closed\&. +.sp +Default: +\fI\fIroot postexec\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +root preexec (S) +.PP +.RS 4 +This is the same as the +\fIpreexec\fR +parameter except that the command is run as root\&. This is useful for mounting filesystems (such as CDROMs) when a connection is opened\&. +.sp +Default: +\fI\fIroot preexec\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +root preexec close (S) +.PP +.RS 4 +This is the same as the +\fIpreexec close \fR +parameter except that the command is run as root\&. +.sp +Default: +\fI\fIroot preexec close\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +rpc big endian (G) +.PP +.RS 4 +Setting this option will force the RPC client and server to transfer data in big endian\&. +.sp +If it is disabled, data will be transferred in little endian\&. +.sp +The behaviour is independent of the endianness of the host machine\&. +.sp +Default: +\fI\fIrpc big endian\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +rpc server dynamic port range (G) +.PP +.RS 4 +This parameter tells the RPC server which port range it is allowed to use to create a listening socket for LSA, SAM, Netlogon and others without wellknown tcp ports\&. The first value is the lowest number of the port range and the second the highest\&. +.sp +This applies to RPC servers in all server roles\&. +.sp +Default: +\fI\fIrpc server dynamic port range\fR\fR\fI = \fR\fI49152\-65535\fR\fI \fR +.RE + +rpc server port (G) +.PP +.RS 4 +Specifies which port the server should listen on for DCE/RPC over TCP/IP traffic\&. +.sp +This controls the default port for all protocols, except for NETLOGON\&. +.sp +If unset, the first available port from +\m[blue]\fBrpc server dynamic port range\fR\m[] +is used, e\&.g\&. 49152\&. +.sp +The NETLOGON server will use the next available port, e\&.g\&. 49153\&. To change this port use (eg) rpc server port:netlogon = 4000\&. +.sp +Furthermore, all RPC servers can have the port they use specified independenty, with (for example) rpc server port:drsuapi = 5000\&. +.sp +This option applies currently only when +\fBsamba\fR(8) +runs as an active directory domain controller\&. +.sp +The default value 0 causes Samba to select the first available port from +\m[blue]\fBrpc server dynamic port range\fR\m[]\&. +.sp +Default: +\fI\fIrpc server port\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +rpc start on demand helpers (G) +.PP +.RS 4 +This global parameter determines if +samba\-dcerpcd +should be started on demand to service named pipe (np) DCE\-RPC requests from +smbd +or +winbindd\&. This is the normal case where no startup scripts have been modified to start +samba\-dcerpcd +as a daemon\&. +.sp +If +samba\-dcerpcd +is started as a daemon or via a system service manager such as systemd, this parameter MUST be set to "no", otherwise +samba\-dcerpcd +will fail to start\&. +.sp +Default: +\fI\fIrpc start on demand helpers\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +samba kcc command (G) +.PP +.RS 4 +This option specifies the path to the Samba KCC command\&. This script is used for replication topology replication\&. +.sp +It should not be necessary to modify this option except for testing purposes or if the +samba_kcc +was installed in a non\-default location\&. +.sp +Default: +\fI\fIsamba kcc command\fR\fR\fI = \fR\fI/builddir/build/BUILD/samba\-4\&.20\&.0rc3/source4/scripting/bin/samba_kcc\fR\fI \fR +.sp +Example: +\fI\fIsamba kcc command\fR\fR\fI = \fR\fI/usr/local/bin/kcc\fR\fI \fR +.RE + +security (G) +.PP +.RS 4 +This option affects how clients respond to Samba and is one of the most important settings in the +smb\&.conf +file\&. +.sp +Unless +\m[blue]\fBserver role\fR\m[] +is specified, the default is +security = user, as this is the most common setting, used for a standalone file server or a DC\&. +.sp +The alternatives to +security = user +are +security = ads +or +security = domain, which support joining Samba to a Windows domain +.sp +You should use +security = user +and +\m[blue]\fBmap to guest\fR\m[] +if you want to mainly setup shares without a password (guest shares)\&. This is commonly used for a shared printer server\&. +.sp +The different settings will now be explained\&. +.sp +\fISECURITY = AUTO\fR +.sp +This is the default security setting in Samba, and causes Samba to consult the +\m[blue]\fBserver role\fR\m[] +parameter (if set) to determine the security mode\&. +.sp +\fISECURITY = USER\fR +.sp +If +\m[blue]\fBserver role\fR\m[] +is not specified, this is the default security setting in Samba\&. With user\-level security a client must first "log\-on" with a valid username and password (which can be mapped using the +\m[blue]\fBusername map\fR\m[] +parameter)\&. Encrypted passwords (see the +\m[blue]\fBencrypt passwords\fR\m[] +parameter) can also be used in this security mode\&. Parameters such as +\m[blue]\fBforce user\fR\m[] +and +\m[blue]\fBguest only\fR\m[] +if set are then applied and may change the UNIX user to use on this connection, but only after the user has been successfully authenticated\&. +.sp +\fINote\fR +that the name of the resource being requested is +\fInot\fR +sent to the server until after the server has successfully authenticated the client\&. This is why guest shares don\*(Aqt work in user level security without allowing the server to automatically map unknown users into the +\m[blue]\fBguest account\fR\m[]\&. See the +\m[blue]\fBmap to guest\fR\m[] +parameter for details on doing this\&. +.sp +\fISECURITY = DOMAIN\fR +.sp +This mode will only work correctly if +\fBnet\fR(8) +has been used to add this machine into a Windows NT Domain\&. It expects the +\m[blue]\fBencrypt passwords\fR\m[] +parameter to be set to +\fByes\fR\&. In this mode Samba will try to validate the username/password by passing it to a Windows NT Primary or Backup Domain Controller, in exactly the same way that a Windows NT Server would do\&. +.sp +\fINote\fR +that a valid UNIX user must still exist as well as the account on the Domain Controller to allow Samba to have a valid UNIX account to map file access to\&. +.sp +\fINote\fR +that from the client\*(Aqs point of view +security = domain +is the same as +security = user\&. It only affects how the server deals with the authentication, it does not in any way affect what the client sees\&. +.sp +\fINote\fR +that the name of the resource being requested is +\fInot\fR +sent to the server until after the server has successfully authenticated the client\&. This is why guest shares don\*(Aqt work in user level security without allowing the server to automatically map unknown users into the +\m[blue]\fBguest account\fR\m[]\&. See the +\m[blue]\fBmap to guest\fR\m[] +parameter for details on doing this\&. +.sp +See also the +\m[blue]\fBpassword server\fR\m[] +parameter and the +\m[blue]\fBencrypt passwords\fR\m[] +parameter\&. +.sp +\fISECURITY = ADS\fR +.sp +In this mode, Samba will act as a domain member in an ADS realm\&. To operate in this mode, the machine running Samba will need to have Kerberos installed and configured and Samba will need to be joined to the ADS realm using the net utility\&. +.sp +Note that this mode does NOT make Samba operate as a Active Directory Domain Controller\&. +.sp +Note that this forces +\m[blue]\fBrequire strong key = yes\fR\m[] +and +\m[blue]\fBclient schannel = yes\fR\m[] +for the primary domain\&. +.sp +Read the chapter about Domain Membership in the HOWTO for details\&. +.sp +Default: +\fI\fIsecurity\fR\fR\fI = \fR\fIAUTO\fR\fI \fR +.sp +Example: +\fI\fIsecurity\fR\fR\fI = \fR\fIDOMAIN\fR\fI \fR +.RE + +security mask (S) +.PP +.RS 4 +This parameter has been removed for Samba 4\&.0\&.0\&. +.sp +\fINo default\fR +.RE + +server addresses (S) +.PP +.RS 4 +This is a per\-share parameter to limit share visibility and accessibility to specific server IP addresses\&. Multi\-homed servers can offer a different set of shares per interface\&. +.sp +An empty list means to offer a share on all interfaces\&. +.sp +Default: +\fI\fIserver addresses\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +max protocol +.PP +.RS 4 +This parameter is a synonym for +server max protocol\&. +.RE + +protocol +.PP +.RS 4 +This parameter is a synonym for +server max protocol\&. +.RE + +server max protocol (G) +.PP +.RS 4 +The value of the parameter (a string) is the highest protocol level that will be supported by the server\&. +.sp +Possible values are : +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBLANMAN1\fR: First +\fImodern\fR +version of the protocol\&. Long filename support\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBLANMAN2\fR: Updates to Lanman1 protocol\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBNT1\fR: Current up to date version of the protocol\&. Used by Windows NT\&. Known as CIFS\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB2\fR: Re\-implementation of the SMB protocol\&. Used by Windows Vista and later versions of Windows\&. SMB2 has sub protocols available\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB2_02\fR: The earliest SMB2 version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB2_10\fR: Windows 7 SMB2 version\&. +.RE +.sp +.RE +By default SMB2 selects the SMB2_10 variant\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3\fR: The same as SMB2\&. Used by Windows 8\&. SMB3 has sub protocols available\&. +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3_00\fR: Windows 8 SMB3 version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3_02\fR: Windows 8\&.1 SMB3 version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSMB3_11\fR: Windows 10 SMB3 version\&. +.RE +.sp +.RE +By default SMB3 selects the SMB3_11 variant\&. +.RE +.sp +.RE +Normally this option should not be set as the automatic negotiation phase in the SMB protocol takes care of choosing the appropriate protocol\&. +.sp +Default: +\fI\fIserver max protocol\fR\fR\fI = \fR\fISMB3\fR\fI \fR +.sp +Example: +\fI\fIserver max protocol\fR\fR\fI = \fR\fILANMAN1\fR\fI \fR +.RE + +min protocol +.PP +.RS 4 +This parameter is a synonym for +server min protocol\&. +.RE + +server min protocol (G) +.PP +.RS 4 +This setting controls the minimum protocol version that the server will allow the client to use\&. +.sp +Normally this option should not be set as the automatic negotiation phase in the SMB protocol takes care of choosing the appropriate protocol unless you have legacy clients which are SMB1 capable only\&. +.sp +See +Related command: \m[blue]\fBserver max protocol\fR\m[] +for a full list of available protocols\&. +.sp +Default: +\fI\fIserver min protocol\fR\fR\fI = \fR\fISMB2_02\fR\fI \fR +.sp +Example: +\fI\fIserver min protocol\fR\fR\fI = \fR\fINT1\fR\fI \fR +.RE + +server multi channel support (G) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will support SMB3 multi\-channel\&. +.sp +This parameter was added with version 4\&.4\&. +.sp +Note that this feature was still considered experimental up to 4\&.14\&. +.sp +Due to dependencies to kernel APIs of Linux or FreeBSD, it\*(Aqs only possible to use this feature on Linux and FreeBSD for now\&. For testing this restriction can be overwritten by specifying +\fBforce:server multi channel support=yes\fR +in addition\&. +.sp +This option is enabled by default starting with to 4\&.15 (on Linux and FreeBSD)\&. +.sp +Default: +\fI\fIserver multi channel support\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +server role (G) +.PP +.RS 4 +This option determines the basic operating mode of a Samba server and is one of the most important settings in the +smb\&.conf +file\&. +.sp +The default is +server role = auto, as causes Samba to operate according to the +\m[blue]\fBsecurity\fR\m[] +setting, or if not specified as a simple file server that is not connected to any domain\&. +.sp +The alternatives are +server role = standalone +or +server role = member server, which support joining Samba to a Windows domain, along with +server role = domain controller, which run Samba as a Windows domain controller\&. +.sp +You should use +server role = standalone +and +\m[blue]\fBmap to guest\fR\m[] +if you want to mainly setup shares without a password (guest shares)\&. This is commonly used for a shared printer server\&. +.sp +\fISERVER ROLE = AUTO\fR +.sp +This is the default server role in Samba, and causes Samba to consult the +\m[blue]\fBsecurity\fR\m[] +parameter (if set) to determine the server role, giving compatible behaviours to previous Samba versions\&. +.sp +\fISERVER ROLE = STANDALONE\fR +.sp +If +\m[blue]\fBsecurity\fR\m[] +is also not specified, this is the default security setting in Samba\&. In standalone operation, a client must first "log\-on" with a valid username and password (which can be mapped using the +\m[blue]\fBusername map\fR\m[] +parameter) stored on this machine\&. Encrypted passwords (see the +\m[blue]\fBencrypt passwords\fR\m[] +parameter) are by default used in this security mode\&. Parameters such as +\m[blue]\fBforce user\fR\m[] +and +\m[blue]\fBguest only\fR\m[] +if set are then applied and may change the UNIX user to use on this connection, but only after the user has been successfully authenticated\&. +.sp +\fISERVER ROLE = MEMBER SERVER\fR +.sp +This mode will only work correctly if +\fBnet\fR(8) +has been used to add this machine into a Windows Domain\&. It expects the +\m[blue]\fBencrypt passwords\fR\m[] +parameter to be set to +\fByes\fR\&. In this mode Samba will try to validate the username/password by passing it to a Windows or Samba Domain Controller, in exactly the same way that a Windows Server would do\&. +.sp +\fINote\fR +that a valid UNIX user must still exist as well as the account on the Domain Controller to allow Samba to have a valid UNIX account to map file access to\&. Winbind can provide this\&. +.sp +\fISERVER ROLE = CLASSIC PRIMARY DOMAIN CONTROLLER\fR +.sp +This mode of operation runs a classic Samba primary domain controller, providing domain logon services to Windows and Samba clients of an NT4\-like domain\&. Clients must be joined to the domain to create a secure, trusted path across the network\&. There must be only one PDC per NetBIOS scope (typically a broadcast network or clients served by a single WINS server)\&. +.sp +\fISERVER ROLE = CLASSIC BACKUP DOMAIN CONTROLLER\fR +.sp +This mode of operation runs a classic Samba backup domain controller, providing domain logon services to Windows and Samba clients of an NT4\-like domain\&. As a BDC, this allows multiple Samba servers to provide redundant logon services to a single NetBIOS scope\&. +.sp +\fISERVER ROLE = ACTIVE DIRECTORY DOMAIN CONTROLLER\fR +.sp +This mode of operation runs Samba as an active directory domain controller, providing domain logon services to Windows and Samba clients of the domain\&. This role requires special configuration, see the +Samba4 HOWTO +.sp +\fISERVER ROLE = IPA DOMAIN CONTROLLER\fR +.sp +This mode of operation runs Samba in a hybrid mode for IPA domain controller, providing forest trust to Active Directory\&. This role requires special configuration performed by IPA installers and should not be used manually by any administrator\&. +.sp +Default: +\fI\fIserver role\fR\fR\fI = \fR\fIAUTO\fR\fI \fR +.sp +Example: +\fI\fIserver role\fR\fR\fI = \fR\fIACTIVE DIRECTORY DOMAIN CONTROLLER\fR\fI \fR +.RE + +server schannel (G) +.PP +.RS 4 +This option is deprecated and will be removed in future, as it is a security problem if not set to "yes" (which will be the hardcoded behavior in future)\&. +.sp +\fIAvoid using this option!\fR +Use explicit \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq instead! +.sp +Samba will log an error in the log files at log level 0 if legacy a client is rejected or allowed without an explicit, \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq option for the client\&. The message will indicate the explicit \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq line to be added, if the legacy client software requires it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2020_1472:error_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +This allows admins to use "auto" only for a short grace period, in order to collect the explicit \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq options\&. +.sp +See +CVE\-2020\-1472(ZeroLogon), +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=14497\&. +.sp +This option is over\-ridden by the +\m[blue]\fBserver require schannel:COMPUTERACCOUNT\fR\m[] +option\&. +.sp +This option is over\-ridden by the effective value of \*(Aqyes\*(Aq from the \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT\fR\m[]\*(Aq and/or \*(Aq\m[blue]\fBserver schannel require seal\fR\m[]\*(Aq options\&. +.sp +Default: +\fI\fIserver schannel\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +server require schannel:COMPUTERACCOUNT (G) +.PP +.RS 4 +If you still have legacy domain members, which required "server schannel = auto" before, it is possible to specify explicit exception per computer account by using \*(Aqserver require schannel:COMPUTERACCOUNT = no\*(Aq as option\&. Note that COMPUTERACCOUNT has to be the sAMAccountName value of the computer account (including the trailing \*(Aq$\*(Aq sign)\&. +.sp +Samba will complain in the log files at log level 0, about the security problem if the option is not set to "no", but the related computer is actually using the netlogon secure channel (schannel) feature\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2020_1472:warn_about_unused_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +Samba will warn in the log files at log level 5, if a setting is still needed for the specified computer account\&. +.sp +See +CVE\-2020\-1472(ZeroLogon), +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=14497\&. +.sp +This option overrides the +\m[blue]\fBserver schannel\fR\m[] +option\&. +.sp +This option is over\-ridden by the effective value of \*(Aqyes\*(Aq from the \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT\fR\m[]\*(Aq and/or \*(Aq\m[blue]\fBserver schannel require seal\fR\m[]\*(Aq options\&. +.sp +Which means \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = no\fR\m[]\*(Aq is only useful in combination with \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT = no\fR\m[]\*(Aq +.sp +.if n \{\ +.RS 4 +.\} +.nf + server require schannel:LEGACYCOMPUTER1$ = no + server require schannel seal:LEGACYCOMPUTER1$ = no + server require schannel:NASBOX$ = no + server require schannel seal:NASBOX$ = no + server require schannel:LEGACYCOMPUTER2$ = no + server require schannel seal:LEGACYCOMPUTER2$ = no + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +server schannel require seal (G) +.PP +.RS 4 +This option is deprecated and will be removed in future, as it is a security problem if not set to "yes" (which will be the hardcoded behavior in future)\&. +.sp +This option controls whether the netlogon server, will reject the usage of netlogon secure channel without privacy/enryption\&. +.sp +The option is modelled after the registry key available on Windows\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + HKEY_LOCAL_MACHINE\eSYSTEM\eCurrentControlSet\eServices\eNetlogon\eParameters\eRequireSeal=2 + +.fi +.if n \{\ +.RE +.\} +.sp +\fIAvoid using this option!\fR +Use the per computer account specific option \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT\fR\m[]\*(Aq instead! Which is available with the patches for +CVE\-2022\-38023 +see +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240\&. +.sp +Samba will log an error in the log files at log level 0 if legacy a client is rejected or allowed without an explicit, \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT = no\fR\m[]\*(Aq option for the client\&. The message will indicate the explicit \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT = no\fR\m[]\*(Aq line to be added, if the legacy client software requires it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2022_38023:error_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +This allows admins to use "no" only for a short grace period, in order to collect the explicit \*(Aq\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT = no\fR\m[]\*(Aq options\&. +.sp +When set to \*(Aqyes\*(Aq this option overrides the \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT\fR\m[]\*(Aq and \*(Aq\m[blue]\fBserver schannel\fR\m[]\*(Aq options and implies \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = yes\fR\m[]\*(Aq\&. +.sp +This option is over\-ridden by the +\m[blue]\fBserver schannel require seal:COMPUTERACCOUNT\fR\m[] +option\&. +.sp +Default: +\fI\fIserver schannel require seal\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +server schannel require seal:COMPUTERACCOUNT (G) +.PP +.RS 4 +If you still have legacy domain members, which required "server schannel require seal = no" before, it is possible to specify explicit exception per computer account by using \*(Aqserver schannel require seal:COMPUTERACCOUNT = no\*(Aq as option\&. Note that COMPUTERACCOUNT has to be the sAMAccountName value of the computer account (including the trailing \*(Aq$\*(Aq sign)\&. +.sp +Samba will log a complaint in the log files at log level 0 about the security problem if the option is set to "no", but the related computer does not require it\&. (The log level can be adjusted with \*(Aq\m[blue]\fBCVE_2022_38023:warn_about_unused_debug_level = 1\fR\m[]\*(Aq in order to complain only at a higher log level)\&. +.sp +Samba will warn in the log files at log level 5, if a setting is still needed for the specified computer account\&. +.sp +See +CVE\-2022\-38023, +https://bugzilla\&.samba\&.org/show_bug\&.cgi?id=15240\&. +.sp +This option overrides the \*(Aq\m[blue]\fBserver schannel require seal\fR\m[]\*(Aq option\&. +.sp +When set to \*(Aqyes\*(Aq this option overrides the \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT\fR\m[]\*(Aq and \*(Aq\m[blue]\fBserver schannel\fR\m[]\*(Aq options and implies \*(Aq\m[blue]\fBserver require schannel:COMPUTERACCOUNT = yes\fR\m[]\*(Aq\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + server require schannel seal:LEGACYCOMPUTER1$ = no + server require schannel seal:NASBOX$ = no + server require schannel seal:LEGACYCOMPUTER2$ = no + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +server services (G) +.PP +.RS 4 +This option contains the services that the Samba daemon will run\&. +.sp +An entry in the +smb\&.conf +file can either override the previous value completely or entries can be removed from or added to it by prefixing them with +\fB+\fR +or +\fB\-\fR\&. +.sp +Default: +\fI\fIserver services\fR\fR\fI = \fR\fIs3fs, rpc, nbt, wrepl, ldap, cldap, kdc, drepl, winbindd, ntp_signd, kcc, dnsupdate, dns\fR\fI \fR +.sp +Example: +\fI\fIserver services\fR\fR\fI = \fR\fI\-s3fs, +smb\fR\fI \fR +.RE + +server signing (G) +.PP +.RS 4 +This controls whether the client is allowed or required to use SMB1 and SMB2 signing\&. Possible values are +\fIdefault\fR, +\fIauto\fR, +\fImandatory\fR +and +\fIdisabled\fR\&. +.sp +By default, and when smb signing is set to +\fIdefault\fR, smb signing is required when +\m[blue]\fBserver role\fR\m[] +is +\fIactive directory domain controller\fR +and disabled otherwise\&. +.sp +When set to auto, SMB1 signing is offered, but not enforced\&. When set to mandatory, SMB1 signing is required and if set to disabled, SMB signing is not offered either\&. +.sp +For the SMB2 protocol, by design, signing cannot be disabled\&. In the case where SMB2 is negotiated, if this parameter is set to +\fIdisabled\fR, it will be treated as +\fIauto\fR\&. Setting it to +\fImandatory\fR +will still require SMB2 clients to use signing\&. +.sp +Default: +\fI\fIserver signing\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +server smb encrypt (S) +.PP +.RS 4 +This parameter controls whether a remote client is allowed or required to use SMB encryption\&. It has different effects depending on whether the connection uses SMB1 or SMB2 and newer: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the connection uses SMB1, then this option controls the use of a Samba\-specific extension to the SMB protocol introduced in Samba 3\&.2 that makes use of the Unix extensions\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the connection uses SMB2 or newer, then this option controls the use of the SMB\-level encryption that is supported in SMB version 3\&.0 and above and available in Windows 8 and newer\&. +.RE +.sp +.RE +This parameter can be set globally and on a per\-share bases\&. Possible values are +\fIoff\fR, +\fIif_required\fR, +\fIdesired\fR, and +\fIrequired\fR\&. A special value is +\fIdefault\fR +which is the implicit default setting of +\fIif_required\fR\&. +.PP +\fIEffects for SMB1\fR +.RS 4 +The Samba\-specific encryption of SMB1 connections is an extension to the SMB protocol negotiated as part of the UNIX extensions\&. SMB encryption uses the GSSAPI (SSPI on Windows) ability to encrypt and sign every request/response in a SMB protocol stream\&. When enabled it provides a secure method of SMB/CIFS communication, similar to an ssh protected session, but using SMB/CIFS authentication to negotiate encryption and signing keys\&. Currently this is only supported smbclient of by Samba 3\&.2 and newer, and hopefully soon Linux CIFSFS and MacOS/X clients\&. Windows clients do not support this feature\&. +.sp +This may be set on a per\-share basis, but clients may chose to encrypt the entire session, not just traffic to a specific share\&. If this is set to mandatory then all traffic to a share +\fImust\fR +be encrypted once the connection has been made to the share\&. The server would return "access denied" to all non\-encrypted requests on such a share\&. Selecting encrypted traffic reduces throughput as smaller packet sizes must be used (no huge UNIX style read/writes allowed) as well as the overhead of encrypting and signing all the data\&. +.sp +If SMB encryption is selected, Windows style SMB signing (see the +\m[blue]\fBserver signing\fR\m[] +option) is no longer necessary, as the GSSAPI flags use select both signing and sealing of the data\&. +.sp +When set to auto or default, SMB encryption is offered, but not enforced\&. When set to mandatory, SMB encryption is required and if set to disabled, SMB encryption can not be negotiated\&. +.RE +.PP +\fIEffects for SMB2 and newer\fR +.RS 4 +Native SMB transport encryption is available in SMB version 3\&.0 or newer\&. It is only offered by Samba if +\fIserver max protocol\fR +is set to +\fISMB3\fR +or newer\&. Clients supporting this type of encryption include Windows 8 and newer, Windows server 2012 and newer, and smbclient of Samba 4\&.1 and newer\&. +.sp +The protocol implementation offers various options: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The capability to perform SMB encryption can be negotiated during protocol negotiation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Data encryption can be enabled globally\&. In that case, an encryption\-capable connection will have all traffic in all its sessions encrypted\&. In particular all share connections will be encrypted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Data encryption can also be enabled per share if not enabled globally\&. For an encryption\-capable connection, all connections to an encryption\-enabled share will be encrypted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Encryption can be enforced\&. This means that session setups will be denied on non\-encryption\-capable connections if data encryption has been enabled globally\&. And tree connections will be denied for non\-encryption capable connections to shares with data encryption enabled\&. +.RE +.sp +.RE +These features can be controlled with settings of +\fIserver smb encrypt\fR +as follows: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Leaving it as default, explicitly setting +\fIdefault\fR, or setting it to +\fIif_required\fR +globally will enable negotiation of encryption but will not turn on data encryption globally or per share\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIdesired\fR +globally will enable negotiation and will turn on data encryption on sessions and share connections for those clients that support it\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIrequired\fR +globally will enable negotiation and turn on data encryption on sessions and share connections\&. Clients that do not support encryption will be denied access to the server\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIoff\fR +globally will completely disable the encryption feature for all connections\&. Setting +\fIserver smb encrypt = required\fR +for individual shares (while it\*(Aqs globally off) will deny access to this shares for all clients\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIdesired\fR +on a share will turn on data encryption for this share for clients that support encryption if negotiation has been enabled globally\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIrequired\fR +on a share will enforce data encryption for this share if negotiation has been enabled globally\&. I\&.e\&. clients that do not support encryption will be denied access to the share\&. +.sp +Note that this allows per\-share enforcing to be controlled in Samba differently from Windows: In Windows, +\fIRejectUnencryptedAccess\fR +is a global setting, and if it is set, all shares with data encryption turned on are automatically enforcing encryption\&. In order to achieve the same effect in Samba, one has to globally set +\fIserver smb encrypt\fR +to +\fIif_required\fR, and then set all shares that should be encrypted to +\fIrequired\fR\&. Additionally, it is possible in Samba to have some shares with encryption +\fIrequired\fR +and some other shares with encryption only +\fIdesired\fR, which is not possible in Windows\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting it to +\fIoff\fR +or +\fIif_required\fR +for a share has no effect\&. +.RE +.sp +.RE +.RE +.sp +Default: +\fI\fIserver smb encrypt\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +server smb3 encryption algorithms (G) +.PP +.RS 4 +This parameter specifies the availability and order of encryption algorithms which are available for negotiation in the SMB3_11 dialect\&. +.sp +It is also possible to remove individual algorithms from the default list, by prefixing them with \*(Aq\-\*(Aq\&. This can avoid having to specify a hardcoded list\&. +.sp +Note: that the removal of AES\-128\-CCM from the list will result in SMB3_00 and SMB3_02 being unavailable, as it is the default and only available algorithm for these dialects\&. +.sp +Default: +\fI\fIserver smb3 encryption algorithms\fR\fR\fI = \fR\fIAES\-128\-GCM, AES\-128\-CCM, AES\-256\-GCM, AES\-256\-CCM\fR\fI \fR +.sp +Example: +\fI\fIserver smb3 encryption algorithms\fR\fR\fI = \fR\fIAES\-256\-GCM\fR\fI \fR +.sp +Example: +\fI\fIserver smb3 encryption algorithms\fR\fR\fI = \fR\fI\-AES\-128\-GCM \-AES\-128\-CCM\fR\fI \fR +.RE + +server smb3 signing algorithms (G) +.PP +.RS 4 +This parameter specifies the availability and order of signing algorithms which are available for negotiation in the SMB3_11 dialect\&. +.sp +It is also possible to remove individual algorithms from the default list, by prefixing them with \*(Aq\-\*(Aq\&. This can avoid having to specify a hardcoded list\&. +.sp +Note: that the removal of AES\-128\-CMAC from the list will result in SMB3_00 and SMB3_02 being unavailable, and the removal of HMAC\-SHA256 will result in SMB2_02 and SMB2_10 being unavailable, as these are the default and only available algorithms for these dialects\&. +.sp +Default: +\fI\fIserver smb3 signing algorithms\fR\fR\fI = \fR\fIAES\-128\-GMAC, AES\-128\-CMAC, HMAC\-SHA256\fR\fI \fR +.sp +Example: +\fI\fIserver smb3 signing algorithms\fR\fR\fI = \fR\fIAES\-128\-CMAC, HMAC\-SHA256\fR\fI \fR +.sp +Example: +\fI\fIserver smb3 signing algorithms\fR\fR\fI = \fR\fI\-AES\-128\-CMAC\fR\fI \fR +.RE + +server string (G) +.PP +.RS 4 +This controls what string will show up in the printer comment box in print manager and next to the IPC connection in +net view\&. It can be any string that you wish to show to your users\&. +.sp +It also sets what will appear in browse lists next to the machine name\&. +.sp +A +\fI%v\fR +will be replaced with the Samba version number\&. +.sp +A +\fI%h\fR +will be replaced with the hostname\&. +.sp +Default: +\fI\fIserver string\fR\fR\fI = \fR\fISamba %v\fR\fI \fR +.sp +Example: +\fI\fIserver string\fR\fR\fI = \fR\fIUniversity of GNUs Samba Server\fR\fI \fR +.RE + +set primary group script (G) +.PP +.RS 4 +Thanks to the Posix subsystem in NT a Windows User has a primary group in addition to the auxiliary groups\&. This script sets the primary group in the unix user database when an administrator sets the primary group from the windows user manager or when fetching a SAM with +net rpc vampire\&. +\fI%u\fR +will be replaced with the user whose primary group is to be set\&. +\fI%g\fR +will be replaced with the group to set\&. +.sp +Default: +\fI\fIset primary group script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIset primary group script\fR\fR\fI = \fR\fI/usr/sbin/usermod \-g \*(Aq%g\*(Aq \*(Aq%u\*(Aq\fR\fI \fR +.RE + +set quota command (G) +.PP +.RS 4 +The +set quota command +should only be used whenever there is no operating system API available from the OS that samba can use\&. +.sp +This option is only available if Samba was compiled with quota support\&. +.sp +This parameter should specify the path to a script that can set quota for the specified arguments\&. +.sp +The specified script should take the following arguments: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +1 \- path to where the quota needs to be set\&. This needs to be interpreted relative to the current working directory that the script may also check for\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +2 \- quota type +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +1 \- user quotas +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +2 \- user default quotas (uid = \-1) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +3 \- group quotas +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +4 \- group default quotas (gid = \-1) +.RE +.sp +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +3 \- id (uid for user, gid for group, \-1 if N/A) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +4 \- quota state (0 = disable, 1 = enable, 2 = enable and enforce) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +5 \- block softlimit +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +6 \- block hardlimit +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +7 \- inode softlimit +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +8 \- inode hardlimit +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +9(optional) \- block size, defaults to 1024 +.RE +.sp +.RE +The script should output at least one line of data on success\&. And nothing on failure\&. +.sp +Default: +\fI\fIset quota command\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIset quota command\fR\fR\fI = \fR\fI/usr/local/sbin/set_quota\fR\fI \fR +.RE + +share:fake_fscaps (G) +.PP +.RS 4 +This is needed to support some special application that makes QFSINFO calls to check whether we set the SPARSE_FILES bit (0x40)\&. If this bit is not set that particular application refuses to work against Samba\&. With +\m[blue]\fBshare:fake_fscaps = 64\fR\m[] +the SPARSE_FILES file system capability flag is set\&. Use other decimal values to specify the bitmask you need to fake\&. +.sp +Default: +\fI\fIshare:fake_fscaps\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +short preserve case (S) +.PP +.RS 4 +This boolean parameter controls if new files which conform to 8\&.3 syntax, that is all in upper case and of suitable length, are created upper case, or if they are forced to be the +\m[blue]\fBdefault case\fR\m[]\&. This option can be use with +\m[blue]\fBpreserve case = yes\fR\m[] +to permit long filenames to retain their case, while short names are lowered\&. +.sp +See the section on +NAME MANGLING\&. +.sp +Default: +\fI\fIshort preserve case\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +show add printer wizard (G) +.PP +.RS 4 +With the introduction of MS\-RPC based printing support for Windows NT/2000 client in Samba 2\&.2, a "Printers\&.\&.\&." folder will appear on Samba hosts in the share listing\&. Normally this folder will contain an icon for the MS Add Printer Wizard (APW)\&. However, it is possible to disable this feature regardless of the level of privilege of the connected user\&. +.sp +Under normal circumstances, the Windows NT/2000 client will open a handle on the printer server with OpenPrinterEx() asking for Administrator privileges\&. If the user does not have administrative access on the print server (i\&.e is not root or has granted the SePrintOperatorPrivilege), the OpenPrinterEx() call fails and the client makes another open call with a request for a lower privilege level\&. This should succeed, however the APW icon will not be displayed\&. +.sp +Disabling the +\fIshow add printer wizard\fR +parameter will always cause the OpenPrinterEx() on the server to fail\&. Thus the APW icon will never be displayed\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This does not prevent the same user from having administrative privilege on an individual printer\&. +.sp .5v +.RE +Default: +\fI\fIshow add printer wizard\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +shutdown script (G) +.PP +.RS 4 +This a full path name to a script called by +\fBsmbd\fR(8) +that should start a shutdown procedure\&. +.sp +If the connected user possesses the +\fBSeRemoteShutdownPrivilege\fR, right, this command will be run as root\&. +.sp +The %z %t %r %f variables are expanded as follows: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%z\fR +will be substituted with the shutdown message sent to the server\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%t\fR +will be substituted with the number of seconds to wait before effectively starting the shutdown procedure\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%r\fR +will be substituted with the switch +\fI\-r\fR\&. It means reboot after shutdown for NT\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI%f\fR +will be substituted with the switch +\fI\-f\fR\&. It means force the shutdown even if applications do not respond for NT\&. +.RE +.sp +.RE +Shutdown script example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#!/bin/bash + +time=$2 +let time="${time} / 60" +let time="${time} + 1" + +/sbin/shutdown $3 $4 +$time $1 & + +.fi +.if n \{\ +.RE +.\} +.sp +Shutdown does not return so we need to launch it in background\&. +.sp +Default: +\fI\fIshutdown script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIshutdown script\fR\fR\fI = \fR\fI/usr/local/samba/sbin/shutdown %m %t %r %f\fR\fI \fR +.RE + +unix extensions +.PP +.RS 4 +This parameter is a synonym for +smb1 unix extensions\&. +.RE + +smb1 unix extensions (G) +.PP +.RS 4 +This boolean parameter controls whether Samba implements the SMB1/CIFS UNIX extensions, as defined by HP\&. These extensions enable Samba to better serve UNIX SMB1/CIFS clients by supporting features such as symbolic links, hard links, etc\&.\&.\&. These extensions require a similarly enabled client, and are of no current use to Windows clients\&. +.sp +Note if this parameter is turned on, the +\m[blue]\fBwide links\fR\m[] +parameter will automatically be disabled\&. +.sp +See the parameter +\m[blue]\fBallow insecure wide links\fR\m[] +if you wish to change this coupling between the two parameters\&. +.sp +Default: +\fI\fIsmb1 unix extensions\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smb2 disable lock sequence checking (G) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will disable lock sequence checking even for multi\-channel connections as well as durable handles\&. +.sp +The [MS\-SMB2] specification (under 3\&.3\&.5\&.14 Receiving an SMB2 LOCK Request) documents that a server should do lock sequence if Open\&.IsResilient or Open\&.IsDurable or Open\&.IsPersistent is TRUE or if Connection\&.Dialect belongs to the SMB 3\&.x dialect family and Connection\&.ServerCapabilities includes SMB2_GLOBAL_CAP_MULTI_CHANNEL\&. +.sp +But Windows Server (at least up to v2004) only does these checks for the Open\&.IsResilient and Open\&.IsPersistent\&. That means they do not implement the behavior specified in [MS\-SMB2]\&. +.sp +By default Samba behaves according to the specification and implements lock sequence checking when multi\-channel is used\&. +.sp +Warning: Only enable this option if existing clients can\*(Aqt handle lock sequence checking for handles without Open\&.IsResilient and Open\&.IsPersistent\&. And it turns out that the Windows Server behavior is required\&. +.sp +Note: it\*(Aqs likely that this option will be removed again if future Windows versions change their behavior\&. +.sp +Note: Samba does not implement Open\&.IsResilient and Open\&.IsPersistent yet\&. +.sp +Default: +\fI\fIsmb2 disable lock sequence checking\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIsmb2 disable lock sequence checking\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smb2 disable oplock break retry (G) +.PP +.RS 4 +This boolean parameter controls whether +\fBsmbd\fR(8) +will trigger smb2 oplock break notification retries when using +\m[blue]\fBserver multi channel support = yes\fR\m[]\&. +.sp +The [MS\-SMB2] specification documents that a server should send smb2 oplock break notification retries on all available channel to the given client\&. +.sp +But Windows Server versions (at least up to 2019) do not send smb2 oplock break notification retries on channel failures\&. That means they do not implement the behavior specified in [MS\-SMB2]\&. +.sp +By default Samba behaves according to the specification and send smb2 oplock break notification retries\&. +.sp +Warning: Only enable this option if existing clients can\*(Aqt handle possible retries and it turns out that the Windows Server behavior is required\&. +.sp +Note: it\*(Aqs likely that this option gets removed again if future Windows versions change their behavior\&. +.sp +Note: this only applies to oplocks and not SMB2 leases\&. +.sp +Default: +\fI\fIsmb2 disable oplock break retry\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIsmb2 disable oplock break retry\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smb2 leases (G) +.PP +.RS 4 +This boolean option tells +smbd +whether to globally negotiate SMB2 leases on file open requests\&. Leasing is an SMB2\-only feature which allows clients to aggressively cache files locally above and beyond the caching allowed by SMB1 oplocks\&. +.sp +This is only available with +\m[blue]\fBoplocks = yes\fR\m[] +and +\m[blue]\fBkernel oplocks = no\fR\m[]\&. +.sp +Default: +\fI\fIsmb2 leases\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smb2 max credits (G) +.PP +.RS 4 +This option controls the maximum number of outstanding simultaneous SMB2 operations that Samba tells the client it will allow\&. This is similar to the +\m[blue]\fBmax mux\fR\m[] +parameter for SMB1\&. You should never need to set this parameter\&. +.sp +The default is 8192 credits, which is the same as a Windows 2008R2 SMB2 server\&. +.sp +Default: +\fI\fIsmb2 max credits\fR\fR\fI = \fR\fI8192\fR\fI \fR +.RE + +smb2 max read (G) +.PP +.RS 4 +This option specifies the protocol value that +\fBsmbd\fR(8) +will return to a client, informing the client of the largest size that may be returned by a single SMB2 read call\&. +.sp +The maximum is 8388608 bytes (8MiB), which is the same as a Windows Server 2012 r2\&. +.sp +Please note that the default is 8MiB, but it\*(Aqs limit is based on the smb2 dialect (64KiB for SMB == 2\&.0, 8MiB for SMB >= 2\&.1 with LargeMTU)\&. Large MTU is not supported over NBT (tcp port 139)\&. +.sp +Default: +\fI\fIsmb2 max read\fR\fR\fI = \fR\fI8388608\fR\fI \fR +.RE + +smb2 max trans (G) +.PP +.RS 4 +This option specifies the protocol value that +\fBsmbd\fR(8) +will return to a client, informing the client of the largest size of buffer that may be used in querying file meta\-data via QUERY_INFO and related SMB2 calls\&. +.sp +The maximum is 8388608 bytes (8MiB), which is the same as a Windows Server 2012 r2\&. +.sp +Please note that the default is 8MiB, but it\*(Aqs limit is based on the smb2 dialect (64KiB for SMB == 2\&.0, 1MiB for SMB >= 2\&.1 with LargeMTU)\&. Large MTU is not supported over NBT (tcp port 139)\&. +.sp +Default: +\fI\fIsmb2 max trans\fR\fR\fI = \fR\fI8388608\fR\fI \fR +.RE + +smb2 max write (G) +.PP +.RS 4 +This option specifies the protocol value that +\fBsmbd\fR(8) +will return to a client, informing the client of the largest size that may be sent to the server by a single SMB2 write call\&. +.sp +The maximum is 8388608 bytes (8MiB), which is the same as a Windows Server 2012 r2\&. +.sp +Please note that the default is 8MiB, but it\*(Aqs limit is based on the smb2 dialect (64KiB for SMB == 2\&.0, 8MiB for SMB => 2\&.1 with LargeMTU)\&. Large MTU is not supported over NBT (tcp port 139)\&. +.sp +Default: +\fI\fIsmb2 max write\fR\fR\fI = \fR\fI8388608\fR\fI \fR +.RE + +smb3 share cap:CONTINUOUS AVAILABILITY (S) +.PP +.RS 4 +The SMB3 protocol introduced the SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY flag\&. It means clients can have different expectations from the server (or cluster of servers)\&. +.sp +Note: this option only applies to disk shares\&. +.sp +In a ctdb cluster shares are continuously available, but windows clients mix this with the global persistent handles support\&. +.sp +Persistent handles are requested if SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY is present even without SMB2_CAP_PERSISTENT_HANDLES\&. +.sp +And SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY is required for SMB2_SHARE_CAP_CLUSTER to have an effect\&. +.sp +So we better don\*(Aqt announce this by default until we support persistent handles\&. +.sp +The +\m[blue]\fBsmb3 share cap:CONTINUOUS AVAILABILITY\fR\m[] +option can be used to force the announcement of SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY\&. +.sp +Warning: only use this if you know what you are doing! +.sp +.if n \{\ +.RS 4 +.\} +.nf + smb3 share cap:CONTINUOUS AVAILABILITY = yes + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +smb3 share cap:SCALE OUT (S) +.PP +.RS 4 +The SMB3 protocol introduced the SMB2_SHARE_CAP_SCALEOUT flag\&. It means clients can have different expectations from cluster of multiple servers and alters the retry/reconnect behavior\&. +.sp +Note: this option only applies to disk shares\&. +.sp +In a ctdb cluster we have multiple active nodes, so we announce SMB2_SHARE_CAP_SCALEOUT in a cluster\&. +.sp +The +\m[blue]\fBsmb3 share cap:SCALE OUT\fR\m[] +option can be used to disable the announcement of SMB2_SHARE_CAP_SCALEOUT, even if +\m[blue]\fBclustering\fR\m[] +is yes\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + clustering = yes + smb3 share cap: SCALE OUT = no + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +smb3 share cap:CLUSTER (S) +.PP +.RS 4 +The SMB3 protocol introduced the SMB2_SHARE_CAP_CLUSTER flag\&. It means clients can expect that all cluster nodes provide a witness service in order to use the [MS\-SWN] protocol to monitor the server cluster\&. +.sp +Note: this option only applies to disk shares\&. +.sp +rpcd_witness is only active if +\fBsamba-dcerpcd\fR(8) +is not started as on demand helper and only in a ctdb cluster\&. +.sp +So we announce SMB2_SHARE_CAP_CLUSTER only if +\m[blue]\fBclustering\fR\m[] +is yes and +\m[blue]\fBrpc start on demand helpers\fR\m[] +is no\&. +.sp +The +\m[blue]\fBsmb3 share cap:SCALE OUT\fR\m[] +option can be used to control the announcement of SMB2_SHARE_CAP_CLUSTER independent of +\m[blue]\fBclustering\fR\m[] +and +\m[blue]\fBrpc start on demand helpers\fR\m[]\&. +.sp +Example to disable the announcement of SMB2_SHARE_CAP_CLUSTER: +.sp +.if n \{\ +.RS 4 +.\} +.nf + clustering = yes + rpc start on demand helpers = no + smb3 share cap: CLUSTER = no + +.fi +.if n \{\ +.RE +.\} +.sp +Example to force the announcement of SMB2_SHARE_CAP_CLUSTER: +.sp +.if n \{\ +.RS 4 +.\} +.nf + smb3 share cap: CLUSTER = yes + +.fi +.if n \{\ +.RE +.\} +.sp +Example to let Windows clients use the witness service, see +\m[blue]\fBsmb3 share cap:CONTINUOUS AVAILABILITY\fR\m[] +option and USE AT YOUR OWN RISK!: +.sp +.if n \{\ +.RS 4 +.\} +.nf + clustering = yes + rpc start on demand helpers = no + # This is the default with the above: + # smb3 share cap: CLUSTER = yes + # + # Use at you own risk! + smb3 share cap: CONTINUOUS AVAILABILITY = yes + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +smb3 share cap:ASYMMETRIC (S) +.PP +.RS 4 +The SMB3_02 protocol introduced the SMB2_SHARE_CAP_ASYMMETRIC flag\&. It means clients alters its behavior and uses isolated transport connections and witness registrations for the share\&. It means a client may connect to different cluster nodes for individual shares and +net witness share\-move +can be used to control the node usage\&. +.sp +Note: this option only applies to disk shares\&. +.sp +Shares in a ctdb cluster are symmetric by design, so we don\*(Aqt announce SMB2_SHARE_CAP_ASYMMETRIC by default\&. +.sp +The +\m[blue]\fBsmb3 share cap:ASYMMETRIC\fR\m[] +option can be used to force the announcement of SMB2_SHARE_CAP_ASYMMETRIC\&. +.sp +Example to force the announcement of SMB2_SHARE_CAP_ASYMMETRIC: +.sp +.if n \{\ +.RS 4 +.\} +.nf + smb3 share cap: ASYMMETRIC = yes + +.fi +.if n \{\ +.RE +.\} +.sp +Example to let Windows clients use the witness service, see +\m[blue]\fBsmb3 share cap:CONTINUOUS AVAILABILITY\fR\m[] +option and USE AT YOUR OWN RISK!: +.sp +.if n \{\ +.RS 4 +.\} +.nf + clustering = yes + rpc start on demand helpers = no + # This is the default with the above: + # smb3 share cap: CLUSTER = yes + # + # Use at you own risk! + smb3 share cap: CONTINUOUS AVAILABILITY = yes + smb3 share cap: ASYMMETRIC = yes + +.fi +.if n \{\ +.RE +.\} +.sp +\fINo default\fR +.RE + +smb3 unix extensions (S) +.PP +.RS 4 +Experimental SMB 3\&.1\&.1 Unix Extensions\&. +.sp +Default: +\fI\fIsmb3 unix extensions\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +smbd async dosmode (S) +.PP +.RS 4 +This parameter control whether the fileserver will use sync or async methods for fetching the DOS attributes when doing a directory listing\&. By default sync methods will be used\&. +.sp +Default: +\fI\fIsmbd async dosmode\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +smbd getinfo ask sharemode (S) +.PP +.RS 4 +This parameter allows disabling fetching file write time from the open file handle database locking\&.tdb when a client requests file or directory metadata\&. It\*(Aqs a performance optimisation at the expense of protocol correctness\&. +.sp +Default: +\fI\fIsmbd getinfo ask sharemode\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smbd max async dosmode (S) +.PP +.RS 4 +This parameter controls how many async operations to fetch the DOS attributes the fileserver will queue when doing directory listings\&. +.sp +Default: +\fI\fIsmbd max async dosmode\fR\fR\fI = \fR\fIaio max threads * 2\fR\fI \fR +.RE + +smbd max xattr size (S) +.PP +.RS 4 +This parameter controls the maximum size of extended attributes that may be written to the server as EAs or as alternate data streams if vfs_streams_xattr is enabled\&. The maximum size of extended attributes depends on the Samba server\*(Aqs operating system and the underlying filesystem\&. The Linux VFS currently sets an upper boundary of 64 KiB per extended attribute\&. FreeBSD does not set a practical upper limit, but since pread() and pwrite() are not possible via the extattr on FreeBSD, it is not recommended to increase this value above a few MiB\&. If a client attempts to write an overly\-large alternate datastream, the Samba server will return STATUS_FILESYSTEM_LIMITATION\&. If this error is encountered, users may try increasing the maximum size supported for xattr writes\&. If this is not possible, and writes are from a MacOS client and to an AFP_Resource extended attribute, the user may enable the vfs_fruit module and configure to allow stream writes for AFP_Resource to an alternative storage location\&. See vfs_fruit documentation for further details\&. +.sp +Default: +\fI\fIsmbd max xattr size\fR\fR\fI = \fR\fI65536\fR\fI \fR +.RE + +smbd profiling level (G) +.PP +.RS 4 +This parameter allows the administrator to enable profiling support\&. +.sp +Possible values are +\fBoff\fR, +\fBcount\fR +and +\fBon\fR\&. +.sp +Default: +\fI\fIsmbd profiling level\fR\fR\fI = \fR\fIoff\fR\fI \fR +.sp +Example: +\fI\fIsmbd profiling level\fR\fR\fI = \fR\fIon\fR\fI \fR +.RE + +smbd search ask sharemode (S) +.PP +.RS 4 +This parameter allows disabling fetching file write time from the open file handle database locking\&.tdb\&. It\*(Aqs a performance optimisation at the expense of protocol correctness\&. +.sp +Default: +\fI\fIsmbd search ask sharemode\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +smb encrypt (S) +.PP +.RS 4 +This is a synonym for +\m[blue]\fBserver smb encrypt\fR\m[]\&. +.sp +Default: +\fI\fIsmb encrypt\fR\fR\fI = \fR\fIdefault\fR\fI \fR +.RE + +smb passwd file (G) +.PP +.RS 4 +This option sets the path to the encrypted smbpasswd file\&. By default the path to the smbpasswd file is compiled into Samba\&. +.sp +An example of use is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +smb passwd file = /etc/samba/smbpasswd +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIsmb passwd file\fR\fR\fI = \fR\fI/var/lib/samba/private/smbpasswd\fR\fI \fR +.RE + +smb ports (G) +.PP +.RS 4 +Specifies which ports the server should listen on for SMB traffic\&. +.sp +Default: +\fI\fIsmb ports\fR\fR\fI = \fR\fI445 139\fR\fI \fR +.RE + +socket options (G) +.PP +.RS 4 +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Modern server operating systems are tuned for high network performance in the majority of situations; when you set socket options you are overriding those settings\&. Linux in particular has an auto\-tuning mechanism for buffer sizes that will be disabled if you specify a socket buffer size\&. This can potentially cripple your TCP/IP stack\&. +.sp +Getting the socket options correct can make a big difference to your performance, but getting them wrong can degrade it by just as much\&. As with any other low level setting, if you must make changes to it, make small changes and +\fItest\fR +the effect before making any large changes\&. +.sp .5v +.RE +.sp +This option allows you to set socket options to be used when talking with the client\&. +.sp +Socket options are controls on the networking layer of the operating systems which allow the connection to be tuned\&. +.sp +This option will typically be used to tune your Samba server for optimal performance for your local network\&. There is no way that Samba can know what the optimal parameters are for your net, so you must experiment and choose them yourself\&. We strongly suggest you read the appropriate documentation for your operating system first (perhaps +man setsockopt +will help)\&. +.sp +You may find that on some systems Samba will say "Unknown socket option" when you supply an option\&. This means you either incorrectly typed it or you need to add an include file to includes\&.h for your OS\&. If the latter is the case please send the patch to +samba\-technical@lists\&.samba\&.org\&. +.sp +Any of the supported socket options may be combined in any way you like, as long as your OS allows it\&. +.sp +This is the list of socket options currently settable using this option: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_KEEPALIVE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_REUSEADDR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_BROADCAST +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_NODELAY +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_KEEPCNT * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_KEEPIDLE * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_KEEPINTVL * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +IPTOS_LOWDELAY +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +IPTOS_THROUGHPUT +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_REUSEPORT +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_SNDBUF * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_RCVBUF * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_SNDLOWAT * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_RCVLOWAT * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_SNDTIMEO * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SO_RCVTIMEO * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_FASTACK * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_QUICKACK +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_NODELAYACK +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_KEEPALIVE_THRESHOLD * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_KEEPALIVE_ABORT_THRESHOLD * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_DEFER_ACCEPT * +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TCP_USER_TIMEOUT * +.RE +.sp +.RE +Those marked with a +\fI\*(Aq*\*(Aq\fR +take an integer argument\&. The others can optionally take a 1 or 0 argument to enable or disable the option, by default they will be enabled if you don\*(Aqt specify 1 or 0\&. +.sp +To specify an argument use the syntax SOME_OPTION = VALUE for example +SO_SNDBUF = 8192\&. Note that you must not have any spaces before or after the = sign\&. +.sp +If you are on a local network then a sensible option might be: +.sp +socket options = IPTOS_LOWDELAY +.sp +If you have a local network then you could try: +.sp +socket options = IPTOS_LOWDELAY TCP_NODELAY +.sp +If you are on a wide area network then perhaps try setting IPTOS_THROUGHPUT\&. +.sp +Note that several of the options may cause your Samba server to fail completely\&. Use these options with caution! +.sp +Default: +\fI\fIsocket options\fR\fR\fI = \fR\fITCP_NODELAY\fR\fI \fR +.sp +Example: +\fI\fIsocket options\fR\fR\fI = \fR\fIIPTOS_LOWDELAY\fR\fI \fR +.RE + +spn update command (G) +.PP +.RS 4 +This option sets the command that for updating servicePrincipalName names from +spn_update_list\&. +.sp +Default: +\fI\fIspn update command\fR\fR\fI = \fR\fI/builddir/build/BUILD/samba\-4\&.20\&.0rc3/source4/scripting/bin/samba_spnupdate\fR\fI \fR +.sp +Example: +\fI\fIspn update command\fR\fR\fI = \fR\fI/usr/local/sbin/spnupdate\fR\fI \fR +.RE + +spoolss: architecture (G) +.PP +.RS 4 +Windows spoolss print clients only allow association of server\-side drivers with printers when the driver architecture matches the advertised print server architecture\&. Samba\*(Aqs spoolss print server architecture can be changed using this parameter\&. +.sp +Default: +\fI\fIspoolss: architecture\fR\fR\fI = \fR\fIWindows x64\fR\fI \fR +.sp +Example: +\fI\fIspoolss: architecture\fR\fR\fI = \fR\fIWindows NT x86\fR\fI \fR +.RE + +spoolss: os_major (G) +.PP +.RS 4 +Windows might require a new os version number\&. This option allows to modify the build number\&. The complete default version number is: 5\&.0\&.2195 (Windows 2000)\&. The example is 6\&.1\&.7601 (Windows 2008 R2)\&. +.sp +Default: +\fI\fIspoolss: os_major\fR\fR\fI = \fR\fI5\fR\fI \fR +.sp +Example: +\fI\fIspoolss: os_major\fR\fR\fI = \fR\fI6\fR\fI \fR +.RE + +spoolss: os_minor (G) +.PP +.RS 4 +Windows might require a new os version number\&. This option allows to modify the build number\&. The complete default version number is: 5\&.0\&.2195 (Windows 2000)\&. The example is 6\&.1\&.7601 (Windows 2008 R2)\&. +.sp +Default: +\fI\fIspoolss: os_minor\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fIspoolss: os_minor\fR\fR\fI = \fR\fI1\fR\fI \fR +.RE + +spoolss: os_build (G) +.PP +.RS 4 +Windows might require a new os version number\&. This option allows to modify the build number\&. The complete default version number is: 5\&.0\&.2195 (Windows 2000)\&. The example is 6\&.1\&.7601 (Windows 2008 R2)\&. +.sp +Default: +\fI\fIspoolss: os_build\fR\fR\fI = \fR\fI2195\fR\fI \fR +.sp +Example: +\fI\fIspoolss: os_build\fR\fR\fI = \fR\fI7601\fR\fI \fR +.RE + +spoolss_client: os_major (G) +.PP +.RS 4 +Windows might require a new os version number\&. This option allows to modify the build number\&. The complete default version number is: 6\&.1\&.7007 (Windows 7 and Windows Server 2008 R2)\&. +.sp +Default: +\fI\fIspoolss_client: os_major\fR\fR\fI = \fR\fI6\fR\fI \fR +.RE + +spoolss_client: os_minor (G) +.PP +.RS 4 +Windows might require a new os version number\&. This option allows to modify the build number\&. The complete default version number is: 6\&.1\&.7007 (Windows 7 and Windows Server 2008 R2)\&. +.sp +Default: +\fI\fIspoolss_client: os_minor\fR\fR\fI = \fR\fI1\fR\fI \fR +.RE + +spoolss_client: os_build (G) +.PP +.RS 4 +Windows might require a new os version number\&. This option allows to modify the build number\&. The complete default version number is: 6\&.1\&.7007 (Windows 7 and Windows Server 2008 R2)\&. +.sp +Default: +\fI\fIspoolss_client: os_build\fR\fR\fI = \fR\fI7007\fR\fI \fR +.RE + +spotlight (S) +.PP +.RS 4 +This parameter controls whether Samba allows Spotlight queries on a share\&. For controlling indexing of filesystems you also have to use Tracker\*(Aqs own configuration system\&. +.sp +Spotlight has several prerequisites: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Samba must be configured and built with Spotlight support\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Tracker integration must be setup and the share must be indexed by Tracker\&. +.RE +.sp +.RE +For a detailed set of instructions please see +https://wiki\&.samba\&.org/index\&.php/Spotlight\&. +.sp +Default: +\fI\fIspotlight\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +spotlight backend (S) +.PP +.RS 4 +Spotlight search backend\&. Available backends: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBnoindex\fR +\- a backend that returns no results\&. +.RE +.sp +.RE +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBtracker\fR +\- Gnome Tracker\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBelasticsearch\fR +\- a backend that uses JSON and REST over HTTP(s) to query an Elasticsearch server\&. +.RE +.sp +.RE +.sp +Default: +\fI\fIspotlight backend\fR\fR\fI = \fR\fInoindex\fR\fI \fR +.RE + +stat cache (G) +.PP +.RS 4 +This parameter determines if +\fBsmbd\fR(8) +will use a cache in order to speed up case insensitive name mappings\&. You should never need to change this parameter\&. +.sp +Default: +\fI\fIstat cache\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +state directory (G) +.PP +.RS 4 +Usually, most of the TDB files are stored in the +\fIlock directory\fR\&. Since Samba 3\&.4\&.0, it is possible to differentiate between TDB files with persistent data and TDB files with non\-persistent data using the +\fIstate directory\fR +and the +\fIcache directory\fR +options\&. +.sp +This option specifies the directory where TDB files containing important persistent data will be stored\&. +.sp +Default: +\fI\fIstate directory\fR\fR\fI = \fR\fI/var/lib/samba\fR\fI \fR +.sp +Example: +\fI\fIstate directory\fR\fR\fI = \fR\fI/var/run/samba/locks/state\fR\fI \fR +.RE + +store dos attributes (S) +.PP +.RS 4 +If this parameter is set Samba attempts to first read DOS attributes (SYSTEM, HIDDEN, ARCHIVE or READ\-ONLY) from a filesystem extended attribute, before mapping DOS attributes to UNIX permission bits (such as occurs with +\m[blue]\fBmap hidden\fR\m[] +and +\m[blue]\fBmap readonly\fR\m[])\&. When set, DOS attributes will be stored onto an extended attribute in the UNIX filesystem, associated with the file or directory\&. When this parameter is set it will override the parameters +\m[blue]\fBmap hidden\fR\m[], +\m[blue]\fBmap system\fR\m[], +\m[blue]\fBmap archive\fR\m[] +and +\m[blue]\fBmap readonly\fR\m[] +and they will behave as if they were set to off\&. This parameter writes the DOS attributes as a string into the extended attribute named "user\&.DOSATTRIB"\&. This extended attribute is explicitly hidden from smbd clients requesting an EA list\&. On Linux the filesystem must have been mounted with the mount option user_xattr in order for extended attributes to work, also extended attributes must be compiled into the Linux kernel\&. In Samba 3\&.5\&.0 and above the "user\&.DOSATTRIB" extended attribute has been extended to store the create time for a file as well as the DOS attributes\&. This is done in a backwards compatible way so files created by Samba 3\&.5\&.0 and above can still have the DOS attribute read from this extended attribute by earlier versions of Samba, but they will not be able to read the create time stored there\&. Storing the create time separately from the normal filesystem meta\-data allows Samba to faithfully reproduce NTFS semantics on top of a POSIX filesystem\&. The default has changed to yes in Samba release 4\&.9\&.0 and above to allow better Windows fileserver compatibility in a default install\&. +.sp +Default: +\fI\fIstore dos attributes\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +strict allocate (S) +.PP +.RS 4 +This is a boolean that controls the handling of disk space allocation in the server\&. When this is set to +\fByes\fR +the server will change from UNIX behaviour of not committing real disk storage blocks when a file is extended to the Windows behaviour of actually forcing the disk system to allocate real storage blocks when a file is created or extended to be a given size\&. In UNIX terminology this means that Samba will stop creating sparse files\&. +.sp +This option is really designed for file systems that support fast allocation of large numbers of blocks such as extent\-based file systems\&. On file systems that don\*(Aqt support extents (most notably ext3) this can make Samba slower\&. When you work with large files over >100MB on file systems without extents you may even run into problems with clients running into timeouts\&. +.sp +When you have an extent based filesystem it\*(Aqs likely that we can make use of unwritten extents which allows Samba to allocate even large amounts of space very fast and you will not see any timeout problems caused by strict allocate\&. With strict allocate in use you will also get much better out of quota messages in case you use quotas\&. Another advantage of activating this setting is that it will help to reduce file fragmentation\&. +.sp +To give you an idea on which filesystems this setting might currently be a good option for you: XFS, ext4, btrfs, ocfs2 on Linux and JFS2 on AIX support unwritten extents\&. On Filesystems that do not support it, preallocation is probably an expensive operation where you will see reduced performance and risk to let clients run into timeouts when creating large files\&. Examples are ext3, ZFS, HFS+ and most others, so be aware if you activate this setting on those filesystems\&. +.sp +Default: +\fI\fIstrict allocate\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +strict locking (S) +.PP +.RS 4 +This is an enumerated type that controls the handling of file locking in the server\&. When this is set to +\fByes\fR, the server will check every read and write access for file locks, and deny access if locks exist\&. This can be slow on some systems\&. +.sp +When strict locking is set to Auto (the default), the server performs file lock checks only on non\-oplocked files\&. As most Windows redirectors perform file locking checks locally on oplocked files this is a good trade off for improved performance\&. +.sp +When strict locking is disabled, the server performs file lock checks only when the client explicitly asks for them\&. +.sp +Well\-behaved clients always ask for lock checks when it is important\&. So in the vast majority of cases, +strict locking = Auto +or +strict locking = no +is acceptable\&. +.sp +Default: +\fI\fIstrict locking\fR\fR\fI = \fR\fIAuto\fR\fI \fR +.RE + +strict rename (S) +.PP +.RS 4 +By default a Windows SMB server prevents directory renames when there are open file or directory handles below it in the filesystem hierarchy\&. Historically Samba has always allowed this as POSIX filesystem semantics require it\&. +.sp +This boolean parameter allows Samba to match the Windows behavior\&. Setting this to "yes" is a very expensive change, as it forces Samba to travers the entire open file handle database on every directory rename request\&. In a clustered Samba system the cost is even greater than the non\-clustered case\&. +.sp +When set to "no" smbd only checks the local process the client is attached to for open files below a directory being renamed, instead of checking for open files across all smbd processes\&. +.sp +Because of the expense in fully searching the database, the default is "no", and it is recommended to be left that way unless a specific Windows application requires it to be changed\&. +.sp +If the client has requested UNIX extensions (POSIX pathnames) then renames are always allowed and this parameter has no effect\&. +.sp +Default: +\fI\fIstrict rename\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +strict sync (S) +.PP +.RS 4 +This parameter controls whether Samba honors a request from an SMB client to ensure any outstanding operating system buffer contents held in memory are safely written onto stable storage on disk\&. If set to +\fByes\fR, which is the default, then Windows applications can force the smbd server to synchronize unwritten data onto the disk\&. If set to +\fBno\fR +then smbd will ignore client requests to synchronize unwritten data onto stable storage on disk\&. +.sp +In Samba 4\&.7\&.0, the default for this parameter changed from +\fBno\fR +to +\fByes\fR +to better match the expectations of SMB2/3 clients and improve application safety when running against smbd\&. +.sp +The flush request from SMB2/3 clients is handled asynchronously inside smbd, so leaving the parameter as the default value of +\fByes\fR +does not block the processing of other requests to the smbd process\&. +.sp +Legacy Windows applications (such as the Windows 98 explorer shell) seemed to confuse writing buffer contents to the operating system with synchronously writing outstanding data onto stable storage on disk\&. Changing this parameter to +\fBno\fR +means that +\fBsmbd\fR(8) +will ignore the Windows applications request to synchronize unwritten data onto disk\&. Only consider changing this if smbd is serving obsolete SMB1 Windows clients prior to Windows XP (Windows 98 and below)\&. There should be no need to change this setting for normal operations\&. +.sp +Default: +\fI\fIstrict sync\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +svcctl list (G) +.PP +.RS 4 +This option defines a list of init scripts that smbd will use for starting and stopping Unix services via the Win32 ServiceControl API\&. This allows Windows administrators to utilize the MS Management Console plug\-ins to manage a Unix server running Samba\&. +.sp +The administrator must create a directory name +svcctl +in Samba\*(Aqs $(libdir) and create symbolic links to the init scripts in +/etc/init\&.d/\&. The name of the links must match the names given as part of the +\fIsvcctl list\fR\&. +.sp +Default: +\fI\fIsvcctl list\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIsvcctl list\fR\fR\fI = \fR\fIcups postfix portmap httpd\fR\fI \fR +.RE + +sync always (S) +.PP +.RS 4 +This is a boolean parameter that controls whether writes will always be written to stable storage before the write call returns\&. If this is +\fBno\fR +then the server will be guided by the client\*(Aqs request in each write call (clients can set a bit indicating that a particular write should be synchronous)\&. If this is +\fByes\fR +then every write will be followed by a +fsync() +call to ensure the data is written to disk\&. Note that the +\fIstrict sync\fR +parameter must be set to +\fByes\fR +in order for this parameter to have any effect\&. +.sp +Default: +\fI\fIsync always\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +syslog (G) +.PP +.RS 4 +This parameter maps how Samba debug messages are logged onto the system syslog logging levels\&. Samba debug level zero maps onto syslog +\fBLOG_ERR\fR, debug level one maps onto +\fBLOG_WARNING\fR, debug level two maps onto +\fBLOG_NOTICE\fR, debug level three maps onto LOG_INFO\&. All higher levels are mapped to +\fBLOG_DEBUG\fR\&. +.sp +This parameter sets the threshold for sending messages to syslog\&. Only messages with debug level less than this value will be sent to syslog\&. There still will be some logging to log\&.[sn]mbd even if +\fIsyslog only\fR +is enabled\&. +.sp +The +\m[blue]\fBlogging\fR\m[] +parameter should be used instead\&. When +\m[blue]\fBlogging\fR\m[] +is set, it overrides the +\m[blue]\fBsyslog\fR\m[] +parameter\&. +.sp +Default: +\fI\fIsyslog\fR\fR\fI = \fR\fI1\fR\fI \fR +.RE + +syslog only (G) +.PP +.RS 4 +If this parameter is set then Samba debug messages are logged into the system syslog only, and not to the debug log files\&. There still will be some logging to log\&.[sn]mbd even if +\fIsyslog only\fR +is enabled\&. +.sp +The +\m[blue]\fBlogging\fR\m[] +parameter should be used instead\&. When +\m[blue]\fBlogging\fR\m[] +is set, it overrides the +\m[blue]\fBsyslog only\fR\m[] +parameter\&. +.sp +Default: +\fI\fIsyslog only\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +template homedir (G) +.PP +.RS 4 +When filling out the user information for a Windows NT user, the +\fBwinbindd\fR(8) +daemon uses this parameter to fill in the home directory for that user\&. If the string +\fI%D\fR +is present it is substituted with the user\*(Aqs Windows NT domain name\&. If the string +\fI%U\fR +is present it is substituted with the user\*(Aqs Windows NT user name\&. +.sp +Default: +\fI\fItemplate homedir\fR\fR\fI = \fR\fI/home/%D/%U\fR\fI \fR +.RE + +template shell (G) +.PP +.RS 4 +When filling out the user information for a Windows NT user, the +\fBwinbindd\fR(8) +daemon uses this parameter to fill in the login shell for that user\&. +.sp +Default: +\fI\fItemplate shell\fR\fR\fI = \fR\fI/bin/false\fR\fI \fR +.RE + +time server (G) +.PP +.RS 4 +This parameter determines if +\fBnmbd\fR(8) +advertises itself as a time server to Windows clients\&. +.sp +Default: +\fI\fItime server\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +debug timestamp +.PP +.RS 4 +This parameter is a synonym for +timestamp logs\&. +.RE + +timestamp logs (G) +.PP +.RS 4 +Samba debug log messages are timestamped by default\&. If you are running at a high +\m[blue]\fBdebug level\fR\m[] +these timestamps can be distracting\&. This boolean parameter allows timestamping to be turned off\&. +.sp +Default: +\fI\fItimestamp logs\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +tls cafile (G) +.PP +.RS 4 +This option can be set to a file (PEM format) containing CA certificates of root CAs to trust to sign certificates or intermediate CA certificates\&. +.sp +This path is relative to +\m[blue]\fBprivate dir\fR\m[] +if the path does not start with a /\&. +.sp +Default: +\fI\fItls cafile\fR\fR\fI = \fR\fItls/ca\&.pem\fR\fI \fR +.RE + +tls certfile (G) +.PP +.RS 4 +This option can be set to a file (PEM format) containing the RSA certificate\&. +.sp +This path is relative to +\m[blue]\fBprivate dir\fR\m[] +if the path does not start with a /\&. +.sp +Default: +\fI\fItls certfile\fR\fR\fI = \fR\fItls/cert\&.pem\fR\fI \fR +.RE + +tls crlfile (G) +.PP +.RS 4 +This option can be set to a file containing a certificate revocation list (CRL)\&. +.sp +This path is relative to +\m[blue]\fBprivate dir\fR\m[] +if the path does not start with a /\&. +.sp +Default: +\fI\fItls crlfile\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +tls dh params file (G) +.PP +.RS 4 +This option can be set to a file with Diffie\-Hellman parameters which will be used with DH ciphers\&. +.sp +This path is relative to +\m[blue]\fBprivate dir\fR\m[] +if the path does not start with a /\&. +.sp +Default: +\fI\fItls dh params file\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +tls enabled (G) +.PP +.RS 4 +If this option is set to +\fByes\fR, then Samba will use TLS when possible in communication\&. +.sp +Default: +\fI\fItls enabled\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +tls keyfile (G) +.PP +.RS 4 +This option can be set to a file (PEM format) containing the RSA private key\&. This file must be accessible without a pass\-phrase, i\&.e\&. it must not be encrypted\&. +.sp +This path is relative to +\m[blue]\fBprivate dir\fR\m[] +if the path does not start with a /\&. +.sp +Default: +\fI\fItls keyfile\fR\fR\fI = \fR\fItls/key\&.pem\fR\fI \fR +.RE + +tls priority (G) +.PP +.RS 4 +This option can be set to a string describing the TLS protocols to be supported in the parts of Samba that use GnuTLS, specifically the AD DC\&. +.sp +The string is appended to the default priority list of GnuTLS\&. +.sp +The valid options are described in the +GNUTLS Priority\-Strings documentation at http://gnutls\&.org/manual/html_node/Priority\-Strings\&.html +.sp +The SSL3\&.0 protocol will be disabled\&. +.sp +Default: +\fI\fItls priority\fR\fR\fI = \fR\fINORMAL:\-VERS\-SSL3\&.0\fR\fI \fR +.RE + +tls verify peer (G) +.PP +.RS 4 +This controls if and how strict the client will verify the peer\*(Aqs certificate and name\&. Possible values are (in increasing order): +\fBno_check\fR, +\fBca_only\fR, +\fBca_and_name_if_available\fR, +\fBca_and_name\fR +and +\fBas_strict_as_possible\fR\&. +.sp +When set to +\fBno_check\fR +the certificate is not verified at all, which allows trivial man in the middle attacks\&. +.sp +When set to +\fBca_only\fR +the certificate is verified to be signed from a ca specified in the +\m[blue]\fBtls ca file\fR\m[] +option\&. Setting +\m[blue]\fBtls ca file\fR\m[] +to a valid file is required\&. The certificate lifetime is also verified\&. If the +\m[blue]\fBtls crl file\fR\m[] +option is configured, the certificate is also verified against the ca crl\&. +.sp +When set to +\fBca_and_name_if_available\fR +all checks from +\fBca_only\fR +are performed\&. In addition, the peer hostname is verified against the certificate\*(Aqs name, if it is provided by the application layer and not given as an ip address string\&. +.sp +When set to +\fBca_and_name\fR +all checks from +\fBca_and_name_if_available\fR +are performed\&. In addition the peer hostname needs to be provided and even an ip address is checked against the certificate\*(Aqs name\&. +.sp +When set to +\fBas_strict_as_possible\fR +all checks from +\fBca_and_name\fR +are performed\&. In addition the +\m[blue]\fBtls crl file\fR\m[] +needs to be configured\&. Future versions of Samba may implement additional checks\&. +.sp +Default: +\fI\fItls verify peer\fR\fR\fI = \fR\fIas_strict_as_possible\fR\fI \fR +.RE + +unicode (G) +.PP +.RS 4 +Specifies whether the server and client should support unicode\&. +.sp +If this option is set to false, the use of ASCII will be forced\&. +.sp +Default: +\fI\fIunicode\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +unix charset (G) +.PP +.RS 4 +Specifies the charset the unix machine Samba runs on uses\&. Samba needs to know this in order to be able to convert text to the charsets other SMB clients use\&. +.sp +This is also the charset Samba will use when specifying arguments to scripts that it invokes\&. +.sp +Default: +\fI\fIunix charset\fR\fR\fI = \fR\fIUTF\-8\fR\fI \fR +.sp +Example: +\fI\fIunix charset\fR\fR\fI = \fR\fIASCII\fR\fI \fR +.RE + +unix password sync (G) +.PP +.RS 4 +This boolean parameter controls whether Samba attempts to synchronize the UNIX password with the SMB password when the encrypted SMB password in the smbpasswd file is changed\&. If this is set to +\fByes\fR +the program specified in the +\fIpasswd program\fR +parameter is called +\fIAS ROOT\fR +\- to allow the new UNIX password to be set without access to the old UNIX password (as the SMB password change code has no access to the old password cleartext, only the new)\&. +.sp +This option has no effect if +samba +is running as an active directory domain controller, in that case have a look at the +\m[blue]\fBpassword hash gpg key ids\fR\m[] +option and the +samba\-tool user syncpasswords +command\&. +.sp +Default: +\fI\fIunix password sync\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +use client driver (S) +.PP +.RS 4 +This parameter applies only to Windows NT/2000 clients\&. It has no effect on Windows 95/98/ME clients\&. When serving a printer to Windows NT/2000 clients without first installing a valid printer driver on the Samba host, the client will be required to install a local printer driver\&. From this point on, the client will treat the print as a local printer and not a network printer connection\&. This is much the same behavior that will occur when +disable spoolss = yes\&. +.sp +The differentiating factor is that under normal circumstances, the NT/2000 client will attempt to open the network printer using MS\-RPC\&. The problem is that because the client considers the printer to be local, it will attempt to issue the OpenPrinterEx() call requesting access rights associated with the logged on user\&. If the user possesses local administrator rights but not root privilege on the Samba host (often the case), the OpenPrinterEx() call will fail\&. The result is that the client will now display an "Access Denied; Unable to connect" message in the printer queue window (even though jobs may successfully be printed)\&. +.sp +If this parameter is enabled for a printer, then any attempt to open the printer with the PRINTER_ACCESS_ADMINISTER right is mapped to PRINTER_ACCESS_USE instead\&. Thus allowing the OpenPrinterEx() call to succeed\&. +\fIThis parameter MUST not be enabled on a print share which has valid print driver installed on the Samba server\&.\fR +.sp +Default: +\fI\fIuse client driver\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +use mmap (G) +.PP +.RS 4 +This global parameter determines if the tdb internals of Samba can depend on mmap working correctly on the running system\&. Samba requires a coherent mmap/read\-write system memory cache\&. Currently only OpenBSD and HPUX do not have such a coherent cache, and on those platforms this parameter is overridden internally to be effectively +\fBno\fR\&. On all systems this parameter should be left alone\&. This parameter is provided to help the Samba developers track down problems with the tdb internal code\&. +.sp +Default: +\fI\fIuse mmap\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +username level (G) +.PP +.RS 4 +This option helps Samba to try and \*(Aqguess\*(Aq at the real UNIX username, as many DOS clients send an all\-uppercase username\&. By default Samba tries all lowercase, followed by the username with the first letter capitalized, and fails if the username is not found on the UNIX machine\&. +.sp +If this parameter is set to non\-zero the behavior changes\&. This parameter is a number that specifies the number of uppercase combinations to try while trying to determine the UNIX user name\&. The higher the number the more combinations will be tried, but the slower the discovery of usernames will be\&. Use this parameter when you have strange usernames on your UNIX machine, such as +\fBAstrangeUser \fR\&. +.sp +This parameter is needed only on UNIX systems that have case sensitive usernames\&. +.sp +Default: +\fI\fIusername level\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fIusername level\fR\fR\fI = \fR\fI5\fR\fI \fR +.RE + +username map (G) +.PP +.RS 4 +This option allows you to specify a file containing a mapping of usernames from the clients to the server\&. This can be used for several purposes\&. The most common is to map usernames that users use on DOS or Windows machines to those that the UNIX box uses\&. The other is to map multiple users to a single username so that they can more easily share files\&. +.sp +Please note that for user mode security, the username map is applied prior to validating the user credentials\&. Domain member servers (domain or ads) apply the username map after the user has been successfully authenticated by the domain controller and require fully qualified entries in the map table (e\&.g\&. biddle = +DOMAIN\efoo)\&. +.sp +The map file is parsed line by line\&. Each line should contain a single UNIX username on the left then a \*(Aq=\*(Aq followed by a list of usernames on the right\&. The list of usernames on the right may contain names of the form @group in which case they will match any UNIX username in that group\&. The special client name \*(Aq*\*(Aq is a wildcard and matches any name\&. Each line of the map file may be up to 1023 characters long\&. +.sp +The file is processed on each line by taking the supplied username and comparing it with each username on the right hand side of the \*(Aq=\*(Aq signs\&. If the supplied name matches any of the names on the right hand side then it is replaced with the name on the left\&. Processing then continues with the next line\&. +.sp +If any line begins with a \*(Aq#\*(Aq or a \*(Aq;\*(Aq then it is ignored\&. +.sp +If any line begins with an \*(Aq!\*(Aq then the processing will stop after that line if a mapping was done by the line\&. Otherwise mapping continues with every line being processed\&. Using \*(Aq!\*(Aq is most useful when you have a wildcard mapping line later in the file\&. +.sp +For example to map from the name +\fBadmin\fR +or +\fBadministrator\fR +to the UNIX name +\fB root\fR +you would use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +root = admin administrator +.fi +.if n \{\ +.RE +.\} +.sp +Or to map anyone in the UNIX group +\fBsystem\fR +to the UNIX name +\fBsys\fR +you would use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +sys = @system +.fi +.if n \{\ +.RE +.\} +.sp +You can have as many mappings as you like in a username map file\&. +.sp +If your system supports the NIS NETGROUP option then the netgroup database is checked before the +/etc/group +database for matching groups\&. +.sp +You can map Windows usernames that have spaces in them by using double quotes around the name\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +tridge = "Andrew Tridgell" +.fi +.if n \{\ +.RE +.\} +.sp +would map the windows username "Andrew Tridgell" to the unix username "tridge"\&. +.sp +The following example would map mary and fred to the unix user sys, and map the rest to guest\&. Note the use of the \*(Aq!\*(Aq to tell Samba to stop processing if it gets a match on that line: +.sp +.if n \{\ +.RS 4 +.\} +.nf +!sys = mary fred +guest = * +.fi +.if n \{\ +.RE +.\} +.sp +Note that the remapping is applied to all occurrences of usernames\&. Thus if you connect to \e\eserver\efred and +\fBfred\fR +is remapped to +\fBmary\fR +then you will actually be connecting to \e\eserver\emary and will need to supply a password suitable for +\fBmary\fR +not +\fBfred\fR\&. The only exception to this is the username passed to a Domain Controller (if you have one)\&. The DC will receive whatever username the client supplies without modification\&. +.sp +Also note that no reverse mapping is done\&. The main effect this has is with printing\&. Users who have been mapped may have trouble deleting print jobs as PrintManager under WfWg will think they don\*(Aqt own the print job\&. +.sp +Samba versions prior to 3\&.0\&.8 would only support reading the fully qualified username (e\&.g\&.: +DOMAIN\euser) from the username map when performing a kerberos login from a client\&. However, when looking up a map entry for a user authenticated by NTLM[SSP], only the login name would be used for matches\&. This resulted in inconsistent behavior sometimes even on the same server\&. +.sp +The following functionality is obeyed in version 3\&.0\&.8 and later: +.sp +When performing local authentication, the username map is applied to the login name before attempting to authenticate the connection\&. +.sp +When relying upon a external domain controller for validating authentication requests, smbd will apply the username map to the fully qualified username (i\&.e\&. +DOMAIN\euser) only after the user has been successfully authenticated\&. +.sp +An example of use is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +username map = /usr/local/samba/lib/users\&.map +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIusername map\fR\fR\fI = \fR\fI # no username map\fR\fI \fR +.RE + +username map cache time (G) +.PP +.RS 4 +Mapping usernames with the +\m[blue]\fBusername map\fR\m[] +or +\m[blue]\fBusername map script\fR\m[] +features of Samba can be relatively expensive\&. During login of a user, the mapping is done several times\&. In particular, calling the +\m[blue]\fBusername map script\fR\m[] +can slow down logins if external databases have to be queried from the script being called\&. +.sp +The parameter +\m[blue]\fBusername map cache time\fR\m[] +controls a mapping cache\&. It specifies the number of seconds a mapping from the username map file or script is to be efficiently cached\&. The default of 0 means no caching is done\&. +.sp +Default: +\fI\fIusername map cache time\fR\fR\fI = \fR\fI0\fR\fI \fR +.sp +Example: +\fI\fIusername map cache time\fR\fR\fI = \fR\fI60\fR\fI \fR +.RE + +username map script (G) +.PP +.RS 4 +This script is a mutually exclusive alternative to the +\m[blue]\fBusername map\fR\m[] +parameter\&. This parameter specifies an external program or script that must accept a single command line option (the username transmitted in the authentication request) and return a line on standard output (the name to which the account should mapped)\&. In this way, it is possible to store username map tables in an LDAP directory services\&. +.sp +Default: +\fI\fIusername map script\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIusername map script\fR\fR\fI = \fR\fI/etc/samba/scripts/mapusers\&.sh\fR\fI \fR +.RE + +usershare allow guests (G) +.PP +.RS 4 +This parameter controls whether user defined shares are allowed to be accessed by non\-authenticated users or not\&. It is the equivalent of allowing people who can create a share the option of setting +\fIguest ok = yes\fR +in a share definition\&. Due to its security sensitive nature, the default is set to off\&. +.sp +Default: +\fI\fIusershare allow guests\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +usershare max shares (G) +.PP +.RS 4 +This parameter specifies the number of user defined shares that are allowed to be created by users belonging to the group owning the usershare directory\&. If set to zero (the default) user defined shares are ignored\&. +.sp +Default: +\fI\fIusershare max shares\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +usershare owner only (G) +.PP +.RS 4 +This parameter controls whether the pathname exported by a user defined shares must be owned by the user creating the user defined share or not\&. If set to True (the default) then smbd checks that the directory path being shared is owned by the user who owns the usershare file defining this share and refuses to create the share if not\&. If set to False then no such check is performed and any directory path may be exported regardless of who owns it\&. +.sp +Default: +\fI\fIusershare owner only\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +usershare path (G) +.PP +.RS 4 +This parameter specifies the absolute path of the directory on the filesystem used to store the user defined share definition files\&. This directory must be owned by root, and have no access for other, and be writable only by the group owner\&. In addition the "sticky" bit must also be set, restricting rename and delete to owners of a file (in the same way the /tmp directory is usually configured)\&. Members of the group owner of this directory are the users allowed to create usershares\&. +.sp +For example, a valid usershare directory might be /usr/local/samba/lib/usershares, set up as follows\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + ls \-ld /usr/local/samba/lib/usershares/ + drwxrwx\-\-T 2 root power_users 4096 2006\-05\-05 12:27 /usr/local/samba/lib/usershares/ + +.fi +.if n \{\ +.RE +.\} +.sp +In this case, only members of the group "power_users" can create user defined shares\&. +.sp +Default: +\fI\fIusershare path\fR\fR\fI = \fR\fI/var/lib/samba/usershares\fR\fI \fR +.RE + +usershare prefix allow list (G) +.PP +.RS 4 +This parameter specifies a list of absolute pathnames the root of which are allowed to be exported by user defined share definitions\&. If the pathname to be exported doesn\*(Aqt start with one of the strings in this list, the user defined share will not be allowed\&. This allows the Samba administrator to restrict the directories on the system that can be exported by user defined shares\&. +.sp +If there is a "usershare prefix deny list" and also a "usershare prefix allow list" the deny list is processed first, followed by the allow list, thus leading to the most restrictive interpretation\&. +.sp +Default: +\fI\fIusershare prefix allow list\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIusershare prefix allow list\fR\fR\fI = \fR\fI/home /data /space\fR\fI \fR +.RE + +usershare prefix deny list (G) +.PP +.RS 4 +This parameter specifies a list of absolute pathnames the root of which are NOT allowed to be exported by user defined share definitions\&. If the pathname exported starts with one of the strings in this list the user defined share will not be allowed\&. Any pathname not starting with one of these strings will be allowed to be exported as a usershare\&. This allows the Samba administrator to restrict the directories on the system that can be exported by user defined shares\&. +.sp +If there is a "usershare prefix deny list" and also a "usershare prefix allow list" the deny list is processed first, followed by the allow list, thus leading to the most restrictive interpretation\&. +.sp +Default: +\fI\fIusershare prefix deny list\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIusershare prefix deny list\fR\fR\fI = \fR\fI/etc /dev /private\fR\fI \fR +.RE + +usershare template share (G) +.PP +.RS 4 +User defined shares only have limited possible parameters such as path, guest ok, etc\&. This parameter allows usershares to "cloned" from an existing share\&. If "usershare template share" is set to the name of an existing share, then all usershares created have their defaults set from the parameters set on this share\&. +.sp +The target share may be set to be invalid for real file sharing by setting the parameter "\-valid = False" on the template share definition\&. This causes it not to be seen as a real exported share but to be able to be used as a template for usershares\&. +.sp +Default: +\fI\fIusershare template share\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIusershare template share\fR\fR\fI = \fR\fItemplate_share\fR\fI \fR +.RE + +use sendfile (S) +.PP +.RS 4 +If this parameter is +\fByes\fR, and the +\fBsendfile()\fR +system call is supported by the underlying operating system, then some SMB read calls (mainly ReadAndX and ReadRaw) will use the more efficient sendfile system call for files that are exclusively oplocked\&. This may make more efficient use of the system CPU\*(Aqs and cause Samba to be faster\&. Samba automatically turns this off for clients that use protocol levels lower than NT LM 0\&.12 and when it detects a client is Windows 9x (using sendfile from Linux will cause these clients to fail)\&. +.sp +Default: +\fI\fIuse sendfile\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +utmp (G) +.PP +.RS 4 +This boolean parameter is only available if Samba has been configured and compiled with the option +\-\-with\-utmp\&. If set to +\fByes\fR +then Samba will attempt to add utmp or utmpx records (depending on the UNIX system) whenever a connection is made to a Samba server\&. Sites may use this to record the user connecting to a Samba share\&. +.sp +Due to the requirements of the utmp record, we are required to create a unique identifier for the incoming user\&. Enabling this option creates an n^2 algorithm to find this number\&. This may impede performance on large installations\&. +.sp +Default: +\fI\fIutmp\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +utmp directory (G) +.PP +.RS 4 +This parameter is only available if Samba has been configured and compiled with the option +\-\-with\-utmp\&. It specifies a directory pathname that is used to store the utmp or utmpx files (depending on the UNIX system) that record user connections to a Samba server\&. By default this is not set, meaning the system will use whatever utmp file the native system is set to use (usually +/var/run/utmp +on Linux)\&. +.sp +Default: +\fI\fIutmp directory\fR\fR\fI = \fR\fI # Determined automatically\fR\fI \fR +.sp +Example: +\fI\fIutmp directory\fR\fR\fI = \fR\fI/var/run/utmp\fR\fI \fR +.RE + +\-valid (S) +.PP +.RS 4 +This parameter indicates whether a share is valid and thus can be used\&. When this parameter is set to false, the share will be in no way visible nor accessible\&. +.sp +This option should not be used by regular users but might be of help to developers\&. Samba uses this option internally to mark shares as deleted\&. +.sp +Default: +\fI\fI\-valid\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +valid users (S) +.PP +.RS 4 +This is a list of users that should be allowed to login to this service\&. Names starting with \*(Aq@\*(Aq, \*(Aq+\*(Aq and \*(Aq&\*(Aq are interpreted using the same rules as described in the +\fIinvalid users\fR +parameter\&. +.sp +If this is empty (the default) then any user can login\&. If a username is in both this list and the +\fIinvalid users\fR +list then access is denied for that user\&. +.sp +The current servicename is substituted for +\fI%S\fR\&. This is useful in the [homes] section\&. +.sp +\fINote: \fRWhen used in the [global] section this parameter may have unwanted side effects\&. For example: If samba is configured as a MASTER BROWSER (see +\fIlocal master\fR, +\fIos level\fR, +\fIdomain master\fR, +\fIpreferred master\fR) this option will prevent workstations from being able to browse the network\&. +.sp +Default: +\fI\fIvalid users\fR\fR\fI = \fR\fI # No valid users list (anyone can login) \fR\fI \fR +.sp +Example: +\fI\fIvalid users\fR\fR\fI = \fR\fIgreg, @pcusers\fR\fI \fR +.RE + +veto files (S) +.PP +.RS 4 +This is a list of files and directories that are neither visible nor accessible\&. Each entry in the list must be separated by a \*(Aq/\*(Aq, which allows spaces to be included in the entry\&. \*(Aq*\*(Aq and \*(Aq?\*(Aq can be used to specify multiple files or directories as in DOS wildcards\&. +.sp +Each entry must be a unix path, not a DOS path and must +\fInot\fR +include the unix directory separator \*(Aq/\*(Aq\&. +.sp +Note that the +\m[blue]\fBcase sensitive\fR\m[] +option is applicable in vetoing files\&. +.sp +One feature of the veto files parameter that it is important to be aware of is Samba\*(Aqs behaviour when trying to delete a directory\&. If a directory that is to be deleted contains nothing but veto files this deletion will +\fIfail\fR +unless you also set the +\m[blue]\fBdelete veto files\fR\m[] +parameter to +\fIyes\fR\&. +.sp +Setting this parameter will affect the performance of Samba, as it will be forced to check all files and directories for a match as they are scanned\&. +.sp +Examples of use include: +.sp +.if n \{\ +.RS 4 +.\} +.nf +; Veto any files containing the word Security, +; any ending in \&.tmp, and any directory containing the +; word root\&. +veto files = /*Security*/*\&.tmp/*root*/ + +; Veto the Apple specific files that a NetAtalk server +; creates\&. +veto files = /\&.AppleDouble/\&.bin/\&.AppleDesktop/Network Trash Folder/ +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIveto files\fR\fR\fI = \fR\fI # No files or directories are vetoed\fR\fI \fR +.RE + +veto oplock files (S) +.PP +.RS 4 +This parameter is only valid when the +\m[blue]\fBoplocks\fR\m[] +parameter is turned on for a share\&. It allows the Samba administrator to selectively turn off the granting of oplocks on selected files that match a wildcarded list, similar to the wildcarded list used in the +\m[blue]\fBveto files\fR\m[] +parameter\&. +.sp +You might want to do this on files that you know will be heavily contended for by clients\&. A good example of this is in the NetBench SMB benchmark program, which causes heavy client contention for files ending in +\&.SEM\&. To cause Samba not to grant oplocks on these files you would use the line (either in the [global] section or in the section for the particular NetBench share\&. +.sp +An example of use is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +veto oplock files = /\&.*SEM/ +.fi +.if n \{\ +.RE +.\} +.sp +Default: +\fI\fIveto oplock files\fR\fR\fI = \fR\fI # No files are vetoed for oplock grants\fR\fI \fR +.RE + +vfs object +.PP +.RS 4 +This parameter is a synonym for +vfs objects\&. +.RE + +vfs objects (S) +.PP +.RS 4 +This parameter specifies the backend names which are used for Samba VFS I/O operations\&. By default, normal disk I/O operations are used but these can be overloaded with one or more VFS objects\&. Be aware that the definition of this parameter will overwrite a possible previous definition of the vfs objects parameter\&. +.sp +Default: +\fI\fIvfs objects\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIvfs objects\fR\fR\fI = \fR\fIextd_audit recycle\fR\fI \fR +.RE + +volume (S) +.PP +.RS 4 +This allows you to override the volume label returned for a share\&. Useful for CDROMs with installation programs that insist on a particular volume label\&. +.sp +Default: +\fI\fIvolume\fR\fR\fI = \fR\fI # the name of the share\fR\fI \fR +.RE + +volume serial number (S) +.PP +.RS 4 +This allows to override the volume serial number (a 32bit value) reported for a share\&. +.sp +The special value +\fI\-1\fR +(default) stands for a unique number that is calculated for each share\&. +.sp +Default: +\fI\fIvolume serial number\fR\fR\fI = \fR\fI\-1\fR\fI \fR +.sp +Example: +\fI\fIvolume serial number\fR\fR\fI = \fR\fI0xabcdefgh\fR\fI \fR +.RE + +wide links (S) +.PP +.RS 4 +This parameter controls whether or not links in the UNIX file system may be followed by the server\&. Links that point to areas within the directory tree exported by the server are always allowed; this parameter controls access only to areas that are outside the directory tree being exported\&. +.sp +Note: Turning this parameter on when UNIX extensions are enabled will allow UNIX clients to create symbolic links on the share that can point to files or directories outside restricted path exported by the share definition\&. This can cause access to areas outside of the share\&. Due to this problem, this parameter will be automatically disabled (with a message in the log file) if the +\m[blue]\fBunix extensions\fR\m[] +option is on\&. +.sp +See the parameter +\m[blue]\fBallow insecure wide links\fR\m[] +if you wish to change this coupling between the two parameters\&. +.sp +Default: +\fI\fIwide links\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winbind cache time (G) +.PP +.RS 4 +This parameter specifies the number of seconds the +\fBwinbindd\fR(8) +daemon will cache user and group information before querying a Windows NT server again\&. +.sp +This does not apply to authentication requests, these are always evaluated in real time unless the +\m[blue]\fBwinbind offline logon\fR\m[] +option has been enabled\&. +.sp +Default: +\fI\fIwinbind cache time\fR\fR\fI = \fR\fI300\fR\fI \fR +.RE + +winbindd socket directory (G) +.PP +.RS 4 +This setting controls the location of the winbind daemon\*(Aqs socket\&. +.sp +Except within automated test scripts, this should not be altered, as the client tools (nss_winbind etc) do not honour this parameter\&. Client tools must then be advised of the altered path with the WINBINDD_SOCKET_DIR environment variable\&. +.sp +Default: +\fI\fIwinbindd socket directory\fR\fR\fI = \fR\fI/run/samba/winbindd\fR\fI \fR +.RE + +winbind enum groups (G) +.PP +.RS 4 +On large installations using +\fBwinbindd\fR(8) +it may be necessary to suppress the enumeration of groups through the +setgrent(), +getgrent() +and +endgrent() +group of system calls\&. If the +\fIwinbind enum groups\fR +parameter is +\fBno\fR, calls to the +getgrent() +system call will not return any data\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Turning off group enumeration may cause some programs to behave oddly\&. +.sp .5v +.RE +Default: +\fI\fIwinbind enum groups\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winbind enum users (G) +.PP +.RS 4 +On large installations using +\fBwinbindd\fR(8) +it may be necessary to suppress the enumeration of users through the +setpwent(), +getpwent() +and +endpwent() +group of system calls\&. If the +\fIwinbind enum users\fR +parameter is +\fBno\fR, calls to the +getpwent +system call will not return any data\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Turning off user enumeration may cause some programs to behave oddly\&. For example, the finger program relies on having access to the full user list when searching for matching usernames\&. +.sp .5v +.RE +Default: +\fI\fIwinbind enum users\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winbind expand groups (G) +.PP +.RS 4 +This option controls the maximum depth that winbindd will traverse when flattening nested group memberships of Windows domain groups\&. This is different from the +\m[blue]\fBwinbind nested groups\fR\m[] +option which implements the Windows NT4 model of local group nesting\&. The "winbind expand groups" parameter specifically applies to the membership of domain groups\&. +.sp +This option also affects the return of non nested group memberships of Windows domain users\&. With the new default "winbind expand groups = 0" winbind does not query group memberships at all\&. +.sp +Be aware that a high value for this parameter can result in system slowdown as the main parent winbindd daemon must perform the group unrolling and will be unable to answer incoming NSS or authentication requests during this time\&. +.sp +The default value was changed from 1 to 0 with Samba 4\&.2\&. Some broken applications (including some implementations of newgrp and sg) calculate the group memberships of users by traversing groups, such applications will require "winbind expand groups = 1"\&. But the new default makes winbindd more reliable as it doesn\*(Aqt require SAMR access to domain controllers of trusted domains\&. +.sp +Default: +\fI\fIwinbind expand groups\fR\fR\fI = \fR\fI0\fR\fI \fR +.RE + +winbind:ignore domains (G) +.PP +.RS 4 +Allows one to enter a list of trusted domains winbind should ignore (untrust)\&. This can avoid the overhead of resources from attempting to login to DCs that should not be communicated with\&. +.sp +Default: +\fI\fIwinbind:ignore domains\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIwinbind:ignore domains\fR\fR\fI = \fR\fIDOMAIN1, DOMAIN2\fR\fI \fR +.RE + +winbind max clients (G) +.PP +.RS 4 +This parameter specifies the maximum number of clients the +\fBwinbindd\fR(8) +daemon can connect with\&. The parameter is not a hard limit\&. The +\fBwinbindd\fR(8) +daemon configures itself to be able to accept at least that many connections, and if the limit is reached, an attempt is made to disconnect idle clients\&. +.sp +Default: +\fI\fIwinbind max clients\fR\fR\fI = \fR\fI200\fR\fI \fR +.RE + +winbind max domain connections (G) +.PP +.RS 4 +This parameter specifies the maximum number of simultaneous connections that the +\fBwinbindd\fR(8) +daemon should open to the domain controller of one domain\&. Setting this parameter to a value greater than 1 can improve scalability with many simultaneous winbind requests, some of which might be slow\&. Changing this value requires a restart of winbindd\&. +.sp +Note that if +\m[blue]\fBwinbind offline logon\fR\m[] +is set to +\fBYes\fR, then only one DC connection is allowed per domain, regardless of this setting\&. +.sp +Default: +\fI\fIwinbind max domain connections\fR\fR\fI = \fR\fI1\fR\fI \fR +.sp +Example: +\fI\fIwinbind max domain connections\fR\fR\fI = \fR\fI10\fR\fI \fR +.RE + +winbind nested groups (G) +.PP +.RS 4 +If set to yes, this parameter activates the support for nested groups\&. Nested groups are also called local groups or aliases\&. They work like their counterparts in Windows: Nested groups are defined locally on any machine (they are shared between DC\*(Aqs through their SAM) and can contain users and global groups from any trusted SAM\&. To be able to use nested groups, you need to run nss_winbind\&. +.sp +Default: +\fI\fIwinbind nested groups\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +winbind normalize names (G) +.PP +.RS 4 +This parameter controls whether winbindd will replace whitespace in user and group names with an underscore (_) character\&. For example, whether the name "Space Kadet" should be replaced with the string "space_kadet"\&. Frequently Unix shell scripts will have difficulty with usernames contains whitespace due to the default field separator in the shell\&. If your domain possesses names containing the underscore character, this option may cause problems unless the name aliasing feature is supported by your nss_info plugin\&. +.sp +This feature also enables the name aliasing API which can be used to make domain user and group names to a non\-qualified version\&. Please refer to the manpage for the configured idmap and nss_info plugin for the specifics on how to configure name aliasing for a specific configuration\&. Name aliasing takes precedence (and is mutually exclusive) over the whitespace replacement mechanism discussed previously\&. +.sp +Default: +\fI\fIwinbind normalize names\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIwinbind normalize names\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +winbind nss info (G) +.PP +.RS 4 +This parameter is designed to control how Winbind retrieves Name Service Information to construct a user\*(Aqs home directory and login shell\&. Currently the following settings are available: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fItemplate\fR +\- The default, using the parameters of +\fItemplate shell\fR +and +\fItemplate homedir\fR) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fI\fR +\- When Samba is running in security = ads and your Active Directory Domain Controller does support the Microsoft "Services for Unix" (SFU) LDAP schema, winbind can retrieve the login shell and the home directory attributes directly from your Directory Server\&. For SFU 3\&.0 or 3\&.5 simply choose "sfu", if you use SFU 2\&.0 please choose "sfu20"\&. +.sp +Note that for the idmap backend +idmap_ad +you need to configure those settings in the idmap configuration section\&. Make sure to consult the documentation of the idmap backend that you are using\&. +.RE +.sp +.RE +.sp +Default: +\fI\fIwinbind nss info\fR\fR\fI = \fR\fItemplate\fR\fI \fR +.sp +Example: +\fI\fIwinbind nss info\fR\fR\fI = \fR\fIsfu\fR\fI \fR +.RE + +winbind offline logon (G) +.PP +.RS 4 +This parameter is designed to control whether Winbind should allow one to login with the +\fIpam_winbind\fR +module using Cached Credentials\&. If enabled, winbindd will store user credentials from successful logins encrypted in a local cache\&. +.sp +Default: +\fI\fIwinbind offline logon\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIwinbind offline logon\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +winbind reconnect delay (G) +.PP +.RS 4 +This parameter specifies the number of seconds the +\fBwinbindd\fR(8) +daemon will wait between attempts to contact a Domain controller for a domain that is determined to be down or not contactable\&. +.sp +Default: +\fI\fIwinbind reconnect delay\fR\fR\fI = \fR\fI30\fR\fI \fR +.RE + +winbind refresh tickets (G) +.PP +.RS 4 +This parameter is designed to control whether Winbind should refresh Kerberos Tickets retrieved using the +\fIpam_winbind\fR +module\&. +.sp +Default: +\fI\fIwinbind refresh tickets\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIwinbind refresh tickets\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +winbind request timeout (G) +.PP +.RS 4 +This parameter specifies the number of seconds the +\fBwinbindd\fR(8) +daemon will wait before disconnecting either a client connection with no outstanding requests (idle) or a client connection with a request that has remained outstanding (hung) for longer than this number of seconds\&. +.sp +Default: +\fI\fIwinbind request timeout\fR\fR\fI = \fR\fI60\fR\fI \fR +.RE + +winbind rpc only (G) +.PP +.RS 4 +Setting this parameter to +yes +forces winbindd to use RPC instead of LDAP to retrieve information from Domain Controllers\&. +.sp +Default: +\fI\fIwinbind rpc only\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winbind scan trusted domains (G) +.PP +.RS 4 +This option only takes effect when the +\m[blue]\fBsecurity\fR\m[] +option is set to +\fBdomain\fR +or +\fBads\fR\&. If it is set to yes, winbindd periodically tries to scan for new trusted domains and adds them to a global list inside of winbindd\&. The list can be extracted with +wbinfo \-\-trusted\-domains \-\-verbose\&. Setting it to yes matches the behaviour of Samba 4\&.7 and older\&. +.sp +The construction of that global list is not reliable and often incomplete in complex trust setups\&. In most situations the list is not needed any more for winbindd to operate correctly\&. E\&.g\&. for plain file serving via SMB using a simple idmap setup with +\fBautorid\fR, +\fBtdb\fR +or +\fBad\fR\&. However some more complex setups require the list, e\&.g\&. if you specify idmap backends for specific domains\&. Some pam_winbind setups may also require the global list\&. +.sp +If you have a setup that doesn\*(Aqt require the global list, you should set +\m[blue]\fBwinbind scan trusted domains = no\fR\m[]\&. +.sp +Default: +\fI\fIwinbind scan trusted domains\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winbind sealed pipes (G) +.PP +.RS 4 +This option controls whether any requests from winbindd to domain controllers pipe will be sealed\&. Disabling sealing can be useful for debugging purposes\&. +.sp +The behavior can be controlled per netbios domain by using \*(Aqwinbind sealed pipes:NETBIOSDOMAIN = no\*(Aq as option\&. +.sp +Default: +\fI\fIwinbind sealed pipes\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +winbind separator (G) +.PP +.RS 4 +This parameter allows an admin to define the character used when listing a username of the form of +\fIDOMAIN \fR\e\fIuser\fR\&. This parameter is only applicable when using the +pam_winbind\&.so +and +nss_winbind\&.so +modules for UNIX services\&. +.sp +Please note that setting this parameter to + causes problems with group membership at least on glibc systems, as the character + is used as a special character for NIS in /etc/group\&. +.sp +Default: +\fI\fIwinbind separator\fR\fR\fI = \fR\fI\e\fR\fI \fR +.sp +Example: +\fI\fIwinbind separator\fR\fR\fI = \fR\fI+\fR\fI \fR +.RE + +winbind use default domain (G) +.PP +.RS 4 +This parameter specifies whether the +\fBwinbindd\fR(8) +daemon should operate on users without domain component in their username\&. Users without a domain component are treated as is part of the winbindd server\*(Aqs own domain\&. While this does not benefit Windows users, it makes SSH, FTP and e\-mail function in a way much closer to the way they would in a native unix system\&. +.sp +This option should be avoided if possible\&. It can cause confusion about responsibilities for a user or group\&. In many situations it is not clear whether winbind or /etc/passwd should be seen as authoritative for a user, likewise for groups\&. +.sp +Default: +\fI\fIwinbind use default domain\fR\fR\fI = \fR\fIno\fR\fI \fR +.sp +Example: +\fI\fIwinbind use default domain\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +winbind use krb5 enterprise principals (G) +.PP +.RS 4 +winbindd is able to get kerberos tickets for pam_winbind with krb5_auth or wbinfo \-K/\-\-krb5auth=\&. +.sp +winbindd (at least on a domain member) is never be able to have a complete picture of the trust topology (which is managed by the DCs)\&. There might be uPNSuffixes and msDS\-SPNSuffixes values, which don\*(Aqt belong to any AD domain at all\&. +.sp +With +\m[blue]\fBwinbind scan trusted domains = no\fR\m[] +winbindd doesn\*(Aqt even get a complete picture of the topology\&. +.sp +It is not really required to know about the trust topology\&. We can just rely on the [K]DCs of our primary domain (e\&.g\&. PRIMARY\&.A\&.EXAMPLE\&.COM) and use enterprise principals e\&.g\&. upnfromB@B\&.EXAMPLE\&.COM@PRIMARY\&.A\&.EXAMPLE\&.COM and follow the WRONG_REALM referrals in order to find the correct DC\&. The final principal might be userfromB@INTERNALB\&.EXAMPLE\&.PRIVATE\&. +.sp +With +\m[blue]\fBwinbind use krb5 enterprise principals = yes\fR\m[] +winbindd enterprise principals will be used\&. +.sp +Default: +\fI\fIwinbind use krb5 enterprise principals\fR\fR\fI = \fR\fIyes\fR\fI \fR +.sp +Example: +\fI\fIwinbind use krb5 enterprise principals\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +winsdb:local_owner (G) +.PP +.RS 4 +This specifies the address that is stored in the winsOwner attribute, of locally registered winsRecord\-objects\&. The default is to use the ip\-address of the first network interface\&. +.sp +\fINo default\fR +.RE + +winsdb:dbnosync (G) +.PP +.RS 4 +This parameter disables fsync() after changes of the WINS database\&. +.sp +Default: +\fI\fIwinsdb:dbnosync\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +wins hook (G) +.PP +.RS 4 +When Samba is running as a WINS server this allows you to call an external program for all changes to the WINS database\&. The primary use for this option is to allow the dynamic update of external name resolution databases such as dynamic DNS\&. +.sp +The wins hook parameter specifies the name of a script or executable that will be called as follows: +.sp +wins_hook operation name nametype ttl IP_list +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The first argument is the operation and is one of "add", "delete", or "refresh"\&. In most cases the operation can be ignored as the rest of the parameters provide sufficient information\&. Note that "refresh" may sometimes be called when the name has not previously been added, in that case it should be treated as an add\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The second argument is the NetBIOS name\&. If the name is not a legal name then the wins hook is not called\&. Legal names contain only letters, digits, hyphens, underscores and periods\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The third argument is the NetBIOS name type as a 2 digit hexadecimal number\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The fourth argument is the TTL (time to live) for the name in seconds\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The fifth and subsequent arguments are the IP addresses currently registered for that name\&. If this list is empty then the name should be deleted\&. +.RE +.sp +.RE +An example script that calls the BIND dynamic DNS update program +nsupdate +is provided in the examples directory of the Samba source code\&. +.sp +\fINo default\fR +.RE + +wins proxy (G) +.PP +.RS 4 +This is a boolean that controls if +\fBnmbd\fR(8) +will respond to broadcast name queries on behalf of other hosts\&. You may need to set this to +\fByes\fR +for some older clients\&. +.sp +Default: +\fI\fIwins proxy\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +wins server (G) +.PP +.RS 4 +This specifies the IP address (or DNS name: IP address for preference) of the WINS server that +\fBnmbd\fR(8) +should register with\&. If you have a WINS server on your network then you should set this to the WINS server\*(Aqs IP\&. +.sp +You should point this at your WINS server if you have a multi\-subnetted network\&. +.sp +If you want to work in multiple namespaces, you can give every wins server a \*(Aqtag\*(Aq\&. For each tag, only one (working) server will be queried for a name\&. The tag should be separated from the ip address by a colon\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +You need to set up Samba to point to a WINS server if you have multiple subnets and wish cross\-subnet browsing to work correctly\&. +.sp .5v +.RE +See the chapter in the Samba3\-HOWTO on Network Browsing\&. +.sp +Default: +\fI\fIwins server\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIwins server\fR\fR\fI = \fR\fImary:192\&.9\&.200\&.1 fred:192\&.168\&.3\&.199 mary:192\&.168\&.2\&.61 # For this example when querying a certain name, 192\&.19\&.200\&.1 will be asked first and if that doesn\*(Aqt respond 192\&.168\&.2\&.61\&. If either of those doesn\*(Aqt know the name 192\&.168\&.3\&.199 will be queried\&.\fR\fI \fR +.sp +Example: +\fI\fIwins server\fR\fR\fI = \fR\fI192\&.9\&.200\&.1 192\&.168\&.2\&.61\fR\fI \fR +.RE + +wins support (G) +.PP +.RS 4 +This boolean controls if the +\fBnmbd\fR(8) +process in Samba will act as a WINS server\&. You should not set this to +\fByes\fR +unless you have a multi\-subnetted network and you wish a particular +nmbd +to be your WINS server\&. Note that you should +\fINEVER\fR +set this to +\fByes\fR +on more than one machine in your network\&. +.sp +Default: +\fI\fIwins support\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +workgroup (G) +.PP +.RS 4 +This controls what workgroup your server will appear to be in when queried by clients\&. Note that this parameter also controls the Domain name used with the +\m[blue]\fBsecurity = domain\fR\m[] +setting\&. +.sp +Default: +\fI\fIworkgroup\fR\fR\fI = \fR\fIWORKGROUP\fR\fI \fR +.sp +Example: +\fI\fIworkgroup\fR\fR\fI = \fR\fIMYGROUP\fR\fI \fR +.RE + +wreplsrv:periodic_interval (G) +.PP +.RS 4 +This maximum interval in seconds between 2 periodically scheduled runs where we check for wins\&.ldb changes and do push notifications to our push partners\&. Also wins_config\&.ldb changes are checked in that interval and partner configuration reloads are done\&. +.sp +Default: +\fI\fIwreplsrv:periodic_interval\fR\fR\fI = \fR\fI15\fR\fI \fR +.RE + +wreplsrv:propagate name releases (G) +.PP +.RS 4 +If this parameter is enabled, then explicit (from the client) and implicit (via the scavenging) name releases are propagated to the other servers directly, even if there are still other addresses active, this applies to SPECIAL GROUP (2) and MULTIHOMED (3) entries\&. Also the replication conflict merge algorithm for SPECIAL GROUP (2) entries discards replica addresses where the address owner is the local server, if the address was not stored locally before\&. The merge result is propagated directly in case an address was discarded\&. A Windows servers doesn\*(Aqt propagate name releases of SPECIAL GROUP (2) and MULTIHOMED (3) entries directly, which means that Windows servers may return different results to name queries for SPECIAL GROUP (2) and MULTIHOMED (3) names\&. The option doesn\*(Aqt have much negative impact if Windows servers are around, but be aware that they might return unexpected results\&. +.sp +Default: +\fI\fIwreplsrv:propagate name releases\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +wreplsrv:scavenging_interval (G) +.PP +.RS 4 +This is the interval in s between 2 scavenging runs which clean up the WINS database and changes the states of expired name records\&. Defaults to half of the value of wreplsrv:renew_interval\&. +.sp +\fINo default\fR +.RE + +wreplsrv:tombstone_extra_timeout (G) +.PP +.RS 4 +This is the time in s the server needs to be up till we\*(Aqll remove tombstone records from our database\&. Defaults to 3 days\&. +.sp +Default: +\fI\fIwreplsrv:tombstone_extra_timeout\fR\fR\fI = \fR\fI259200\fR\fI \fR +.RE + +wreplsrv:tombstone_interval (G) +.PP +.RS 4 +This is the interval in s till released records of the WINS server become tombstone\&. Defaults to 6 days\&. +.sp +Default: +\fI\fIwreplsrv:tombstone_interval\fR\fR\fI = \fR\fI518400\fR\fI \fR +.RE + +wreplsrv:tombstone_timeout (G) +.PP +.RS 4 +This is the interval in s till tombstone records are deleted from the WINS database\&. Defaults to 1 day\&. +.sp +Default: +\fI\fIwreplsrv:tombstone_timeout\fR\fR\fI = \fR\fI86400\fR\fI \fR +.RE + +wreplsrv:verify_interval (G) +.PP +.RS 4 +This is the interval in s till we verify active replica records with the owning WINS server\&. Unfortunately not implemented yet\&. Defaults to 24 days\&. +.sp +Default: +\fI\fIwreplsrv:verify_interval\fR\fR\fI = \fR\fI2073600\fR\fI \fR +.RE + +writable +.PP +.RS 4 +This parameter is a synonym for +writeable\&. +.RE + +write ok +.PP +.RS 4 +This parameter is a synonym for +writeable\&. +.RE + +writeable (S) +.PP +.RS 4 +Inverted synonym for +\m[blue]\fBread only\fR\m[]\&. +.sp +Default: +\fI\fIwriteable\fR\fR\fI = \fR\fIno\fR\fI \fR +.RE + +write list (S) +.PP +.RS 4 +This is a list of users that are given read\-write access to a service\&. If the connecting user is in this list then they will be given write access, no matter what the +\m[blue]\fBread only\fR\m[] +option is set to\&. The list can include group names using the @group syntax\&. +.sp +Note that if a user is in both the read list and the write list then they will be given write access\&. +.sp +Default: +\fI\fIwrite list\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIwrite list\fR\fR\fI = \fR\fIadmin, root, @staff\fR\fI \fR +.RE + +write raw (G) +.PP +.RS 4 +This is ignored if +\m[blue]\fBasync smb echo handler\fR\m[] +is set, because this feature is incompatible with raw write SMB requests +.sp +If enabled, raw writes allow writes of 65535 bytes in one packet\&. This typically provides a major performance benefit for some very, very old clients\&. +.sp +However, some clients either negotiate the allowable block size incorrectly or are incapable of supporting larger block sizes, and for these clients you may need to disable raw writes\&. +.sp +In general this parameter should be viewed as a system tuning tool and left severely alone\&. +.sp +Default: +\fI\fIwrite raw\fR\fR\fI = \fR\fIyes\fR\fI \fR +.RE + +wsp property file (G) +.PP +.RS 4 +\m[blue]\fBwsp property file\fR\m[] +parameter\&. This parameter specifies the file where additional WSP Windows Search Protocol properties are stored\&. The format of the file is a csv consisting of 10 comma separated columns\&. The first 3 columns are required, the other columns are desirable but not necessary\&. +.PP +Property Name +.RS 4 +A property name e\&.g\&. System\&.ItemUrl\&. +.RE +.PP +GUID +.RS 4 +A guid that identifies the propertyset the property belongs to\&. +.RE +.PP +prop ID +.RS 4 +A number that together with the GUID uniquely identifies the property\&. +.RE +.PP +inInverted Index +.RS 4 +Set to TRUE is the property is indexed\&. +.RE +.PP +isColumn +.RS 4 +Set to TRUE if the property is one that can be returned in rows returned from WSP query\&. +.RE +.PP +type +.RS 4 +One of +\fIBoolean\fR,\fIBuffer\fR,\fIByte\fR,\fIDateTime\fR,\fIDouble\fR,\fIInt32\fR,\fIString\fR,\fIUInt16\fR,\fIUInt32\fR,\fIUInt64\fR +.RE +.PP +MaxSize +.RS 4 +maximum size when stored\&. +.RE +.PP +Vector Property +.RS 4 +TRUE if this is a multivalue property\&. +.RE +.PP +Description +.RS 4 +Description of what the property is used for\&. +.RE +.sp +Default: +\fI\fIwsp property file\fR\fR\fI = \fR\fI\fR\fI \fR +.RE + +wtmp directory (G) +.PP +.RS 4 +This parameter is only available if Samba has been configured and compiled with the option +\-\-with\-utmp\&. It specifies a directory pathname that is used to store the wtmp or wtmpx files (depending on the UNIX system) that record user connections to a Samba server\&. The difference with the utmp directory is the fact that user info is kept after a user has logged out\&. +.sp +By default this is not set, meaning the system will use whatever utmp file the native system is set to use (usually +/var/run/wtmp +on Linux)\&. +.sp +Default: +\fI\fIwtmp directory\fR\fR\fI = \fR\fI\fR\fI \fR +.sp +Example: +\fI\fIwtmp directory\fR\fR\fI = \fR\fI/var/log/wtmp\fR\fI \fR +.RE +.SH "WARNINGS" +.PP +Although the configuration file permits service names to contain spaces, your client software may not\&. Spaces will be ignored in comparisons anyway, so it shouldn\*(Aqt be a problem \- but be aware of the possibility\&. +.PP +On a similar note, many clients \- especially DOS clients \- limit service names to eight characters\&. +\fBsmbd\fR(8) +has no such limitation, but attempts to connect from such clients will fail if they truncate the service names\&. For this reason you should probably keep your service names down to eight characters in length\&. +.PP +Use of the +[homes] +and +[printers] +special sections make life for an administrator easy, but the various combinations of default attributes can be tricky\&. Take extreme care when designing these sections\&. In particular, ensure that the permissions on spool directories are correct\&. +.SH "VERSION" +.PP +This man page is part of version 4\&.20\&.0rc3 of the Samba suite\&. +.SH "SEE ALSO" +.PP +\fBsamba\fR(7), +\fBsmbpasswd\fR(8), +\fBsmbd\fR(8), +\fBnmbd\fR(8), +\fBwinbindd\fR(8), +\fBsamba\fR(8), +\fBsamba-tool\fR(8), +\fBsmbclient\fR(1), +\fBnmblookup\fR(1), +\fBtestparm\fR(1)\&. +.SH "AUTHOR" +.PP +The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&. diff --git a/upstream/fedora-40/man5/smbpasswd.5 b/upstream/fedora-40/man5/smbpasswd.5 new file mode 100644 index 00000000..d18b9a61 --- /dev/null +++ b/upstream/fedora-40/man5/smbpasswd.5 @@ -0,0 +1,175 @@ +'\" t +.\" Title: smbpasswd +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 02/26/2024 +.\" Manual: File Formats and Conventions +.\" Source: Samba 4.20.0rc3 +.\" Language: English +.\" +.TH "SMBPASSWD" "5" "02/26/2024" "Samba 4\&.20\&.0rc3" "File Formats and Conventions" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +smbpasswd \- The Samba encrypted password file +.SH "SYNOPSIS" +.PP +smbpasswd +.SH "DESCRIPTION" +.PP +This tool is part of the +\fBsamba\fR(7) +suite\&. +.PP +smbpasswd is the Samba encrypted password file\&. It contains the username, Unix user id and the SMB hashed passwords of the user, as well as account flag information and the time the password was last changed\&. This file format has been evolving with Samba and has had several different formats in the past\&. +.SH "FILE FORMAT" +.PP +The format of the smbpasswd file used by Samba 2\&.2 is very similar to the familiar Unix +passwd(5) +file\&. It is an ASCII file containing one line for each user\&. Each field within each line is separated from the next by a colon\&. Any entry beginning with \*(Aq#\*(Aq is ignored\&. The smbpasswd file contains the following information for each user: +.PP +name +.RS 4 +This is the user name\&. It must be a name that already exists in the standard UNIX passwd file\&. +.RE +.PP +uid +.RS 4 +This is the UNIX uid\&. It must match the uid field for the same user entry in the standard UNIX passwd file\&. If this does not match then Samba will refuse to recognize this smbpasswd file entry as being valid for a user\&. +.RE +.PP +Lanman Password Hash +.RS 4 +This is the LANMAN hash of the user\*(Aqs password, encoded as 32 hex digits\&. The LANMAN hash is created by DES encrypting a well known string with the user\*(Aqs password as the DES key\&. This is the same password used by Windows 95/98 machines\&. Note that this password hash is regarded as weak as it is vulnerable to dictionary attacks and if two users choose the same password this entry will be identical (i\&.e\&. the password is not "salted" as the UNIX password is)\&. If the user has a null password this field will contain the characters "NO PASSWORD" as the start of the hex string\&. If the hex string is equal to 32 \*(AqX\*(Aq characters then the user\*(Aqs account is marked as +\fBdisabled\fR +and the user will not be able to log onto the Samba server\&. +.sp +\fIWARNING !!\fR +Note that, due to the challenge\-response nature of the SMB/CIFS authentication protocol, anyone with a knowledge of this password hash will be able to impersonate the user on the network\&. For this reason these hashes are known as +\fIplain text equivalents\fR +and must +\fINOT\fR +be made available to anyone but the root user\&. To protect these passwords the smbpasswd file is placed in a directory with read and traverse access only to the root user and the smbpasswd file itself must be set to be read/write only by root, with no other access\&. +.RE +.PP +NT Password Hash +.RS 4 +This is the Windows NT hash of the user\*(Aqs password, encoded as 32 hex digits\&. The Windows NT hash is created by taking the user\*(Aqs password as represented in 16\-bit, little\-endian UNICODE and then applying the MD4 (internet rfc1321) hashing algorithm to it\&. +.sp +This password hash is considered more secure than the LANMAN Password Hash as it preserves the case of the password and uses a much higher quality hashing algorithm\&. However, it is still the case that if two users choose the same password this entry will be identical (i\&.e\&. the password is not "salted" as the UNIX password is)\&. +.sp +\fIWARNING !!\fR\&. Note that, due to the challenge\-response nature of the SMB/CIFS authentication protocol, anyone with a knowledge of this password hash will be able to impersonate the user on the network\&. For this reason these hashes are known as +\fIplain text equivalents\fR +and must +\fINOT\fR +be made available to anyone but the root user\&. To protect these passwords the smbpasswd file is placed in a directory with read and traverse access only to the root user and the smbpasswd file itself must be set to be read/write only by root, with no other access\&. +.RE +.PP +Account Flags +.RS 4 +This section contains flags that describe the attributes of the users account\&. This field is bracketed by \*(Aq[\*(Aq and \*(Aq]\*(Aq characters and is always 13 characters in length (including the \*(Aq[\*(Aq and \*(Aq]\*(Aq characters)\&. The contents of this field may be any of the following characters: +.RS +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIU\fR +\- This means this is a "User" account, i\&.e\&. an ordinary user\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIN\fR +\- This means the account has no password (the passwords in the fields LANMAN Password Hash and NT Password Hash are ignored)\&. Note that this will only allow users to log on with no password if the +\fI null passwords\fR +parameter is set in the +\fBsmb.conf\fR(5) +config file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fID\fR +\- This means the account is disabled and no SMB/CIFS logins will be allowed for this user\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIX\fR +\- This means the password does not expire\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIW\fR +\- This means this account is a "Workstation Trust" account\&. This kind of account is used in the Samba PDC code stream to allow Windows NT Workstations and Servers to join a Domain hosted by a Samba PDC\&. +.RE +.sp +.RE +Other flags may be added as the code is extended in future\&. The rest of this field space is filled in with spaces\&. For further information regarding the flags that are supported please refer to the man page for the +pdbedit +command\&. +.RE +.PP +Last Change Time +.RS 4 +This field consists of the time the account was last modified\&. It consists of the characters \*(AqLCT\-\*(Aq (standing for "Last Change Time") followed by a numeric encoding of the UNIX time in seconds since the epoch (1970) that the last change was made\&. +.RE +.PP +All other colon separated fields are ignored at this time\&. +.SH "VERSION" +.PP +This man page is part of version 4\&.20\&.0rc3 of the Samba suite\&. +.SH "SEE ALSO" +.PP +\fBsmbpasswd\fR(8), +\fBSamba\fR(7), and the Internet RFC1321 for details on the MD4 algorithm\&. +.SH "AUTHOR" +.PP +The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&. diff --git a/upstream/fedora-40/man5/ssh_config.5 b/upstream/fedora-40/man5/ssh_config.5 new file mode 100644 index 00000000..83164dad --- /dev/null +++ b/upstream/fedora-40/man5/ssh_config.5 @@ -0,0 +1,2400 @@ +.\" +.\" Author: Tatu Ylonen +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" As far as I am concerned, the code I have written for this software +.\" can be used freely for any purpose. Any derived versions of this +.\" software must be clearly marked as such, and if the derived work is +.\" incompatible with the protocol description in the RFC file, it must be +.\" called by a name other than "ssh" or "Secure Shell". +.\" +.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. +.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. +.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $OpenBSD: ssh_config.5,v 1.391 2023/10/12 02:18:18 djm Exp $ +.Dd $Mdocdate: October 12 2023 $ +.Dt SSH_CONFIG 5 +.Os +.Sh NAME +.Nm ssh_config +.Nd OpenSSH client configuration file +.Sh DESCRIPTION +.Xr ssh 1 +obtains configuration data from the following sources in +the following order: +.Pp +.Bl -enum -offset indent -compact +.It +command-line options +.It +user's configuration file +.Pq Pa ~/.ssh/config +.It +system-wide configuration file +.Pq Pa /etc/ssh/ssh_config +.El +.Pp +Unless noted otherwise, for each parameter, the first obtained value +will be used. +The configuration files contain sections separated by +.Cm Host +specifications, and that section is only applied for hosts that +match one of the patterns given in the specification. +The matched host name is usually the one given on the command line +(see the +.Cm CanonicalizeHostname +option for exceptions). +.Pp +Since the first obtained value for each parameter is used, more +host-specific declarations should be given near the beginning of the +file, and general defaults at the end. +.Pp +The file contains keyword-argument pairs, one per line. +Lines starting with +.Ql # +and empty lines are interpreted as comments. +Arguments may optionally be enclosed in double quotes +.Pq \&" +in order to represent arguments containing spaces. +Configuration options may be separated by whitespace or +optional whitespace and exactly one +.Ql = ; +the latter format is useful to avoid the need to quote whitespace +when specifying configuration options using the +.Nm ssh , +.Nm scp , +and +.Nm sftp +.Fl o +option. +.Pp +The possible +keywords and their meanings are as follows (note that +keywords are case-insensitive and arguments are case-sensitive): +.Bl -tag -width Ds +.It Cm Host +Restricts the following declarations (up to the next +.Cm Host +or +.Cm Match +keyword) to be only for those hosts that match one of the patterns +given after the keyword. +If more than one pattern is provided, they should be separated by whitespace. +A single +.Ql * +as a pattern can be used to provide global +defaults for all hosts. +The host is usually the +.Ar hostname +argument given on the command line +(see the +.Cm CanonicalizeHostname +keyword for exceptions). +.Pp +A pattern entry may be negated by prefixing it with an exclamation mark +.Pq Sq !\& . +If a negated entry is matched, then the +.Cm Host +entry is ignored, regardless of whether any other patterns on the line +match. +Negated matches are therefore useful to provide exceptions for wildcard +matches. +.Pp +See +.Sx PATTERNS +for more information on patterns. +.It Cm Match +Restricts the following declarations (up to the next +.Cm Host +or +.Cm Match +keyword) to be used only when the conditions following the +.Cm Match +keyword are satisfied. +Match conditions are specified using one or more criteria +or the single token +.Cm all +which always matches. +The available criteria keywords are: +.Cm canonical , +.Cm final , +.Cm exec , +.Cm localnetwork , +.Cm host , +.Cm originalhost , +.Cm Tag , +.Cm user , +and +.Cm localuser . +The +.Cm all +criteria must appear alone or immediately after +.Cm canonical +or +.Cm final . +Other criteria may be combined arbitrarily. +All criteria but +.Cm all , +.Cm canonical , +and +.Cm final +require an argument. +Criteria may be negated by prepending an exclamation mark +.Pq Sq !\& . +.Pp +The +.Cm canonical +keyword matches only when the configuration file is being re-parsed +after hostname canonicalization (see the +.Cm CanonicalizeHostname +option). +This may be useful to specify conditions that work with canonical host +names only. +.Pp +The +.Cm final +keyword requests that the configuration be re-parsed (regardless of whether +.Cm CanonicalizeHostname +is enabled), and matches only during this final pass. +If +.Cm CanonicalizeHostname +is enabled, then +.Cm canonical +and +.Cm final +match during the same pass. +.Pp +The +.Cm exec +keyword executes the specified command under the user's shell. +If the command returns a zero exit status then the condition is considered true. +Commands containing whitespace characters must be quoted. +Arguments to +.Cm exec +accept the tokens described in the +.Sx TOKENS +section. +.Pp +The +.Cm localnetwork +keyword matches the addresses of active local network interfaces against the +supplied list of networks in CIDR format. +This may be convenient for varying the effective configuration on devices that +roam between networks. +Note that network address is not a trustworthy criteria in many +situations (e.g. when the network is automatically configured using DHCP) +and so caution should be applied if using it to control security-sensitive +configuration. +.Pp +The other keywords' criteria must be single entries or comma-separated +lists and may use the wildcard and negation operators described in the +.Sx PATTERNS +section. +The criteria for the +.Cm host +keyword are matched against the target hostname, after any substitution +by the +.Cm Hostname +or +.Cm CanonicalizeHostname +options. +The +.Cm originalhost +keyword matches against the hostname as it was specified on the command-line. +The +.Cm tagged +keyword matches a tag name specified by a prior +.Cm Tag +directive or on the +.Xr ssh 1 +command-line using the +.Fl P +flag. +The +.Cm user +keyword matches against the target username on the remote host. +The +.Cm localuser +keyword matches against the name of the local user running +.Xr ssh 1 +(this keyword may be useful in system-wide +.Nm +files). +.It Cm AddKeysToAgent +Specifies whether keys should be automatically added to a running +.Xr ssh-agent 1 . +If this option is set to +.Cm yes +and a key is loaded from a file, the key and its passphrase are added to +the agent with the default lifetime, as if by +.Xr ssh-add 1 . +If this option is set to +.Cm ask , +.Xr ssh 1 +will require confirmation using the +.Ev SSH_ASKPASS +program before adding a key (see +.Xr ssh-add 1 +for details). +If this option is set to +.Cm confirm , +each use of the key must be confirmed, as if the +.Fl c +option was specified to +.Xr ssh-add 1 . +If this option is set to +.Cm no , +no keys are added to the agent. +Alternately, this option may be specified as a time interval +using the format described in the +.Sx TIME FORMATS +section of +.Xr sshd_config 5 +to specify the key's lifetime in +.Xr ssh-agent 1 , +after which it will automatically be removed. +The argument must be +.Cm no +(the default), +.Cm yes , +.Cm confirm +(optionally followed by a time interval), +.Cm ask +or a time interval. +.It Cm AddressFamily +Specifies which address family to use when connecting. +Valid arguments are +.Cm any +(the default), +.Cm inet +(use IPv4 only), or +.Cm inet6 +(use IPv6 only). +.It Cm BatchMode +If set to +.Cm yes , +user interaction such as password prompts and host key confirmation requests +will be disabled. +This option is useful in scripts and other batch jobs where no user +is present to interact with +.Xr ssh 1 . +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm BindAddress +Use the specified address on the local machine as the source address of +the connection. +Only useful on systems with more than one address. +.It Cm BindInterface +Use the address of the specified interface on the local machine as the +source address of the connection. +.It Cm CanonicalDomains +When +.Cm CanonicalizeHostname +is enabled, this option specifies the list of domain suffixes in which to +search for the specified destination host. +.It Cm CanonicalizeFallbackLocal +Specifies whether to fail with an error when hostname canonicalization fails. +The default, +.Cm yes , +will attempt to look up the unqualified hostname using the system resolver's +search rules. +A value of +.Cm no +will cause +.Xr ssh 1 +to fail instantly if +.Cm CanonicalizeHostname +is enabled and the target hostname cannot be found in any of the domains +specified by +.Cm CanonicalDomains . +.It Cm CanonicalizeHostname +Controls whether explicit hostname canonicalization is performed. +The default, +.Cm no , +is not to perform any name rewriting and let the system resolver handle all +hostname lookups. +If set to +.Cm yes +then, for connections that do not use a +.Cm ProxyCommand +or +.Cm ProxyJump , +.Xr ssh 1 +will attempt to canonicalize the hostname specified on the command line +using the +.Cm CanonicalDomains +suffixes and +.Cm CanonicalizePermittedCNAMEs +rules. +If +.Cm CanonicalizeHostname +is set to +.Cm always , +then canonicalization is applied to proxied connections too. +.Pp +If this option is enabled, then the configuration files are processed +again using the new target name to pick up any new configuration in matching +.Cm Host +and +.Cm Match +stanzas. +A value of +.Cm none +disables the use of a +.Cm ProxyJump +host. +.It Cm CanonicalizeMaxDots +Specifies the maximum number of dot characters in a hostname before +canonicalization is disabled. +The default, 1, +allows a single dot (i.e. hostname.subdomain). +.It Cm CanonicalizePermittedCNAMEs +Specifies rules to determine whether CNAMEs should be followed when +canonicalizing hostnames. +The rules consist of one or more arguments of +.Ar source_domain_list : Ns Ar target_domain_list , +where +.Ar source_domain_list +is a pattern-list of domains that may follow CNAMEs in canonicalization, +and +.Ar target_domain_list +is a pattern-list of domains that they may resolve to. +.Pp +For example, +.Qq *.a.example.com:*.b.example.com,*.c.example.com +will allow hostnames matching +.Qq *.a.example.com +to be canonicalized to names in the +.Qq *.b.example.com +or +.Qq *.c.example.com +domains. +.Pp +A single argument of +.Qq none +causes no CNAMEs to be considered for canonicalization. +This is the default behaviour. +.It Cm CASignatureAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies which algorithms are allowed for signing of certificates +by certificate authorities (CAs). +If the specified list begins with a +.Sq + +character, then the specified algorithms will be appended to the default set +instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the default set instead of replacing them. +.Pp +.Xr ssh 1 +will not accept host certificates signed using algorithms other than those +specified. +.It Cm CertificateFile +Specifies a file from which the user's certificate is read. +A corresponding private key must be provided separately in order +to use this certificate either +from an +.Cm IdentityFile +directive or +.Fl i +flag to +.Xr ssh 1 , +via +.Xr ssh-agent 1 , +or via a +.Cm PKCS11Provider +or +.Cm SecurityKeyProvider . +.Pp +Arguments to +.Cm CertificateFile +may use the tilde syntax to refer to a user's home directory, +the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +.Pp +It is possible to have multiple certificate files specified in +configuration files; these certificates will be tried in sequence. +Multiple +.Cm CertificateFile +directives will add to the list of certificates used for +authentication. +.It Cm ChannelTimeout +Specifies whether and how quickly +.Xr ssh 1 +should close inactive channels. +Timeouts are specified as one or more +.Dq type=interval +pairs separated by whitespace, where the +.Dq type +must be a channel type name (as described in the table below), optionally +containing wildcard characters. +.Pp +The timeout value +.Dq interval +is specified in seconds or may use any of the units documented in the +.Sx TIME FORMATS +section. +For example, +.Dq session=5m +would cause the interactive session to terminate after five minutes of +inactivity. +Specifying a zero value disables the inactivity timeout. +.Pp +The available channel types include: +.Bl -tag -width Ds +.It Cm agent-connection +Open connections to +.Xr ssh-agent 1 . +.It Cm direct-tcpip , Cm direct-streamlocal@openssh.com +Open TCP or Unix socket (respectively) connections that have +been established from a +.Xr ssh 1 +local forwarding, i.e.\& +.Cm LocalForward +or +.Cm DynamicForward . +.It Cm forwarded-tcpip , Cm forwarded-streamlocal@openssh.com +Open TCP or Unix socket (respectively) connections that have been +established to a +.Xr sshd 8 +listening on behalf of a +.Xr ssh 1 +remote forwarding, i.e.\& +.Cm RemoteForward . +.It Cm session +The interactive main session, including shell session, command execution, +.Xr scp 1 , +.Xr sftp 1 , +etc. +.It Cm tun-connection +Open +.Cm TunnelForward +connections. +.It Cm x11-connection +Open X11 forwarding sessions. +.El +.Pp +Note that in all the above cases, terminating an inactive session does not +guarantee to remove all resources associated with the session, e.g. shell +processes or X11 clients relating to the session may continue to execute. +.Pp +Moreover, terminating an inactive channel or session does not necessarily +close the SSH connection, nor does it prevent a client from +requesting another channel of the same type. +In particular, expiring an inactive forwarding session does not prevent +another identical forwarding from being subsequently created. +.Pp +The default is not to expire channels of any type for inactivity. +.It Cm CheckHostIP +If set to +.Cm yes , +.Xr ssh 1 +will additionally check the host IP address in the +.Pa known_hosts +file. +This allows it to detect if a host key changed due to DNS spoofing +and will add addresses of destination hosts to +.Pa ~/.ssh/known_hosts +in the process, regardless of the setting of +.Cm StrictHostKeyChecking . +If the option is set to +.Cm no +(the default), +the check will not be executed. +.It Cm Ciphers +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the ciphers allowed and their order of preference. +Multiple ciphers must be comma-separated. +If the specified list begins with a +.Sq + +character, then the specified ciphers will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified ciphers (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified ciphers will be placed at the head of the +built-in openssh default set. +.Pp +The supported ciphers are: +.Bd -literal -offset indent +3des-cbc +aes128-cbc +aes192-cbc +aes256-cbc +aes128-ctr +aes192-ctr +aes256-ctr +aes128-gcm@openssh.com +aes256-gcm@openssh.com +chacha20-poly1305@openssh.com +.Ed +.Pp +The list of available ciphers may also be obtained using +.Qq ssh -Q cipher . +.It Cm ClearAllForwardings +Specifies that all local, remote, and dynamic port forwardings +specified in the configuration files or on the command line be +cleared. +This option is primarily useful when used from the +.Xr ssh 1 +command line to clear port forwardings set in +configuration files, and is automatically set by +.Xr scp 1 +and +.Xr sftp 1 . +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm Compression +Specifies whether to use compression. +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm ConnectionAttempts +Specifies the number of tries (one per second) to make before exiting. +The argument must be an integer. +This may be useful in scripts if the connection sometimes fails. +The default is 1. +.It Cm ConnectTimeout +Specifies the timeout (in seconds) used when connecting to the +SSH server, instead of using the default system TCP timeout. +This timeout is applied both to establishing the connection and to performing +the initial SSH protocol handshake and key exchange. +.It Cm ControlMaster +Enables the sharing of multiple sessions over a single network connection. +When set to +.Cm yes , +.Xr ssh 1 +will listen for connections on a control socket specified using the +.Cm ControlPath +argument. +Additional sessions can connect to this socket using the same +.Cm ControlPath +with +.Cm ControlMaster +set to +.Cm no +(the default). +These sessions will try to reuse the master instance's network connection +rather than initiating new ones, but will fall back to connecting normally +if the control socket does not exist, or is not listening. +.Pp +Setting this to +.Cm ask +will cause +.Xr ssh 1 +to listen for control connections, but require confirmation using +.Xr ssh-askpass 1 . +If the +.Cm ControlPath +cannot be opened, +.Xr ssh 1 +will continue without connecting to a master instance. +.Pp +X11 and +.Xr ssh-agent 1 +forwarding is supported over these multiplexed connections, however the +display and agent forwarded will be the one belonging to the master +connection i.e. it is not possible to forward multiple displays or agents. +.Pp +Two additional options allow for opportunistic multiplexing: try to use a +master connection but fall back to creating a new one if one does not already +exist. +These options are: +.Cm auto +and +.Cm autoask . +The latter requires confirmation like the +.Cm ask +option. +.It Cm ControlPath +Specify the path to the control socket used for connection sharing as described +in the +.Cm ControlMaster +section above or the string +.Cm none +to disable connection sharing. +Arguments to +.Cm ControlPath +may use the tilde syntax to refer to a user's home directory, +the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +It is recommended that any +.Cm ControlPath +used for opportunistic connection sharing include +at least %h, %p, and %r (or alternatively %C) and be placed in a directory +that is not writable by other users. +This ensures that shared connections are uniquely identified. +.It Cm ControlPersist +When used in conjunction with +.Cm ControlMaster , +specifies that the master connection should remain open +in the background (waiting for future client connections) +after the initial client connection has been closed. +If set to +.Cm no +(the default), +then the master connection will not be placed into the background, +and will close as soon as the initial client connection is closed. +If set to +.Cm yes +or 0, +then the master connection will remain in the background indefinitely +(until killed or closed via a mechanism such as the +.Qq ssh -O exit ) . +If set to a time in seconds, or a time in any of the formats documented in +.Xr sshd_config 5 , +then the backgrounded master connection will automatically terminate +after it has remained idle (with no client connections) for the +specified time. +.It Cm DynamicForward +Specifies that a TCP port on the local machine be forwarded +over the secure channel, and the application +protocol is then used to determine where to connect to from the +remote machine. +.Pp +The argument must be +.Sm off +.Oo Ar bind_address : Oc Ar port . +.Sm on +IPv6 addresses can be specified by enclosing addresses in square brackets. +By default, the local port is bound in accordance with the +.Cm GatewayPorts +setting. +However, an explicit +.Ar bind_address +may be used to bind the connection to a specific address. +The +.Ar bind_address +of +.Cm localhost +indicates that the listening port be bound for local use only, while an +empty address or +.Sq * +indicates that the port should be available from all interfaces. +.Pp +Currently the SOCKS4 and SOCKS5 protocols are supported, and +.Xr ssh 1 +will act as a SOCKS server. +Multiple forwardings may be specified, and +additional forwardings can be given on the command line. +Only the superuser can forward privileged ports. +.It Cm EnableEscapeCommandline +Enables the command line option in the +.Cm EscapeChar +menu for interactive sessions (default +.Ql ~C ) . +By default, the command line is disabled. +.It Cm EnableSSHKeysign +Setting this option to +.Cm yes +in the global client configuration file +.Pa /etc/ssh/ssh_config +enables the use of the helper program +.Xr ssh-keysign 8 +during +.Cm HostbasedAuthentication . +The argument must be +.Cm yes +or +.Cm no +(the default). +This option should be placed in the non-hostspecific section. +See +.Xr ssh-keysign 8 +for more information. +.It Cm EscapeChar +Sets the escape character (default: +.Ql ~ ) . +The escape character can also +be set on the command line. +The argument should be a single character, +.Ql ^ +followed by a letter, or +.Cm none +to disable the escape +character entirely (making the connection transparent for binary +data). +.It Cm ExitOnForwardFailure +Specifies whether +.Xr ssh 1 +should terminate the connection if it cannot set up all requested +dynamic, tunnel, local, and remote port forwardings, (e.g.\& +if either end is unable to bind and listen on a specified port). +Note that +.Cm ExitOnForwardFailure +does not apply to connections made over port forwardings and will not, +for example, cause +.Xr ssh 1 +to exit if TCP connections to the ultimate forwarding destination fail. +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm FingerprintHash +Specifies the hash algorithm used when displaying key fingerprints. +Valid options are: +.Cm md5 +and +.Cm sha256 +(the default). +.It Cm ForkAfterAuthentication +Requests +.Nm ssh +to go to background just before command execution. +This is useful if +.Nm ssh +is going to ask for passwords or passphrases, but the user +wants it in the background. +This implies the +.Cm StdinNull +configuration option being set to +.Dq yes . +The recommended way to start X11 programs at a remote site is with +something like +.Ic ssh -f host xterm , +which is the same as +.Ic ssh host xterm +if the +.Cm ForkAfterAuthentication +configuration option is set to +.Dq yes . +.Pp +If the +.Cm ExitOnForwardFailure +configuration option is set to +.Dq yes , +then a client started with the +.Cm ForkAfterAuthentication +configuration option being set to +.Dq yes +will wait for all remote port forwards to be successfully established +before placing itself in the background. +The argument to this keyword must be +.Cm yes +(same as the +.Fl f +option) or +.Cm no +(the default). +.It Cm ForwardAgent +Specifies whether the connection to the authentication agent (if any) +will be forwarded to the remote machine. +The argument may be +.Cm yes , +.Cm no +(the default), +an explicit path to an agent socket or the name of an environment variable +(beginning with +.Sq $ ) +in which to find the path. +.Pp +Agent forwarding should be enabled with caution. +Users with the ability to bypass file permissions on the remote host +(for the agent's Unix-domain socket) +can access the local agent through the forwarded connection. +An attacker cannot obtain key material from the agent, +however they can perform operations on the keys that enable them to +authenticate using the identities loaded into the agent. +.It Cm ForwardX11 +Specifies whether X11 connections will be automatically redirected +over the secure channel and +.Ev DISPLAY +set. +The argument must be +.Cm yes +or +.Cm no +(the default). +.Pp +X11 forwarding should be enabled with caution. +Users with the ability to bypass file permissions on the remote host +(for the user's X11 authorization database) +can access the local X11 display through the forwarded connection. +An attacker may then be able to perform activities such as keystroke monitoring +if the +.Cm ForwardX11Trusted +option is also enabled. +.It Cm ForwardX11Timeout +Specify a timeout for untrusted X11 forwarding +using the format described in the +.Sx TIME FORMATS +section of +.Xr sshd_config 5 . +X11 connections received by +.Xr ssh 1 +after this time will be refused. +Setting +.Cm ForwardX11Timeout +to zero will disable the timeout and permit X11 forwarding for the life +of the connection. +The default is to disable untrusted X11 forwarding after twenty minutes has +elapsed. +.It Cm ForwardX11Trusted +If this option is set to +.Cm yes , +remote X11 clients will have full access to the original X11 display. +.Pp +If this option is set to +.Cm no +(the default), +remote X11 clients will be considered untrusted and prevented +from stealing or tampering with data belonging to trusted X11 +clients. +Furthermore, the +.Xr xauth 1 +token used for the session will be set to expire after 20 minutes. +Remote clients will be refused access after this time. +.Pp +See the X11 SECURITY extension specification for full details on +the restrictions imposed on untrusted clients. +.It Cm GatewayPorts +Specifies whether remote hosts are allowed to connect to local +forwarded ports. +By default, +.Xr ssh 1 +binds local port forwardings to the loopback address. +This prevents other remote hosts from connecting to forwarded ports. +.Cm GatewayPorts +can be used to specify that ssh +should bind local port forwardings to the wildcard address, +thus allowing remote hosts to connect to forwarded ports. +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm GlobalKnownHostsFile +Specifies one or more files to use for the global +host key database, separated by whitespace. +The default is +.Pa /etc/ssh/ssh_known_hosts , +.Pa /etc/ssh/ssh_known_hosts2 . +.It Cm GSSAPIAuthentication +Specifies whether user authentication based on GSSAPI is allowed. +The default is +.Cm no . +.It Cm GSSAPIClientIdentity +If set, specifies the GSSAPI client identity that ssh should use when +connecting to the server. The default is unset, which means that the default +identity will be used. +.It Cm GSSAPIDelegateCredentials +Forward (delegate) credentials to the server. +The default is +.Cm no . +.It Cm GSSAPIKeyExchange +Specifies whether key exchange based on GSSAPI may be used. When using +GSSAPI key exchange the server need not have a host key. +The default is +.Dq no . +.It Cm GSSAPIRenewalForcesRekey +If set to +.Dq yes +then renewal of the client's GSSAPI credentials will force the rekeying of the +ssh connection. With a compatible server, this will delegate the renewed +credentials to a session on the server. +.Pp +Checks are made to ensure that credentials are only propagated when the new +credentials match the old ones on the originating client and where the +receiving server still has the old set in its cache. +.Pp +The default is +.Dq no . +.Pp +For this to work +.Cm GSSAPIKeyExchange +needs to be enabled in the server and also used by the client. +.It Cm GSSAPIServerIdentity +If set, specifies the GSSAPI server identity that ssh should expect when +connecting to the server. The default is unset, which means that the +expected GSSAPI server identity will be determined from the target +hostname. +.It Cm GSSAPITrustDns +Set to +.Dq yes +to indicate that the DNS is trusted to securely canonicalize +the name of the host being connected to. If +.Dq no , +the hostname entered on the +command line will be passed untouched to the GSSAPI library. +The default is +.Dq no . +.It Cm GSSAPIKexAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +The list of key exchange algorithms that are offered for GSSAPI +key exchange. Possible values are +.Bd -literal -offset 3n +gss-gex-sha1-, +gss-group1-sha1-, +gss-group14-sha1-, +gss-group14-sha256-, +gss-group16-sha512-, +gss-nistp256-sha256-, +gss-curve25519-sha256- +.Ed +.Pp +This option only applies to connections using GSSAPI. +.Pp +.It Cm HashKnownHosts +Indicates that +.Xr ssh 1 +should hash host names and addresses when they are added to +.Pa ~/.ssh/known_hosts . +These hashed names may be used normally by +.Xr ssh 1 +and +.Xr sshd 8 , +but they do not visually reveal identifying information if the +file's contents are disclosed. +The default is +.Cm no . +Note that existing names and addresses in known hosts files +will not be converted automatically, +but may be manually hashed using +.Xr ssh-keygen 1 . +.It Cm HostbasedAcceptedAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the signature algorithms that will be used for hostbased +authentication as a comma-separated list of patterns. +Alternately if the specified list begins with a +.Sq + +character, then the specified signature algorithms will be appended +to the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified signature algorithms (including wildcards) +will be removed from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified signature algorithms will be placed +at the head of the built-in openssh default set. +.Pp +The +.Fl Q +option of +.Xr ssh 1 +may be used to list supported signature algorithms. +This was formerly named HostbasedKeyTypes. +.It Cm HostbasedAuthentication +Specifies whether to try rhosts based authentication with public key +authentication. +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm HostKeyAlgorithms +Specifies the host key signature algorithms +that the client wants to use in order of preference. +Alternately if the specified list begins with a +.Sq + +character, then the specified signature algorithms will be appended to +the default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified signature algorithms (including wildcards) +will be removed from the default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified signature algorithms will be placed +at the head of the default set. +The default for this option is: +.Bd -literal -offset 3n +ssh-ed25519-cert-v01@openssh.com, +ecdsa-sha2-nistp256-cert-v01@openssh.com, +ecdsa-sha2-nistp384-cert-v01@openssh.com, +ecdsa-sha2-nistp521-cert-v01@openssh.com, +sk-ssh-ed25519-cert-v01@openssh.com, +sk-ecdsa-sha2-nistp256-cert-v01@openssh.com, +rsa-sha2-512-cert-v01@openssh.com, +rsa-sha2-256-cert-v01@openssh.com, +ssh-ed25519, +ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521, +sk-ecdsa-sha2-nistp256@openssh.com, +sk-ssh-ed25519@openssh.com, +rsa-sha2-512,rsa-sha2-256 +.Ed +.Pp +If hostkeys are known for the destination host then this default is modified +to prefer their algorithms. +.Pp +The list of available signature algorithms may also be obtained using +.Qq ssh -Q HostKeyAlgorithms . +.Pp +The proposed +.Cm HostKeyAlgorithms +during KEX are limited to the set of algorithms that is defined in +.Cm PubkeyAcceptedAlgorithms +and therefore they are indirectly affected by system-wide +.Xr crypto_policies 7 . +.Xr crypto_policies 7 can not handle the list of host key algorithms directly as doing so +would break the order given by the +.Pa known_hosts +file. +.It Cm HostKeyAlias +Specifies an alias that should be used instead of the +real host name when looking up or saving the host key +in the host key database files and when validating host certificates. +This option is useful for tunneling SSH connections +or for multiple servers running on a single host. +.It Cm Hostname +Specifies the real host name to log into. +This can be used to specify nicknames or abbreviations for hosts. +Arguments to +.Cm Hostname +accept the tokens described in the +.Sx TOKENS +section. +Numeric IP addresses are also permitted (both on the command line and in +.Cm Hostname +specifications). +The default is the name given on the command line. +.It Cm IdentitiesOnly +Specifies that +.Xr ssh 1 +should only use the configured authentication identity and certificate files +(either the default files, or those explicitly configured in the +.Nm +files +or passed on the +.Xr ssh 1 +command-line), +even if +.Xr ssh-agent 1 +or a +.Cm PKCS11Provider +or +.Cm SecurityKeyProvider +offers more identities. +The argument to this keyword must be +.Cm yes +or +.Cm no +(the default). +This option is intended for situations where ssh-agent +offers many different identities. +.It Cm IdentityAgent +Specifies the +.Ux Ns -domain +socket used to communicate with the authentication agent. +.Pp +This option overrides the +.Ev SSH_AUTH_SOCK +environment variable and can be used to select a specific agent. +Setting the socket name to +.Cm none +disables the use of an authentication agent. +If the string +.Qq SSH_AUTH_SOCK +is specified, the location of the socket will be read from the +.Ev SSH_AUTH_SOCK +environment variable. +Otherwise if the specified value begins with a +.Sq $ +character, then it will be treated as an environment variable containing +the location of the socket. +.Pp +Arguments to +.Cm IdentityAgent +may use the tilde syntax to refer to a user's home directory, +the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +.It Cm IdentityFile +Specifies a file from which the user's DSA, ECDSA, authenticator-hosted ECDSA, +Ed25519, authenticator-hosted Ed25519 or RSA authentication identity is read. +You can also specify a public key file to use the corresponding +private key that is loaded in +.Xr ssh-agent 1 +when the private key file is not present locally. +The default is +.Pa ~/.ssh/id_rsa , +.Pa ~/.ssh/id_ecdsa , +.Pa ~/.ssh/id_ecdsa_sk , +.Pa ~/.ssh/id_ed25519 , +.Pa ~/.ssh/id_ed25519_sk +and +.Pa ~/.ssh/id_dsa . +Additionally, any identities represented by the authentication agent +will be used for authentication unless +.Cm IdentitiesOnly +is set. +If no certificates have been explicitly specified by +.Cm CertificateFile , +.Xr ssh 1 +will try to load certificate information from the filename obtained by +appending +.Pa -cert.pub +to the path of a specified +.Cm IdentityFile . +.Pp +Arguments to +.Cm IdentityFile +may use the tilde syntax to refer to a user's home directory +or the tokens described in the +.Sx TOKENS +section. +Alternately an argument of +.Cm none +may be used to indicate no identity files should be loaded. +.Pp +It is possible to have +multiple identity files specified in configuration files; all these +identities will be tried in sequence. +Multiple +.Cm IdentityFile +directives will add to the list of identities tried (this behaviour +differs from that of other configuration directives). +.Pp +.Cm IdentityFile +may be used in conjunction with +.Cm IdentitiesOnly +to select which identities in an agent are offered during authentication. +.Cm IdentityFile +may also be used in conjunction with +.Cm CertificateFile +in order to provide any certificate also needed for authentication with +the identity. +.Pp +The authentication identity can be also specified in a form of PKCS#11 URI +starting with a string +.Cm pkcs11: . +There is supported a subset of the PKCS#11 URI as defined +in RFC 7512 (implemented path arguments +.Cm id , +.Cm manufacturer , +.Cm object , +.Cm token +and query arguments +.Cm module-path +and +.Cm pin-value +). The URI can not be in quotes. +.It Cm IgnoreUnknown +Specifies a pattern-list of unknown options to be ignored if they are +encountered in configuration parsing. +This may be used to suppress errors if +.Nm +contains options that are unrecognised by +.Xr ssh 1 . +It is recommended that +.Cm IgnoreUnknown +be listed early in the configuration file as it will not be applied +to unknown options that appear before it. +.It Cm Include +Include the specified configuration file(s). +Multiple pathnames may be specified and each pathname may contain +.Xr glob 7 +wildcards and, for user configurations, shell-like +.Sq ~ +references to user home directories. +Wildcards will be expanded and processed in lexical order. +Files without absolute paths are assumed to be in +.Pa ~/.ssh +if included in a user configuration file or +.Pa /etc/ssh +if included from the system configuration file. +.Cm Include +directive may appear inside a +.Cm Match +or +.Cm Host +block +to perform conditional inclusion. +.It Cm IPQoS +Specifies the IPv4 type-of-service or DSCP class for connections. +Accepted values are +.Cm af11 , +.Cm af12 , +.Cm af13 , +.Cm af21 , +.Cm af22 , +.Cm af23 , +.Cm af31 , +.Cm af32 , +.Cm af33 , +.Cm af41 , +.Cm af42 , +.Cm af43 , +.Cm cs0 , +.Cm cs1 , +.Cm cs2 , +.Cm cs3 , +.Cm cs4 , +.Cm cs5 , +.Cm cs6 , +.Cm cs7 , +.Cm ef , +.Cm le , +.Cm lowdelay , +.Cm throughput , +.Cm reliability , +a numeric value, or +.Cm none +to use the operating system default. +This option may take one or two arguments, separated by whitespace. +If one argument is specified, it is used as the packet class unconditionally. +If two values are specified, the first is automatically selected for +interactive sessions and the second for non-interactive sessions. +The default is +.Cm af21 +(Low-Latency Data) +for interactive sessions and +.Cm cs1 +(Lower Effort) +for non-interactive sessions. +.It Cm KbdInteractiveAuthentication +Specifies whether to use keyboard-interactive authentication. +The argument to this keyword must be +.Cm yes +(the default) +or +.Cm no . +.Cm ChallengeResponseAuthentication +is a deprecated alias for this. +.It Cm KbdInteractiveDevices +Specifies the list of methods to use in keyboard-interactive authentication. +Multiple method names must be comma-separated. +The default is to use the server specified list. +The methods available vary depending on what the server supports. +For an OpenSSH server, +it may be zero or more of: +.Cm bsdauth +and +.Cm pam . +.It Cm KexAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the available KEX (Key Exchange) algorithms. +Multiple algorithms must be comma-separated. +If the specified list begins with a +.Sq + +character, then the specified methods will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified algorithms will be placed at the head of the +built-in openssh default set. +.Pp +The list of available key exchange algorithms may also be obtained using +.Qq ssh -Q kex . +.It Cm KnownHostsCommand +Specifies a command to use to obtain a list of host keys, in addition to +those listed in +.Cm UserKnownHostsFile +and +.Cm GlobalKnownHostsFile . +This command is executed after the files have been read. +It may write host key lines to standard output in identical format to the +usual files (described in the +.Sx VERIFYING HOST KEYS +section in +.Xr ssh 1 ) . +Arguments to +.Cm KnownHostsCommand +accept the tokens described in the +.Sx TOKENS +section. +The command may be invoked multiple times per connection: once when preparing +the preference list of host key algorithms to use, again to obtain the +host key for the requested host name and, if +.Cm CheckHostIP +is enabled, one more time to obtain the host key matching the server's +address. +If the command exits abnormally or returns a non-zero exit status then the +connection is terminated. +.It Cm LocalCommand +Specifies a command to execute on the local machine after successfully +connecting to the server. +The command string extends to the end of the line, and is executed with +the user's shell. +Arguments to +.Cm LocalCommand +accept the tokens described in the +.Sx TOKENS +section. +.Pp +The command is run synchronously and does not have access to the +session of the +.Xr ssh 1 +that spawned it. +It should not be used for interactive commands. +.Pp +This directive is ignored unless +.Cm PermitLocalCommand +has been enabled. +.It Cm LocalForward +Specifies that a TCP port on the local machine be forwarded over +the secure channel to the specified host and port from the remote machine. +The first argument specifies the listener and may be +.Sm off +.Oo Ar bind_address : Oc Ar port +.Sm on +or a Unix domain socket path. +The second argument is the destination and may be +.Ar host : Ns Ar hostport +or a Unix domain socket path if the remote host supports it. +.Pp +IPv6 addresses can be specified by enclosing addresses in square brackets. +Multiple forwardings may be specified, and additional forwardings can be +given on the command line. +Only the superuser can forward privileged ports. +By default, the local port is bound in accordance with the +.Cm GatewayPorts +setting. +However, an explicit +.Ar bind_address +may be used to bind the connection to a specific address. +The +.Ar bind_address +of +.Cm localhost +indicates that the listening port be bound for local use only, while an +empty address or +.Sq * +indicates that the port should be available from all interfaces. +Unix domain socket paths may use the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +.It Cm LogLevel +Gives the verbosity level that is used when logging messages from +.Xr ssh 1 . +The possible values are: +QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3. +The default is INFO. +DEBUG and DEBUG1 are equivalent. +DEBUG2 and DEBUG3 each specify higher levels of verbose output. +.It Cm LogVerbose +Specify one or more overrides to LogLevel. +An override consists of a pattern lists that matches the source file, function +and line number to force detailed logging for. +For example, an override pattern of: +.Bd -literal -offset indent +kex.c:*:1000,*:kex_exchange_identification():*,packet.c:* +.Ed +.Pp +would enable detailed logging for line 1000 of +.Pa kex.c , +everything in the +.Fn kex_exchange_identification +function, and all code in the +.Pa packet.c +file. +This option is intended for debugging and no overrides are enabled by default. +.It Cm MACs +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the MAC (message authentication code) algorithms +in order of preference. +The MAC algorithm is used for data integrity protection. +Multiple algorithms must be comma-separated. +If the specified list begins with a +.Sq + +character, then the specified algorithms will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified algorithms will be placed at the head of the +built-in openssh default set. +.Pp +The algorithms that contain +.Qq -etm +calculate the MAC after encryption (encrypt-then-mac). +These are considered safer and their use recommended. +.Pp +The list of available MAC algorithms may also be obtained using +.Qq ssh -Q mac . +.It Cm NoHostAuthenticationForLocalhost +Disable host authentication for localhost (loopback addresses). +The argument to this keyword must be +.Cm yes +or +.Cm no +(the default). +.It Cm NumberOfPasswordPrompts +Specifies the number of password prompts before giving up. +The argument to this keyword must be an integer. +The default is 3. +.It Cm ObscureKeystrokeTiming +Specifies whether +.Xr ssh 1 +should try to obscure inter-keystroke timings from passive observers of +network traffic. +If enabled, then for interactive sessions, +.Xr ssh 1 +will send keystrokes at fixed intervals of a few tens of milliseconds +and will send fake keystroke packets for some time after typing ceases. +The argument to this keyword must be +.Cm yes , +.Cm no +or an interval specifier of the form +.Cm interval:milliseconds +(e.g.\& +.Cm interval:80 +for 80 milliseconds). +The default is to obscure keystrokes using a 20ms packet interval. +Note that smaller intervals will result in higher fake keystroke packet rates. +.It Cm PasswordAuthentication +Specifies whether to use password authentication. +The argument to this keyword must be +.Cm yes +(the default) +or +.Cm no . +.It Cm PermitLocalCommand +Allow local command execution via the +.Ic LocalCommand +option or using the +.Ic !\& Ns Ar command +escape sequence in +.Xr ssh 1 . +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm PermitRemoteOpen +Specifies the destinations to which remote TCP port forwarding is permitted when +.Cm RemoteForward +is used as a SOCKS proxy. +The forwarding specification must be one of the following forms: +.Pp +.Bl -item -offset indent -compact +.It +.Cm PermitRemoteOpen +.Sm off +.Ar host : port +.Sm on +.It +.Cm PermitRemoteOpen +.Sm off +.Ar IPv4_addr : port +.Sm on +.It +.Cm PermitRemoteOpen +.Sm off +.Ar \&[ IPv6_addr \&] : port +.Sm on +.El +.Pp +Multiple forwards may be specified by separating them with whitespace. +An argument of +.Cm any +can be used to remove all restrictions and permit any forwarding requests. +An argument of +.Cm none +can be used to prohibit all forwarding requests. +The wildcard +.Sq * +can be used for host or port to allow all hosts or ports respectively. +Otherwise, no pattern matching or address lookups are performed on supplied +names. +.It Cm PKCS11Provider +Specifies which PKCS#11 provider to use or +.Cm none +to indicate that no provider should be used (the default). +The argument to this keyword is a path to the PKCS#11 shared library +.Xr ssh 1 +should use to communicate with a PKCS#11 token providing keys for user +authentication. +.It Cm Port +Specifies the port number to connect on the remote host. +The default is 22. +.It Cm PreferredAuthentications +Specifies the order in which the client should try authentication methods. +This allows a client to prefer one method (e.g.\& +.Cm keyboard-interactive ) +over another method (e.g.\& +.Cm password ) . +The default is: +.Bd -literal -offset indent +gssapi-with-mic,hostbased,publickey, +keyboard-interactive,password +.Ed +.It Cm ProxyCommand +Specifies the command to use to connect to the server. +The command +string extends to the end of the line, and is executed +using the user's shell +.Ql exec +directive to avoid a lingering shell process. +.Pp +Arguments to +.Cm ProxyCommand +accept the tokens described in the +.Sx TOKENS +section. +The command can be basically anything, +and should read from its standard input and write to its standard output. +It should eventually connect an +.Xr sshd 8 +server running on some machine, or execute +.Ic sshd -i +somewhere. +Host key management will be done using the +.Cm Hostname +of the host being connected (defaulting to the name typed by the user). +Setting the command to +.Cm none +disables this option entirely. +Note that +.Cm CheckHostIP +is not available for connects with a proxy command. +.Pp +This directive is useful in conjunction with +.Xr nc 1 +and its proxy support. +For example, the following directive would connect via an HTTP proxy at +192.0.2.0: +.Bd -literal -offset 3n +ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p +.Ed +.It Cm ProxyJump +Specifies one or more jump proxies as either +.Xo +.Sm off +.Op Ar user No @ +.Ar host +.Op : Ns Ar port +.Sm on +or an ssh URI +.Xc . +Multiple proxies may be separated by comma characters and will be visited +sequentially. +Setting this option will cause +.Xr ssh 1 +to connect to the target host by first making a +.Xr ssh 1 +connection to the specified +.Cm ProxyJump +host and then establishing a +TCP forwarding to the ultimate target from there. +Setting the host to +.Cm none +disables this option entirely. +.Pp +Note that this option will compete with the +.Cm ProxyCommand +option - whichever is specified first will prevent later instances of the +other from taking effect. +.Pp +Note also that the configuration for the destination host (either supplied +via the command-line or the configuration file) is not generally applied +to jump hosts. +.Pa ~/.ssh/config +should be used if specific configuration is required for jump hosts. +.It Cm ProxyUseFdpass +Specifies that +.Cm ProxyCommand +will pass a connected file descriptor back to +.Xr ssh 1 +instead of continuing to execute and pass data. +The default is +.Cm no . +.It Cm PubkeyAcceptedAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the signature algorithms that will be used for public key +authentication as a comma-separated list of patterns. +If the specified list begins with a +.Sq + +character, then the algorithms after it will be appended to the built-in +openssh default instead of replacing it. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified algorithms will be placed at the head of the +built-in openssh default set. +.Pp +The list of available signature algorithms may also be obtained using +.Qq ssh -Q PubkeyAcceptedAlgorithms . +.Pp +This option affects also +.Cm HostKeyAlgorithms +.It Cm PubkeyAuthentication +Specifies whether to try public key authentication. +The argument to this keyword must be +.Cm yes +(the default), +.Cm no , +.Cm unbound +or +.Cm host-bound . +The final two options enable public key authentication while respectively +disabling or enabling the OpenSSH host-bound authentication protocol +extension required for restricted +.Xr ssh-agent 1 +forwarding. +.It Cm RekeyLimit +Specifies the maximum amount of data that may be transmitted or received +before the session key is renegotiated, optionally followed by a maximum +amount of time that may pass before the session key is renegotiated. +The first argument is specified in bytes and may have a suffix of +.Sq K , +.Sq M , +or +.Sq G +to indicate Kilobytes, Megabytes, or Gigabytes, respectively. +The default is between +.Sq 1G +and +.Sq 4G , +depending on the cipher. +The optional second value is specified in seconds and may use any of the +units documented in the TIME FORMATS section of +.Xr sshd_config 5 . +The default value for +.Cm RekeyLimit +is +.Cm default none , +which means that rekeying is performed after the cipher's default amount +of data has been sent or received and no time based rekeying is done. +.It Cm RemoteCommand +Specifies a command to execute on the remote machine after successfully +connecting to the server. +The command string extends to the end of the line, and is executed with +the user's shell. +Arguments to +.Cm RemoteCommand +accept the tokens described in the +.Sx TOKENS +section. +.It Cm RemoteForward +Specifies that a TCP port on the remote machine be forwarded over +the secure channel. +The remote port may either be forwarded to a specified host and port +from the local machine, or may act as a SOCKS 4/5 proxy that allows a remote +client to connect to arbitrary destinations from the local machine. +The first argument is the listening specification and may be +.Sm off +.Oo Ar bind_address : Oc Ar port +.Sm on +or, if the remote host supports it, a Unix domain socket path. +If forwarding to a specific destination then the second argument must be +.Ar host : Ns Ar hostport +or a Unix domain socket path, +otherwise if no destination argument is specified then the remote forwarding +will be established as a SOCKS proxy. +When acting as a SOCKS proxy, the destination of the connection can be +restricted by +.Cm PermitRemoteOpen . +.Pp +IPv6 addresses can be specified by enclosing addresses in square brackets. +Multiple forwardings may be specified, and additional +forwardings can be given on the command line. +Privileged ports can be forwarded only when +logging in as root on the remote machine. +Unix domain socket paths may use the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +.Pp +If the +.Ar port +argument is 0, +the listen port will be dynamically allocated on the server and reported +to the client at run time. +.Pp +If the +.Ar bind_address +is not specified, the default is to only bind to loopback addresses. +If the +.Ar bind_address +is +.Ql * +or an empty string, then the forwarding is requested to listen on all +interfaces. +Specifying a remote +.Ar bind_address +will only succeed if the server's +.Cm GatewayPorts +option is enabled (see +.Xr sshd_config 5 ) . +.It Cm RequestTTY +Specifies whether to request a pseudo-tty for the session. +The argument may be one of: +.Cm no +(never request a TTY), +.Cm yes +(always request a TTY when standard input is a TTY), +.Cm force +(always request a TTY) or +.Cm auto +(request a TTY when opening a login session). +This option mirrors the +.Fl t +and +.Fl T +flags for +.Xr ssh 1 . +.It Cm RequiredRSASize +Specifies the minimum RSA key size (in bits) that +.Xr ssh 1 +will accept. +User authentication keys smaller than this limit will be ignored. +Servers that present host keys smaller than this limit will cause the +connection to be terminated. +The default is +.Cm 1024 +bits. +Note that this limit may only be raised from the default. +.It Cm RevokedHostKeys +Specifies revoked host public keys. +Keys listed in this file will be refused for host authentication. +Note that if this file does not exist or is not readable, +then host authentication will be refused for all hosts. +Keys may be specified as a text file, listing one public key per line, or as +an OpenSSH Key Revocation List (KRL) as generated by +.Xr ssh-keygen 1 . +For more information on KRLs, see the KEY REVOCATION LISTS section in +.Xr ssh-keygen 1 . +Arguments to +.Cm RevokedHostKeys +may use the tilde syntax to refer to a user's home directory, +the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +.It Cm SecurityKeyProvider +Specifies a path to a library that will be used when loading any +FIDO authenticator-hosted keys, overriding the default of using +the built-in USB HID support. +.Pp +If the specified value begins with a +.Sq $ +character, then it will be treated as an environment variable containing +the path to the library. +.It Cm SendEnv +Specifies what variables from the local +.Xr environ 7 +should be sent to the server. +The server must also support it, and the server must be configured to +accept these environment variables. +Note that the +.Ev TERM +environment variable is always sent whenever a +pseudo-terminal is requested as it is required by the protocol. +Refer to +.Cm AcceptEnv +in +.Xr sshd_config 5 +for how to configure the server. +Variables are specified by name, which may contain wildcard characters. +Multiple environment variables may be separated by whitespace or spread +across multiple +.Cm SendEnv +directives. +.Pp +See +.Sx PATTERNS +for more information on patterns. +.Pp +It is possible to clear previously set +.Cm SendEnv +variable names by prefixing patterns with +.Pa - . +The default is not to send any environment variables. +.It Cm ServerAliveCountMax +Sets the number of server alive messages (see below) which may be +sent without +.Xr ssh 1 +receiving any messages back from the server. +If this threshold is reached while server alive messages are being sent, +ssh will disconnect from the server, terminating the session. +It is important to note that the use of server alive messages is very +different from +.Cm TCPKeepAlive +(below). +The server alive messages are sent through the encrypted channel +and therefore will not be spoofable. +The TCP keepalive option enabled by +.Cm TCPKeepAlive +is spoofable. +The server alive mechanism is valuable when the client or +server depend on knowing when a connection has become unresponsive. +.Pp +The default value is 3. +If, for example, +.Cm ServerAliveInterval +(see below) is set to 15 and +.Cm ServerAliveCountMax +is left at the default, if the server becomes unresponsive, +ssh will disconnect after approximately 45 seconds. +.It Cm ServerAliveInterval +Sets a timeout interval in seconds after which if no data has been received +from the server, +.Xr ssh 1 +will send a message through the encrypted +channel to request a response from the server. +The default +is 0, indicating that these messages will not be sent to the server. +.It Cm SessionType +May be used to either request invocation of a subsystem on the remote system, +or to prevent the execution of a remote command at all. +The latter is useful for just forwarding ports. +The argument to this keyword must be +.Cm none +(same as the +.Fl N +option), +.Cm subsystem +(same as the +.Fl s +option) or +.Cm default +(shell or command execution). +.It Cm SetEnv +Directly specify one or more environment variables and their contents to +be sent to the server. +Similarly to +.Cm SendEnv , +with the exception of the +.Ev TERM +variable, the server must be prepared to accept the environment variable. +.It Cm StdinNull +Redirects stdin from +.Pa /dev/null +(actually, prevents reading from stdin). +Either this or the equivalent +.Fl n +option must be used when +.Nm ssh +is run in the background. +The argument to this keyword must be +.Cm yes +(same as the +.Fl n +option) or +.Cm no +(the default). +.It Cm StreamLocalBindMask +Sets the octal file creation mode mask +.Pq umask +used when creating a Unix-domain socket file for local or remote +port forwarding. +This option is only used for port forwarding to a Unix-domain socket file. +.Pp +The default value is 0177, which creates a Unix-domain socket file that is +readable and writable only by the owner. +Note that not all operating systems honor the file mode on Unix-domain +socket files. +.It Cm StreamLocalBindUnlink +Specifies whether to remove an existing Unix-domain socket file for local +or remote port forwarding before creating a new one. +If the socket file already exists and +.Cm StreamLocalBindUnlink +is not enabled, +.Nm ssh +will be unable to forward the port to the Unix-domain socket file. +This option is only used for port forwarding to a Unix-domain socket file. +.Pp +The argument must be +.Cm yes +or +.Cm no +(the default). +.It Cm StrictHostKeyChecking +If this flag is set to +.Cm yes , +.Xr ssh 1 +will never automatically add host keys to the +.Pa ~/.ssh/known_hosts +file, and refuses to connect to hosts whose host key has changed. +This provides maximum protection against man-in-the-middle (MITM) attacks, +though it can be annoying when the +.Pa /etc/ssh/ssh_known_hosts +file is poorly maintained or when connections to new hosts are +frequently made. +This option forces the user to manually +add all new hosts. +.Pp +If this flag is set to +.Cm accept-new +then ssh will automatically add new host keys to the user's +.Pa known_hosts +file, but will not permit connections to hosts with +changed host keys. +If this flag is set to +.Cm no +or +.Cm off , +ssh will automatically add new host keys to the user known hosts files +and allow connections to hosts with changed hostkeys to proceed, +subject to some restrictions. +If this flag is set to +.Cm ask +(the default), +new host keys +will be added to the user known host files only after the user +has confirmed that is what they really want to do, and +ssh will refuse to connect to hosts whose host key has changed. +The host keys of +known hosts will be verified automatically in all cases. +.It Cm SyslogFacility +Gives the facility code that is used when logging messages from +.Xr ssh 1 . +The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2, +LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7. +The default is USER. +.It Cm TCPKeepAlive +Specifies whether the system should send TCP keepalive messages to the +other side. +If they are sent, death of the connection or crash of one +of the machines will be properly noticed. +However, this means that +connections will die if the route is down temporarily, and some people +find it annoying. +.Pp +The default is +.Cm yes +(to send TCP keepalive messages), and the client will notice +if the network goes down or the remote host dies. +This is important in scripts, and many users want it too. +.Pp +To disable TCP keepalive messages, the value should be set to +.Cm no . +See also +.Cm ServerAliveInterval +for protocol-level keepalives. +.It Cm Tag +Specify a configuration tag name that may be later used by a +.Cm Match +directive to select a block of configuration. +.It Cm Tunnel +Request +.Xr tun 4 +device forwarding between the client and the server. +The argument must be +.Cm yes , +.Cm point-to-point +(layer 3), +.Cm ethernet +(layer 2), +or +.Cm no +(the default). +Specifying +.Cm yes +requests the default tunnel mode, which is +.Cm point-to-point . +.It Cm TunnelDevice +Specifies the +.Xr tun 4 +devices to open on the client +.Pq Ar local_tun +and the server +.Pq Ar remote_tun . +.Pp +The argument must be +.Sm off +.Ar local_tun Op : Ar remote_tun . +.Sm on +The devices may be specified by numerical ID or the keyword +.Cm any , +which uses the next available tunnel device. +If +.Ar remote_tun +is not specified, it defaults to +.Cm any . +The default is +.Cm any:any . +.It Cm UpdateHostKeys +Specifies whether +.Xr ssh 1 +should accept notifications of additional hostkeys from the server sent +after authentication has completed and add them to +.Cm UserKnownHostsFile . +The argument must be +.Cm yes , +.Cm no +or +.Cm ask . +This option allows learning alternate hostkeys for a server +and supports graceful key rotation by allowing a server to send replacement +public keys before old ones are removed. +.Pp +Additional hostkeys are only accepted if the key used to authenticate the +host was already trusted or explicitly accepted by the user, the host was +authenticated via +.Cm UserKnownHostsFile +(i.e. not +.Cm GlobalKnownHostsFile ) +and the host was authenticated using a plain key and not a certificate. +.Pp +.Cm UpdateHostKeys +is enabled by default if the user has not overridden the default +.Cm UserKnownHostsFile +setting and has not enabled +.Cm VerifyHostKeyDNS , +otherwise +.Cm UpdateHostKeys +will be set to +.Cm no . +.Pp +If +.Cm UpdateHostKeys +is set to +.Cm ask , +then the user is asked to confirm the modifications to the known_hosts file. +Confirmation is currently incompatible with +.Cm ControlPersist , +and will be disabled if it is enabled. +.Pp +Presently, only +.Xr sshd 8 +from OpenSSH 6.8 and greater support the +.Qq hostkeys@openssh.com +protocol extension used to inform the client of all the server's hostkeys. +.It Cm User +Specifies the user to log in as. +This can be useful when a different user name is used on different machines. +This saves the trouble of +having to remember to give the user name on the command line. +.It Cm UserKnownHostsFile +Specifies one or more files to use for the user +host key database, separated by whitespace. +Each filename may use tilde notation to refer to the user's home directory, +the tokens described in the +.Sx TOKENS +section and environment variables as described in the +.Sx ENVIRONMENT VARIABLES +section. +A value of +.Cm none +causes +.Xr ssh 1 +to ignore any user-specific known hosts files. +The default is +.Pa ~/.ssh/known_hosts , +.Pa ~/.ssh/known_hosts2 . +.It Cm VerifyHostKeyDNS +Specifies whether to verify the remote key using DNS and SSHFP resource +records. +If this option is set to +.Cm yes , +the client will implicitly trust keys that match a secure fingerprint +from DNS. +Insecure fingerprints will be handled as if this option was set to +.Cm ask . +If this option is set to +.Cm ask , +information on fingerprint match will be displayed, but the user will still +need to confirm new host keys according to the +.Cm StrictHostKeyChecking +option. +The default is +.Cm no . +.Pp +See also +.Sx VERIFYING HOST KEYS +in +.Xr ssh 1 . +.It Cm VisualHostKey +If this flag is set to +.Cm yes , +an ASCII art representation of the remote host key fingerprint is +printed in addition to the fingerprint string at login and +for unknown host keys. +If this flag is set to +.Cm no +(the default), +no fingerprint strings are printed at login and +only the fingerprint string will be printed for unknown host keys. +.It Cm XAuthLocation +Specifies the full pathname of the +.Xr xauth 1 +program. +The default is +.Pa /usr/bin/xauth . +.El +.Sh PATTERNS +A +.Em pattern +consists of zero or more non-whitespace characters, +.Sq * +(a wildcard that matches zero or more characters), +or +.Sq ?\& +(a wildcard that matches exactly one character). +For example, to specify a set of declarations for any host in the +.Qq .co.uk +set of domains, +the following pattern could be used: +.Pp +.Dl Host *.co.uk +.Pp +The following pattern +would match any host in the 192.168.0.[0-9] network range: +.Pp +.Dl Host 192.168.0.? +.Pp +A +.Em pattern-list +is a comma-separated list of patterns. +Patterns within pattern-lists may be negated +by preceding them with an exclamation mark +.Pq Sq !\& . +For example, +to allow a key to be used from anywhere within an organization +except from the +.Qq dialup +pool, +the following entry (in authorized_keys) could be used: +.Pp +.Dl from=\&"!*.dialup.example.com,*.example.com\&" +.Pp +Note that a negated match will never produce a positive result by itself. +For example, attempting to match +.Qq host3 +against the following pattern-list will fail: +.Pp +.Dl from=\&"!host1,!host2\&" +.Pp +The solution here is to include a term that will yield a positive match, +such as a wildcard: +.Pp +.Dl from=\&"!host1,!host2,*\&" +.Sh TOKENS +Arguments to some keywords can make use of tokens, +which are expanded at runtime: +.Pp +.Bl -tag -width XXXX -offset indent -compact +.It %% +A literal +.Sq % . +.It \&%C +Hash of %l%h%p%r%j. +.It %d +Local user's home directory. +.It %f +The fingerprint of the server's host key. +.It %H +The +.Pa known_hosts +hostname or address that is being searched for. +.It %h +The remote hostname. +.It \%%I +A string describing the reason for a +.Cm KnownHostsCommand +execution: either +.Cm ADDRESS +when looking up a host by address (only when +.Cm CheckHostIP +is enabled), +.Cm HOSTNAME +when searching by hostname, or +.Cm ORDER +when preparing the host key algorithm preference list to use for the +destination host. +.It %i +The local user ID. +.It %j +The contents of the ProxyJump option, or the empty string if this +option is unset. +.It %K +The base64 encoded host key. +.It %k +The host key alias if specified, otherwise the original remote hostname given +on the command line. +.It %L +The local hostname. +.It %l +The local hostname, including the domain name. +.It %n +The original remote hostname, as given on the command line. +.It %p +The remote port. +.It %r +The remote username. +.It \&%T +The local +.Xr tun 4 +or +.Xr tap 4 +network interface assigned if +tunnel forwarding was requested, or +.Qq NONE +otherwise. +.It %t +The type of the server host key, e.g. +.Cm ssh-ed25519 . +.It %u +The local username. +.El +.Pp +.Cm CertificateFile , +.Cm ControlPath , +.Cm IdentityAgent , +.Cm IdentityFile , +.Cm KnownHostsCommand , +.Cm LocalForward , +.Cm Match exec , +.Cm RemoteCommand , +.Cm RemoteForward , +.Cm RevokedHostKeys , +and +.Cm UserKnownHostsFile +accept the tokens %%, %C, %d, %h, %i, %j, %k, %L, %l, %n, %p, %r, and %u. +.Pp +.Cm KnownHostsCommand +additionally accepts the tokens %f, %H, %I, %K and %t. +.Pp +.Cm Hostname +accepts the tokens %% and %h. +.Pp +.Cm LocalCommand +accepts all tokens. +.Pp +.Cm ProxyCommand +and +.Cm ProxyJump +accept the tokens %%, %h, %n, %p, and %r. +.Pp +Note that some of these directives build commands for execution via the shell. +Because +.Xr ssh 1 +performs no filtering or escaping of characters that have special meaning in +shell commands (e.g. quotes), it is the user's responsibility to ensure that +the arguments passed to +.Xr ssh 1 +do not contain such characters and that tokens are appropriately quoted +when used. +.Sh ENVIRONMENT VARIABLES +Arguments to some keywords can be expanded at runtime from environment +variables on the client by enclosing them in +.Ic ${} , +for example +.Ic ${HOME}/.ssh +would refer to the user's .ssh directory. +If a specified environment variable does not exist then an error will be +returned and the setting for that keyword will be ignored. +.Pp +The keywords +.Cm CertificateFile , +.Cm ControlPath , +.Cm IdentityAgent , +.Cm IdentityFile , +.Cm KnownHostsCommand , +and +.Cm UserKnownHostsFile +support environment variables. +The keywords +.Cm LocalForward +and +.Cm RemoteForward +support environment variables only for Unix domain socket paths. +.Sh FILES +.Bl -tag -width Ds +.It Pa ~/.ssh/config +This is the per-user configuration file. +The format of this file is described above. +This file is used by the SSH client. +Because of the potential for abuse, this file must have strict permissions: +read/write for the user, and not writable by others. +.It Pa /etc/ssh/ssh_config +Systemwide configuration file. +This file provides defaults for those +values that are not specified in the user's configuration file, and +for those users who do not have a configuration file. +This file must be world-readable. +.El +.Sh SEE ALSO +.Xr ssh 1 , +.Xr crypto-policies 7 , +.Xr update-crypto-policies 8 +.Sh AUTHORS +.An -nosplit +OpenSSH is a derivative of the original and free +ssh 1.2.12 release by +.An Tatu Ylonen . +.An Aaron Campbell , Bob Beck , Markus Friedl , +.An Niels Provos , Theo de Raadt +and +.An Dug Song +removed many bugs, re-added newer features and +created OpenSSH. +.An Markus Friedl +contributed the support for SSH protocol versions 1.5 and 2.0. diff --git a/upstream/fedora-40/man5/sshd_config.5 b/upstream/fedora-40/man5/sshd_config.5 new file mode 100644 index 00000000..7964833e --- /dev/null +++ b/upstream/fedora-40/man5/sshd_config.5 @@ -0,0 +1,2110 @@ +.\" +.\" Author: Tatu Ylonen +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" As far as I am concerned, the code I have written for this software +.\" can be used freely for any purpose. Any derived versions of this +.\" software must be clearly marked as such, and if the derived work is +.\" incompatible with the protocol description in the RFC file, it must be +.\" called by a name other than "ssh" or "Secure Shell". +.\" +.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. +.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. +.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $OpenBSD: sshd_config.5,v 1.350 2023/07/28 05:42:36 jmc Exp $ +.Dd $Mdocdate: July 28 2023 $ +.Dt SSHD_CONFIG 5 +.Os +.Sh NAME +.Nm sshd_config +.Nd OpenSSH daemon configuration file +.Sh DESCRIPTION +.Xr sshd 8 +reads configuration data from +.Pa /etc/ssh/sshd_config +(or the file specified with +.Fl f +on the command line). +The file contains keyword-argument pairs, one per line. +Unless noted otherwise, for each keyword, the first obtained value will be used. +Lines starting with +.Ql # +and empty lines are interpreted as comments. +Arguments may optionally be enclosed in double quotes +.Pq \&" +in order to represent arguments containing spaces. +.Pp +The possible +keywords and their meanings are as follows (note that +keywords are case-insensitive and arguments are case-sensitive): +.Bl -tag -width Ds +.It Cm AcceptEnv +Specifies what environment variables sent by the client will be copied into +the session's +.Xr environ 7 . +See +.Cm SendEnv +and +.Cm SetEnv +in +.Xr ssh_config 5 +for how to configure the client. +The +.Ev TERM +environment variable is always accepted whenever the client +requests a pseudo-terminal as it is required by the protocol. +Variables are specified by name, which may contain the wildcard characters +.Ql * +and +.Ql \&? . +Multiple environment variables may be separated by whitespace or spread +across multiple +.Cm AcceptEnv +directives. +Be warned that some environment variables could be used to bypass restricted +user environments. +For this reason, care should be taken in the use of this directive. +The default is not to accept any environment variables. +.It Cm AddressFamily +Specifies which address family should be used by +.Xr sshd 8 . +Valid arguments are +.Cm any +(the default), +.Cm inet +(use IPv4 only), or +.Cm inet6 +(use IPv6 only). +.It Cm AllowAgentForwarding +Specifies whether +.Xr ssh-agent 1 +forwarding is permitted. +The default is +.Cm yes . +Note that disabling agent forwarding does not improve security +unless users are also denied shell access, as they can always install +their own forwarders. +.It Cm AllowGroups +This keyword can be followed by a list of group name patterns, separated +by spaces. +If specified, login is allowed only for users whose primary +group or supplementary group list matches one of the patterns. +Only group names are valid; a numerical group ID is not recognized. +By default, login is allowed for all groups. +The allow/deny groups directives are processed in the following order: +.Cm DenyGroups , +.Cm AllowGroups . +.Pp +See PATTERNS in +.Xr ssh_config 5 +for more information on patterns. +This keyword may appear multiple times in +.Nm +with each instance appending to the list. +.It Cm AllowStreamLocalForwarding +Specifies whether StreamLocal (Unix-domain socket) forwarding is permitted. +The available options are +.Cm yes +(the default) +or +.Cm all +to allow StreamLocal forwarding, +.Cm no +to prevent all StreamLocal forwarding, +.Cm local +to allow local (from the perspective of +.Xr ssh 1 ) +forwarding only or +.Cm remote +to allow remote forwarding only. +Note that disabling StreamLocal forwarding does not improve security unless +users are also denied shell access, as they can always install their +own forwarders. +.It Cm AllowTcpForwarding +Specifies whether TCP forwarding is permitted. +The available options are +.Cm yes +(the default) +or +.Cm all +to allow TCP forwarding, +.Cm no +to prevent all TCP forwarding, +.Cm local +to allow local (from the perspective of +.Xr ssh 1 ) +forwarding only or +.Cm remote +to allow remote forwarding only. +Note that disabling TCP forwarding does not improve security unless +users are also denied shell access, as they can always install their +own forwarders. +.It Cm AllowUsers +This keyword can be followed by a list of user name patterns, separated +by spaces. +If specified, login is allowed only for user names that +match one of the patterns. +Only user names are valid; a numerical user ID is not recognized. +By default, login is allowed for all users. +If the pattern takes the form USER@HOST then USER and HOST +are separately checked, restricting logins to particular +users from particular hosts. +HOST criteria may additionally contain addresses to match in CIDR +address/masklen format. +The allow/deny users directives are processed in the following order: +.Cm DenyUsers , +.Cm AllowUsers . +.Pp +See PATTERNS in +.Xr ssh_config 5 +for more information on patterns. +This keyword may appear multiple times in +.Nm +with each instance appending to the list. +.It Cm AuthenticationMethods +Specifies the authentication methods that must be successfully completed +for a user to be granted access. +This option must be followed by one or more lists of comma-separated +authentication method names, or by the single string +.Cm any +to indicate the default behaviour of accepting any single authentication +method. +If the default is overridden, then successful authentication requires +completion of every method in at least one of these lists. +.Pp +For example, +.Qq publickey,password publickey,keyboard-interactive +would require the user to complete public key authentication, followed by +either password or keyboard interactive authentication. +Only methods that are next in one or more lists are offered at each stage, +so for this example it would not be possible to attempt password or +keyboard-interactive authentication before public key. +.Pp +For keyboard interactive authentication it is also possible to +restrict authentication to a specific device by appending a +colon followed by the device identifier +.Cm bsdauth +or +.Cm pam . +depending on the server configuration. +For example, +.Qq keyboard-interactive:bsdauth +would restrict keyboard interactive authentication to the +.Cm bsdauth +device. +.Pp +If the publickey method is listed more than once, +.Xr sshd 8 +verifies that keys that have been used successfully are not reused for +subsequent authentications. +For example, +.Qq publickey,publickey +requires successful authentication using two different public keys. +.Pp +Note that each authentication method listed should also be explicitly enabled +in the configuration. +.Pp +The available authentication methods are: +.Qq gssapi-with-mic , +.Qq hostbased , +.Qq keyboard-interactive , +.Qq none +(used for access to password-less accounts when +.Cm PermitEmptyPasswords +is enabled), +.Qq password +and +.Qq publickey . +.It Cm AuthorizedKeysCommand +Specifies a program to be used to look up the user's public keys. +The program must be owned by root, not writable by group or others and +specified by an absolute path. +Arguments to +.Cm AuthorizedKeysCommand +accept the tokens described in the +.Sx TOKENS +section. +If no arguments are specified then the username of the target user is used. +.Pp +The program should produce on standard output zero or +more lines of authorized_keys output (see +.Sx AUTHORIZED_KEYS +in +.Xr sshd 8 ) . +.Cm AuthorizedKeysCommand +is tried after the usual +.Cm AuthorizedKeysFile +files and will not be executed if a matching key is found there. +By default, no +.Cm AuthorizedKeysCommand +is run. +.It Cm AuthorizedKeysCommandUser +Specifies the user under whose account the +.Cm AuthorizedKeysCommand +is run. +It is recommended to use a dedicated user that has no other role on the host +than running authorized keys commands. +If +.Cm AuthorizedKeysCommand +is specified but +.Cm AuthorizedKeysCommandUser +is not, then +.Xr sshd 8 +will refuse to start. +.It Cm AuthorizedKeysFile +Specifies the file that contains the public keys used for user authentication. +The format is described in the AUTHORIZED_KEYS FILE FORMAT section of +.Xr sshd 8 . +Arguments to +.Cm AuthorizedKeysFile +accept the tokens described in the +.Sx TOKENS +section. +After expansion, +.Cm AuthorizedKeysFile +is taken to be an absolute path or one relative to the user's home +directory. +Multiple files may be listed, separated by whitespace. +Alternately this option may be set to +.Cm none +to skip checking for user keys in files. +The default is +.Qq .ssh/authorized_keys .ssh/authorized_keys2 . +.It Cm AuthorizedPrincipalsCommand +Specifies a program to be used to generate the list of allowed +certificate principals as per +.Cm AuthorizedPrincipalsFile . +The program must be owned by root, not writable by group or others and +specified by an absolute path. +Arguments to +.Cm AuthorizedPrincipalsCommand +accept the tokens described in the +.Sx TOKENS +section. +If no arguments are specified then the username of the target user is used. +.Pp +The program should produce on standard output zero or +more lines of +.Cm AuthorizedPrincipalsFile +output. +If either +.Cm AuthorizedPrincipalsCommand +or +.Cm AuthorizedPrincipalsFile +is specified, then certificates offered by the client for authentication +must contain a principal that is listed. +By default, no +.Cm AuthorizedPrincipalsCommand +is run. +.It Cm AuthorizedPrincipalsCommandUser +Specifies the user under whose account the +.Cm AuthorizedPrincipalsCommand +is run. +It is recommended to use a dedicated user that has no other role on the host +than running authorized principals commands. +If +.Cm AuthorizedPrincipalsCommand +is specified but +.Cm AuthorizedPrincipalsCommandUser +is not, then +.Xr sshd 8 +will refuse to start. +.It Cm AuthorizedPrincipalsFile +Specifies a file that lists principal names that are accepted for +certificate authentication. +When using certificates signed by a key listed in +.Cm TrustedUserCAKeys , +this file lists names, one of which must appear in the certificate for it +to be accepted for authentication. +Names are listed one per line preceded by key options (as described in +.Sx AUTHORIZED_KEYS FILE FORMAT +in +.Xr sshd 8 ) . +Empty lines and comments starting with +.Ql # +are ignored. +.Pp +Arguments to +.Cm AuthorizedPrincipalsFile +accept the tokens described in the +.Sx TOKENS +section. +After expansion, +.Cm AuthorizedPrincipalsFile +is taken to be an absolute path or one relative to the user's home directory. +The default is +.Cm none , +i.e. not to use a principals file \(en in this case, the username +of the user must appear in a certificate's principals list for it to be +accepted. +.Pp +Note that +.Cm AuthorizedPrincipalsFile +is only used when authentication proceeds using a CA listed in +.Cm TrustedUserCAKeys +and is not consulted for certification authorities trusted via +.Pa ~/.ssh/authorized_keys , +though the +.Cm principals= +key option offers a similar facility (see +.Xr sshd 8 +for details). +.It Cm Banner +The contents of the specified file are sent to the remote user before +authentication is allowed. +If the argument is +.Cm none +then no banner is displayed. +By default, no banner is displayed. +.It Cm CASignatureAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies which algorithms are allowed for signing of certificates +by certificate authorities (CAs). +If the specified list begins with a +.Sq + +character, then the specified algorithms will be appended to the default set +instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the default set instead of replacing them. +.Pp +Certificates signed using other algorithms will not be accepted for +public key or host-based authentication. +.It Cm ChannelTimeout +Specifies whether and how quickly +.Xr sshd 8 +should close inactive channels. +Timeouts are specified as one or more +.Dq type=interval +pairs separated by whitespace, where the +.Dq type +must be a channel type name (as described in the table below), optionally +containing wildcard characters. +.Pp +The timeout value +.Dq interval +is specified in seconds or may use any of the units documented in the +.Sx TIME FORMATS +section. +For example, +.Dq session:*=5m +would cause all sessions to terminate after five minutes of inactivity. +Specifying a zero value disables the inactivity timeout. +.Pp +The available channel types include: +.Bl -tag -width Ds +.It Cm agent-connection +Open connections to +.Xr ssh-agent 1 . +.It Cm direct-tcpip , Cm direct-streamlocal@openssh.com +Open TCP or Unix socket (respectively) connections that have +been established from a +.Xr ssh 1 +local forwarding, i.e.\& +.Cm LocalForward +or +.Cm DynamicForward . +.It Cm forwarded-tcpip , Cm forwarded-streamlocal@openssh.com +Open TCP or Unix socket (respectively) connections that have been +established to a +.Xr sshd 8 +listening on behalf of a +.Xr ssh 1 +remote forwarding, i.e.\& +.Cm RemoteForward . +.It Cm session:command +Command execution sessions. +.It Cm session:shell +Interactive shell sessions. +.It Cm session:subsystem:... +Subsystem sessions, e.g. for +.Xr sftp 1 , +which could be identified as +.Cm session:subsystem:sftp . +.It Cm x11-connection +Open X11 forwarding sessions. +.El +.Pp +Note that in all the above cases, terminating an inactive session does not +guarantee to remove all resources associated with the session, e.g. shell +processes or X11 clients relating to the session may continue to execute. +.Pp +Moreover, terminating an inactive channel or session does not necessarily +close the SSH connection, nor does it prevent a client from +requesting another channel of the same type. +In particular, expiring an inactive forwarding session does not prevent +another identical forwarding from being subsequently created. +See also +.Cm UnusedConnectionTimeout , +which may be used in conjunction with this option. +.Pp +The default is not to expire channels of any type for inactivity. +.It Cm ChrootDirectory +Specifies the pathname of a directory to +.Xr chroot 2 +to after authentication. +At session startup +.Xr sshd 8 +checks that all components of the pathname are root-owned directories +which are not writable by any other user or group. +After the chroot, +.Xr sshd 8 +changes the working directory to the user's home directory. +Arguments to +.Cm ChrootDirectory +accept the tokens described in the +.Sx TOKENS +section. +.Pp +The +.Cm ChrootDirectory +must contain the necessary files and directories to support the +user's session. +For an interactive session this requires at least a shell, typically +.Xr sh 1 , +and basic +.Pa /dev +nodes such as +.Xr null 4 , +.Xr zero 4 , +.Xr stdin 4 , +.Xr stdout 4 , +.Xr stderr 4 , +and +.Xr tty 4 +devices. +For file transfer sessions using SFTP +no additional configuration of the environment is necessary if the in-process +sftp-server is used, +though sessions which use logging may require +.Pa /dev/log +inside the chroot directory on some operating systems (see +.Xr sftp-server 8 +for details). +.Pp +For safety, it is very important that the directory hierarchy be +prevented from modification by other processes on the system (especially +those outside the jail). +Misconfiguration can lead to unsafe environments which +.Xr sshd 8 +cannot detect. +.Pp +The default is +.Cm none , +indicating not to +.Xr chroot 2 . +.It Cm Ciphers +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the ciphers allowed. +Multiple ciphers must be comma-separated. +If the specified list begins with a +.Sq + +character, then the specified ciphers will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified ciphers (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified ciphers will be placed at the head of the +built-in openssh default set. +.Pp +The supported ciphers are: +.Pp +.Bl -item -compact -offset indent +.It +3des-cbc +.It +aes128-cbc +.It +aes192-cbc +.It +aes256-cbc +.It +aes128-ctr +.It +aes192-ctr +.It +aes256-ctr +.It +aes128-gcm@openssh.com +.It +aes256-gcm@openssh.com +.It +chacha20-poly1305@openssh.com +.El +.Pp +The list of available ciphers may also be obtained using +.Qq ssh -Q cipher . +.It Cm ClientAliveCountMax +Sets the number of client alive messages which may be sent without +.Xr sshd 8 +receiving any messages back from the client. +If this threshold is reached while client alive messages are being sent, +sshd will disconnect the client, terminating the session. +It is important to note that the use of client alive messages is very +different from +.Cm TCPKeepAlive . +The client alive messages are sent through the encrypted channel +and therefore will not be spoofable. +The TCP keepalive option enabled by +.Cm TCPKeepAlive +is spoofable. +The client alive mechanism is valuable when the client or +server depend on knowing when a connection has become unresponsive. +.Pp +The default value is 3. +If +.Cm ClientAliveInterval +is set to 15, and +.Cm ClientAliveCountMax +is left at the default, unresponsive SSH clients +will be disconnected after approximately 45 seconds. +Setting a zero +.Cm ClientAliveCountMax +disables connection termination. +.It Cm ClientAliveInterval +Sets a timeout interval in seconds after which if no data has been received +from the client, +.Xr sshd 8 +will send a message through the encrypted +channel to request a response from the client. +The default +is 0, indicating that these messages will not be sent to the client. +.It Cm Compression +Specifies whether compression is enabled after +the user has authenticated successfully. +The argument must be +.Cm yes , +.Cm delayed +(a legacy synonym for +.Cm yes ) +or +.Cm no . +The default is +.Cm yes . +.It Cm DenyGroups +This keyword can be followed by a list of group name patterns, separated +by spaces. +Login is disallowed for users whose primary group or supplementary +group list matches one of the patterns. +Only group names are valid; a numerical group ID is not recognized. +By default, login is allowed for all groups. +The allow/deny groups directives are processed in the following order: +.Cm DenyGroups , +.Cm AllowGroups . +.Pp +See PATTERNS in +.Xr ssh_config 5 +for more information on patterns. +This keyword may appear multiple times in +.Nm +with each instance appending to the list. +.It Cm DenyUsers +This keyword can be followed by a list of user name patterns, separated +by spaces. +Login is disallowed for user names that match one of the patterns. +Only user names are valid; a numerical user ID is not recognized. +By default, login is allowed for all users. +If the pattern takes the form USER@HOST then USER and HOST +are separately checked, restricting logins to particular +users from particular hosts. +HOST criteria may additionally contain addresses to match in CIDR +address/masklen format. +The allow/deny users directives are processed in the following order: +.Cm DenyUsers , +.Cm AllowUsers . +.Pp +See PATTERNS in +.Xr ssh_config 5 +for more information on patterns. +This keyword may appear multiple times in +.Nm +with each instance appending to the list. +.It Cm DisableForwarding +Disables all forwarding features, including X11, +.Xr ssh-agent 1 , +TCP and StreamLocal. +This option overrides all other forwarding-related options and may +simplify restricted configurations. +.It Cm ExposeAuthInfo +Writes a temporary file containing a list of authentication methods and +public credentials (e.g. keys) used to authenticate the user. +The location of the file is exposed to the user session through the +.Ev SSH_USER_AUTH +environment variable. +The default is +.Cm no . +.It Cm FingerprintHash +Specifies the hash algorithm used when logging key fingerprints. +Valid options are: +.Cm md5 +and +.Cm sha256 . +The default is +.Cm sha256 . +.It Cm ForceCommand +Forces the execution of the command specified by +.Cm ForceCommand , +ignoring any command supplied by the client and +.Pa ~/.ssh/rc +if present. +The command is invoked by using the user's login shell with the -c option. +This applies to shell, command, or subsystem execution. +It is most useful inside a +.Cm Match +block. +The command originally supplied by the client is available in the +.Ev SSH_ORIGINAL_COMMAND +environment variable. +Specifying a command of +.Cm internal-sftp +will force the use of an in-process SFTP server that requires no support +files when used with +.Cm ChrootDirectory . +The default is +.Cm none . +.It Cm GatewayPorts +Specifies whether remote hosts are allowed to connect to ports +forwarded for the client. +By default, +.Xr sshd 8 +binds remote port forwardings to the loopback address. +This prevents other remote hosts from connecting to forwarded ports. +.Cm GatewayPorts +can be used to specify that sshd +should allow remote port forwardings to bind to non-loopback addresses, thus +allowing other hosts to connect. +The argument may be +.Cm no +to force remote port forwardings to be available to the local host only, +.Cm yes +to force remote port forwardings to bind to the wildcard address, or +.Cm clientspecified +to allow the client to select the address to which the forwarding is bound. +The default is +.Cm no . +.It Cm GSSAPIAuthentication +Specifies whether user authentication based on GSSAPI is allowed. +The default is +.Cm no . +.It Cm GSSAPICleanupCredentials +Specifies whether to automatically destroy the user's credentials cache +on logout. +The default is +.Cm yes . +.It Cm GSSAPIEnablek5users +Specifies whether to look at .k5users file for GSSAPI authentication +access control. Further details are described in +.Xr ksu 1 . +The default is +.Cm no . +.It Cm GSSAPIKeyExchange +Specifies whether key exchange based on GSSAPI is allowed. GSSAPI key exchange +doesn't rely on ssh keys to verify host identity. +The default is +.Cm no . +.It Cm GSSAPIStrictAcceptorCheck +Determines whether to be strict about the identity of the GSSAPI acceptor +a client authenticates against. +If set to +.Cm yes +then the client must authenticate against the host +service on the current hostname. +If set to +.Cm no +then the client may authenticate against any service key stored in the +machine's default store. +This facility is provided to assist with operation on multi homed machines. +The default is +.Cm yes . +.It Cm GSSAPIStoreCredentialsOnRekey +Controls whether the user's GSSAPI credentials should be updated following a +successful connection rekeying. This option can be used to accepted renewed +or updated credentials from a compatible client. The default is +.Dq no . +.Pp +For this to work +.Cm GSSAPIKeyExchange +needs to be enabled in the server and also used by the client. +.It Cm GSSAPIKexAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +The list of key exchange algorithms that are accepted by GSSAPI +key exchange. Possible values are +.Bd -literal -offset 3n +gss-gex-sha1- +gss-group1-sha1- +gss-group14-sha1- +gss-group14-sha256- +gss-group16-sha512- +gss-nistp256-sha256- +gss-curve25519-sha256- +.Ed +This option only applies to connections using GSSAPI. +.It Cm HostbasedAcceptedAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the signature algorithms that will be accepted for hostbased +authentication as a list of comma-separated patterns. +Alternately if the specified list begins with a +.Sq + +character, then the specified signature algorithms will be appended to +the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified signature algorithms (including wildcards) +will be removed from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified signature algorithms will be placed at +the head of the built-in openssh default set. +.Pp +The list of available signature algorithms may also be obtained using +.Qq ssh -Q HostbasedAcceptedAlgorithms . +This was formerly named HostbasedAcceptedKeyTypes. +.It Cm HostbasedAuthentication +Specifies whether rhosts or /etc/hosts.equiv authentication together +with successful public key client host authentication is allowed +(host-based authentication). +The default is +.Cm no . +.It Cm HostbasedUsesNameFromPacketOnly +Specifies whether or not the server will attempt to perform a reverse +name lookup when matching the name in the +.Pa ~/.shosts , +.Pa ~/.rhosts , +and +.Pa /etc/hosts.equiv +files during +.Cm HostbasedAuthentication . +A setting of +.Cm yes +means that +.Xr sshd 8 +uses the name supplied by the client rather than +attempting to resolve the name from the TCP connection itself. +The default is +.Cm no . +.It Cm HostCertificate +Specifies a file containing a public host certificate. +The certificate's public key must match a private host key already specified +by +.Cm HostKey . +The default behaviour of +.Xr sshd 8 +is not to load any certificates. +.It Cm HostKey +Specifies a file containing a private host key +used by SSH. +The defaults are +.Pa /etc/ssh/ssh_host_ecdsa_key , +.Pa /etc/ssh/ssh_host_ed25519_key +and +.Pa /etc/ssh/ssh_host_rsa_key . +.Pp +Note that +.Xr sshd 8 +will refuse to use a file if it is group/world-accessible +and that the +.Cm HostKeyAlgorithms +option restricts which of the keys are actually used by +.Xr sshd 8 . +.Pp +It is possible to have multiple host key files. +It is also possible to specify public host key files instead. +In this case operations on the private key will be delegated +to an +.Xr ssh-agent 1 . +.It Cm HostKeyAgent +Identifies the UNIX-domain socket used to communicate +with an agent that has access to the private host keys. +If the string +.Qq SSH_AUTH_SOCK +is specified, the location of the socket will be read from the +.Ev SSH_AUTH_SOCK +environment variable. +.It Cm HostKeyAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the host key signature algorithms +that the server offers. +The default for this option is: +The list of available signature algorithms may also be obtained using +.Qq ssh -Q HostKeyAlgorithms . +.It Cm IgnoreRhosts +Specifies whether to ignore per-user +.Pa .rhosts +and +.Pa .shosts +files during +.Cm HostbasedAuthentication . +The system-wide +.Pa /etc/hosts.equiv +and +.Pa /etc/ssh/shosts.equiv +are still used regardless of this setting. +.Pp +Accepted values are +.Cm yes +(the default) to ignore all per-user files, +.Cm shosts-only +to allow the use of +.Pa .shosts +but to ignore +.Pa .rhosts +or +.Cm no +to allow both +.Pa .shosts +and +.Pa rhosts . +.It Cm IgnoreUserKnownHosts +Specifies whether +.Xr sshd 8 +should ignore the user's +.Pa ~/.ssh/known_hosts +during +.Cm HostbasedAuthentication +and use only the system-wide known hosts file +.Pa /etc/ssh/ssh_known_hosts . +The default is +.Dq no . +.It Cm Include +Include the specified configuration file(s). +Multiple pathnames may be specified and each pathname may contain +.Xr glob 7 +wildcards that will be expanded and processed in lexical order. +Files without absolute paths are assumed to be in +.Pa /etc/ssh . +An +.Cm Include +directive may appear inside a +.Cm Match +block +to perform conditional inclusion. +.It Cm IPQoS +Specifies the IPv4 type-of-service or DSCP class for the connection. +Accepted values are +.Cm af11 , +.Cm af12 , +.Cm af13 , +.Cm af21 , +.Cm af22 , +.Cm af23 , +.Cm af31 , +.Cm af32 , +.Cm af33 , +.Cm af41 , +.Cm af42 , +.Cm af43 , +.Cm cs0 , +.Cm cs1 , +.Cm cs2 , +.Cm cs3 , +.Cm cs4 , +.Cm cs5 , +.Cm cs6 , +.Cm cs7 , +.Cm ef , +.Cm le , +.Cm lowdelay , +.Cm throughput , +.Cm reliability , +a numeric value, or +.Cm none +to use the operating system default. +This option may take one or two arguments, separated by whitespace. +If one argument is specified, it is used as the packet class unconditionally. +If two values are specified, the first is automatically selected for +interactive sessions and the second for non-interactive sessions. +The default is +.Cm af21 +(Low-Latency Data) +for interactive sessions and +.Cm cs1 +(Lower Effort) +for non-interactive sessions. +.It Cm KbdInteractiveAuthentication +Specifies whether to allow keyboard-interactive authentication. +All authentication styles from +.Xr login.conf 5 +are supported. +The default is +.Cm yes . +The argument to this keyword must be +.Cm yes +or +.Cm no . +.Cm ChallengeResponseAuthentication +is a deprecated alias for this. +.It Cm KerberosAuthentication +Specifies whether the password provided by the user for +.Cm PasswordAuthentication +will be validated through the Kerberos KDC. +To use this option, the server needs a +Kerberos servtab which allows the verification of the KDC's identity. +The default is +.Cm no . +.It Cm KerberosGetAFSToken +If AFS is active and the user has a Kerberos 5 TGT, attempt to acquire +an AFS token before accessing the user's home directory. +The default is +.Cm no . +.It Cm KerberosOrLocalPasswd +If password authentication through Kerberos fails then +the password will be validated via any additional local mechanism +such as +.Pa /etc/passwd . +The default is +.Cm yes . +.It Cm KerberosTicketCleanup +Specifies whether to automatically destroy the user's ticket cache +file on logout. +The default is +.Cm yes . +.It Cm KerberosUniqueCCache +Specifies whether to store the acquired tickets in the per-session credential +cache under /tmp/ or whether to use per-user credential cache as configured in +.Pa /etc/krb5.conf . +The default value +.Cm no +can lead to overwriting previous tickets by subseqent connections to the same +user account. +.It Cm KerberosUseKuserok +Specifies whether to look at .k5login file for user's aliases. +The default is +.Cm yes . +.It Cm KexAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the available KEX (Key Exchange) algorithms. +Multiple algorithms must be comma-separated. +Alternately if the specified list begins with a +.Sq + +character, then the specified methods will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified algorithms will be placed at the head of the +built-in openssh default set. +The supported algorithms are: +.Pp +.Bl -item -compact -offset indent +.It +curve25519-sha256 +.It +curve25519-sha256@libssh.org +.It +diffie-hellman-group1-sha1 +.It +diffie-hellman-group14-sha1 +.It +diffie-hellman-group14-sha256 +.It +diffie-hellman-group16-sha512 +.It +diffie-hellman-group18-sha512 +.It +diffie-hellman-group-exchange-sha1 +.It +diffie-hellman-group-exchange-sha256 +.It +ecdh-sha2-nistp256 +.It +ecdh-sha2-nistp384 +.It +ecdh-sha2-nistp521 +.It +sntrup761x25519-sha512@openssh.com +.El +.Pp +The list of available key exchange algorithms may also be obtained using +.Qq ssh -Q KexAlgorithms . +.It Cm ListenAddress +Specifies the local addresses +.Xr sshd 8 +should listen on. +The following forms may be used: +.Pp +.Bl -item -offset indent -compact +.It +.Cm ListenAddress +.Sm off +.Ar hostname | address +.Sm on +.Op Cm rdomain Ar domain +.It +.Cm ListenAddress +.Sm off +.Ar hostname : port +.Sm on +.Op Cm rdomain Ar domain +.It +.Cm ListenAddress +.Sm off +.Ar IPv4_address : port +.Sm on +.Op Cm rdomain Ar domain +.It +.Cm ListenAddress +.Sm off +.Oo Ar hostname | address Oc : Ar port +.Sm on +.Op Cm rdomain Ar domain +.El +.Pp +The optional +.Cm rdomain +qualifier requests +.Xr sshd 8 +listen in an explicit routing domain. +If +.Ar port +is not specified, +sshd will listen on the address and all +.Cm Port +options specified. +The default is to listen on all local addresses on the current default +routing domain. +Multiple +.Cm ListenAddress +options are permitted. +For more information on routing domains, see +.Xr rdomain 4 . +.It Cm LoginGraceTime +The server disconnects after this time if the user has not +successfully logged in. +If the value is 0, there is no time limit. +The default is 120 seconds. +.It Cm LogLevel +Gives the verbosity level that is used when logging messages from +.Xr sshd 8 . +The possible values are: +QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3. +The default is INFO. +DEBUG and DEBUG1 are equivalent. +DEBUG2 and DEBUG3 each specify higher levels of debugging output. +Logging with a DEBUG level violates the privacy of users and is not recommended. +.It Cm LogVerbose +Specify one or more overrides to LogLevel. +An override consists of a pattern lists that matches the source file, function +and line number to force detailed logging for. +For example, an override pattern of: +.Bd -literal -offset indent +kex.c:*:1000,*:kex_exchange_identification():*,packet.c:* +.Ed +.Pp +would enable detailed logging for line 1000 of +.Pa kex.c , +everything in the +.Fn kex_exchange_identification +function, and all code in the +.Pa packet.c +file. +This option is intended for debugging and no overrides are enabled by default. +.It Cm MACs +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the available MAC (message authentication code) algorithms. +The MAC algorithm is used for data integrity protection. +Multiple algorithms must be comma-separated. +If the specified list begins with a +.Sq + +character, then the specified algorithms will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified algorithms will be placed at the head of the +built-in openssh default set. +.Pp +The algorithms that contain +.Qq -etm +calculate the MAC after encryption (encrypt-then-mac). +These are considered safer and their use recommended. +The supported MACs are: +.Pp +.Bl -item -compact -offset indent +.It +hmac-md5 +.It +hmac-md5-96 +.It +hmac-sha1 +.It +hmac-sha1-96 +.It +hmac-sha2-256 +.It +hmac-sha2-512 +.It +umac-64@openssh.com +.It +umac-128@openssh.com +.It +hmac-md5-etm@openssh.com +.It +hmac-md5-96-etm@openssh.com +.It +hmac-sha1-etm@openssh.com +.It +hmac-sha1-96-etm@openssh.com +.It +hmac-sha2-256-etm@openssh.com +.It +hmac-sha2-512-etm@openssh.com +.It +umac-64-etm@openssh.com +.It +umac-128-etm@openssh.com +.El +.Pp +The list of available MAC algorithms may also be obtained using +.Qq ssh -Q mac . +.It Cm Match +Introduces a conditional block. +If all of the criteria on the +.Cm Match +line are satisfied, the keywords on the following lines override those +set in the global section of the config file, until either another +.Cm Match +line or the end of the file. +If a keyword appears in multiple +.Cm Match +blocks that are satisfied, only the first instance of the keyword is +applied. +.Pp +The arguments to +.Cm Match +are one or more criteria-pattern pairs or the single token +.Cm All +which matches all criteria. +The available criteria are +.Cm User , +.Cm Group , +.Cm Host , +.Cm LocalAddress , +.Cm LocalPort , +.Cm RDomain , +and +.Cm Address +(with +.Cm RDomain +representing the +.Xr rdomain 4 +on which the connection was received). +.Pp +The match patterns may consist of single entries or comma-separated +lists and may use the wildcard and negation operators described in the +.Sx PATTERNS +section of +.Xr ssh_config 5 . +.Pp +The patterns in an +.Cm Address +criteria may additionally contain addresses to match in CIDR +address/masklen format, +such as 192.0.2.0/24 or 2001:db8::/32. +Note that the mask length provided must be consistent with the address - +it is an error to specify a mask length that is too long for the address +or one with bits set in this host portion of the address. +For example, 192.0.2.0/33 and 192.0.2.0/8, respectively. +.Pp +Only a subset of keywords may be used on the lines following a +.Cm Match +keyword. +Available keywords are +.Cm AcceptEnv , +.Cm AllowAgentForwarding , +.Cm AllowGroups , +.Cm AllowStreamLocalForwarding , +.Cm AllowTcpForwarding , +.Cm AllowUsers , +.Cm AuthenticationMethods , +.Cm AuthorizedKeysCommand , +.Cm AuthorizedKeysCommandUser , +.Cm AuthorizedKeysFile , +.Cm AuthorizedPrincipalsCommand , +.Cm AuthorizedPrincipalsCommandUser , +.Cm AuthorizedPrincipalsFile , +.Cm Banner , +.Cm CASignatureAlgorithms , +.Cm ChannelTimeout , +.Cm ChrootDirectory , +.Cm ClientAliveCountMax , +.Cm ClientAliveInterval , +.Cm DenyGroups , +.Cm DenyUsers , +.Cm DisableForwarding , +.Cm ExposeAuthInfo , +.Cm ForceCommand , +.Cm GatewayPorts , +.Cm GSSAPIAuthentication , +.Cm HostbasedAcceptedAlgorithms , +.Cm HostbasedAuthentication , +.Cm HostbasedUsesNameFromPacketOnly , +.Cm IgnoreRhosts , +.Cm Include , +.Cm IPQoS , +.Cm KbdInteractiveAuthentication , +.Cm KerberosAuthentication , +.Cm KerberosUseKuserok , +.Cm LogLevel , +.Cm MaxAuthTries , +.Cm MaxSessions , +.Cm PasswordAuthentication , +.Cm PermitEmptyPasswords , +.Cm PermitListen , +.Cm PermitOpen , +.Cm PermitRootLogin , +.Cm PermitTTY , +.Cm PermitTunnel , +.Cm PermitUserRC , +.Cm PubkeyAcceptedAlgorithms , +.Cm PubkeyAuthentication , +.Cm PubkeyAuthOptions , +.Cm RekeyLimit , +.Cm RevokedKeys , +.Cm RDomain , +.Cm SetEnv , +.Cm StreamLocalBindMask , +.Cm StreamLocalBindUnlink , +.Cm TrustedUserCAKeys , +.Cm UnusedConnectionTimeout , +.Cm X11DisplayOffset , +.Cm X11MaxDisplays , +.Cm X11Forwarding +and +.Cm X11UseLocalhost . +.It Cm MaxAuthTries +Specifies the maximum number of authentication attempts permitted per +connection. +Once the number of failures reaches half this value, +additional failures are logged. +The default is 6. +.It Cm MaxSessions +Specifies the maximum number of open shell, login or subsystem (e.g. sftp) +sessions permitted per network connection. +Multiple sessions may be established by clients that support connection +multiplexing. +Setting +.Cm MaxSessions +to 1 will effectively disable session multiplexing, whereas setting it to 0 +will prevent all shell, login and subsystem sessions while still permitting +forwarding. +The default is 10. +.It Cm MaxStartups +Specifies the maximum number of concurrent unauthenticated connections to the +SSH daemon. +Additional connections will be dropped until authentication succeeds or the +.Cm LoginGraceTime +expires for a connection. +The default is 10:30:100. +.Pp +Alternatively, random early drop can be enabled by specifying +the three colon separated values +start:rate:full (e.g. "10:30:60"). +.Xr sshd 8 +will refuse connection attempts with a probability of rate/100 (30%) +if there are currently start (10) unauthenticated connections. +The probability increases linearly and all connection attempts +are refused if the number of unauthenticated connections reaches full (60). +.It Cm ModuliFile +Specifies the +.Xr moduli 5 +file that contains the Diffie-Hellman groups used for the +.Dq diffie-hellman-group-exchange-sha1 +and +.Dq diffie-hellman-group-exchange-sha256 +key exchange methods. +The default is +.Pa /etc/ssh/moduli . +.It Cm PasswordAuthentication +Specifies whether password authentication is allowed. +The default is +.Cm yes . +.It Cm PermitEmptyPasswords +When password authentication is allowed, it specifies whether the +server allows login to accounts with empty password strings. +The default is +.Cm no . +.It Cm PermitListen +Specifies the addresses/ports on which a remote TCP port forwarding may listen. +The listen specification must be one of the following forms: +.Pp +.Bl -item -offset indent -compact +.It +.Cm PermitListen +.Sm off +.Ar port +.Sm on +.It +.Cm PermitListen +.Sm off +.Ar host : port +.Sm on +.El +.Pp +Multiple permissions may be specified by separating them with whitespace. +An argument of +.Cm any +can be used to remove all restrictions and permit any listen requests. +An argument of +.Cm none +can be used to prohibit all listen requests. +The host name may contain wildcards as described in the PATTERNS section in +.Xr ssh_config 5 . +The wildcard +.Sq * +can also be used in place of a port number to allow all ports. +By default all port forwarding listen requests are permitted. +Note that the +.Cm GatewayPorts +option may further restrict which addresses may be listened on. +Note also that +.Xr ssh 1 +will request a listen host of +.Dq localhost +if no listen host was specifically requested, and this name is +treated differently to explicit localhost addresses of +.Dq 127.0.0.1 +and +.Dq ::1 . +.It Cm PermitOpen +Specifies the destinations to which TCP port forwarding is permitted. +The forwarding specification must be one of the following forms: +.Pp +.Bl -item -offset indent -compact +.It +.Cm PermitOpen +.Sm off +.Ar host : port +.Sm on +.It +.Cm PermitOpen +.Sm off +.Ar IPv4_addr : port +.Sm on +.It +.Cm PermitOpen +.Sm off +.Ar \&[ IPv6_addr \&] : port +.Sm on +.El +.Pp +Multiple forwards may be specified by separating them with whitespace. +An argument of +.Cm any +can be used to remove all restrictions and permit any forwarding requests. +An argument of +.Cm none +can be used to prohibit all forwarding requests. +The wildcard +.Sq * +can be used for host or port to allow all hosts or ports respectively. +Otherwise, no pattern matching or address lookups are performed on supplied +names. +By default all port forwarding requests are permitted. +.It Cm PermitRootLogin +Specifies whether root can log in using +.Xr ssh 1 . +The argument must be +.Cm yes , +.Cm prohibit-password , +.Cm forced-commands-only , +or +.Cm no . +The default is +.Cm prohibit-password . +.Pp +If this option is set to +.Cm prohibit-password +(or its deprecated alias, +.Cm without-password ) , +password and keyboard-interactive authentication are disabled for root. +.Pp +If this option is set to +.Cm forced-commands-only , +root login with public key authentication will be allowed, +but only if the +.Ar command +option has been specified +(which may be useful for taking remote backups even if root login is +normally not allowed). +All other authentication methods are disabled for root. +.Pp +If this option is set to +.Cm no , +root is not allowed to log in. +.It Cm PermitTTY +Specifies whether +.Xr pty 4 +allocation is permitted. +The default is +.Cm yes . +.It Cm PermitTunnel +Specifies whether +.Xr tun 4 +device forwarding is allowed. +The argument must be +.Cm yes , +.Cm point-to-point +(layer 3), +.Cm ethernet +(layer 2), or +.Cm no . +Specifying +.Cm yes +permits both +.Cm point-to-point +and +.Cm ethernet . +The default is +.Cm no . +.Pp +Independent of this setting, the permissions of the selected +.Xr tun 4 +device must allow access to the user. +.It Cm PermitUserEnvironment +Specifies whether +.Pa ~/.ssh/environment +and +.Cm environment= +options in +.Pa ~/.ssh/authorized_keys +are processed by +.Xr sshd 8 . +Valid options are +.Cm yes , +.Cm no +or a pattern-list specifying which environment variable names to accept +(for example +.Qq LANG,LC_* ) . +The default is +.Cm no . +Enabling environment processing may enable users to bypass access +restrictions in some configurations using mechanisms such as +.Ev LD_PRELOAD . +.It Cm PermitUserRC +Specifies whether any +.Pa ~/.ssh/rc +file is executed. +The default is +.Cm yes . +.It Cm PerSourceMaxStartups +Specifies the number of unauthenticated connections allowed from a +given source address, or +.Dq none +if there is no limit. +This limit is applied in addition to +.Cm MaxStartups , +whichever is lower. +The default is +.Cm none . +.It Cm PerSourceNetBlockSize +Specifies the number of bits of source address that are grouped together +for the purposes of applying PerSourceMaxStartups limits. +Values for IPv4 and optionally IPv6 may be specified, separated by a colon. +The default is +.Cm 32:128 , +which means each address is considered individually. +.It Cm PidFile +Specifies the file that contains the process ID of the +SSH daemon, or +.Cm none +to not write one. +The default is +.Pa /var/run/sshd.pid . +.It Cm Port +Specifies the port number that +.Xr sshd 8 +listens on. +The default is 22. +Multiple options of this type are permitted. +See also +.Cm ListenAddress . +.It Cm PrintLastLog +Specifies whether +.Xr sshd 8 +should print the date and time of the last user login when a user logs +in interactively. +The default is +.Cm yes . +.It Cm PrintMotd +Specifies whether +.Xr sshd 8 +should print +.Pa /etc/motd +when a user logs in interactively. +(On some systems it is also printed by the shell, +.Pa /etc/profile , +or equivalent.) +The default is +.Cm yes . +.It Cm PubkeyAcceptedAlgorithms +The default is handled system-wide by +.Xr crypto-policies 7 . +Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page +.Xr update-crypto-policies 8 . +.Pp +Specifies the signature algorithms that will be accepted for public key +authentication as a list of comma-separated patterns. +Alternately if the specified list begins with a +.Sq + +character, then the specified algorithms will be appended to the built-in +openssh default set instead of replacing them. +If the specified list begins with a +.Sq - +character, then the specified algorithms (including wildcards) will be removed +from the built-in openssh default set instead of replacing them. +If the specified list begins with a +.Sq ^ +character, then the specified algorithms will be placed at the head of the +built-in openssh default set. +.Pp +The list of available signature algorithms may also be obtained using +.Qq ssh -Q PubkeyAcceptedAlgorithms . +.It Cm PubkeyAuthOptions +Sets one or more public key authentication options. +The supported keywords are: +.Cm none +(the default; indicating no additional options are enabled), +.Cm touch-required +and +.Cm verify-required . +.Pp +The +.Cm touch-required +option causes public key authentication using a FIDO authenticator algorithm +(i.e.\& +.Cm ecdsa-sk +or +.Cm ed25519-sk ) +to always require the signature to attest that a physically present user +explicitly confirmed the authentication (usually by touching the authenticator). +By default, +.Xr sshd 8 +requires user presence unless overridden with an authorized_keys option. +The +.Cm touch-required +flag disables this override. +.Pp +The +.Cm verify-required +option requires a FIDO key signature attest that the user was verified, +e.g. via a PIN. +.Pp +Neither the +.Cm touch-required +or +.Cm verify-required +options have any effect for other, non-FIDO, public key types. +.It Cm PubkeyAuthentication +Specifies whether public key authentication is allowed. +The default is +.Cm yes . +.It Cm RekeyLimit +Specifies the maximum amount of data that may be transmitted or received +before the session key is renegotiated, optionally followed by a maximum +amount of time that may pass before the session key is renegotiated. +The first argument is specified in bytes and may have a suffix of +.Sq K , +.Sq M , +or +.Sq G +to indicate Kilobytes, Megabytes, or Gigabytes, respectively. +The default is between +.Sq 1G +and +.Sq 4G , +depending on the cipher. +The optional second value is specified in seconds and may use any of the +units documented in the +.Sx TIME FORMATS +section. +The default value for +.Cm RekeyLimit +is +.Cm default none , +which means that rekeying is performed after the cipher's default amount +of data has been sent or received and no time based rekeying is done. +.It Cm RequiredRSASize +Specifies the minimum RSA key size (in bits) that +.Xr sshd 8 +will accept. +User and host-based authentication keys smaller than this limit will be +refused. +The default is +.Cm 1024 +bits. +Note that this limit may only be raised from the default. +.It Cm RevokedKeys +Specifies revoked public keys file, or +.Cm none +to not use one. +Keys listed in this file will be refused for public key authentication. +Note that if this file is not readable, then public key authentication will +be refused for all users. +Keys may be specified as a text file, listing one public key per line, or as +an OpenSSH Key Revocation List (KRL) as generated by +.Xr ssh-keygen 1 . +For more information on KRLs, see the KEY REVOCATION LISTS section in +.Xr ssh-keygen 1 . +.It Cm RDomain +Specifies an explicit routing domain that is applied after authentication +has completed. +The user session, as well as any forwarded or listening IP sockets, +will be bound to this +.Xr rdomain 4 . +If the routing domain is set to +.Cm \&%D , +then the domain in which the incoming connection was received will be applied. +.It Cm SecurityKeyProvider +Specifies a path to a library that will be used when loading +FIDO authenticator-hosted keys, overriding the default of using +the built-in USB HID support. +.It Cm SetEnv +Specifies one or more environment variables to set in child sessions started +by +.Xr sshd 8 +as +.Dq NAME=VALUE . +The environment value may be quoted (e.g. if it contains whitespace +characters). +Environment variables set by +.Cm SetEnv +override the default environment and any variables specified by the user +via +.Cm AcceptEnv +or +.Cm PermitUserEnvironment . +.It Cm StreamLocalBindMask +Sets the octal file creation mode mask +.Pq umask +used when creating a Unix-domain socket file for local or remote +port forwarding. +This option is only used for port forwarding to a Unix-domain socket file. +.Pp +The default value is 0177, which creates a Unix-domain socket file that is +readable and writable only by the owner. +Note that not all operating systems honor the file mode on Unix-domain +socket files. +.It Cm StreamLocalBindUnlink +Specifies whether to remove an existing Unix-domain socket file for local +or remote port forwarding before creating a new one. +If the socket file already exists and +.Cm StreamLocalBindUnlink +is not enabled, +.Nm sshd +will be unable to forward the port to the Unix-domain socket file. +This option is only used for port forwarding to a Unix-domain socket file. +.Pp +The argument must be +.Cm yes +or +.Cm no . +The default is +.Cm no . +.It Cm StrictModes +Specifies whether +.Xr sshd 8 +should check file modes and ownership of the +user's files and home directory before accepting login. +This is normally desirable because novices sometimes accidentally leave their +directory or files world-writable. +The default is +.Cm yes . +Note that this does not apply to +.Cm ChrootDirectory , +whose permissions and ownership are checked unconditionally. +.It Cm Subsystem +Configures an external subsystem (e.g. file transfer daemon). +Arguments should be a subsystem name and a command (with optional arguments) +to execute upon subsystem request. +.Pp +The command +.Cm sftp-server +implements the SFTP file transfer subsystem. +.Pp +Alternately the name +.Cm internal-sftp +implements an in-process SFTP server. +This may simplify configurations using +.Cm ChrootDirectory +to force a different filesystem root on clients. +.Pp +By default no subsystems are defined. +.It Cm SyslogFacility +Gives the facility code that is used when logging messages from +.Xr sshd 8 . +The possible values are: DAEMON, USER, AUTH, AUTHPRIV, LOCAL0, LOCAL1, LOCAL2, +LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7. +The default is AUTH. +.It Cm TCPKeepAlive +Specifies whether the system should send TCP keepalive messages to the +other side. +If they are sent, death of the connection or crash of one +of the machines will be properly noticed. +However, this means that +connections will die if the route is down temporarily, and some people +find it annoying. +On the other hand, if TCP keepalives are not sent, +sessions may hang indefinitely on the server, leaving +.Qq ghost +users and consuming server resources. +.Pp +The default is +.Cm yes +(to send TCP keepalive messages), and the server will notice +if the network goes down or the client host crashes. +This avoids infinitely hanging sessions. +.Pp +To disable TCP keepalive messages, the value should be set to +.Cm no . +.It Cm TrustedUserCAKeys +Specifies a file containing public keys of certificate authorities that are +trusted to sign user certificates for authentication, or +.Cm none +to not use one. +Keys are listed one per line; empty lines and comments starting with +.Ql # +are allowed. +If a certificate is presented for authentication and has its signing CA key +listed in this file, then it may be used for authentication for any user +listed in the certificate's principals list. +Note that certificates that lack a list of principals will not be permitted +for authentication using +.Cm TrustedUserCAKeys . +For more details on certificates, see the CERTIFICATES section in +.Xr ssh-keygen 1 . +.It Cm UnusedConnectionTimeout +Specifies whether and how quickly +.Xr sshd 8 +should close client connections with no open channels. +Open channels include active shell, command execution or subsystem +sessions, connected network, socket, agent or X11 forwardings. +Forwarding listeners, such as those from the +.Xr ssh 1 +.Fl R +flag, are not considered as open channels and do not prevent the timeout. +The timeout value +is specified in seconds or may use any of the units documented in the +.Sx TIME FORMATS +section. +.Pp +Note that this timeout starts when the client connection completes +user authentication but before the client has an opportunity to open any +channels. +Caution should be used when using short timeout values, as they may not +provide sufficient time for the client to request and open its channels +before terminating the connection. +.Pp +The default +.Cm none +is to never expire connections for having no open channels. +This option may be useful in conjunction with +.Cm ChannelTimeout . +.It Cm UseDNS +Specifies whether +.Xr sshd 8 +should look up the remote host name, and to check that +the resolved host name for the remote IP address maps back to the +very same IP address. +.Pp +If this option is set to +.Cm no +(the default) then only addresses and not host names may be used in +.Pa ~/.ssh/authorized_keys +.Cm from +and +.Nm +.Cm Match +.Cm Host +directives. +.It Cm UsePAM +Enables the Pluggable Authentication Module interface. +If set to +.Cm yes +this will enable PAM authentication using +.Cm KbdInteractiveAuthentication +and +.Cm PasswordAuthentication +in addition to PAM account and session module processing for all +authentication types. +.Pp +Because PAM keyboard-interactive authentication usually serves an equivalent +role to password authentication, you should disable either +.Cm PasswordAuthentication +or +.Cm KbdInteractiveAuthentication . +.Pp +If +.Cm UsePAM +is enabled, you will not be able to run +.Xr sshd 8 +as a non-root user. +The default is +.Cm no . +.It Cm VersionAddendum +Optionally specifies additional text to append to the SSH protocol banner +sent by the server upon connection. +The default is +.Cm none . +.It Cm X11DisplayOffset +Specifies the first display number available for +.Xr sshd 8 Ns 's +X11 forwarding. +This prevents sshd from interfering with real X11 servers. +The default is 10. +.It Cm X11MaxDisplays +Specifies the maximum number of displays available for +.Xr sshd 8 Ns 's +X11 forwarding. +This prevents sshd from exhausting local ports. +The default is 1000. +.It Cm X11Forwarding +Specifies whether X11 forwarding is permitted. +The argument must be +.Cm yes +or +.Cm no . +The default is +.Cm no . +.Pp +When X11 forwarding is enabled, there may be additional exposure to +the server and to client displays if the +.Xr sshd 8 +proxy display is configured to listen on the wildcard address (see +.Cm X11UseLocalhost ) , +though this is not the default. +Additionally, the authentication spoofing and authentication data +verification and substitution occur on the client side. +The security risk of using X11 forwarding is that the client's X11 +display server may be exposed to attack when the SSH client requests +forwarding (see the warnings for +.Cm ForwardX11 +in +.Xr ssh_config 5 ) . +A system administrator may have a stance in which they want to +protect clients that may expose themselves to attack by unwittingly +requesting X11 forwarding, which can warrant a +.Cm no +setting. +.Pp +Note that disabling X11 forwarding does not prevent users from +forwarding X11 traffic, as users can always install their own forwarders. +.It Cm X11UseLocalhost +Specifies whether +.Xr sshd 8 +should bind the X11 forwarding server to the loopback address or to +the wildcard address. +By default, +sshd binds the forwarding server to the loopback address and sets the +hostname part of the +.Ev DISPLAY +environment variable to +.Cm localhost . +This prevents remote hosts from connecting to the proxy display. +However, some older X11 clients may not function with this +configuration. +.Cm X11UseLocalhost +may be set to +.Cm no +to specify that the forwarding server should be bound to the wildcard +address. +The argument must be +.Cm yes +or +.Cm no . +The default is +.Cm yes . +.It Cm XAuthLocation +Specifies the full pathname of the +.Xr xauth 1 +program, or +.Cm none +to not use one. +The default is +.Pa /usr/bin/xauth . +.El +.Sh TIME FORMATS +.Xr sshd 8 +command-line arguments and configuration file options that specify time +may be expressed using a sequence of the form: +.Sm off +.Ar time Op Ar qualifier , +.Sm on +where +.Ar time +is a positive integer value and +.Ar qualifier +is one of the following: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It Aq Cm none +seconds +.It Cm s | Cm S +seconds +.It Cm m | Cm M +minutes +.It Cm h | Cm H +hours +.It Cm d | Cm D +days +.It Cm w | Cm W +weeks +.El +.Pp +Each member of the sequence is added together to calculate +the total time value. +.Pp +Time format examples: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It 600 +600 seconds (10 minutes) +.It 10m +10 minutes +.It 1h30m +1 hour 30 minutes (90 minutes) +.El +.Sh TOKENS +Arguments to some keywords can make use of tokens, +which are expanded at runtime: +.Pp +.Bl -tag -width XXXX -offset indent -compact +.It %% +A literal +.Sq % . +.It \&%C +Identifies the connection endpoints, containing +four space-separated values: client address, client port number, +server address, and server port number. +.It \&%D +The routing domain in which the incoming connection was received. +.It %F +The fingerprint of the CA key. +.It %f +The fingerprint of the key or certificate. +.It %h +The home directory of the user. +.It %i +The key ID in the certificate. +.It %K +The base64-encoded CA key. +.It %k +The base64-encoded key or certificate for authentication. +.It %s +The serial number of the certificate. +.It \&%T +The type of the CA key. +.It %t +The key or certificate type. +.It \&%U +The numeric user ID of the target user. +.It %u +The username. +.El +.Pp +.Cm AuthorizedKeysCommand +accepts the tokens %%, %C, %D, %f, %h, %k, %t, %U, and %u. +.Pp +.Cm AuthorizedKeysFile +accepts the tokens %%, %h, %U, and %u. +.Pp +.Cm AuthorizedPrincipalsCommand +accepts the tokens %%, %C, %D, %F, %f, %h, %i, %K, %k, %s, %T, %t, %U, and %u. +.Pp +.Cm AuthorizedPrincipalsFile +accepts the tokens %%, %h, %U, and %u. +.Pp +.Cm ChrootDirectory +accepts the tokens %%, %h, %U, and %u. +.Pp +.Cm RoutingDomain +accepts the token %D. +.Sh FILES +.Bl -tag -width Ds +.It Pa /etc/ssh/sshd_config +Contains configuration data for +.Xr sshd 8 . +This file should be writable by root only, but it is recommended +(though not necessary) that it be world-readable. +.El +.Sh SEE ALSO +.Xr sftp-server 8 , +.Xr sshd 8 , +.Xr crypto-policies 7 , +.Xr update-crypto-policies 8 +.Sh AUTHORS +.An -nosplit +OpenSSH is a derivative of the original and free +ssh 1.2.12 release by +.An Tatu Ylonen . +.An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , +.An Theo de Raadt +and +.An Dug Song +removed many bugs, re-added newer features and +created OpenSSH. +.An Markus Friedl +contributed the support for SSH protocol versions 1.5 and 2.0. +.An Niels Provos +and +.An Markus Friedl +contributed support for privilege separation. diff --git a/upstream/fedora-40/man5/sysctl.d.5 b/upstream/fedora-40/man5/sysctl.d.5 new file mode 100644 index 00000000..9b232b02 --- /dev/null +++ b/upstream/fedora-40/man5/sysctl.d.5 @@ -0,0 +1,245 @@ +'\" t +.TH "SYSCTL\&.D" "5" "" "systemd 255" "sysctl.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +sysctl.d \- Configure kernel parameters at boot +.SH "SYNOPSIS" +.PP +/etc/sysctl\&.d/*\&.conf +.PP +/run/sysctl\&.d/*\&.conf +.PP +/usr/lib/sysctl\&.d/*\&.conf +.sp +.nf +key\&.name\&.under\&.proc\&.sys = some value +key/name/under/proc/sys = some value +key/middle\&.part\&.with\&.dots/foo = 123 +key\&.middle/part/with/dots\&.foo = 123 +\-key\&.that\&.will\&.not\&.fail = value +key\&.pattern\&.*\&.with\&.glob = whatever +\-key\&.pattern\&.excluded\&.with\&.glob +key\&.pattern\&.overridden\&.with\&.glob = custom +.fi +.SH "DESCRIPTION" +.PP +At boot, +\fBsystemd-sysctl.service\fR(8) +reads configuration files from the above directories to configure +\fBsysctl\fR(8) +kernel parameters\&. +.SH "CONFIGURATION FORMAT" +.PP +The configuration files contain a list of variable assignments, separated by newlines\&. Empty lines and lines whose first non\-whitespace character is +"#" +or +";" +are ignored\&. +.PP +Note that either +"/" +or +"\&." +may be used as separators within sysctl variable names\&. If the first separator is a slash, remaining slashes and dots are left intact\&. If the first separator is a dot, dots and slashes are interchanged\&. +"kernel\&.domainname=foo" +and +"kernel/domainname=foo" +are equivalent and will cause +"foo" +to be written to +/proc/sys/kernel/domainname\&. Either +"net\&.ipv4\&.conf\&.enp3s0/200\&.forwarding" +or +"net/ipv4/conf/enp3s0\&.200/forwarding" +may be used to refer to +/proc/sys/net/ipv4/conf/enp3s0\&.200/forwarding\&. A glob +\fBglob\fR(7) +pattern may be used to write the same value to all matching keys\&. Keys for which an explicit pattern exists will be excluded from any glob matching\&. In addition, a key may be explicitly excluded from being set by any matching glob patterns by specifying the key name prefixed with a +"\-" +character and not followed by +"=", see SYNOPSIS\&. +.PP +Any access permission errors and attempts to write variables not present on the local system are logged at debug level and do not cause the service to fail\&. Other types of errors when setting variables are logged with higher priority and cause the service to return failure at the end (after processing other variables)\&. As an exception, if a variable assignment is prefixed with a single +"\-" +character, failure to set the variable for any reason will be logged at debug level and will not cause the service to fail\&. +.PP +The settings configured with +sysctl\&.d +files will be applied early on boot\&. The network interface\-specific options will also be applied individually for each network interface as it shows up in the system\&. (More specifically, +net\&.ipv4\&.conf\&.*, +net\&.ipv6\&.conf\&.*, +net\&.ipv4\&.neigh\&.* +and +net\&.ipv6\&.neigh\&.*)\&. +.PP +Many sysctl parameters only become available when certain kernel modules are loaded\&. Modules are usually loaded on demand, e\&.g\&. when certain hardware is plugged in or network brought up\&. This means that +\fBsystemd-sysctl.service\fR(8) +which runs during early boot will not configure such parameters if they become available after it has run\&. To set such parameters, it is recommended to add an +\fBudev\fR(7) +rule to set those parameters when they become available\&. Alternatively, a slightly simpler and less efficient option is to add the module to +\fBmodules-load.d\fR(5), causing it to be loaded statically before sysctl settings are applied (see example below)\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +Configuration files are read from directories in +/etc/, +/run/, +/usr/local/lib/, and +/usr/lib/, in order of precedence, as listed in the SYNOPSIS section above\&. Files must have the +"\&.conf" +extension\&. Files in +/etc/ +override files with the same name in +/run/, +/usr/local/lib/, and +/usr/lib/\&. Files in +/run/ +override files with the same name under +/usr/\&. +.PP +All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same option, the entry in the file with the lexicographically latest name will take precedence\&. Thus, the configuration in a certain file may either be replaced completely (by placing a file with the same name in a directory with higher priority), or individual settings might be changed (by specifying additional settings in a file with a different name that is ordered later)\&. +.PP +Packages should install their configuration files in +/usr/lib/ +(distribution packages) or +/usr/local/lib/ +(local installs)\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. It is recommended to prefix all filenames with a two\-digit number and a dash, to simplify the ordering of the files\&. +.PP +If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. If the vendor configuration file is included in the initrd image, the image has to be regenerated\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Set kernel YP domain name\fR +.PP +/etc/sysctl\&.d/domain\-name\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +kernel\&.domainname=example\&.com +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Apply settings available only when a certain module is loaded (method one)\fR +.PP +/etc/udev/rules\&.d/99\-bridge\&.rules: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \e + RUN+="/usr/lib/systemd/systemd\-sysctl \-\-prefix=/net/bridge" +.fi +.if n \{\ +.RE +.\} +.PP +/etc/sysctl\&.d/bridge\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +net\&.bridge\&.bridge\-nf\-call\-ip6tables = 0 +net\&.bridge\&.bridge\-nf\-call\-iptables = 0 +net\&.bridge\&.bridge\-nf\-call\-arptables = 0 +.fi +.if n \{\ +.RE +.\} +.PP +This method applies settings when the module is loaded\&. Please note that, unless the +br_netfilter +module is loaded, bridged packets will not be filtered by Netfilter (starting with kernel 3\&.18), so simply not loading the module is sufficient to avoid filtering\&. +.PP +\fBExample\ \&3.\ \&Apply settings available only when a certain module is loaded (method two)\fR +.PP +/etc/modules\-load\&.d/bridge\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +br_netfilter +.fi +.if n \{\ +.RE +.\} +.PP +/etc/sysctl\&.d/bridge\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +net\&.bridge\&.bridge\-nf\-call\-ip6tables = 0 +net\&.bridge\&.bridge\-nf\-call\-iptables = 0 +net\&.bridge\&.bridge\-nf\-call\-arptables = 0 +.fi +.if n \{\ +.RE +.\} +.PP +This method forces the module to be always loaded\&. Please note that, unless the +br_netfilter +module is loaded, bridged packets will not be filtered with Netfilter (starting with kernel 3\&.18), so simply not loading the module is sufficient to avoid filtering\&. +.PP +\fBExample\ \&4.\ \&Set network routing properties for all interfaces\fR +.PP +/etc/sysctl\&.d/20\-rp_filter\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +net\&.ipv4\&.conf\&.default\&.rp_filter = 2 +net\&.ipv4\&.conf\&.*\&.rp_filter = 2 +\-net\&.ipv4\&.conf\&.all\&.rp_filter +net\&.ipv4\&.conf\&.hub0\&.rp_filter = 1 +.fi +.if n \{\ +.RE +.\} +.PP +The +\fBrp_filter\fR +key will be set to "2" for all interfaces, except "hub0"\&. We set +net\&.ipv4\&.conf\&.default\&.rp_filter +first, so any interfaces which are added +\fIlater\fR +will get this value (this also covers any interfaces detected while we\*(Aqre running)\&. The glob matches any interfaces which were detected +\fIearlier\fR\&. The glob will also match +net\&.ipv4\&.conf\&.all\&.rp_filter, which we don\*(Aqt want to set at all, so it is explicitly excluded\&. And "hub0" is excluded from the glob because it has an explicit setting\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-sysctl.service\fR(8), +\fBsystemd-delta\fR(1), +\fBsysctl\fR(8), +\fBsysctl.conf\fR(5), +\fBmodprobe\fR(8) diff --git a/upstream/fedora-40/man5/sysfs.5 b/upstream/fedora-40/man5/sysfs.5 new file mode 100644 index 00000000..7c18e4be --- /dev/null +++ b/upstream/fedora-40/man5/sysfs.5 @@ -0,0 +1,275 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sysfs 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +sysfs \- a filesystem for exporting kernel objects +.SH DESCRIPTION +The +.B sysfs +filesystem is a pseudo-filesystem which provides an interface to +kernel data structures. +(More precisely, the files and directories in +.B sysfs +provide a view of the +.I kobject +structures defined internally within the kernel.) +The files under +.B sysfs +provide information about devices, kernel modules, filesystems, +and other kernel components. +.P +The +.B sysfs +filesystem is commonly mounted at +.IR /sys . +Typically, it is mounted automatically by the system, +but it can also be mounted manually using a command such as: +.P +.in +4n +.EX +mount \-t sysfs sysfs /sys +.EE +.in +.P +Many of the files in the +.B sysfs +filesystem are read-only, +but some files are writable, allowing kernel variables to be changed. +To avoid redundancy, +symbolic links are heavily used to connect entries across the filesystem tree. +.\" +.SS Files and directories +The following list describes some of the files and directories under the +.I /sys +hierarchy. +.TP +.I /sys/block +This subdirectory contains one symbolic link for each block device +that has been discovered on the system. +The symbolic links point to corresponding directories under +.IR /sys/devices . +.TP +.I /sys/bus +This directory contains one subdirectory for each of the bus types +in the kernel. +Inside each of these directories are two subdirectories: +.RS +.TP +.I devices +This subdirectory contains symbolic links to entries in +.I /sys/devices +that correspond to the devices discovered on this bus. +.TP +.I drivers +This subdirectory contains one subdirectory for each device driver +that is loaded on this bus. +.RE +.TP +.I /sys/class +This subdirectory contains a single layer of further subdirectories +for each of the device classes that have been registered on the system +(e.g., terminals, network devices, block devices, graphics devices, +sound devices, and so on). +Inside each of these subdirectories are symbolic links for each of the +devices in this class. +These symbolic links refer to entries in the +.I /sys/devices +directory. +.TP +.I /sys/class/net +Each of the entries in this directory is a symbolic link +representing one of the real or virtual networking devices +that are visible in the network namespace of the process +that is accessing the directory. +Each of these symbolic links refers to entries in the +.I /sys/devices +directory. +.TP +.I /sys/dev +This directory contains two subdirectories +.I block/ +and +.IR char/ , +corresponding, respectively, +to the block and character devices on the system. +Inside each of these subdirectories are symbolic links with names of the form +.IR major-ID : minor-ID , +where the ID values correspond to the major and minor ID of a specific device. +Each symbolic link points to the +.B sysfs +directory for a device. +The symbolic links inside +.I /sys/dev +thus provide an easy way to look up the +.B sysfs +interface using the device IDs returned by a call to +.BR stat (2) +(or similar). +.IP +The following shell session shows an example from +.IR /sys/dev : +.IP +.in +4n +.EX +$ \fBstat \-c "%t %T" /dev/null\fP +1 3 +$ \fBreadlink /sys/dev/char/1\e:3\fP +\&../../devices/virtual/mem/null +$ \fBls \-Fd /sys/devices/virtual/mem/null\fP +/sys/devices/virtual/mem/null/ +$ \fBls \-d1 /sys/devices/virtual/mem/null/*\fP +/sys/devices/virtual/mem/null/dev +/sys/devices/virtual/mem/null/power/ +/sys/devices/virtual/mem/null/subsystem@ +/sys/devices/virtual/mem/null/uevent +.EE +.in +.TP +.I /sys/devices +This is a directory that contains a filesystem representation of +the kernel device tree, +which is a hierarchy of +.I device +structures within the kernel. +.TP +.I /sys/firmware +This subdirectory contains interfaces for viewing and manipulating +firmware-specific objects and attributes. +.TP +.I /sys/fs +This directory contains subdirectories for some filesystems. +A filesystem will have a subdirectory here only if it chose +to explicitly create the subdirectory. +.TP +.I /sys/fs/cgroup +This directory conventionally is used as a mount point for a +.BR tmpfs (5) +filesystem containing mount points for +.BR cgroups (7) +filesystems. +.TP +.I /sys/fs/smackfs +The directory contains configuration files for the SMACK LSM. +See the kernel source file +.IR Documentation/admin\-guide/LSM/Smack.rst . +.TP +.I /sys/hypervisor +[To be documented] +.TP +.I /sys/kernel +This subdirectory contains various files and subdirectories that provide +information about the running kernel. +.TP +.I /sys/kernel/cgroup/ +For information about the files in this directory, see +.BR cgroups (7). +.TP +.I /sys/kernel/debug/tracing +Mount point for the +.I tracefs +filesystem used by the kernel's +.I ftrace +facility. +(For information on +.IR ftrace , +see the kernel source file +.IR Documentation/trace/ftrace.txt .) +.TP +.I /sys/kernel/mm +This subdirectory contains various files and subdirectories that provide +information about the kernel's memory management subsystem. +.TP +.I /sys/kernel/mm/hugepages +This subdirectory contains one subdirectory for each of the +huge page sizes that the system supports. +The subdirectory name indicates the huge page size (e.g., +.IR hugepages\-2048kB ). +Within each of these subdirectories is a set of files +that can be used to view and (in some cases) change settings +associated with that huge page size. +For further information, see the kernel source file +.IR Documentation/admin\-guide/mm/hugetlbpage.rst . +.TP +.I /sys/module +This subdirectory contains one subdirectory +for each module that is loaded into the kernel. +The name of each directory is the name of the module. +In each of the subdirectories, there may be following files: +.RS +.TP +.I coresize +[to be documented] +.TP +.I initsize +[to be documented] +.TP +.I initstate +[to be documented] +.TP +.I refcnt +[to be documented] +.TP +.I srcversion +[to be documented] +.TP +.I taint +[to be documented] +.TP +.I uevent +[to be documented] +.TP +.I version +[to be documented] +.RE +.IP +In each of the subdirectories, there may be following subdirectories: +.RS +.TP +.I drivers +[To be documented] +.TP +.I holders +[To be documented] +.TP +.I notes +[To be documented] +.TP +.I parameters +This directory contains one file for each module parameter, +with each file containing the value of the corresponding parameter. +Some of these files are writable, allowing the +.TP +.I sections +This subdirectories contains files with information about module sections. +This information is mainly used for debugging. +.TP +.I +[To be documented] +.RE +.TP +.I /sys/power +[To be documented] +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.0. +.SH NOTES +This manual page is incomplete, possibly inaccurate, and is the kind +of thing that needs to be updated very often. +.SH SEE ALSO +.BR proc (5), +.BR udev (7) +.P +P.\& Mochel. (2005). +.IR "The sysfs filesystem" . +Proceedings of the 2005 Ottawa Linux Symposium. +.\" https://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf +.P +The kernel source file +.I Documentation/filesystems/sysfs.txt +and various other files in +.I Documentation/ABI +and +.I Documentation/*/sysfs.txt diff --git a/upstream/fedora-40/man5/sysstat.5 b/upstream/fedora-40/man5/sysstat.5 new file mode 100644 index 00000000..e31f6b31 --- /dev/null +++ b/upstream/fedora-40/man5/sysstat.5 @@ -0,0 +1,176 @@ +.\" sysstat manual page - (C) 2020 Sebastien Godard (sysstat orange.fr) +.TH SYSSTAT 5 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- +.SH NAME +sysstat \- sysstat configuration file. + +.SH DESCRIPTION +This file is read by +.BR "sa1" "(8) and " "sa2" "(8) shell scripts from the sysstat's set of tools." +It consists of a sequence of shell variable assignments used to +configure sysstat logging. +The variables and their meanings are: +.TP +.B COMPRESSAFTER +Number of days after which daily data files are to be compressed. +The compression program is given in the +.BR "ZIP " "variable." +.TP +.B DELAY_RANGE +.RB "Tell " "sa2" +script to wait for a random delay in the indicated range before running. +This delay is expressed in seconds, and is aimed at preventing a massive I/O burst +at the same time on VM sharing the same storage area. +.RB "A value of 0 means that " "sa2" +script will generate its reports files immediately. +.TP +.B HISTORY +The number of days during which a daily data file or a report +should be kept. Data files or reports older than this number of +days will be removed by the +.BR "sa2" "(8) shell script." +Data files and reports are normally saved in the /var/log/sa directory, +under the name +.IR "saDD " "(for data files) or " "sarDD " "(for reports), where the " "DD" +parameter indicates the current day. + +The number of files actually kept in the /var/log/sa directory may be +slightly higher than the +.BR "HISTORY " "value due to the way the " "sa2" +script figures out which files are to be removed (see below "How the +.BR "sa2" "(8) script applies " "HISTORY" +value"). Using a value of 28 keeps a whole month's worth of data. If you set +.B HISTORY +to a value greater than 28 then you should consider using +.BR "sadc" "'s option " "\-D" +to prevent older data files from being overwritten (see +.BR "sadc" "(8)" +manual page). In this latter case data files are named +.IR "saYYYYMMDD " "and reports " "sarYYYYMMDD" ", where" +.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD" +for the current day. + +How the +.BR "sa2" "(8) script applies " "HISTORY " "value" + +.RB "The " "sa2" +script uses the +.BR "find " "command with the " "\-mtime " "option to figure" +out which files are to be removed. The +.BR "find " "command interprets this value" +as "N 24 hour periods", ignoring any fractional part. This means that the +last modified time of a given +.IR "sa[r]DD " "data or report file, using a" +.B HISTORY +of 1, has to have been modified at least two days ago before it will be +removed. And for a +.BR "HISTORY " "of 28 that would mean 29 days ago." + +.RB "To figure out how a " "HISTORY" +of 28 is applied in practice, we need to consider that the +.BR "sa2 " "script that issues the " "find " "command to remove the" +old files typically runs just before midnight on a given system, and since +the first record from +.B sadc +can also be written to the previous day's data file +(thereby moving its modification time up a bit), the +.B sa2 +script will leave +30 files untouched. So for a setting of 28, and counting the data file of +the current day, there will always be 31 files (or 30 files, depending on the +number of days in a month) in the /var/log/sa directory during the majority +of a given day. E.g.: + +April 30th: 31 files (Apr 30th-1st, Mar 31th) +.br +May 1st: 30 files (May 1st, Apr 30th-2nd) + +Yet we can note the following exceptions (as inspected at Noon of the given day): + +February 28th: 31 files (Feb 28th-1st, Jan 31st, 30th & 29th) +.br +March 1st: 30 files (Mar 1st, Feb 28th-2nd, Jan 31st & 30th) +.br +March 2nd: 29 files (Mar 1st & 2nd, Feb 28th-3rd, Jan. 31st) +.br +March 3rd: 28 files (Mar 1st-3rd, Feb 28th-4th) +.br +March 4th - March 28th: 28 files +.br +March 29th: 29 files +.br +March 30th: 30 files +.br +March 31st: 31 files + +(Determining the number of files in March on a leap year is left as an +exercise for the reader). + +Things are simpler if you use the +.IR "sa[r]YYYYMMDD " "name format." +Apply the same logic as above in this case and you will find that there +are always +.BR "HISTORY " "+ 3 files in the" +.IR /var/log/sa +directory during the majority of a given day. +.TP +.B REPEAT_HEADER +Maximum number of lines after which a header will be inserted in the report +generated by +.BR "sa2" " script. By default there is only a header at the beginning of" +each report and it is not repeated afterwards. +.TP +.B REPORTS +Set this variable to +.BR "false " "to prevent the " "sa2" +script from generating reports (the +.IR "sarDD " "files)." +.TP +.B SA_DIR +Directory where the standard system activity daily data and report files +are saved. Its default value is +.IR "/var/log/sa" "." +.TP +.B SADC_OPTIONS +Options that should be passed to +.BR "sadc" "(8)." +With these options (see +.BR "sadc" "(8)" +manual page), you can select some additional data which are going to be saved in +daily data files. +These options are used only when a new data file is created. They will be +ignored with an already existing one. +.TP +.B UMASK +.RB "The " "sa1" " and " "sa2" +scripts generate system activity data and report files in the +.IR /var/log/sa +directory. By default the files are created with umask 0022 +and are therefore readable for all users. Change this variable to restrict +the permissions on the files (e.g. use 0027 to adhere to more strict +security standards). +.TP +.B YESTERDAY +.RB "By default " "sa2" +script generates yesterday's summary, since the +.BR "cron " "job" +usually runs right after midnight. If you want +.B sa2 +to generate the summary of the same day (for example when cron +job runs at 23:53) set this variable to +.BR "no" "." +.TP +.B ZIP +Program used to compress data and report files. + +.SH FILE +.I /etc/sysconfig/sysstat + +.SH AUTHOR +Sebastien Godard (sysstat orange.fr) + +.SH SEE ALSO +.BR "sadc" "(8), " "sa1" "(8), " "sa2" "(8)" +.PP +.I https://github.com/sysstat/sysstat +.br +.I https://sysstat.github.io/ diff --git a/upstream/fedora-40/man5/systemd-sleep.conf.5 b/upstream/fedora-40/man5/systemd-sleep.conf.5 new file mode 100644 index 00000000..20d3e071 --- /dev/null +++ b/upstream/fedora-40/man5/systemd-sleep.conf.5 @@ -0,0 +1,236 @@ +'\" t +.TH "SYSTEMD\-SLEEP\&.CONF" "5" "" "systemd 255" "systemd-sleep.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd-sleep.conf, sleep.conf.d \- Suspend and hibernation configuration file +.SH "SYNOPSIS" +.PP +/etc/systemd/sleep\&.conf +.PP +/etc/systemd/sleep\&.conf\&.d/*\&.conf +.PP +/run/systemd/sleep\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/sleep\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +\fBsystemd\fR +supports four general power\-saving modes: +.PP +suspend +.RS 4 +a low\-power state where execution of the OS is paused, and complete power loss might result in lost data, and which is fast to enter and exit\&. This corresponds to suspend, standby, or freeze states as understood by the kernel\&. +.sp +Added in version 203\&. +.RE +.PP +hibernate +.RS 4 +a low\-power state where execution of the OS is paused, and complete power loss does not result in lost data, and which might be slow to enter and exit\&. This corresponds to the hibernation as understood by the kernel\&. +.sp +Added in version 203\&. +.RE +.PP +hybrid\-sleep +.RS 4 +a low\-power state where execution of the OS is paused, which might be slow to enter, and on complete power loss does not result in lost data but might be slower to exit in that case\&. This mode is called suspend\-to\-both by the kernel\&. +.sp +Added in version 203\&. +.RE +.PP +suspend\-then\-hibernate +.RS 4 +A low power state where the system is initially suspended (the state is stored in RAM)\&. When the battery level is too low (less than 5%) or a certain timespan has passed, whichever happens first, the system is automatically woken up and then hibernated\&. This establishes a balance between speed and safety\&. +.sp +If the system has no battery, it would be hibernated after +\fIHibernateDelaySec=\fR +has passed\&. If not set, then defaults to +"2h"\&. +.sp +If the system has battery and +\fIHibernateDelaySec=\fR +is not set, low\-battery alarms (ACPI _BTP) are tried first for detecting battery percentage and wake up the system for hibernation\&. If not available, or +\fIHibernateDelaySec=\fR +is set, the system would regularly wake up to check the time and detect the battery percentage/discharging rate\&. The rate is used to schedule the next detection\&. If that is also not available, +\fISuspendEstimationSec=\fR +is used as last resort\&. +.sp +Added in version 239\&. +.RE +.PP +Settings in these files determine what strings will be written to +/sys/power/disk +and +/sys/power/state +by +\fBsystemd-sleep\fR(8) +when +\fBsystemd\fR(1) +attempts to suspend or hibernate the machine\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +The following options can be configured in the [Sleep] section of +/etc/systemd/sleep\&.conf +or a +sleep\&.conf\&.d +file: +.PP +\fIAllowSuspend=\fR, \fIAllowHibernation=\fR, \fIAllowHybridSleep=\fR, \fIAllowSuspendThenHibernate=\fR +.RS 4 +By default any power\-saving mode is advertised if possible (i\&.e\&. the kernel supports that mode, the necessary resources are available)\&. Those switches can be used to disable specific modes\&. +.sp +If +\fIAllowHibernation=no\fR +or +\fIAllowSuspend=no\fR +is used, this implies +\fIAllowSuspendThenHibernate=no\fR +and +\fIAllowHybridSleep=no\fR, since those methods use both suspend and hibernation internally\&. +\fIAllowSuspendThenHibernate=yes\fR +and +\fIAllowHybridSleep=yes\fR +can be used to override and enable those specific modes\&. +.sp +Added in version 240\&. +.RE +.PP +\fIHibernateMode=\fR +.RS 4 +The string to be written to +/sys/power/disk +by +\fBsystemd-hibernate.service\fR(8)\&. More than one value can be specified by separating multiple values with whitespace\&. They will be tried in turn, until one is written without error\&. If none of the writes succeed, the operation will be aborted\&. +.sp +The allowed set of values is determined by the kernel and is shown in the file itself (use +\fBcat /sys/power/disk\fR +to display)\&. See the kernel documentation page +\m[blue]\fBBasic sysfs Interfaces for System Suspend and Hibernation\fR\m[]\&\s-2\u[1]\d\s+2 +for more details\&. +.sp +\fBsystemd-suspend-then-hibernate.service\fR(8) +uses the value of +\fIHibernateMode=\fR +when hibernating\&. +.sp +Added in version 203\&. +.RE +.PP +\fISuspendState=\fR +.RS 4 +The string to be written to +/sys/power/state +by +\fBsystemd-suspend.service\fR(8)\&. More than one value can be specified by separating multiple values with whitespace\&. They will be tried in turn, until one is written without error\&. If none of the writes succeed, the operation will be aborted\&. +.sp +The allowed set of values is determined by the kernel and is shown in the file itself (use +\fBcat /sys/power/state\fR +to display)\&. See +\m[blue]\fBBasic sysfs Interfaces for System Suspend and Hibernation\fR\m[]\&\s-2\u[1]\d\s+2 +for more details\&. +.sp +\fBsystemd-suspend-then-hibernate.service\fR(8) +uses this value when suspending\&. +.sp +Added in version 203\&. +.RE +.PP +\fIHibernateDelaySec=\fR +.RS 4 +The amount of time the system spends in suspend mode before the system is automatically put into hibernate mode\&. Only used by +\fBsystemd-suspend-then-hibernate.service\fR(8)\&. Refer to +\fBsuspend\-then\-hibernate\fR +for details on how this option interacts with other options/system battery state\&. +.sp +Added in version 239\&. +.RE +.PP +\fISuspendEstimationSec=\fR +.RS 4 +The RTC alarm will wake the system after the specified timespan to measure the system battery capacity level and estimate battery discharging rate\&. Only used by +\fBsystemd-suspend-then-hibernate.service\fR(8)\&. Refer to +\fBsuspend\-then\-hibernate\fR +for details on how this option interacts with other options/system battery state\&. +.sp +Added in version 253\&. +.RE +.SH "EXAMPLE: FREEZE" +.PP +Example: to exploit the +\(lqfreeze\(rq +mode added in Linux 3\&.9, one can use +\fBsystemctl suspend\fR +with +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Sleep] +SuspendState=freeze +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd-sleep\fR(8), +\fBsystemd-suspend.service\fR(8), +\fBsystemd-hibernate.service\fR(8), +\fBsystemd-hybrid-sleep.service\fR(8), +\fBsystemd-suspend-then-hibernate.service\fR(8), +\fBsystemd\fR(1), +\fBsystemd.directives\fR(7) +.SH "NOTES" +.IP " 1." 4 +Basic sysfs Interfaces for System Suspend and Hibernation +.RS 4 +\%https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation +.RE diff --git a/upstream/fedora-40/man5/systemd-system.conf.5 b/upstream/fedora-40/man5/systemd-system.conf.5 new file mode 100644 index 00000000..6d2267c2 --- /dev/null +++ b/upstream/fedora-40/man5/systemd-system.conf.5 @@ -0,0 +1,837 @@ +'\" t +.TH "SYSTEMD\-SYSTEM\&.CONF" "5" "" "systemd 255" "systemd-system.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd-system.conf, system.conf.d, systemd-user.conf, user.conf.d \- System and session service manager configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/system\&.conf, +/etc/systemd/system\&.conf\&.d/*\&.conf, +/run/systemd/system\&.conf\&.d/*\&.conf, +/usr/lib/systemd/system\&.conf\&.d/*\&.conf +.PP +~/\&.config/systemd/user\&.conf, +/etc/systemd/user\&.conf, +/etc/systemd/user\&.conf\&.d/*\&.conf, +/run/systemd/user\&.conf\&.d/*\&.conf, +/usr/lib/systemd/user\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +When run as a system instance, +\fBsystemd\fR +interprets the configuration file +system\&.conf +and the files in +system\&.conf\&.d +directories; when run as a user instance, it interprets the configuration file +user\&.conf +(either in the home directory of the user, or if not found, under +/etc/systemd/) and the files in +user\&.conf\&.d +directories\&. These configuration files contain a few settings controlling basic manager operations\&. +.PP +See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +All options are configured in the [Manager] section: +.PP +\fILogColor=\fR, \fILogLevel=\fR, \fILogLocation=\fR, \fILogTarget=\fR, \fILogTime=\fR, \fIDumpCore=yes\fR, \fICrashChangeVT=no\fR, \fICrashShell=no\fR, \fICrashReboot=no\fR, \fIShowStatus=yes\fR, \fIDefaultStandardOutput=journal\fR, \fIDefaultStandardError=inherit\fR +.RS 4 +Configures various parameters of basic manager operation\&. These options may be overridden by the respective process and kernel command line arguments\&. See +\fBsystemd\fR(1) +for details\&. +.sp +Added in version 198\&. +.RE +.PP +\fICtrlAltDelBurstAction=\fR +.RS 4 +Defines what action will be performed if user presses Ctrl\-Alt\-Delete more than 7 times in 2s\&. Can be set to +"reboot\-force", +"poweroff\-force", +"reboot\-immediate", +"poweroff\-immediate" +or disabled with +"none"\&. Defaults to +"reboot\-force"\&. +.sp +Added in version 232\&. +.RE +.PP +\fICPUAffinity=\fR +.RS 4 +Configures the CPU affinity for the service manager as well as the default CPU affinity for all forked off processes\&. Takes a list of CPU indices or ranges separated by either whitespace or commas\&. CPU ranges are specified by the lower and upper CPU indices separated by a dash\&. This option may be specified more than once, in which case the specified CPU affinity masks are merged\&. If the empty string is assigned, the mask is reset, all assignments prior to this will have no effect\&. Individual services may override the CPU affinity for their processes with the +\fICPUAffinity=\fR +setting in unit files, see +\fBsystemd.exec\fR(5)\&. +.sp +Added in version 198\&. +.RE +.PP +\fINUMAPolicy=\fR +.RS 4 +Configures the NUMA memory policy for the service manager and the default NUMA memory policy for all forked off processes\&. Individual services may override the default policy with the +\fINUMAPolicy=\fR +setting in unit files, see +\fBsystemd.exec\fR(5)\&. +.sp +Added in version 243\&. +.RE +.PP +\fINUMAMask=\fR +.RS 4 +Configures the NUMA node mask that will be associated with the selected NUMA policy\&. Note that +\fBdefault\fR +and +\fBlocal\fR +NUMA policies don\*(Aqt require explicit NUMA node mask and value of the option can be empty\&. Similarly to +\fINUMAPolicy=\fR, value can be overridden by individual services in unit files, see +\fBsystemd.exec\fR(5)\&. +.sp +Added in version 243\&. +.RE +.PP +\fIRuntimeWatchdogSec=\fR, \fIRebootWatchdogSec=\fR, \fIKExecWatchdogSec=\fR +.RS 4 +Configure the hardware watchdog at runtime and at reboot\&. Takes a timeout value in seconds (or in other time units if suffixed with +"ms", +"min", +"h", +"d", +"w"), or the special strings +"off" +or +"default"\&. If set to +"off" +(alternatively: +"0") the watchdog logic is disabled: no watchdog device is opened, configured, or pinged\&. If set to the special string +"default" +the watchdog is opened and pinged in regular intervals, but the timeout is not changed from the default\&. If set to any other time value the watchdog timeout is configured to the specified value (or a value close to it, depending on hardware capabilities)\&. +.sp +If +\fIRuntimeWatchdogSec=\fR +is set to a non\-zero value, the watchdog hardware (/dev/watchdog0 +or the path specified with +\fIWatchdogDevice=\fR +or the kernel option +\fIsystemd\&.watchdog\-device=\fR) will be programmed to automatically reboot the system if it is not contacted within the specified timeout interval\&. The system manager will ensure to contact it at least once in half the specified timeout interval\&. This feature requires a hardware watchdog device to be present, as it is commonly the case in embedded and server systems\&. Not all hardware watchdogs allow configuration of all possible reboot timeout values, in which case the closest available timeout is picked\&. +.sp +\fIRebootWatchdogSec=\fR +may be used to configure the hardware watchdog when the system is asked to reboot\&. It works as a safety net to ensure that the reboot takes place even if a clean reboot attempt times out\&. Note that the +\fIRebootWatchdogSec=\fR +timeout applies only to the second phase of the reboot, i\&.e\&. after all regular services are already terminated, and after the system and service manager process (PID 1) got replaced by the +systemd\-shutdown +binary, see system +\fBbootup\fR(7) +for details\&. During the first phase of the shutdown operation the system and service manager remains running and hence +\fIRuntimeWatchdogSec=\fR +is still honoured\&. In order to define a timeout on this first phase of system shutdown, configure +\fIJobTimeoutSec=\fR +and +\fIJobTimeoutAction=\fR +in the [Unit] section of the +shutdown\&.target +unit\&. By default +\fIRuntimeWatchdogSec=\fR +defaults to 0 (off), and +\fIRebootWatchdogSec=\fR +to 10min\&. +.sp +\fIKExecWatchdogSec=\fR +may be used to additionally enable the watchdog when kexec is being executed rather than when rebooting\&. Note that if the kernel does not reset the watchdog on kexec (depending on the specific hardware and/or driver), in this case the watchdog might not get disabled after kexec succeeds and thus the system might get rebooted, unless +\fIRuntimeWatchdogSec=\fR +is also enabled at the same time\&. For this reason it is recommended to enable +\fIKExecWatchdogSec=\fR +only if +\fIRuntimeWatchdogSec=\fR +is also enabled\&. +.sp +These settings have no effect if a hardware watchdog is not available\&. +.sp +Added in version 198\&. +.RE +.PP +\fIRuntimeWatchdogPreSec=\fR +.RS 4 +Configure the hardware watchdog device pre\-timeout value\&. Takes a timeout value in seconds (or in other time units similar to +\fIRuntimeWatchdogSec=\fR)\&. A watchdog pre\-timeout is a notification generated by the watchdog before the watchdog reset might occur in the event the watchdog has not been serviced\&. This notification is handled by the kernel and can be configured to take an action (i\&.e\&. generate a kernel panic) using +\fIRuntimeWatchdogPreGovernor=\fR\&. Not all watchdog hardware or drivers support generating a pre\-timeout and depending on the state of the system, the kernel may be unable to take the configured action before the watchdog reboot\&. The watchdog will be configured to generate the pre\-timeout event at the amount of time specified by +\fIRuntimeWatchdogPreSec=\fR +before the runtime watchdog timeout (set by +\fIRuntimeWatchdogSec=\fR)\&. For example, if the we have +\fIRuntimeWatchdogSec=30\fR +and +\fIRuntimeWatchdogPreSec=10\fR, then the pre\-timeout event will occur if the watchdog has not pinged for 20s (10s before the watchdog would fire)\&. By default, +\fIRuntimeWatchdogPreSec=\fR +defaults to 0 (off)\&. The value set for +\fIRuntimeWatchdogPreSec=\fR +must be smaller than the timeout value for +\fIRuntimeWatchdogSec=\fR\&. This setting has no effect if a hardware watchdog is not available or the hardware watchdog does not support a pre\-timeout and will be ignored by the kernel if the setting is greater than the actual watchdog timeout\&. +.sp +Added in version 251\&. +.RE +.PP +\fIRuntimeWatchdogPreGovernor=\fR +.RS 4 +Configure the action taken by the hardware watchdog device when the pre\-timeout expires\&. The default action for the pre\-timeout event depends on the kernel configuration, but it is usually to log a kernel message\&. For a list of valid actions available for a given watchdog device, check the content of the +/sys/class/watchdog/watchdog\fIX\fR/pretimeout_available_governors +file\&. Typically, available governor types are +\fInoop\fR +and +\fIpanic\fR\&. Availability, names and functionality might vary depending on the specific device driver in use\&. If the +pretimeout_available_governors +sysfs file is empty, the governor might be built as a kernel module and might need to be manually loaded (e\&.g\&. +\fIpretimeout_noop\&.ko\fR), or the watchdog device might not support pre\-timeouts\&. +.sp +Added in version 251\&. +.RE +.PP +\fIWatchdogDevice=\fR +.RS 4 +Configure the hardware watchdog device that the runtime and shutdown watchdog timers will open and use\&. Defaults to +/dev/watchdog0\&. This setting has no effect if a hardware watchdog is not available\&. +.sp +Added in version 236\&. +.RE +.PP +\fICapabilityBoundingSet=\fR +.RS 4 +Controls which capabilities to include in the capability bounding set for PID 1 and its children\&. See +\fBcapabilities\fR(7) +for details\&. Takes a whitespace\-separated list of capability names as read by +\fBcap_from_name\fR(3)\&. Capabilities listed will be included in the bounding set, all others are removed\&. If the list of capabilities is prefixed with ~, all but the listed capabilities will be included, the effect of the assignment inverted\&. Note that this option also affects the respective capabilities in the effective, permitted and inheritable capability sets\&. The capability bounding set may also be individually configured for units using the +\fICapabilityBoundingSet=\fR +directive for units, but note that capabilities dropped for PID 1 cannot be regained in individual units, they are lost for good\&. +.sp +Added in version 198\&. +.RE +.PP +\fINoNewPrivileges=\fR +.RS 4 +Takes a boolean argument\&. If true, ensures that PID 1 and all its children can never gain new privileges through +\fBexecve\fR(2) +(e\&.g\&. via setuid or setgid bits, or filesystem capabilities)\&. Defaults to false\&. General purpose distributions commonly rely on executables with setuid or setgid bits and will thus not function properly with this option enabled\&. Individual units cannot disable this option\&. Also see +\m[blue]\fBNo New Privileges Flag\fR\m[]\&\s-2\u[1]\d\s+2\&. +.sp +Added in version 239\&. +.RE +.PP +\fISystemCallArchitectures=\fR +.RS 4 +Takes a space\-separated list of architecture identifiers\&. Selects from which architectures system calls may be invoked on this system\&. This may be used as an effective way to disable invocation of non\-native binaries system\-wide, for example to prohibit execution of 32\-bit x86 binaries on 64\-bit x86\-64 systems\&. This option operates system\-wide, and acts similar to the +\fISystemCallArchitectures=\fR +setting of unit files, see +\fBsystemd.exec\fR(5) +for details\&. This setting defaults to the empty list, in which case no filtering of system calls based on architecture is applied\&. Known architecture identifiers are +"x86", +"x86\-64", +"x32", +"arm" +and the special identifier +"native"\&. The latter implicitly maps to the native architecture of the system (or more specifically, the architecture the system manager was compiled for)\&. Set this setting to +"native" +to prohibit execution of any non\-native binaries\&. When a binary executes a system call of an architecture that is not listed in this setting, it will be immediately terminated with the SIGSYS signal\&. +.sp +Added in version 209\&. +.RE +.PP +\fITimerSlackNSec=\fR +.RS 4 +Sets the timer slack in nanoseconds for PID 1, which is inherited by all executed processes, unless overridden individually, for example with the +\fITimerSlackNSec=\fR +setting in service units (for details see +\fBsystemd.exec\fR(5))\&. The timer slack controls the accuracy of wake\-ups triggered by system timers\&. See +\fBprctl\fR(2) +for more information\&. Note that in contrast to most other time span definitions this parameter takes an integer value in nano\-seconds if no unit is specified\&. The usual time units are understood too\&. +.sp +Added in version 198\&. +.RE +.PP +\fIStatusUnitFormat=\fR +.RS 4 +Takes +\fBname\fR, +\fBdescription\fR +or +\fBcombined\fR +as the value\&. If +\fBname\fR, the system manager will use unit names in status messages (e\&.g\&. +"systemd\-journald\&.service"), instead of the longer and more informative descriptions set with +\fIDescription=\fR +(e\&.g\&. +"Journal Logging Service")\&. If +\fBcombined\fR, the system manager will use both unit names and descriptions in status messages (e\&.g\&. +"systemd\-journald\&.service \- Journal Logging Service")\&. +.sp +See +\fBsystemd.unit\fR(5) +for details about unit names and +\fIDescription=\fR\&. +.sp +Added in version 243\&. +.RE +.PP +\fIDefaultTimerAccuracySec=\fR +.RS 4 +Sets the default accuracy of timer units\&. This controls the global default for the +\fIAccuracySec=\fR +setting of timer units, see +\fBsystemd.timer\fR(5) +for details\&. +\fIAccuracySec=\fR +set in individual units override the global default for the specific unit\&. Defaults to 1min\&. Note that the accuracy of timer units is also affected by the configured timer slack for PID 1, see +\fITimerSlackNSec=\fR +above\&. +.sp +Added in version 212\&. +.RE +.PP +\fIDefaultTimeoutStartSec=\fR, \fIDefaultTimeoutStopSec=\fR, \fIDefaultTimeoutAbortSec=\fR, \fIDefaultRestartSec=\fR +.RS 4 +Configures the default timeouts for starting, stopping and aborting of units, as well as the default time to sleep between automatic restarts of units, as configured per\-unit in +\fITimeoutStartSec=\fR, +\fITimeoutStopSec=\fR, +\fITimeoutAbortSec=\fR +and +\fIRestartSec=\fR +(for services, see +\fBsystemd.service\fR(5) +for details on the per\-unit settings)\&. For non\-service units, +\fIDefaultTimeoutStartSec=\fR +sets the default +\fITimeoutSec=\fR +value\&. +.sp +\fIDefaultTimeoutStartSec=\fR +and +\fIDefaultTimeoutStopSec=\fR +default to 45 s in the system manager and 45 s in the user manager\&. +\fIDefaultTimeoutAbortSec=\fR +is not set by default so that all units fall back to +\fITimeoutStopSec=\fR\&. +\fIDefaultRestartSec=\fR +defaults to 100 ms\&. +.sp +Added in version 209\&. +.RE +.PP +\fIDefaultDeviceTimeoutSec=\fR +.RS 4 +Configures the default timeout for waiting for devices\&. It can be changed per device via the +\fIx\-systemd\&.device\-timeout=\fR +option in +/etc/fstab +and +/etc/crypttab +(see +\fBsystemd.mount\fR(5), +\fBcrypttab\fR(5))\&. Defaults to 45 s in the system manager and 45 s in the user manager\&. +.sp +Added in version 252\&. +.RE +.PP +\fIDefaultStartLimitIntervalSec=\fR, \fIDefaultStartLimitBurst=\fR +.RS 4 +Configure the default unit start rate limiting, as configured per\-service by +\fIStartLimitIntervalSec=\fR +and +\fIStartLimitBurst=\fR\&. See +\fBsystemd.service\fR(5) +for details on the per\-service settings\&. +\fIDefaultStartLimitIntervalSec=\fR +defaults to 10s\&. +\fIDefaultStartLimitBurst=\fR +defaults to 5\&. +.sp +Added in version 209\&. +.RE +.PP +\fIDefaultEnvironment=\fR +.RS 4 +Configures environment variables passed to all executed processes\&. Takes a space\-separated list of variable assignments\&. See +\fBenviron\fR(7) +for details about environment variables\&. +.sp +Simple +"%"\-specifier expansion is supported, see below for a list of supported specifiers\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6" +.fi +.if n \{\ +.RE +.\} +.sp +Sets three variables +"VAR1", +"VAR2", +"VAR3"\&. +.sp +Added in version 205\&. +.RE +.PP +\fIManagerEnvironment=\fR +.RS 4 +Takes the same arguments as +\fIDefaultEnvironment=\fR, see above\&. Sets environment variables just for the manager process itself\&. In contrast to user managers, these variables are not inherited by processes spawned by the system manager, use +\fIDefaultEnvironment=\fR +for that\&. Note that these variables are merged into the existing environment block\&. In particular, in case of the system manager, this includes variables set by the kernel based on the kernel command line\&. +.sp +Setting environment variables for the manager process may be useful to modify its behaviour\&. See +\m[blue]\fBKnown Environment Variables\fR\m[]\&\s-2\u[2]\d\s+2 +for a descriptions of some variables understood by +\fBsystemd\fR\&. +.sp +Simple +"%"\-specifier expansion is supported, see below for a list of supported specifiers\&. +.sp +Added in version 248\&. +.RE +.PP +\fIDefaultCPUAccounting=\fR, \fIDefaultMemoryAccounting=\fR, \fIDefaultTasksAccounting=\fR, \fIDefaultIOAccounting=\fR, \fIDefaultIPAccounting=\fR +.RS 4 +Configure the default resource accounting settings, as configured per\-unit by +\fICPUAccounting=\fR, +\fIMemoryAccounting=\fR, +\fITasksAccounting=\fR, +\fIIOAccounting=\fR +and +\fIIPAccounting=\fR\&. See +\fBsystemd.resource-control\fR(5) +for details on the per\-unit settings\&. +.sp +\fIDefaultCPUAccounting=\fR +defaults to yes when running on kernel ≥4\&.15, and no on older versions\&. +\fIDefaultMemoryAccounting=\fR +defaults to yes\&. +\fIDefaultTasksAccounting=\fR +defaults to yes\&. The other settings default to no\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDefaultTasksMax=\fR +.RS 4 +Configure the default value for the per\-unit +\fITasksMax=\fR +setting\&. See +\fBsystemd.resource-control\fR(5) +for details\&. This setting applies to all unit types that support resource control settings, with the exception of slice units\&. Defaults to 15% of the minimum of +\fIkernel\&.pid_max=\fR, +\fIkernel\&.threads\-max=\fR +and root cgroup +\fIpids\&.max\fR\&. Kernel has a default value for +\fIkernel\&.pid_max=\fR +and an algorithm of counting in case of more than 32 cores\&. For example, with the default +\fIkernel\&.pid_max=\fR, +\fIDefaultTasksMax=\fR +defaults to 4915, but might be greater in other systems or smaller in OS containers\&. +.sp +Added in version 228\&. +.RE +.PP +\fIDefaultLimitCPU=\fR, \fIDefaultLimitFSIZE=\fR, \fIDefaultLimitDATA=\fR, \fIDefaultLimitSTACK=\fR, \fIDefaultLimitCORE=\fR, \fIDefaultLimitRSS=\fR, \fIDefaultLimitNOFILE=\fR, \fIDefaultLimitAS=\fR, \fIDefaultLimitNPROC=\fR, \fIDefaultLimitMEMLOCK=\fR, \fIDefaultLimitLOCKS=\fR, \fIDefaultLimitSIGPENDING=\fR, \fIDefaultLimitMSGQUEUE=\fR, \fIDefaultLimitNICE=\fR, \fIDefaultLimitRTPRIO=\fR, \fIDefaultLimitRTTIME=\fR +.RS 4 +These settings control various default resource limits for processes executed by units\&. See +\fBsetrlimit\fR(2) +for details\&. These settings may be overridden in individual units using the corresponding +\fILimitXXX=\fR +directives and they accept the same parameter syntax, see +\fBsystemd.exec\fR(5) +for details\&. Note that these resource limits are only defaults for units, they are not applied to the service manager process (i\&.e\&. PID 1) itself\&. +.sp +Most of these settings are unset, which means the resource limits are inherited from the kernel or, if invoked in a container, from the container manager\&. However, the following have defaults: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIDefaultLimitNOFILE=\fR +defaults to 1024:524288\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIDefaultLimitMEMLOCK=\fR +defaults to 8M\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIDefaultLimitCORE=\fR +does not have a default but it is worth mentioning that +\fIRLIMIT_CORE\fR +is set to +"infinity" +by PID 1 which is inherited by its children\&. +.RE +.sp +Note that the service manager internally in PID 1 bumps +\fIRLIMIT_NOFILE\fR +and +\fIRLIMIT_MEMLOCK\fR +to higher values, however the limit is reverted to the mentioned defaults for all child processes forked off\&. +.sp +Added in version 198\&. +.RE +.PP +\fIDefaultOOMPolicy=\fR +.RS 4 +Configure the default policy for reacting to processes being killed by the Linux Out\-Of\-Memory (OOM) killer or +\fBsystemd\-oomd\fR\&. This may be used to pick a global default for the per\-unit +\fIOOMPolicy=\fR +setting\&. See +\fBsystemd.service\fR(5) +for details\&. Note that this default is not used for services that have +\fIDelegate=\fR +turned on\&. +.sp +Added in version 243\&. +.RE +.PP +\fIDefaultOOMScoreAdjust=\fR +.RS 4 +Configures the default OOM score adjustments of processes run by the service manager\&. This defaults to unset (meaning the forked off processes inherit the service manager\*(Aqs OOM score adjustment value), except if the service manager is run for an unprivileged user, in which case this defaults to the service manager\*(Aqs OOM adjustment value plus 100 (this makes service processes slightly more likely to be killed under memory pressure than the manager itself)\&. This may be used to pick a global default for the per\-unit +\fIOOMScoreAdjust=\fR +setting\&. See +\fBsystemd.exec\fR(5) +for details\&. Note that this setting has no effect on the OOM score adjustment value of the service manager process itself, it retains the original value set during its invocation\&. +.sp +Added in version 250\&. +.RE +.PP +\fIDefaultSmackProcessLabel=\fR +.RS 4 +Takes a +\fBSMACK64\fR +security label as the argument\&. The process executed by a unit will be started under this label if +\fISmackProcessLabel=\fR +is not set in the unit\&. See +\fBsystemd.exec\fR(5) +for the details\&. +.sp +If the value is +"/", only labels specified with +\fISmackProcessLabel=\fR +are assigned and the compile\-time default is ignored\&. +.sp +Added in version 252\&. +.RE +.PP +\fIReloadLimitIntervalSec=\fR, \fIReloadLimitBurst=\fR +.RS 4 +Rate limiting for daemon\-reload requests\&. Default to unset, and any number of daemon\-reload operations can be requested at any time\&. +\fIReloadLimitIntervalSec=\fR +takes a value in seconds to configure the rate limit window, and +\fIReloadLimitBurst=\fR +takes a positive integer to configure the maximum allowed number of reloads within the configured time window\&. +.sp +Added in version 253\&. +.RE +.PP +\fIDefaultMemoryPressureWatch=\fR, \fIDefaultMemoryPressureThresholdSec=\fR +.RS 4 +Configures the default settings for the per\-unit +\fIMemoryPressureWatch=\fR +and +\fIMemoryPressureThresholdSec=\fR +settings\&. See +\fBsystemd.resource-control\fR(5) +for details\&. Defaults to +"auto" +and +"200ms", respectively\&. This also sets the memory pressure monitoring threshold for the service manager itself\&. +.sp +Added in version 254\&. +.RE +.SH "SPECIFIERS" +.PP +Specifiers may be used in the +\fIDefaultEnvironment=\fR +and +\fIManagerEnvironment=\fR +settings\&. The following expansions are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system\&. +T} +T{ +"%l" +T}:T{ +Short host name +T}:T{ +The hostname of the running system, truncated at the first dot to remove any domain component\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%T" +T}:T{ +Directory for temporary files +T}:T{ +This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%V" +T}:T{ +Directory for larger and persistent temporary files +T}:T{ +This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%h" +T}:T{ +User home directory +T}:T{ +This is the home directory of the \fIuser running the service manager instance\fR\&. +T} +T{ +"%u" +T}:T{ +Username +T}:T{ +This is the username of the \fIuser running the service manager instance\fR\&. +T} +T{ +"%U" +T}:T{ +User id +T}:T{ +This is the user id of the \fIuser running the service manager instance\fR\&. +T} +T{ +"%g" +T}:T{ +Primary group +T}:T{ +This is the primary group of the \fIuser running the service manager instance\fR\&. +T} +T{ +"%G" +T}:T{ +Primary group id +T}:T{ +This is the primary group id of the \fIuser running the service manager instance\fR\&. +T} +T{ +"%s" +T}:T{ +User shell +T}:T{ +This is the shell of the \fIuser running the service manager instance\fR\&. +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +.SH "HISTORY" +.PP +systemd 252 +.RS 4 +Option +\fIDefaultBlockIOAccounting=\fR +was deprecated\&. Please switch to the unified cgroup hierarchy\&. +.sp +Added in version 252\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd.directives\fR(7), +\fBsystemd.exec\fR(5), +\fBsystemd.service\fR(5), +\fBenviron\fR(7), +\fBcapabilities\fR(7) +.SH "NOTES" +.IP " 1." 4 +No New Privileges Flag +.RS 4 +\%https://docs.kernel.org/userspace-api/no_new_privs.html +.RE +.IP " 2." 4 +Known Environment Variables +.RS 4 +\%https://systemd.io/ENVIRONMENT +.RE diff --git a/upstream/fedora-40/man5/systemd.automount.5 b/upstream/fedora-40/man5/systemd.automount.5 new file mode 100644 index 00000000..b61efb9a --- /dev/null +++ b/upstream/fedora-40/man5/systemd.automount.5 @@ -0,0 +1,192 @@ +'\" t +.TH "SYSTEMD\&.AUTOMOUNT" "5" "" "systemd 255" "systemd.automount" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.automount \- Automount unit configuration +.SH "SYNOPSIS" +.PP +\fIautomount\fR\&.automount +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.automount" +encodes information about a file system automount point controlled and supervised by systemd\&. Automount units may be used to implement on\-demand mounting as well as parallelized mounting of file systems\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The automount specific configuration options are configured in the [Automount] section\&. +.PP +Automount units must be named after the automount directories they control\&. Example: the automount point +/home/lennart +must be configured in a unit file +home\-lennart\&.automount\&. For details about the escaping logic used to convert a file system path to a unit name see +\fBsystemd.unit\fR(5)\&. Note that automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating symlinks to its unit file\&. +.PP +For each automount unit file a matching mount unit file (see +\fBsystemd.mount\fR(5) +for details) must exist which is activated when the automount path is accessed\&. Example: if an automount unit +home\-lennart\&.automount +is active and the user accesses +/home/lennart +the mount unit +home\-lennart\&.mount +will be activated\&. +.PP +Note that automount units are separate from the mount itself, so you should not set +\fIAfter=\fR +or +\fIRequires=\fR +for mount dependencies here\&. For example, you should not set +\fIAfter=network\-online\&.target\fR +or similar on network filesystems\&. Doing so may result in an ordering cycle\&. +.PP +Note that automount support on Linux is privileged, automount units are hence only available in the system service manager (and root\*(Aqs user service manager), but not in unprivileged users\*(Aq service managers\&. +.PP +Note that automount units should not be nested\&. (The establishment of the inner automount point would unconditionally pin the outer mount point, defeating its purpose\&.) +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If an automount unit is beneath another mount unit in the file system hierarchy, a requirement and ordering dependencies are created to the on the unit higher in the hierarchy\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An implicit +\fIBefore=\fR +dependency is created between an automount unit and the mount unit it activates\&. +.RE +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Automount units acquire automatic +\fIBefore=\fR +and +\fIConflicts=\fR +on +umount\&.target +in order to be stopped during shutdown\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Automount units automatically gain an +\fIAfter=\fR +dependency on +local\-fs\-pre\&.target, and a +\fIBefore=\fR +dependency on +local\-fs\&.target\&. +.RE +.SH "FSTAB" +.PP +Automount units may either be configured via unit files, or via +/etc/fstab +(see +\fBfstab\fR(5) +for details)\&. +.PP +For details how systemd parses +/etc/fstab +see +\fBsystemd.mount\fR(5)\&. +.PP +If an automount point is configured in both +/etc/fstab +and a unit file, the configuration in the latter takes precedence\&. +.SH "OPTIONS" +.PP +Automount unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Automount unit files must include an [Automount] section, which carries information about the file system automount points it supervises\&. The options specific to the [Automount] section of automount units are the following: +.PP +\fIWhere=\fR +.RS 4 +Takes an absolute path of a directory of the automount point\&. If the automount point does not exist at time that the automount point is installed, it is created\&. This string must be reflected in the unit filename\&. (See above\&.) This option is mandatory\&. +.RE +.PP +\fIExtraOptions=\fR +.RS 4 +Extra mount options to use when creating the autofs mountpoint\&. This takes a comma\-separated list of options\&. This setting is optional\&. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as +"%%"\&. +.sp +Added in version 250\&. +.RE +.PP +\fIDirectoryMode=\fR +.RS 4 +Directories of automount points (and any parent directories) are automatically created if needed\&. This option specifies the file system access mode used when creating these directories\&. Takes an access mode in octal notation\&. Defaults to 0755\&. +.RE +.PP +\fITimeoutIdleSec=\fR +.RS 4 +Configures an idle timeout\&. Once the mount has been idle for the specified time, systemd will attempt to unmount\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass 0 to disable the timeout logic\&. The timeout is disabled by default\&. +.sp +Added in version 220\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.mount\fR(5), +\fBmount\fR(8), +\fBautomount\fR(8), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/systemd.device.5 b/upstream/fedora-40/man5/systemd.device.5 new file mode 100644 index 00000000..6d6744c4 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.device.5 @@ -0,0 +1,138 @@ +'\" t +.TH "SYSTEMD\&.DEVICE" "5" "" "systemd 255" "systemd.device" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.device \- Device unit configuration +.SH "SYNOPSIS" +.PP +\fIdevice\fR\&.device +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.device" +encodes information about a device unit as exposed in the sysfs/\fBudev\fR(7) +device tree\&. This may be used to define dependencies between devices and other units\&. +.PP +This unit type has no specific options\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. A separate [Device] section does not exist, since no device\-specific options may be configured\&. +.PP +systemd will dynamically create device units for all kernel devices that are marked with the +"systemd" +udev tag (by default all block and network devices, and a few others)\&. Note that +\fIif \fR\fIsystemd\-udevd\&.service\fR\fI is not running, no device units will be available (for example in a typical container)\fR\&. +.PP +Device units are named after the +/sys/ +and +/dev/ +paths they control\&. Example: the device +/dev/sda5 +is exposed in systemd as +dev\-sda5\&.device\&. For details about the escaping logic used to convert a file system path to a unit name see +\fBsystemd.unit\fR(5)\&. +.PP +To tag a udev device, use +"TAG+="systemd"" +in the udev rules file, see +\fBudev\fR(7) +for details\&. +.PP +Device units will be reloaded by systemd whenever the corresponding device generates a +"changed" +event\&. Other units can use +\fIReloadPropagatedFrom=\fR +to react to that event\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +Many unit types automatically acquire dependencies on device units of devices they require\&. For example, +\&.socket +unit acquire dependencies on the device units of the network interface specified in +\fIBindToDevice=\fR\&. Similar, swap and mount units acquire dependencies on the units encapsulating their backing block devices\&. +.SS "Default Dependencies" +.PP +There are no default dependencies for device units\&. +.SH "THE UDEV DATABASE" +.PP +Unit settings of device units may either be configured via unit files, or directly from the udev database\&. The following udev device properties are understood by the service manager: +.PP +\fISYSTEMD_WANTS=\fR, \fISYSTEMD_USER_WANTS=\fR +.RS 4 +Adds dependencies of type +\fIWants=\fR +from the device unit to the specified units\&. +\fISYSTEMD_WANTS=\fR +is read by the system service manager, +\fISYSTEMD_USER_WANTS=\fR +by user service manager instances\&. These properties may be used to activate arbitrary units when a specific device becomes available\&. +.sp +Note that this and the other udev device properties are not taken into account unless the device is tagged with the +"systemd" +tag in the udev database, because otherwise the device is not exposed as a systemd unit (see above)\&. +.sp +Note that systemd will only act on +\fIWants=\fR +dependencies when a device first becomes active\&. It will not act on them if they are added to devices that are already active\&. Use +\fISYSTEMD_READY=\fR +(see below) to configure when a udev device shall be considered active, and thus when to trigger the dependencies\&. +.sp +The specified property value should be a space\-separated list of valid unit names\&. If a unit template name is specified (that is, a unit name containing an +"@" +character indicating a unit name to use for multiple instantiation, but with an empty instance name following the +"@"), it will be automatically instantiated by the device\*(Aqs +"sysfs" +path (that is: the path is escaped and inserted as instance name into the template unit name)\&. This is useful in order to instantiate a specific template unit once for each device that appears and matches specific properties\&. +.RE +.PP +\fISYSTEMD_ALIAS=\fR +.RS 4 +Adds an additional alias name to the device unit\&. This must be an absolute path that is automatically transformed into a unit name\&. (See above\&.) +.RE +.PP +\fISYSTEMD_READY=\fR +.RS 4 +If set to 0, systemd will consider this device unplugged even if it shows up in the udev tree\&. If this property is unset or set to 1, the device will be considered plugged if it is visible in the udev tree\&. +.sp +This option is useful for devices that initially show up in an uninitialized state in the tree, and for which a +"changed" +event is generated the moment they are fully set up\&. Note that +\fISYSTEMD_WANTS=\fR +(see above) is not acted on as long as +\fISYSTEMD_READY=0\fR +is set for a device\&. +.RE +.PP +\fIID_MODEL_FROM_DATABASE=\fR, \fIID_MODEL=\fR +.RS 4 +If set, this property is used as description string for the device unit\&. +.RE +.SH "OPTIONS" +.PP +Device unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. No options specific to this file type are supported\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.unit\fR(5), +\fBudev\fR(7), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/systemd.dnssd.5 b/upstream/fedora-40/man5/systemd.dnssd.5 new file mode 100644 index 00000000..708d02ca --- /dev/null +++ b/upstream/fedora-40/man5/systemd.dnssd.5 @@ -0,0 +1,336 @@ +'\" t +.TH "SYSTEMD\&.DNSSD" "5" "" "systemd 255" "systemd.dnssd" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.dnssd \- DNS\-SD configuration +.SH "SYNOPSIS" +.PP +\fInetwork_service\fR\&.dnssd +.SH "DESCRIPTION" +.PP +DNS\-SD setup is performed by +\fBsystemd-resolved\fR(8)\&. +.PP +The main network service file must have the extension +\&.dnssd; other extensions are ignored\&. +.PP +The +\&.dnssd +files are read from the files located in the system network directories +/usr/lib/systemd/dnssd +and +/usr/local/lib/systemd/dnssd, the volatile runtime network directory +/run/systemd/dnssd +and the local administration network directory +/etc/systemd/dnssd\&. All configuration files are collectively sorted and processed in lexical order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. Files in +/etc/ +have the highest priority, files in +/run/ +take precedence over files with the same name in +/usr/lib/\&. This can be used to override a system\-supplied configuration file with a local file if needed\&. +.PP +Along with the network service file +foo\&.dnssd, a "drop\-in" directory +foo\&.dnssd\&.d/ +may exist\&. All files with the suffix +"\&.conf" +from this directory will be parsed after the file itself is parsed\&. This is useful to alter or add configuration settings, without having to modify the main configuration file\&. Each drop\-in file must have appropriate section headers\&. +.PP +In addition to +/etc/systemd/dnssd, drop\-in +"\&.d" +directories can be placed in +/usr/lib/systemd/dnssd +or +/run/systemd/dnssd +directories\&. Drop\-in files in +/etc/ +take precedence over those in +/run/ +which in turn take precedence over those in +/usr/lib/ +or +/usr/local/lib\&. Drop\-in files under any of these directories take precedence over the main network service file wherever located\&. +.SH "[SERVICE] SECTION OPTIONS" +.PP +The network service file contains a [Service] section, which specifies a discoverable network service announced in a local network with Multicast DNS broadcasts\&. +.PP +\fIName=\fR +.RS 4 +An instance name of the network service as defined in the section 4\&.1\&.1 of +\m[blue]\fBRFC 6763\fR\m[]\&\s-2\u[1]\d\s+2, e\&.g\&. +"webserver"\&. +.sp +The option supports simple specifier expansion\&. The following expansions are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +Added in version 236\&. +.RE +.PP +\fIType=\fR +.RS 4 +A type of the network service as defined in the section 4\&.1\&.2 of +\m[blue]\fBRFC 6763\fR\m[]\&\s-2\u[1]\d\s+2, e\&.g\&. +"_http\&._tcp"\&. +.sp +Added in version 236\&. +.RE +.PP +\fIPort=\fR +.RS 4 +An IP port number of the network service\&. +.sp +Added in version 236\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +A priority number set in +\fBSRV\fR +resource records corresponding to the network service\&. +.sp +Added in version 236\&. +.RE +.PP +\fIWeight=\fR +.RS 4 +A weight number set in +\fBSRV\fR +resource records corresponding to the network service\&. +.sp +Added in version 236\&. +.RE +.PP +\fITxtText=\fR +.RS 4 +A whitespace\-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record, e\&.g\&. +"path=/portal/index\&.html"\&. Keys and values can contain C\-style escape sequences which get translated upon reading configuration files\&. +.sp +This option together with +\fITxtData=\fR +may be specified more than once, in which case multiple TXT resource records will be created for the service\&. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect\&. +.sp +Added in version 236\&. +.RE +.PP +\fITxtData=\fR +.RS 4 +A whitespace\-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record where values are base64\-encoded string representing any binary data, e\&.g\&. +"data=YW55IGJpbmFyeSBkYXRhCg=="\&. Keys can contain C\-style escape sequences which get translated upon reading configuration files\&. +.sp +This option together with +\fITxtText=\fR +may be specified more than once, in which case multiple TXT resource records will be created for the service\&. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect\&. +.sp +Added in version 236\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&HTTP service\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/dnssd/http\&.dnssd +[Service] +Name=%H +Type=_http\&._tcp +Port=80 +TxtText=path=/stats/index\&.html t=temperature_sensor +.fi +.if n \{\ +.RE +.\} +.PP +This makes the http server running on the host discoverable in the local network given MulticastDNS is enabled on the network interface\&. +.PP +Now the utility +"resolvectl" +should be able to resolve the service to the host\*(Aqs name: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ resolvectl service meteo\&._http\&._tcp\&.local +meteo\&._http\&._tcp\&.local: meteo\&.local:80 [priority=0, weight=0] + 169\&.254\&.208\&.106%senp0s21f0u2u4 + fe80::213:3bff:fe49:8aa%senp0s21f0u2u4 + path=/stats/index\&.html + t=temperature_sensor + (meteo/_http\&._tcp/local) + +\-\- Information acquired via protocol mDNS/IPv6 in 4\&.0ms\&. +\-\- Data is authenticated: yes +.fi +.if n \{\ +.RE +.\} +.PP +"Avahi" +running on a different host in the same local network should see the service as well: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ avahi\-browse \-a \-r ++ enp3s0 IPv6 meteo Web Site local ++ enp3s0 IPv4 meteo Web Site local += enp3s0 IPv6 meteo Web Site local + hostname = [meteo\&.local] + address = [fe80::213:3bff:fe49:8aa] + port = [80] + txt = ["path=/stats/index\&.html" "t=temperature_sensor"] += enp3s0 IPv4 meteo Web Site local + hostname = [meteo\&.local] + address = [169\&.254\&.208\&.106] + port = [80] + txt = ["path=/stats/index\&.html" "t=temperature_sensor"] +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-resolved.service\fR(8), +\fBresolvectl\fR(1) +.SH "NOTES" +.IP " 1." 4 +RFC 6763 +.RS 4 +\%https://tools.ietf.org/html/rfc6763 +.RE diff --git a/upstream/fedora-40/man5/systemd.exec.5 b/upstream/fedora-40/man5/systemd.exec.5 new file mode 100644 index 00000000..3e30d6d5 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.exec.5 @@ -0,0 +1,5667 @@ +'\" t +.TH "SYSTEMD\&.EXEC" "5" "" "systemd 255" "systemd.exec" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.exec \- Execution environment configuration +.SH "SYNOPSIS" +.PP +\fIservice\fR\&.service, +\fIsocket\fR\&.socket, +\fImount\fR\&.mount, +\fIswap\fR\&.swap +.SH "DESCRIPTION" +.PP +Unit configuration files for services, sockets, mount points, and swap devices share a subset of configuration options which define the execution environment of spawned processes\&. +.PP +This man page lists the configuration options shared by these four unit types\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files, and +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.swap\fR(5), and +\fBsystemd.mount\fR(5) +for more information on the specific unit configuration files\&. The execution specific configuration options are configured in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type\&. +.PP +In addition, options which control resources through Linux Control Groups (cgroups) are listed in +\fBsystemd.resource-control\fR(5)\&. Those options complement options listed here\&. +.SH "IMPLICIT DEPENDENCIES" +.PP +A few execution parameters result in additional, automatic dependencies to be added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Units with +\fIWorkingDirectory=\fR, +\fIRootDirectory=\fR, +\fIRootImage=\fR, +\fIRuntimeDirectory=\fR, +\fIStateDirectory=\fR, +\fICacheDirectory=\fR, +\fILogsDirectory=\fR +or +\fIConfigurationDirectory=\fR +set automatically gain dependencies of type +\fIRequires=\fR +and +\fIAfter=\fR +on all mount units required to access the specified paths\&. This is equivalent to having them listed explicitly in +\fIRequiresMountsFor=\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Similarly, units with +\fIPrivateTmp=\fR +enabled automatically get mount unit dependencies for all mounts required to access +/tmp/ +and +/var/tmp/\&. They will also gain an automatic +\fIAfter=\fR +dependency on +\fBsystemd-tmpfiles-setup.service\fR(8)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Units whose standard output or error output is connected to +\fBjournal\fR +or +\fBkmsg\fR +(or their combinations with console output, see below) automatically acquire dependencies of type +\fIAfter=\fR +on +systemd\-journald\&.socket\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Units using +\fILogNamespace=\fR +will automatically gain ordering and requirement dependencies on the two socket units associated with +systemd\-journald@\&.service +instances\&. +.RE +.SH "PATHS" +.PP +The following settings may be used to change a service\*(Aqs view of the filesystem\&. Please note that the paths must be absolute and must not contain a +"\&.\&." +path component\&. +.PP +\fIExecSearchPath=\fR +.RS 4 +Takes a colon separated list of absolute paths relative to which the executable used by the +\fIExec*=\fR +(e\&.g\&. +\fIExecStart=\fR, +\fIExecStop=\fR, etc\&.) properties can be found\&. +\fIExecSearchPath=\fR +overrides +\fI$PATH\fR +if +\fI$PATH\fR +is not supplied by the user through +\fIEnvironment=\fR, +\fIEnvironmentFile=\fR +or +\fIPassEnvironment=\fR\&. Assigning an empty string removes previous assignments and setting +\fIExecSearchPath=\fR +to a value multiple times will append to the previous setting\&. +.sp +Added in version 250\&. +.RE +.PP +\fIWorkingDirectory=\fR +.RS 4 +Takes a directory path relative to the service\*(Aqs root directory specified by +\fIRootDirectory=\fR, or the special value +"~"\&. Sets the working directory for executed processes\&. If set to +"~", the home directory of the user specified in +\fIUser=\fR +is used\&. If not set, defaults to the root directory when systemd is running as a system instance and the respective user\*(Aqs home directory if run as user\&. If the setting is prefixed with the +"\-" +character, a missing working directory is not considered fatal\&. If +\fIRootDirectory=\fR/\fIRootImage=\fR +is not set, then +\fIWorkingDirectory=\fR +is relative to the root of the system running the service manager\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&. +.RE +.PP +\fIRootDirectory=\fR +.RS 4 +Takes a directory path relative to the host\*(Aqs root directory (i\&.e\&. the root of the system running the service manager)\&. Sets the root directory for executed processes, with the +\fBchroot\fR(2) +system call\&. If this is used, it must be ensured that the process binary and all its auxiliary files are available in the +\fBchroot()\fR +jail\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&. +.sp +The +\fIMountAPIVFS=\fR +and +\fIPrivateUsers=\fR +settings are particularly useful in conjunction with +\fIRootDirectory=\fR\&. For details, see below\&. +.sp +If +\fIRootDirectory=\fR/\fIRootImage=\fR +are used together with +\fINotifyAccess=\fR +the notification socket is automatically mounted from the host into the root environment, to ensure the notification interface can work correctly\&. +.sp +Note that services using +\fIRootDirectory=\fR/\fIRootImage=\fR +will not be able to log via the syslog or journal protocols to the host logging infrastructure, unless the relevant sockets are mounted from the host, specifically: +.sp +The host\*(Aqs +\fBos-release\fR(5) +file will be made available for the service (read\-only) as +/run/host/os\-release\&. It will be updated automatically on soft reboot (see: +\fBsystemd-soft-reboot.service\fR(8)), in case the service is configured to survive it\&. +.PP +\fBExample\ \&1.\ \&Mounting logging sockets into root environment\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout +.fi +.if n \{\ +.RE +.\} + +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.RE +.PP +\fIRootImage=\fR +.RS 4 +Takes a path to a block device node or regular file as argument\&. This call is similar to +\fIRootDirectory=\fR +however mounts a file system hierarchy from a block device node or loopback file instead of a directory\&. The device node or file system image file needs to contain a file system without a partition table, or a file system within an MBR/MS\-DOS or GPT partition table with only a single Linux\-compatible partition, or a set of file systems within a GPT partition table that follows the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.sp +When +\fIDevicePolicy=\fR +is set to +"closed" +or +"strict", or set to +"auto" +and +\fIDeviceAllow=\fR +is set, then this setting adds +/dev/loop\-control +with +\fBrw\fR +mode, +"block\-loop" +and +"block\-blkext" +with +\fBrwm\fR +mode to +\fIDeviceAllow=\fR\&. See +\fBsystemd.resource-control\fR(5) +for the details about +\fIDevicePolicy=\fR +or +\fIDeviceAllow=\fR\&. Also, see +\fIPrivateDevices=\fR +below, as it may change the setting of +\fIDevicePolicy=\fR\&. +.sp +Units making use of +\fIRootImage=\fR +automatically gain an +\fIAfter=\fR +dependency on +systemd\-udevd\&.service\&. +.sp +The host\*(Aqs +\fBos-release\fR(5) +file will be made available for the service (read\-only) as +/run/host/os\-release\&. It will be updated automatically on soft reboot (see: +\fBsystemd-soft-reboot.service\fR(8)), in case the service is configured to survive it\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 233\&. +.RE +.PP +\fIRootImageOptions=\fR +.RS 4 +Takes a comma\-separated list of mount options that will be used on disk images specified by +\fIRootImage=\fR\&. Optionally a partition name can be prefixed, followed by colon, in case the image has multiple partitions, otherwise partition name +"root" +is implied\&. Options for multiple partitions can be specified in a single line with space separators\&. Assigning an empty string removes previous assignments\&. Duplicated options are ignored\&. For a list of valid mount options, please refer to +\fBmount\fR(8)\&. +.sp +Valid partition names follow the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2: +\fBroot\fR, +\fBusr\fR, +\fBhome\fR, +\fBsrv\fR, +\fBesp\fR, +\fBxbootldr\fR, +\fBtmp\fR, +\fBvar\fR\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 247\&. +.RE +.PP +\fIRootEphemeral=\fR +.RS 4 +Takes a boolean argument\&. If enabled, executed processes will run in an ephemeral copy of the root directory or root image\&. The ephemeral copy is placed in +/var/lib/systemd/ephemeral\-trees/ +while the service is active and is cleaned up when the service is stopped or restarted\&. If +\fIRootDirectory=\fR +is used and the root directory is a subvolume, the ephemeral copy will be created by making a snapshot of the subvolume\&. +.sp +To make sure making ephemeral copies can be made efficiently, the root directory or root image should be located on the same filesystem as +/var/lib/systemd/ephemeral\-trees/\&. When using +\fIRootEphemeral=\fR +with root directories, +\fBbtrfs\fR(5) +should be used as the filesystem and the root directory should ideally be a subvolume which +\fBsystemd\fR +can snapshot to make the ephemeral copy\&. For root images, a filesystem with support for reflinks should be used to ensure an efficient ephemeral copy\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 254\&. +.RE +.PP +\fIRootHash=\fR +.RS 4 +Takes a data integrity (dm\-verity) root hash specified in hexadecimal, or the path to a file containing a root hash in ASCII hexadecimal format\&. This option enables data integrity checks using dm\-verity, if the used image contains the appropriate integrity data (see above) or if +\fIRootVerity=\fR +is used\&. The specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64 formatted hexadecimal characters) long (in case of SHA256 for example)\&. If this option is not specified, but the image file carries the +"user\&.verity\&.roothash" +extended file attribute (see +\fBxattr\fR(7)), then the root hash is read from it, also as formatted hexadecimal characters\&. If the extended file attribute is not found (or is not supported by the underlying file system), but a file with the +\&.roothash +suffix is found next to the image file, bearing otherwise the same name (except if the image has the +\&.raw +suffix, in which case the root hash file must not have it in its name), the root hash is read from it and automatically used, also as formatted hexadecimal characters\&. +.sp +If the disk image contains a separate +/usr/ +partition it may also be Verity protected, in which case the root hash may configured via an extended attribute +"user\&.verity\&.usrhash" +or a +\&.usrhash +file adjacent to the disk image\&. There\*(Aqs currently no option to configure the root hash for the +/usr/ +file system via the unit file directly\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRootHashSignature=\fR +.RS 4 +Takes a PKCS7 signature of the +\fIRootHash=\fR +option as a path to a DER\-encoded signature file, or as an ASCII base64 string encoding of a DER\-encoded signature prefixed by +"base64:"\&. The dm\-verity volume will only be opened if the signature of the root hash is valid and signed by a public key present in the kernel keyring\&. If this option is not specified, but a file with the +\&.roothash\&.p7s +suffix is found next to the image file, bearing otherwise the same name (except if the image has the +\&.raw +suffix, in which case the signature file must not have it in its name), the signature is read from it and automatically used\&. +.sp +If the disk image contains a separate +/usr/ +partition it may also be Verity protected, in which case the signature for the root hash may configured via a +\&.usrhash\&.p7s +file adjacent to the disk image\&. There\*(Aqs currently no option to configure the root hash signature for the +/usr/ +via the unit file directly\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRootVerity=\fR +.RS 4 +Takes the path to a data integrity (dm\-verity) file\&. This option enables data integrity checks using dm\-verity, if +\fIRootImage=\fR +is used and a root\-hash is passed and if the used image itself does not contain the integrity data\&. The integrity data must be matched by the root hash\&. If this option is not specified, but a file with the +\&.verity +suffix is found next to the image file, bearing otherwise the same name (except if the image has the +\&.raw +suffix, in which case the verity data file must not have it in its name), the verity data is read from it and automatically used\&. +.sp +This option is supported only for disk images that contain a single file system, without an enveloping partition table\&. Images that contain a GPT partition table should instead include both root file system and matching Verity data in the same image, implementing the +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRootImagePolicy=\fR, \fIMountImagePolicy=\fR, \fIExtensionImagePolicy=\fR +.RS 4 +Takes an image policy string as per +\fBsystemd.image-policy\fR(7) +to use when mounting the disk images (DDI) specified in +\fIRootImage=\fR, +\fIMountImage=\fR, +\fIExtensionImage=\fR, respectively\&. If not specified the following policy string is the default for +\fIRootImagePolicy=\fR +and +\fIMountImagePolicy\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +root=verity+signed+encrypted+unprotected+absent: \e + usr=verity+signed+encrypted+unprotected+absent: \e + home=encrypted+unprotected+absent: \e + srv=encrypted+unprotected+absent: \e + tmp=encrypted+unprotected+absent: \e + var=encrypted+unprotected+absent +.fi +.if n \{\ +.RE +.\} +.sp +The default policy for +\fIExtensionImagePolicy=\fR +is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +root=verity+signed+encrypted+unprotected+absent: \e + usr=verity+signed+encrypted+unprotected+absent +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 254\&. +.RE +.PP +\fIMountAPIVFS=\fR +.RS 4 +Takes a boolean argument\&. If on, a private mount namespace for the unit\*(Aqs processes is created and the API file systems +/proc/, +/sys/, +/dev/ +and +/run/ +(as an empty +"tmpfs") are mounted inside of it, unless they are already mounted\&. Note that this option has no effect unless used in conjunction with +\fIRootDirectory=\fR/\fIRootImage=\fR +as these four mounts are generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace will be a 1:1 copy of the host\*(Aqs, and include these four mounts\&. Note that the +/dev/ +file system of the host is bind mounted if this option is used without +\fIPrivateDevices=\fR\&. To run the service with a private, minimal version of +/dev/, combine this option with +\fIPrivateDevices=\fR\&. +.sp +In order to allow propagating mounts at runtime in a safe manner, +/run/systemd/propagate/ +on the host will be used to set up new mounts, and +/run/host/incoming/ +in the private namespace will be used as an intermediate step to store them before being moved to the final mount point\&. +.sp +Added in version 233\&. +.RE +.PP +\fIProtectProc=\fR +.RS 4 +Takes one of +"noaccess", +"invisible", +"ptraceable" +or +"default" +(which it defaults to)\&. When set, this controls the +"hidepid=" +mount option of the +"procfs" +instance for the unit that controls which directories with process metainformation (/proc/\fIPID\fR) are visible and accessible: when set to +"noaccess" +the ability to access most of other users\*(Aq process metadata in +/proc/ +is taken away for processes of the service\&. When set to +"invisible" +processes owned by other users are hidden from +/proc/\&. If +"ptraceable" +all processes that cannot be +\fBptrace()\fR\*(Aqed by a process are hidden to it\&. If +"default" +no restrictions on +/proc/ +access or visibility are made\&. For further details see +\m[blue]\fBThe /proc Filesystem\fR\m[]\&\s-2\u[2]\d\s+2\&. It is generally recommended to run most system services with this option set to +"invisible"\&. This option is implemented via file system namespacing, and thus cannot be used with services that shall be able to install mount points in the host file system hierarchy\&. Note that the root user is unaffected by this option, so to be effective it has to be used together with +\fIUser=\fR +or +\fIDynamicUser=yes\fR, and also without the +"CAP_SYS_PTRACE" +capability, which also allows a process to bypass this feature\&. It cannot be used for services that need to access metainformation about other users\*(Aq processes\&. This option implies +\fIMountAPIVFS=\fR\&. +.sp +If the kernel doesn\*(Aqt support per\-mount point +\fBhidepid=\fR +mount options this setting remains without effect, and the unit\*(Aqs processes will be able to access and see other process as if the option was not used\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 247\&. +.RE +.PP +\fIProcSubset=\fR +.RS 4 +Takes one of +"all" +(the default) and +"pid"\&. If +"pid", all files and directories not directly associated with process management and introspection are made invisible in the +/proc/ +file system configured for the unit\*(Aqs processes\&. This controls the +"subset=" +mount option of the +"procfs" +instance for the unit\&. For further details see +\m[blue]\fBThe /proc Filesystem\fR\m[]\&\s-2\u[2]\d\s+2\&. Note that Linux exposes various kernel APIs via +/proc/, which are made unavailable with this setting\&. Since these APIs are used frequently this option is useful only in a few, specific cases, and is not suitable for most non\-trivial programs\&. +.sp +Much like +\fIProtectProc=\fR +above, this is implemented via file system mount namespacing, and hence the same restrictions apply: it is only available to system services, it disables mount propagation to the host mount table, and it implies +\fIMountAPIVFS=\fR\&. Also, like +\fIProtectProc=\fR +this setting is gracefully disabled if the used kernel does not support the +"subset=" +mount option of +"procfs"\&. +.sp +Added in version 247\&. +.RE +.PP +\fIBindPaths=\fR, \fIBindReadOnlyPaths=\fR +.RS 4 +Configures unit\-specific bind mounts\&. A bind mount makes a particular file or directory available at an additional place in the unit\*(Aqs view of the file system\&. Any bind mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&. This option expects a whitespace separated list of bind mount definitions\&. Each definition consists of a colon\-separated triple of source path, destination path and option string, where the latter two are optional\&. If only a source path is specified the source and destination is taken to be the same\&. The option string may be either +"rbind" +or +"norbind" +for configuring a recursive or non\-recursive bind mount\&. If the destination path is omitted, the option string must be omitted too\&. Each bind mount definition may be prefixed with +"\-", in which case it will be ignored when its source path does not exist\&. +.sp +\fIBindPaths=\fR +creates regular writable bind mounts (unless the source file system mount is already marked read\-only), while +\fIBindReadOnlyPaths=\fR +creates read\-only bind mounts\&. These settings may be used more than once, each usage appends to the unit\*(Aqs list of bind mounts\&. If the empty string is assigned to either of these two options the entire list of bind mounts defined prior to this is reset\&. Note that in this case both read\-only and regular bind mounts are reset, regardless which of the two settings is used\&. +.sp +This option is particularly useful when +\fIRootDirectory=\fR/\fIRootImage=\fR +is used\&. In this case the source path refers to a path on the host file system, while the destination path refers to a path below the root directory of the unit\&. +.sp +Note that the destination directory must exist or systemd must be able to create it\&. Thus, it is not possible to use those options for mount points nested underneath paths specified in +\fIInaccessiblePaths=\fR, or under +/home/ +and other protected directories if +\fIProtectHome=yes\fR +is specified\&. +\fITemporaryFileSystem=\fR +with +":ro" +or +\fIProtectHome=tmpfs\fR +should be used instead\&. +.sp +Added in version 233\&. +.RE +.PP +\fIMountImages=\fR +.RS 4 +This setting is similar to +\fIRootImage=\fR +in that it mounts a file system hierarchy from a block device node or loopback file, but the destination directory can be specified as well as mount options\&. This option expects a whitespace separated list of mount definitions\&. Each definition consists of a colon\-separated tuple of source path and destination definitions, optionally followed by another colon and a list of mount options\&. +.sp +Mount options may be defined as a single comma\-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon\-separated tuples of partition name and mount options\&. Valid partition names and mount options are the same as for +\fIRootImageOptions=\fR +setting described above\&. +.sp +Each mount definition may be prefixed with +"\-", in which case it will be ignored when its source path does not exist\&. The source argument is a path to a block device node or regular file\&. If source or destination contain a +":", it needs to be escaped as +"\e:"\&. The device node or file system image file needs to follow the same rules as specified for +\fIRootImage=\fR\&. Any mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&. +.sp +These settings may be used more than once, each usage appends to the unit\*(Aqs list of mount paths\&. If the empty string is assigned, the entire list of mount paths defined prior to this is reset\&. +.sp +Note that the destination directory must exist or systemd must be able to create it\&. Thus, it is not possible to use those options for mount points nested underneath paths specified in +\fIInaccessiblePaths=\fR, or under +/home/ +and other protected directories if +\fIProtectHome=yes\fR +is specified\&. +.sp +When +\fIDevicePolicy=\fR +is set to +"closed" +or +"strict", or set to +"auto" +and +\fIDeviceAllow=\fR +is set, then this setting adds +/dev/loop\-control +with +\fBrw\fR +mode, +"block\-loop" +and +"block\-blkext" +with +\fBrwm\fR +mode to +\fIDeviceAllow=\fR\&. See +\fBsystemd.resource-control\fR(5) +for the details about +\fIDevicePolicy=\fR +or +\fIDeviceAllow=\fR\&. Also, see +\fIPrivateDevices=\fR +below, as it may change the setting of +\fIDevicePolicy=\fR\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 247\&. +.RE +.PP +\fIExtensionImages=\fR +.RS 4 +This setting is similar to +\fIMountImages=\fR +in that it mounts a file system hierarchy from a block device node or loopback file, but instead of providing a destination path, an overlay will be set up\&. This option expects a whitespace separated list of mount definitions\&. Each definition consists of a source path, optionally followed by a colon and a list of mount options\&. +.sp +A read\-only OverlayFS will be set up on top of +/usr/ +and +/opt/ +hierarchies for sysext images and +/etc/ +hierarchy for confext images\&. The order in which the images are listed will determine the order in which the overlay is laid down: images specified first to last will result in overlayfs layers bottom to top\&. +.sp +Mount options may be defined as a single comma\-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon\-separated tuples of partition name and mount options\&. Valid partition names and mount options are the same as for +\fIRootImageOptions=\fR +setting described above\&. +.sp +Each mount definition may be prefixed with +"\-", in which case it will be ignored when its source path does not exist\&. The source argument is a path to a block device node or regular file\&. If the source path contains a +":", it needs to be escaped as +"\e:"\&. The device node or file system image file needs to follow the same rules as specified for +\fIRootImage=\fR\&. Any mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&. +.sp +These settings may be used more than once, each usage appends to the unit\*(Aqs list of image paths\&. If the empty string is assigned, the entire list of mount paths defined prior to this is reset\&. +.sp +Each sysext image must carry a +/usr/lib/extension\-release\&.d/extension\-release\&.IMAGE +file while each confext image must carry a +/etc/extension\-release\&.d/extension\-release\&.IMAGE +file, with the appropriate metadata which matches +\fIRootImage=\fR/\fIRootDirectory=\fR +or the host\&. See: +\fBos-release\fR(5)\&. To disable the safety check that the extension\-release file name matches the image file name, the +\fIx\-systemd\&.relax\-extension\-release\-check\fR +mount option may be appended\&. +.sp +When +\fIDevicePolicy=\fR +is set to +"closed" +or +"strict", or set to +"auto" +and +\fIDeviceAllow=\fR +is set, then this setting adds +/dev/loop\-control +with +\fBrw\fR +mode, +"block\-loop" +and +"block\-blkext" +with +\fBrwm\fR +mode to +\fIDeviceAllow=\fR\&. See +\fBsystemd.resource-control\fR(5) +for the details about +\fIDevicePolicy=\fR +or +\fIDeviceAllow=\fR\&. Also, see +\fIPrivateDevices=\fR +below, as it may change the setting of +\fIDevicePolicy=\fR\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 248\&. +.RE +.PP +\fIExtensionDirectories=\fR +.RS 4 +This setting is similar to +\fIBindReadOnlyPaths=\fR +in that it mounts a file system hierarchy from a directory, but instead of providing a destination path, an overlay will be set up\&. This option expects a whitespace separated list of source directories\&. +.sp +A read\-only OverlayFS will be set up on top of +/usr/ +and +/opt/ +hierarchies for sysext images and +/etc/ +hierarchy for confext images\&. The order in which the directories are listed will determine the order in which the overlay is laid down: directories specified first to last will result in overlayfs layers bottom to top\&. +.sp +Each directory listed in +\fIExtensionDirectories=\fR +may be prefixed with +"\-", in which case it will be ignored when its source path does not exist\&. Any mounts created with this option are specific to the unit, and are not visible in the host\*(Aqs mount table\&. +.sp +These settings may be used more than once, each usage appends to the unit\*(Aqs list of directories paths\&. If the empty string is assigned, the entire list of mount paths defined prior to this is reset\&. +.sp +Each sysext directory must contain a +/usr/lib/extension\-release\&.d/extension\-release\&.IMAGE +file while each confext directory must carry a +/etc/extension\-release\&.d/extension\-release\&.IMAGE +file, with the appropriate metadata which matches +\fIRootImage=\fR/\fIRootDirectory=\fR +or the host\&. See: +\fBos-release\fR(5)\&. +.sp +Note that usage from user units requires overlayfs support in unprivileged user namespaces, which was first introduced in kernel v5\&.11\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 251\&. +.RE +.SH "USER/GROUP IDENTITY" +.PP +These options are only available for system services and are not supported for services running in per\-user instances of the service manager\&. +.PP +\fIUser=\fR, \fIGroup=\fR +.RS 4 +Set the UNIX user or group that the processes are executed as, respectively\&. Takes a single user or group name, or a numeric ID as argument\&. For system services (services run by the system service manager, i\&.e\&. managed by PID 1) and for user services of the root user (services managed by root\*(Aqs instance of +\fBsystemd \-\-user\fR), the default is +"root", but +\fIUser=\fR +may be used to specify a different user\&. For user services of any other user, switching user identity is not permitted, hence the only valid setting is the same user the user\*(Aqs service manager is running as\&. If no group is set, the default group of the user is used\&. This setting does not affect commands whose command line is prefixed with +"+"\&. +.sp +Note that this enforces only weak restrictions on the user/group name syntax, but will generate warnings in many cases where user/group names do not adhere to the following rules: the specified name should consist only of the characters a\-z, A\-Z, 0\-9, +"_" +and +"\-", except for the first character which must be one of a\-z, A\-Z and +"_" +(i\&.e\&. digits and +"\-" +are not permitted as first character)\&. The user/group name must have at least one character, and at most 31\&. These restrictions are made in order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux systems\&. For further details on the names accepted and the names warned about see +\m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[3]\d\s+2\&. +.sp +When used in conjunction with +\fIDynamicUser=\fR +the user/group name specified is dynamically allocated at the time the service is started, and released at the time the service is stopped \(em unless it is already allocated statically (see below)\&. If +\fIDynamicUser=\fR +is not used the specified user and group must have been created statically in the user database no later than the moment the service is started, for example using the +\fBsysusers.d\fR(5) +facility, which is applied at boot or package install time\&. If the user does not exist by then program invocation will fail\&. +.sp +If the +\fIUser=\fR +setting is used the supplementary group list is initialized from the specified user\*(Aqs default group list, as defined in the system\*(Aqs user and group database\&. Additional groups may be configured through the +\fISupplementaryGroups=\fR +setting (see below)\&. +.RE +.PP +\fIDynamicUser=\fR +.RS 4 +Takes a boolean parameter\&. If set, a UNIX user and group pair is allocated dynamically when the unit is started, and released as soon as it is stopped\&. The user and group will not be added to +/etc/passwd +or +/etc/group, but are managed transiently during runtime\&. The +\fBnss-systemd\fR(8) +glibc NSS module provides integration of these dynamic users/groups into the system\*(Aqs user and group databases\&. The user and group name to use may be configured via +\fIUser=\fR +and +\fIGroup=\fR +(see above)\&. If these options are not used and dynamic user/group allocation is enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name\&. If the unit name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a hash of it is used\&. If a statically allocated user or group of the configured name already exists, it is used and no dynamic user/group is allocated\&. Note that if +\fIUser=\fR +is specified and the static group with the name exists, then it is required that the static user with the name already exists\&. Similarly, if +\fIGroup=\fR +is specified and the static user with the name exists, then it is required that the static group with the name already exists\&. Dynamic users/groups are allocated from the UID/GID range 61184\&...65519\&. It is recommended to avoid this range for regular system or login users\&. At any point in time each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in use\&. However, UID/GIDs are recycled after a unit is terminated\&. Care should be taken that any processes running as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to these files or directories\&. If +\fIDynamicUser=\fR +is enabled, +\fIRemoveIPC=\fR +and +\fIPrivateTmp=\fR +are implied (and cannot be turned off)\&. This ensures that the lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic user/group\&. Since +/tmp/ +and +/var/tmp/ +are usually the only world\-writable directories on a system this ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit termination\&. Furthermore +\fINoNewPrivileges=\fR +and +\fIRestrictSUIDSGID=\fR +are implicitly enabled (and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID files or directories\&. Moreover +\fIProtectSystem=strict\fR +and +\fIProtectHome=read\-only\fR +are implied, thus prohibiting the service to write to arbitrary file system locations\&. In order to allow the service to write to certain directories, they have to be allow\-listed using +\fIReadWritePaths=\fR, but care must be taken so that UID/GID recycling doesn\*(Aqt create security issues involving files created by the service\&. Use +\fIRuntimeDirectory=\fR +(see below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and removed automatically when the unit is terminated\&. Use +\fIStateDirectory=\fR, +\fICacheDirectory=\fR +and +\fILogsDirectory=\fR +in order to assign a set of writable directories for specific purposes to the service in a way that they are protected from vulnerabilities due to UID reuse (see below)\&. If this option is enabled, care should be taken that the unit\*(Aqs processes do not get access to directories outside of these explicitly configured and managed ones\&. Specifically, do not use +\fIBindPaths=\fR +and be careful with +\fBAF_UNIX\fR +file descriptor passing for directory file descriptors, as this would permit processes to create files or directories owned by the dynamic user/group that are not subject to the lifecycle and access guarantees of the service\&. Note that this option is currently incompatible with D\-Bus policies, thus a service using this option may currently not allocate a D\-Bus service name (note that this does not affect calling into other D\-Bus services)\&. Defaults to off\&. +.sp +Added in version 232\&. +.RE +.PP +\fISupplementaryGroups=\fR +.RS 4 +Sets the supplementary Unix groups the processes are executed as\&. This takes a space\-separated list of group names or IDs\&. This option may be specified more than once, in which case all listed groups are set as supplementary groups\&. When the empty string is assigned, the list of supplementary groups is reset, and all assignments prior to this one will have no effect\&. In any way, this option does not override, but extends the list of supplementary groups configured in the system group database for the user\&. This does not affect commands prefixed with +"+"\&. +.RE +.PP +\fISetLoginEnvironment=\fR +.RS 4 +Takes a boolean parameter that controls whether to set +\fI$HOME\fR, +\fI$LOGNAME\fR, and +\fI$SHELL\fR +environment variables\&. If unset, this is controlled by whether +\fIUser=\fR +is set\&. If true, they will always be set for system services, i\&.e\&. even when the default user +"root" +is used\&. If false, the mentioned variables are not set by systemd, no matter whether +\fIUser=\fR +is used or not\&. This option normally has no effect on user services, since these variables are typically inherited from user manager\*(Aqs own environment anyway\&. +.sp +Added in version 255\&. +.RE +.PP +\fIPAMName=\fR +.RS 4 +Sets the PAM service name to set up a session as\&. If set, the executed process will be registered as a PAM session under the specified service name\&. This is only useful in conjunction with the +\fIUser=\fR +setting, and is otherwise ignored\&. If not set, no PAM session will be opened for the executed processes\&. See +\fBpam\fR(8) +for details\&. +.sp +Note that for each unit making use of this option a PAM session handler process will be maintained as part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be taken when the unit and hence the PAM session terminates\&. This process is named +"(sd\-pam)" +and is an immediate child process of the unit\*(Aqs main process\&. +.sp +Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the main unit process will be migrated to its own session scope unit when it is activated\&. This process will hence be associated with two units: the unit it was originally started from (and for which +\fIPAMName=\fR +was configured), and the session scope unit\&. Any child processes of that process will however be associated with the session scope unit only\&. This has implications when used in combination with +\fINotifyAccess=\fR\fBall\fR, as these child processes will not be able to affect changes in the original unit through notification messages\&. These messages will be considered belonging to the session scope unit and not the original unit\&. It is hence not recommended to use +\fIPAMName=\fR +in combination with +\fINotifyAccess=\fR\fBall\fR\&. +.RE +.SH "CAPABILITIES" +.PP +These options are only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.PP +\fICapabilityBoundingSet=\fR +.RS 4 +Controls which capabilities to include in the capability bounding set for the executed process\&. See +\fBcapabilities\fR(7) +for details\&. Takes a whitespace\-separated list of capability names, e\&.g\&. +\fBCAP_SYS_ADMIN\fR, +\fBCAP_DAC_OVERRIDE\fR, +\fBCAP_SYS_PTRACE\fR\&. Capabilities listed will be included in the bounding set, all others are removed\&. If the list of capabilities is prefixed with +"~", all but the listed capabilities will be included, the effect of the assignment inverted\&. Note that this option also affects the respective capabilities in the effective, permitted and inheritable capability sets\&. If this option is not used, the capability bounding set is not modified on process execution, hence no limits on the capabilities of the process are enforced\&. This option may appear more than once, in which case the bounding sets are merged by +\fBOR\fR, or by +\fBAND\fR +if the lines are prefixed with +"~" +(see below)\&. If the empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior settings have no effect\&. If set to +"~" +(without any further argument), the bounding set is reset to the full set of available capabilities, also undoing any previous settings\&. This does not affect commands prefixed with +"+"\&. +.sp +Use +\fBsystemd-analyze\fR(1)\*(Aqs +\fBcapability\fR +command to retrieve a list of capabilities defined on the local system\&. +.sp +Example: if a unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +CapabilityBoundingSet=CAP_A CAP_B +CapabilityBoundingSet=CAP_B CAP_C +.fi +.if n \{\ +.RE +.\} +.sp +then +\fBCAP_A\fR, +\fBCAP_B\fR, and +\fBCAP_C\fR +are set\&. If the second line is prefixed with +"~", e\&.g\&., +.sp +.if n \{\ +.RS 4 +.\} +.nf +CapabilityBoundingSet=CAP_A CAP_B +CapabilityBoundingSet=~CAP_B CAP_C +.fi +.if n \{\ +.RE +.\} +.sp +then, only +\fBCAP_A\fR +is set\&. +.RE +.PP +\fIAmbientCapabilities=\fR +.RS 4 +Controls which capabilities to include in the ambient capability set for the executed process\&. Takes a whitespace\-separated list of capability names, e\&.g\&. +\fBCAP_SYS_ADMIN\fR, +\fBCAP_DAC_OVERRIDE\fR, +\fBCAP_SYS_PTRACE\fR\&. This option may appear more than once, in which case the ambient capability sets are merged (see the above examples in +\fICapabilityBoundingSet=\fR)\&. If the list of capabilities is prefixed with +"~", all but the listed capabilities will be included, the effect of the assignment inverted\&. If the empty string is assigned to this option, the ambient capability set is reset to the empty capability set, and all prior settings have no effect\&. If set to +"~" +(without any further argument), the ambient capability set is reset to the full set of available capabilities, also undoing any previous settings\&. Note that adding capabilities to the ambient capability set adds them to the process\*(Aqs inherited capability set\&. +.sp +Ambient capability sets are useful if you want to execute a process as a non\-privileged user but still want to give it some capabilities\&. Note that in this case option +\fBkeep\-caps\fR +is automatically added to +\fISecureBits=\fR +to retain the capabilities over the user change\&. +\fIAmbientCapabilities=\fR +does not affect commands prefixed with +"+"\&. +.sp +Added in version 229\&. +.RE +.SH "SECURITY" +.PP +\fINoNewPrivileges=\fR +.RS 4 +Takes a boolean argument\&. If true, ensures that the service process and all its children can never gain new privileges through +\fBexecve()\fR +(e\&.g\&. via setuid or setgid bits, or filesystem capabilities)\&. This is the simplest and most effective way to ensure that a process and its children can never elevate privileges again\&. Defaults to false\&. In case the service will be run in a new mount namespace anyway and SELinux is disabled, all file systems are mounted with +\fBMS_NOSUID\fR +flag\&. Also see +\m[blue]\fBNo New Privileges Flag\fR\m[]\&\s-2\u[4]\d\s+2\&. +.sp +Note that this setting only has an effect on the unit\*(Aqs processes themselves (or any processes directly or indirectly forked off them)\&. It has no effect on processes potentially invoked on request of them through tools such as +\fBat\fR(1), +\fBcrontab\fR(1), +\fBsystemd-run\fR(1), or arbitrary IPC services\&. +.sp +Added in version 187\&. +.RE +.PP +\fISecureBits=\fR +.RS 4 +Controls the secure bits set for the executed process\&. Takes a space\-separated combination of options from the following list: +\fBkeep\-caps\fR, +\fBkeep\-caps\-locked\fR, +\fBno\-setuid\-fixup\fR, +\fBno\-setuid\-fixup\-locked\fR, +\fBnoroot\fR, and +\fBnoroot\-locked\fR\&. This option may appear more than once, in which case the secure bits are ORed\&. If the empty string is assigned to this option, the bits are reset to 0\&. This does not affect commands prefixed with +"+"\&. See +\fBcapabilities\fR(7) +for details\&. +.RE +.SH "MANDATORY ACCESS CONTROL" +.PP +These options are only available for system services and are not supported for services running in per\-user instances of the service manager\&. +.PP +\fISELinuxContext=\fR +.RS 4 +Set the SELinux security context of the executed process\&. If set, this will override the automated domain transition\&. However, the policy still needs to authorize the transition\&. This directive is ignored if SELinux is disabled\&. If prefixed by +"\-", failing to set the SELinux security context will be ignored, but it\*(Aqs still possible that the subsequent +\fBexecve()\fR +may fail if the policy doesn\*(Aqt allow the transition for the non\-overridden context\&. This does not affect commands prefixed with +"+"\&. See +\fBsetexeccon\fR(3) +for details\&. +.sp +Added in version 209\&. +.RE +.PP +\fIAppArmorProfile=\fR +.RS 4 +Takes a profile name as argument\&. The process executed by the unit will switch to this profile when started\&. Profiles must already be loaded in the kernel, or the unit will fail\&. If prefixed by +"\-", all errors will be ignored\&. This setting has no effect if AppArmor is not enabled\&. This setting does not affect commands prefixed with +"+"\&. +.sp +Added in version 210\&. +.RE +.PP +\fISmackProcessLabel=\fR +.RS 4 +Takes a +\fBSMACK64\fR +security label as argument\&. The process executed by the unit will be started under this label and SMACK will decide whether the process is allowed to run or not, based on it\&. The process will continue to run under the label specified here unless the executable has its own +\fBSMACK64EXEC\fR +label, in which case the process will transition to run under that label\&. When not specified, the label that systemd is running under is used\&. This directive is ignored if SMACK is disabled\&. +.sp +The value may be prefixed by +"\-", in which case all errors will be ignored\&. An empty value may be specified to unset previous assignments\&. This does not affect commands prefixed with +"+"\&. +.sp +Added in version 218\&. +.RE +.SH "PROCESS PROPERTIES" +.PP +\fILimitCPU=\fR, \fILimitFSIZE=\fR, \fILimitDATA=\fR, \fILimitSTACK=\fR, \fILimitCORE=\fR, \fILimitRSS=\fR, \fILimitNOFILE=\fR, \fILimitAS=\fR, \fILimitNPROC=\fR, \fILimitMEMLOCK=\fR, \fILimitLOCKS=\fR, \fILimitSIGPENDING=\fR, \fILimitMSGQUEUE=\fR, \fILimitNICE=\fR, \fILimitRTPRIO=\fR, \fILimitRTTIME=\fR +.RS 4 +Set soft and hard limits on various resources for executed processes\&. See +\fBsetrlimit\fR(2) +for details on the process resource limit concept\&. Process resource limits may be specified in two formats: either as single value to set a specific soft and hard limit to the same value, or as colon\-separated pair +\fBsoft:hard\fR +to set both limits individually (e\&.g\&. +"LimitAS=4G:16G")\&. Use the string +\fBinfinity\fR +to configure no limit on a specific resource\&. The multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits measured in bytes (e\&.g\&. +"LimitAS=16G")\&. For the limits referring to time values, the usual time units ms, s, min, h and so on may be used (see +\fBsystemd.time\fR(7) +for details)\&. Note that if no time unit is specified for +\fILimitCPU=\fR +the default unit of seconds is implied, while for +\fILimitRTTIME=\fR +the default unit of microseconds is implied\&. Also, note that the effective granularity of the limits might influence their enforcement\&. For example, time limits specified for +\fILimitCPU=\fR +will be rounded up implicitly to multiples of 1s\&. For +\fILimitNICE=\fR +the value may be specified in two syntaxes: if prefixed with +"+" +or +"\-", the value is understood as regular Linux nice value in the range \-20\&...19\&. If not prefixed like this the value is understood as raw resource limit parameter in the range 0\&...40 (with 0 being equivalent to 1)\&. +.sp +Note that most process resource limits configured with these options are per\-process, and processes may fork in order to acquire a new set of resources that are accounted independently of the original process, and may thus escape limits set\&. Also note that +\fILimitRSS=\fR +is not implemented on Linux, and setting it has no effect\&. Often it is advisable to prefer the resource controls listed in +\fBsystemd.resource-control\fR(5) +over these per\-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and are generally more expressive\&. For example, +\fIMemoryMax=\fR +is a more powerful (and working) replacement for +\fILimitRSS=\fR\&. +.sp +Note that +\fILimitNPROC=\fR +will limit the number of processes from one (real) UID and not the number of processes started (forked) by the service\&. Therefore the limit is cumulative for all processes running under the same UID\&. Please also note that the +\fILimitNPROC=\fR +will not be enforced if the service is running as root (and not dropping privileges)\&. Due to these limitations, +\fITasksMax=\fR +(see +\fBsystemd.resource-control\fR(5)) is typically a better choice than +\fILimitNPROC=\fR\&. +.sp +Resource limits not configured explicitly for a unit default to the value configured in the various +\fIDefaultLimitCPU=\fR, +\fIDefaultLimitFSIZE=\fR, \&... options available in +\fBsystemd-system.conf\fR(5), and \(en if not configured there \(en the kernel or per\-user defaults, as defined by the OS (the latter only for user services, see below)\&. +.sp +For system units these resource limits may be chosen freely\&. When these settings are configured in a user service (i\&.e\&. a service run by the per\-user instance of the service manager) they cannot be used to raise the limits above those set for the user manager itself when it was first invoked, as the user\*(Aqs service manager generally lacks the privileges to do so\&. In user context these configuration options are hence only useful to lower the limits passed in or to raise the soft limit to the maximum of the hard limit as configured for the user\&. To raise the user\*(Aqs limits further, the available configuration mechanisms differ between operating systems, but typically require privileges\&. In most cases it is possible to configure higher per\-user resource limits via PAM or by setting limits on the system service encapsulating the user\*(Aqs service manager, i\&.e\&. the user\*(Aqs instance of +user@\&.service\&. After making such changes, make sure to restart the user\*(Aqs service manager\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Resource limit directives, their equivalent ulimit shell commands and the unit used +.TS +allbox tab(:); +lB lB lB lB. +T{ +Directive +T}:T{ +\fBulimit\fR equivalent +T}:T{ +Unit +T}:T{ +Notes +T} +.T& +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l. +T{ +LimitCPU= +T}:T{ +ulimit \-t +T}:T{ +Seconds +T}:T{ +\- +T} +T{ +LimitFSIZE= +T}:T{ +ulimit \-f +T}:T{ +Bytes +T}:T{ +\- +T} +T{ +LimitDATA= +T}:T{ +ulimit \-d +T}:T{ +Bytes +T}:T{ +Don\*(Aqt use\&. This limits the allowed address range, not memory use! Defaults to unlimited and should not be lowered\&. To limit memory use, see \fIMemoryMax=\fR in \fBsystemd.resource-control\fR(5)\&. +T} +T{ +LimitSTACK= +T}:T{ +ulimit \-s +T}:T{ +Bytes +T}:T{ +\- +T} +T{ +LimitCORE= +T}:T{ +ulimit \-c +T}:T{ +Bytes +T}:T{ +\- +T} +T{ +LimitRSS= +T}:T{ +ulimit \-m +T}:T{ +Bytes +T}:T{ +Don\*(Aqt use\&. No effect on Linux\&. +T} +T{ +LimitNOFILE= +T}:T{ +ulimit \-n +T}:T{ +Number of File Descriptors +T}:T{ +Don\*(Aqt use\&. Be careful when raising the soft limit above 1024, since \fBselect\fR(2) cannot function with file descriptors above 1023 on Linux\&. Nowadays, the hard limit defaults to 524288, a very high value compared to historical defaults\&. Typically applications should increase their soft limit to the hard limit on their own, if they are OK with working with file descriptors above 1023, i\&.e\&. do not use \fBselect\fR(2)\&. Note that file descriptors are nowadays accounted like any other form of memory, thus there should not be any need to lower the hard limit\&. Use \fIMemoryMax=\fR to control overall service memory use, including file descriptor memory\&. +T} +T{ +LimitAS= +T}:T{ +ulimit \-v +T}:T{ +Bytes +T}:T{ +Don\*(Aqt use\&. This limits the allowed address range, not memory use! Defaults to unlimited and should not be lowered\&. To limit memory use, see \fIMemoryMax=\fR in \fBsystemd.resource-control\fR(5)\&. +T} +T{ +LimitNPROC= +T}:T{ +ulimit \-u +T}:T{ +Number of Processes +T}:T{ +This limit is enforced based on the number of processes belonging to the user\&. Typically it\*(Aqs better to track processes per service, i\&.e\&. use \fITasksMax=\fR, see \fBsystemd.resource-control\fR(5)\&. +T} +T{ +LimitMEMLOCK= +T}:T{ +ulimit \-l +T}:T{ +Bytes +T}:T{ +\- +T} +T{ +LimitLOCKS= +T}:T{ +ulimit \-x +T}:T{ +Number of Locks +T}:T{ +\- +T} +T{ +LimitSIGPENDING= +T}:T{ +ulimit \-i +T}:T{ +Number of Queued Signals +T}:T{ +\- +T} +T{ +LimitMSGQUEUE= +T}:T{ +ulimit \-q +T}:T{ +Bytes +T}:T{ +\- +T} +T{ +LimitNICE= +T}:T{ +ulimit \-e +T}:T{ +Nice Level +T}:T{ +\- +T} +T{ +LimitRTPRIO= +T}:T{ +ulimit \-r +T}:T{ +Realtime Priority +T}:T{ +\- +T} +T{ +LimitRTTIME= +T}:T{ +ulimit \-R +T}:T{ +Microseconds +T}:T{ +\- +T} +.TE +.sp 1 +.RE +.PP +\fIUMask=\fR +.RS 4 +Controls the file mode creation mask\&. Takes an access mode in octal notation\&. See +\fBumask\fR(2) +for details\&. Defaults to 0022 for system units\&. For user units the default value is inherited from the per\-user service manager (whose default is in turn inherited from the system service manager, and thus typically also is 0022 \(em unless overridden by a PAM module)\&. In order to change the per\-user mask for all user services, consider setting the +\fIUMask=\fR +setting of the user\*(Aqs +user@\&.service +system service instance\&. The per\-user umask may also be set via the +\fIumask\fR +field of a user\*(Aqs +\m[blue]\fBJSON User Record\fR\m[]\&\s-2\u[5]\d\s+2 +(for users managed by +\fBsystemd-homed.service\fR(8) +this field may be controlled via +\fBhomectl \-\-umask=\fR)\&. It may also be set via a PAM module, such as +\fBpam_umask\fR(8)\&. +.RE +.PP +\fICoredumpFilter=\fR +.RS 4 +Controls which types of memory mappings will be saved if the process dumps core (using the +/proc/\fIpid\fR/coredump_filter +file)\&. Takes a whitespace\-separated combination of mapping type names or numbers (with the default base 16)\&. Mapping type names are +\fBprivate\-anonymous\fR, +\fBshared\-anonymous\fR, +\fBprivate\-file\-backed\fR, +\fBshared\-file\-backed\fR, +\fBelf\-headers\fR, +\fBprivate\-huge\fR, +\fBshared\-huge\fR, +\fBprivate\-dax\fR, +\fBshared\-dax\fR, and the special values +\fBall\fR +(all types) and +\fBdefault\fR +(the kernel default of +"\fBprivate\-anonymous\fR \fBshared\-anonymous\fR \fBelf\-headers\fR \fBprivate\-huge\fR")\&. See +\fBcore\fR(5) +for the meaning of the mapping types\&. When specified multiple times, all specified masks are ORed\&. When not set, or if the empty value is assigned, the inherited value is not changed\&. +.PP +\fBExample\ \&2.\ \&Add DAX pages to the dump filter\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +CoredumpFilter=default private\-dax shared\-dax +.fi +.if n \{\ +.RE +.\} + +Added in version 246\&. +.RE +.PP +\fIKeyringMode=\fR +.RS 4 +Controls how the kernel session keyring is set up for the service (see +\fBsession-keyring\fR(7) +for details on the session keyring)\&. Takes one of +\fBinherit\fR, +\fBprivate\fR, +\fBshared\fR\&. If set to +\fBinherit\fR +no special keyring setup is done, and the kernel\*(Aqs default behaviour is applied\&. If +\fBprivate\fR +is used a new session keyring is allocated when a service process is invoked, and it is not linked up with any user keyring\&. This is the recommended setting for system services, as this ensures that multiple services running under the same system user ID (in particular the root user) do not share their key material among each other\&. If +\fBshared\fR +is used a new session keyring is allocated as for +\fBprivate\fR, but the user keyring of the user configured with +\fIUser=\fR +is linked into it, so that keys assigned to the user may be requested by the unit\*(Aqs processes\&. In this mode multiple units running processes under the same user ID may share key material\&. Unless +\fBinherit\fR +is selected the unique invocation ID for the unit (see below) is added as a protected key by the name +"invocation_id" +to the newly created session keyring\&. Defaults to +\fBprivate\fR +for services of the system service manager and to +\fBinherit\fR +for non\-service units and for services of the user service manager\&. +.sp +Added in version 235\&. +.RE +.PP +\fIOOMScoreAdjust=\fR +.RS 4 +Sets the adjustment value for the Linux kernel\*(Aqs Out\-Of\-Memory (OOM) killer score for executed processes\&. Takes an integer between \-1000 (to disable OOM killing of processes of this unit) and 1000 (to make killing of processes of this unit under memory pressure very likely)\&. See +\m[blue]\fBThe /proc Filesystem\fR\m[]\&\s-2\u[6]\d\s+2 +for details\&. If not specified defaults to the OOM score adjustment level of the service manager itself, which is normally at 0\&. +.sp +Use the +\fIOOMPolicy=\fR +setting of service units to configure how the service manager shall react to the kernel OOM killer or +\fBsystemd\-oomd\fR +terminating a process of the service\&. See +\fBsystemd.service\fR(5) +for details\&. +.RE +.PP +\fITimerSlackNSec=\fR +.RS 4 +Sets the timer slack in nanoseconds for the executed processes\&. The timer slack controls the accuracy of wake\-ups triggered by timers\&. See +\fBprctl\fR(2) +for more information\&. Note that in contrast to most other time span definitions this parameter takes an integer value in nano\-seconds if no unit is specified\&. The usual time units are understood too\&. +.RE +.PP +\fIPersonality=\fR +.RS 4 +Controls which kernel architecture +\fBuname\fR(2) +shall report, when invoked by unit processes\&. Takes one of the architecture identifiers +\fBarm64\fR, +\fBarm64\-be\fR, +\fBarm\fR, +\fBarm\-be\fR, +\fBx86\fR, +\fBx86\-64\fR, +\fBppc\fR, +\fBppc\-le\fR, +\fBppc64\fR, +\fBppc64\-le\fR, +\fBs390\fR +or +\fBs390x\fR\&. Which personality architectures are supported depends on the kernel\*(Aqs native architecture\&. Usually the 64\-bit versions of the various system architectures support their immediate 32\-bit personality architecture counterpart, but no others\&. For example, +\fBx86\-64\fR +systems support the +\fBx86\-64\fR +and +\fBx86\fR +personalities but no others\&. The personality feature is useful when running 32\-bit services on a 64\-bit host system\&. If not specified, the personality is left unmodified and thus reflects the personality of the host system\*(Aqs kernel\&. This option is not useful on architectures for which only one native word width was ever available, such as +\fBm68k\fR +(32\-bit only) or +\fBalpha\fR +(64\-bit only)\&. +.sp +Added in version 209\&. +.RE +.PP +\fIIgnoreSIGPIPE=\fR +.RS 4 +Takes a boolean argument\&. If true, causes +\fBSIGPIPE\fR +to be ignored in the executed process\&. Defaults to true because +\fBSIGPIPE\fR +generally is useful only in shell pipelines\&. +.RE +.SH "SCHEDULING" +.PP +\fINice=\fR +.RS 4 +Sets the default nice level (scheduling priority) for executed processes\&. Takes an integer between \-20 (highest priority) and 19 (lowest priority)\&. In case of resource contention, smaller values mean more resources will be made available to the unit\*(Aqs processes, larger values mean less resources will be made available\&. See +\fBsetpriority\fR(2) +for details\&. +.RE +.PP +\fICPUSchedulingPolicy=\fR +.RS 4 +Sets the CPU scheduling policy for executed processes\&. Takes one of +\fBother\fR, +\fBbatch\fR, +\fBidle\fR, +\fBfifo\fR +or +\fBrr\fR\&. See +\fBsched_setscheduler\fR(2) +for details\&. +.RE +.PP +\fICPUSchedulingPriority=\fR +.RS 4 +Sets the CPU scheduling priority for executed processes\&. The available priority range depends on the selected CPU scheduling policy (see above)\&. For real\-time scheduling policies an integer between 1 (lowest priority) and 99 (highest priority) can be used\&. In case of CPU resource contention, smaller values mean less CPU time is made available to the service, larger values mean more\&. See +\fBsched_setscheduler\fR(2) +for details\&. +.RE +.PP +\fICPUSchedulingResetOnFork=\fR +.RS 4 +Takes a boolean argument\&. If true, elevated CPU scheduling priorities and policies will be reset when the executed processes call +\fBfork\fR(2), and can hence not leak into child processes\&. See +\fBsched_setscheduler\fR(2) +for details\&. Defaults to false\&. +.RE +.PP +\fICPUAffinity=\fR +.RS 4 +Controls the CPU affinity of the executed processes\&. Takes a list of CPU indices or ranges separated by either whitespace or commas\&. Alternatively, takes a special "numa" value in which case systemd automatically derives allowed CPU range based on the value of +\fINUMAMask=\fR +option\&. CPU ranges are specified by the lower and upper CPU indices separated by a dash\&. This option may be specified more than once, in which case the specified CPU affinity masks are merged\&. If the empty string is assigned, the mask is reset, all assignments prior to this will have no effect\&. See +\fBsched_setaffinity\fR(2) +for details\&. +.RE +.PP +\fINUMAPolicy=\fR +.RS 4 +Controls the NUMA memory policy of the executed processes\&. Takes a policy type, one of: +\fBdefault\fR, +\fBpreferred\fR, +\fBbind\fR, +\fBinterleave\fR +and +\fBlocal\fR\&. A list of NUMA nodes that should be associated with the policy must be specified in +\fINUMAMask=\fR\&. For more details on each policy please see, +\fBset_mempolicy\fR(2)\&. For overall overview of NUMA support in Linux see, +\fBnuma\fR(7)\&. +.sp +Added in version 243\&. +.RE +.PP +\fINUMAMask=\fR +.RS 4 +Controls the NUMA node list which will be applied alongside with selected NUMA policy\&. Takes a list of NUMA nodes and has the same syntax as a list of CPUs for +\fICPUAffinity=\fR +option or special "all" value which will include all available NUMA nodes in the mask\&. Note that the list of NUMA nodes is not required for +\fBdefault\fR +and +\fBlocal\fR +policies and for +\fBpreferred\fR +policy we expect a single NUMA node\&. +.sp +Added in version 243\&. +.RE +.PP +\fIIOSchedulingClass=\fR +.RS 4 +Sets the I/O scheduling class for executed processes\&. Takes one of the strings +\fBrealtime\fR, +\fBbest\-effort\fR +or +\fBidle\fR\&. The kernel\*(Aqs default scheduling class is +\fBbest\-effort\fR +at a priority of 4\&. If the empty string is assigned to this option, all prior assignments to both +\fIIOSchedulingClass=\fR +and +\fIIOSchedulingPriority=\fR +have no effect\&. See +\fBioprio_set\fR(2) +for details\&. +.RE +.PP +\fIIOSchedulingPriority=\fR +.RS 4 +Sets the I/O scheduling priority for executed processes\&. Takes an integer between 0 (highest priority) and 7 (lowest priority)\&. In case of I/O contention, smaller values mean more I/O bandwidth is made available to the unit\*(Aqs processes, larger values mean less bandwidth\&. The available priorities depend on the selected I/O scheduling class (see above)\&. If the empty string is assigned to this option, all prior assignments to both +\fIIOSchedulingClass=\fR +and +\fIIOSchedulingPriority=\fR +have no effect\&. For the kernel\*(Aqs default scheduling class (\fBbest\-effort\fR) this defaults to 4\&. See +\fBioprio_set\fR(2) +for details\&. +.RE +.SH "SANDBOXING" +.PP +The following sandboxing options are an effective way to limit the exposure of the system towards the unit\*(Aqs processes\&. It is recommended to turn on as many of these options for each unit as is possible without negatively affecting the process\*(Aq ability to operate\&. Note that many of these sandboxing features are gracefully turned off on systems where the underlying security mechanism is not available\&. For example, +\fIProtectSystem=\fR +has no effect if the kernel is built without file system namespacing or if the service manager runs in a container manager that makes file system namespacing unavailable to its payload\&. Similarly, +\fIRestrictRealtime=\fR +has no effect on systems that lack support for SECCOMP system call filtering, or in containers where support for this is turned off\&. +.PP +Also note that some sandboxing functionality is generally not available in user services (i\&.e\&. services run by the per\-user service manager)\&. Specifically, the various settings requiring file system namespacing support (such as +\fIProtectSystem=\fR) are not available, as the underlying kernel functionality is only accessible to privileged processes\&. However, most namespacing settings, that will not work on their own in user services, will work when used in conjunction with +\fIPrivateUsers=\fR\fBtrue\fR\&. +.PP +\fIProtectSystem=\fR +.RS 4 +Takes a boolean argument or the special values +"full" +or +"strict"\&. If true, mounts the +/usr/ +and the boot loader directories (/boot +and +/efi) read\-only for processes invoked by this unit\&. If set to +"full", the +/etc/ +directory is mounted read\-only, too\&. If set to +"strict" +the entire file system hierarchy is mounted read\-only, except for the API file system subtrees +/dev/, +/proc/ +and +/sys/ +(protect these directories using +\fIPrivateDevices=\fR, +\fIProtectKernelTunables=\fR, +\fIProtectControlGroups=\fR)\&. This setting ensures that any modification of the vendor\-supplied operating system (and optionally its configuration, and local mounts) is prohibited for the service\&. It is recommended to enable this setting for all long\-running services, unless they are involved with system updates or need to modify the operating system in other ways\&. If this option is used, +\fIReadWritePaths=\fR +may be used to exclude specific directories from being made read\-only\&. This setting is implied if +\fIDynamicUser=\fR +is set\&. This setting cannot ensure protection in all cases\&. In general it has the same limitations as +\fIReadOnlyPaths=\fR, see below\&. Defaults to off\&. +.sp +Added in version 214\&. +.RE +.PP +\fIProtectHome=\fR +.RS 4 +Takes a boolean argument or the special values +"read\-only" +or +"tmpfs"\&. If true, the directories +/home/, +/root, and +/run/user +are made inaccessible and empty for processes invoked by this unit\&. If set to +"read\-only", the three directories are made read\-only instead\&. If set to +"tmpfs", temporary file systems are mounted on the three directories in read\-only mode\&. The value +"tmpfs" +is useful to hide home directories not relevant to the processes invoked by the unit, while still allowing necessary directories to be made visible when listed in +\fIBindPaths=\fR +or +\fIBindReadOnlyPaths=\fR\&. +.sp +Setting this to +"yes" +is mostly equivalent to setting the three directories in +\fIInaccessiblePaths=\fR\&. Similarly, +"read\-only" +is mostly equivalent to +\fIReadOnlyPaths=\fR, and +"tmpfs" +is mostly equivalent to +\fITemporaryFileSystem=\fR +with +":ro"\&. +.sp +It is recommended to enable this setting for all long\-running services (in particular network\-facing ones), to ensure they cannot get access to private user data, unless the services actually require access to the user\*(Aqs private data\&. This setting is implied if +\fIDynamicUser=\fR +is set\&. This setting cannot ensure protection in all cases\&. In general it has the same limitations as +\fIReadOnlyPaths=\fR, see below\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 214\&. +.RE +.PP +\fIRuntimeDirectory=\fR, \fIStateDirectory=\fR, \fICacheDirectory=\fR, \fILogsDirectory=\fR, \fIConfigurationDirectory=\fR +.RS 4 +These options take a whitespace\-separated list of directory names\&. The specified directory names must be relative, and may not include +"\&.\&."\&. If set, when the unit is started, one or more directories by the specified names will be created (including their parents) below the locations defined in the following table\&. Also, the corresponding environment variable will be defined with the full paths of the directories\&. If multiple directories are set, then in the environment variable the paths are concatenated with colon (":")\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Automatic directory creation and environment variables +.TS +allbox tab(:); +lB lB lB lB. +T{ +Directory +T}:T{ +Below path for system units +T}:T{ +Below path for user units +T}:T{ +Environment variable set +T} +.T& +l l l l +l l l l +l l l l +l l l l +l l l l. +T{ +\fIRuntimeDirectory=\fR +T}:T{ +/run/ +T}:T{ +\fI$XDG_RUNTIME_DIR\fR +T}:T{ +\fI$RUNTIME_DIRECTORY\fR +T} +T{ +\fIStateDirectory=\fR +T}:T{ +/var/lib/ +T}:T{ +\fI$XDG_STATE_HOME\fR +T}:T{ +\fI$STATE_DIRECTORY\fR +T} +T{ +\fICacheDirectory=\fR +T}:T{ +/var/cache/ +T}:T{ +\fI$XDG_CACHE_HOME\fR +T}:T{ +\fI$CACHE_DIRECTORY\fR +T} +T{ +\fILogsDirectory=\fR +T}:T{ +/var/log/ +T}:T{ +\fI$XDG_STATE_HOME\fR/log/ +T}:T{ +\fI$LOGS_DIRECTORY\fR +T} +T{ +\fIConfigurationDirectory=\fR +T}:T{ +/etc/ +T}:T{ +\fI$XDG_CONFIG_HOME\fR +T}:T{ +\fI$CONFIGURATION_DIRECTORY\fR +T} +.TE +.sp 1 +In case of +\fIRuntimeDirectory=\fR +the innermost subdirectories are removed when the unit is stopped\&. It is possible to preserve the specified directories in this case if +\fIRuntimeDirectoryPreserve=\fR +is configured to +\fBrestart\fR +or +\fByes\fR +(see below)\&. The directories specified with +\fIStateDirectory=\fR, +\fICacheDirectory=\fR, +\fILogsDirectory=\fR, +\fIConfigurationDirectory=\fR +are not removed when the unit is stopped\&. +.sp +Except in case of +\fIConfigurationDirectory=\fR, the innermost specified directories will be owned by the user and group specified in +\fIUser=\fR +and +\fIGroup=\fR\&. If the specified directories already exist and their owning user or group do not match the configured ones, all files and directories below the specified directories as well as the directories themselves will have their file ownership recursively changed to match what is configured\&. As an optimization, if the specified directories are already owned by the right user and group, files and directories below of them are left as\-is, even if they do not match what is requested\&. The innermost specified directories will have their access mode adjusted to the what is specified in +\fIRuntimeDirectoryMode=\fR, +\fIStateDirectoryMode=\fR, +\fICacheDirectoryMode=\fR, +\fILogsDirectoryMode=\fR +and +\fIConfigurationDirectoryMode=\fR\&. +.sp +These options imply +\fIBindPaths=\fR +for the specified paths\&. When combined with +\fIRootDirectory=\fR +or +\fIRootImage=\fR +these paths always reside on the host and are mounted from there into the unit\*(Aqs file system namespace\&. +.sp +If +\fIDynamicUser=\fR +is used, the logic for +\fICacheDirectory=\fR, +\fILogsDirectory=\fR +and +\fIStateDirectory=\fR +is slightly altered: the directories are created below +/var/cache/private, +/var/log/private +and +/var/lib/private, respectively, which are host directories made inaccessible to unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID recycling\&. Symbolic links are created to hide this difference in behaviour\&. Both from perspective of the host and from inside the unit, the relevant directories hence always appear directly below +/var/cache, +/var/log +and +/var/lib\&. +.sp +Use +\fIRuntimeDirectory=\fR +to manage one or more runtime directories for the unit and bind their lifetime to the daemon runtime\&. This is particularly useful for unprivileged daemons that cannot create runtime directories in +/run/ +due to lack of privileges, and to make sure the runtime directory is cleaned up automatically after use\&. For runtime directories that require more complex or different configuration or lifetime guarantees, please consider using +\fBtmpfiles.d\fR(5)\&. +.sp +\fIRuntimeDirectory=\fR, +\fIStateDirectory=\fR, +\fICacheDirectory=\fR +and +\fILogsDirectory=\fR +optionally support a second parameter, separated by +":"\&. The second parameter will be interpreted as a destination path that will be created as a symlink to the directory\&. The symlinks will be created after any +\fIBindPaths=\fR +or +\fITemporaryFileSystem=\fR +options have been set up, to make ephemeral symlinking possible\&. The same source can have multiple symlinks, by using the same first parameter, but a different second parameter\&. +.sp +The directories defined by these options are always created under the standard paths used by systemd (/var/, +/run/, +/etc/, \&...)\&. If the service needs directories in a different location, a different mechanism has to be used to create them\&. +.sp +\fBtmpfiles.d\fR(5) +provides functionality that overlaps with these options\&. Using these options is recommended, because the lifetime of the directories is tied directly to the lifetime of the unit, and it is not necessary to ensure that the +tmpfiles\&.d +configuration is executed before the unit is started\&. +.sp +To remove any of the directories created by these settings, use the +\fBsystemctl clean \&...\fR +command on the relevant units, see +\fBsystemctl\fR(1) +for details\&. +.sp +Example: if a system service unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RuntimeDirectory=foo/bar baz +.fi +.if n \{\ +.RE +.\} +.sp +the service manager creates +/run/foo +(if it does not exist), +/run/foo/bar, and +/run/baz\&. The directories +/run/foo/bar +and +/run/baz +except +/run/foo +are owned by the user and group specified in +\fIUser=\fR +and +\fIGroup=\fR, and removed when the service is stopped\&. +.sp +Example: if a system service unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RuntimeDirectory=foo/bar +StateDirectory=aaa/bbb ccc +.fi +.if n \{\ +.RE +.\} +.sp +then the environment variable +"RUNTIME_DIRECTORY" +is set with +"/run/foo/bar", and +"STATE_DIRECTORY" +is set with +"/var/lib/aaa/bbb:/var/lib/ccc"\&. +.sp +Example: if a system service unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RuntimeDirectory=foo:bar foo:baz +.fi +.if n \{\ +.RE +.\} +.sp +the service manager creates +/run/foo +(if it does not exist), and +/run/bar +plus +/run/baz +as symlinks to +/run/foo\&. +.sp +Added in version 211\&. +.RE +.PP +\fIRuntimeDirectoryMode=\fR, \fIStateDirectoryMode=\fR, \fICacheDirectoryMode=\fR, \fILogsDirectoryMode=\fR, \fIConfigurationDirectoryMode=\fR +.RS 4 +Specifies the access mode of the directories specified in +\fIRuntimeDirectory=\fR, +\fIStateDirectory=\fR, +\fICacheDirectory=\fR, +\fILogsDirectory=\fR, or +\fIConfigurationDirectory=\fR, respectively, as an octal number\&. Defaults to +\fB0755\fR\&. See "Permissions" in +\fBpath_resolution\fR(7) +for a discussion of the meaning of permission bits\&. +.sp +Added in version 234\&. +.RE +.PP +\fIRuntimeDirectoryPreserve=\fR +.RS 4 +Takes a boolean argument or +\fBrestart\fR\&. If set to +\fBno\fR +(the default), the directories specified in +\fIRuntimeDirectory=\fR +are always removed when the service stops\&. If set to +\fBrestart\fR +the directories are preserved when the service is both automatically and manually restarted\&. Here, the automatic restart means the operation specified in +\fIRestart=\fR, and manual restart means the one triggered by +\fBsystemctl restart foo\&.service\fR\&. If set to +\fByes\fR, then the directories are not removed when the service is stopped\&. Note that since the runtime directory +/run/ +is a mount point of +"tmpfs", then for system services the directories specified in +\fIRuntimeDirectory=\fR +are removed when the system is rebooted\&. +.sp +Added in version 235\&. +.RE +.PP +\fITimeoutCleanSec=\fR +.RS 4 +Configures a timeout on the clean\-up operation requested through +\fBsystemctl clean \&...\fR, see +\fBsystemctl\fR(1) +for details\&. Takes the usual time values and defaults to +\fBinfinity\fR, i\&.e\&. by default no timeout is applied\&. If a timeout is configured the clean operation will be aborted forcibly when the timeout is reached, potentially leaving resources on disk\&. +.sp +Added in version 244\&. +.RE +.PP +\fIReadWritePaths=\fR, \fIReadOnlyPaths=\fR, \fIInaccessiblePaths=\fR, \fIExecPaths=\fR, \fINoExecPaths=\fR +.RS 4 +Sets up a new file system namespace for executed processes\&. These options may be used to limit access a process has to the file system\&. Each setting takes a space\-separated list of paths relative to the host\*(Aqs root directory (i\&.e\&. the system running the service manager)\&. Note that if paths contain symlinks, they are resolved relative to the root directory set with +\fIRootDirectory=\fR/\fIRootImage=\fR\&. +.sp +Paths listed in +\fIReadWritePaths=\fR +are accessible from within the namespace with the same access modes as from outside of it\&. Paths listed in +\fIReadOnlyPaths=\fR +are accessible for reading only, writing will be refused even if the usual file access controls would permit this\&. Nest +\fIReadWritePaths=\fR +inside of +\fIReadOnlyPaths=\fR +in order to provide writable subdirectories within read\-only directories\&. Use +\fIReadWritePaths=\fR +in order to allow\-list specific paths for write access if +\fIProtectSystem=strict\fR +is used\&. Note that +\fIReadWritePaths=\fR +cannot be used to gain write access to a file system whose superblock is mounted read\-only\&. On Linux, for each mount point write access is granted only if the mount point itself +\fIand\fR +the file system superblock backing it are not marked read\-only\&. +\fIReadWritePaths=\fR +only controls the former, not the latter, hence a read\-only file system superblock remains protected\&. +.sp +Paths listed in +\fIInaccessiblePaths=\fR +will be made inaccessible for processes inside the namespace along with everything below them in the file system hierarchy\&. This may be more restrictive than desired, because it is not possible to nest +\fIReadWritePaths=\fR, +\fIReadOnlyPaths=\fR, +\fIBindPaths=\fR, or +\fIBindReadOnlyPaths=\fR +inside it\&. For a more flexible option, see +\fITemporaryFileSystem=\fR\&. +.sp +Content in paths listed in +\fINoExecPaths=\fR +are not executable even if the usual file access controls would permit this\&. Nest +\fIExecPaths=\fR +inside of +\fINoExecPaths=\fR +in order to provide executable content within non\-executable directories\&. +.sp +Non\-directory paths may be specified as well\&. These options may be specified more than once, in which case all paths listed will have limited access from within the namespace\&. If the empty string is assigned to this option, the specific list is reset, and all prior assignments have no effect\&. +.sp +Paths in +\fIReadWritePaths=\fR, +\fIReadOnlyPaths=\fR, +\fIInaccessiblePaths=\fR, +\fIExecPaths=\fR +and +\fINoExecPaths=\fR +may be prefixed with +"\-", in which case they will be ignored when they do not exist\&. If prefixed with +"+" +the paths are taken relative to the root directory of the unit, as configured with +\fIRootDirectory=\fR/\fIRootImage=\fR, instead of relative to the root directory of the host (see above)\&. When combining +"\-" +and +"+" +on the same path make sure to specify +"\-" +first, and +"+" +second\&. +.sp +Note that these settings will disconnect propagation of mounts from the unit\*(Aqs processes to the host\&. This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace\&. For +\fIReadWritePaths=\fR +and +\fIReadOnlyPaths=\fR, propagation in the other direction is not affected, i\&.e\&. mounts created on the host generally appear in the unit processes\*(Aq namespace, and mounts removed on the host also disappear there too\&. In particular, note that mount propagation from host to unit will result in unmodified mounts to be created in the unit\*(Aqs namespace, i\&.e\&. writable mounts appearing on the host will be writable in the unit\*(Aqs namespace too, even when propagated below a path marked with +\fIReadOnlyPaths=\fR! Restricting access with these options hence does not extend to submounts of a directory that are created later on\&. This means the lock\-down offered by that setting is not complete, and does not offer full protection\&. +.sp +Note that the effect of these settings may be undone by privileged processes\&. In order to set up an effective sandboxed environment for a unit it is thus recommended to combine these settings with either +\fICapabilityBoundingSet=~CAP_SYS_ADMIN\fR +or +\fISystemCallFilter=~@mount\fR\&. +.sp +Please be extra careful when applying these options to API file systems (a list of them could be found in +\fIMountAPIVPS=\fR), since they may be required for basic system functionalities\&. Moreover, +/run/ +needs to be writable for setting up mount namespace and propagation\&. +.sp +Simple allow\-list example using these directives: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Service] +ReadOnlyPaths=/ +ReadWritePaths=/var /run +InaccessiblePaths=\-/lost+found +NoExecPaths=/ +ExecPaths=/usr/sbin/my_daemon /usr/lib /usr/lib64 +.fi +.if n \{\ +.RE +.\} +.sp +These options are only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 231\&. +.RE +.PP +\fITemporaryFileSystem=\fR +.RS 4 +Takes a space\-separated list of mount points for temporary file systems (tmpfs)\&. If set, a new file system namespace is set up for executed processes, and a temporary file system is mounted on each mount point\&. This option may be specified more than once, in which case temporary file systems are mounted on all listed mount points\&. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect\&. Each mount point may optionally be suffixed with a colon (":") and mount options such as +"size=10%" +or +"ro"\&. By default, each temporary file system is mounted with +"nodev,strictatime,mode=0755"\&. These can be disabled by explicitly specifying the corresponding mount options, e\&.g\&., +"dev" +or +"nostrictatime"\&. +.sp +This is useful to hide files or directories not relevant to the processes invoked by the unit, while necessary files or directories can be still accessed by combining with +\fIBindPaths=\fR +or +\fIBindReadOnlyPaths=\fR: +.sp +Example: if a unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +TemporaryFileSystem=/var:ro +BindReadOnlyPaths=/var/lib/systemd +.fi +.if n \{\ +.RE +.\} +.sp +then the invoked processes by the unit cannot see any files or directories under +/var/ +except for +/var/lib/systemd +or its contents\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 238\&. +.RE +.PP +\fIPrivateTmp=\fR +.RS 4 +Takes a boolean argument\&. If true, sets up a new file system namespace for the executed processes and mounts private +/tmp/ +and +/var/tmp/ +directories inside it that are not shared by processes outside of the namespace\&. This is useful to secure access to temporary files of the process, but makes sharing between processes via +/tmp/ +or +/var/tmp/ +impossible\&. If true, all temporary files created by a service in these directories will be removed after the service is stopped\&. Defaults to false\&. It is possible to run two or more units within the same private +/tmp/ +and +/var/tmp/ +namespace by using the +\fIJoinsNamespaceOf=\fR +directive, see +\fBsystemd.unit\fR(5) +for details\&. This setting is implied if +\fIDynamicUser=\fR +is set\&. For this setting, the same restrictions regarding mount propagation and privileges apply as for +\fIReadOnlyPaths=\fR +and related calls, see above\&. Enabling this setting has the side effect of adding +\fIRequires=\fR +and +\fIAfter=\fR +dependencies on all mount units necessary to access +/tmp/ +and +/var/tmp/\&. Moreover an implicitly +\fIAfter=\fR +ordering on +\fBsystemd-tmpfiles-setup.service\fR(8) +is added\&. +.sp +Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.RE +.PP +\fIPrivateDevices=\fR +.RS 4 +Takes a boolean argument\&. If true, sets up a new +/dev/ +mount for the executed processes and only adds API pseudo devices such as +/dev/null, +/dev/zero +or +/dev/random +(as well as the pseudo TTY subsystem) to it, but no physical devices such as +/dev/sda, system memory +/dev/mem, system ports +/dev/port +and others\&. This is useful to turn off physical device access by the executed process\&. Defaults to false\&. +.sp +Enabling this option will install a system call filter to block low\-level I/O system calls that are grouped in the +\fI@raw\-io\fR +set, remove +\fBCAP_MKNOD\fR +and +\fBCAP_SYS_RAWIO\fR +from the capability bounding set for the unit, and set +\fIDevicePolicy=closed\fR +(see +\fBsystemd.resource-control\fR(5) +for details)\&. Note that using this setting will disconnect propagation of mounts from the service to the host (propagation in the opposite direction continues to work)\&. This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace\&. The new +/dev/ +will be mounted read\-only and \*(Aqnoexec\*(Aq\&. The latter may break old programs which try to set up executable memory by using +\fBmmap\fR(2) +of +/dev/zero +instead of using +\fBMAP_ANON\fR\&. For this setting the same restrictions regarding mount propagation and privileges apply as for +\fIReadOnlyPaths=\fR +and related calls, see above\&. +.sp +Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +When access to some but not all devices must be possible, the +\fIDeviceAllow=\fR +setting might be used instead\&. See +\fBsystemd.resource-control\fR(5)\&. +.sp +Added in version 209\&. +.RE +.PP +\fIPrivateNetwork=\fR +.RS 4 +Takes a boolean argument\&. If true, sets up a new network namespace for the executed processes and configures only the loopback network device +"lo" +inside it\&. No other network devices will be available to the executed process\&. This is useful to turn off network access by the executed process\&. Defaults to false\&. It is possible to run two or more units within the same private network namespace by using the +\fIJoinsNamespaceOf=\fR +directive, see +\fBsystemd.unit\fR(5) +for details\&. Note that this option will disconnect all socket families from the host, including +\fBAF_NETLINK\fR +and +\fBAF_UNIX\fR\&. Effectively, for +\fBAF_NETLINK\fR +this means that device configuration events received from +\fBsystemd-udevd.service\fR(8) +are not delivered to the unit\*(Aqs processes\&. And for +\fBAF_UNIX\fR +this has the effect that +\fBAF_UNIX\fR +sockets in the abstract socket namespace of the host will become unavailable to the unit\*(Aqs processes (however, those located in the file system will continue to be accessible)\&. +.sp +Note that the implementation of this setting might be impossible (for example if network namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&. +.sp +When this option is enabled, +\fIPrivateMounts=\fR +is implied unless it is explicitly disabled, and +/sys +will be remounted to associate it with the new network namespace\&. +.sp +When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within a private network namespace\&. This may be combined with +\fIJoinsNamespaceOf=\fR +to listen on sockets inside of network namespaces of other services\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.RE +.PP +\fINetworkNamespacePath=\fR +.RS 4 +Takes an absolute file system path referring to a Linux network namespace pseudo\-file (i\&.e\&. a file like +/proc/$PID/ns/net +or a bind mount or symlink to one)\&. When set the invoked processes are added to the network namespace referenced by that path\&. The path has to point to a valid namespace file at the moment the processes are forked off\&. If this option is used +\fIPrivateNetwork=\fR +has no effect\&. If this option is used together with +\fIJoinsNamespaceOf=\fR +then it only has an effect if this unit is started before any of the listed units that have +\fIPrivateNetwork=\fR +or +\fINetworkNamespacePath=\fR +configured, as otherwise the network namespace of those units is reused\&. +.sp +When this option is enabled, +\fIPrivateMounts=\fR +is implied unless it is explicitly disabled, and +/sys +will be remounted to associate it with the new network namespace\&. +.sp +When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within the specified network namespace\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 242\&. +.RE +.PP +\fIPrivateIPC=\fR +.RS 4 +Takes a boolean argument\&. If true, sets up a new IPC namespace for the executed processes\&. Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue file system\&. This is useful to avoid name clash of IPC identifiers\&. Defaults to false\&. It is possible to run two or more units within the same private IPC namespace by using the +\fIJoinsNamespaceOf=\fR +directive, see +\fBsystemd.unit\fR(5) +for details\&. +.sp +Note that IPC namespacing does not have an effect on +\fBAF_UNIX\fR +sockets, which are the most common form of IPC used on Linux\&. Instead, +\fBAF_UNIX\fR +sockets in the file system are subject to mount namespacing, and those in the abstract namespace are subject to network namespacing\&. IPC namespacing only has an effect on SysV IPC (which is mostly legacy) as well as POSIX message queues (for which +\fBAF_UNIX\fR/\fBSOCK_SEQPACKET\fR +sockets are typically a better replacement)\&. IPC namespacing also has no effect on POSIX shared memory (which is subject to mount namespacing) either\&. See +\fBipc_namespaces\fR(7) +for the details\&. +.sp +Note that the implementation of this setting might be impossible (for example if IPC namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 248\&. +.RE +.PP +\fIIPCNamespacePath=\fR +.RS 4 +Takes an absolute file system path referring to a Linux IPC namespace pseudo\-file (i\&.e\&. a file like +/proc/$PID/ns/ipc +or a bind mount or symlink to one)\&. When set the invoked processes are added to the network namespace referenced by that path\&. The path has to point to a valid namespace file at the moment the processes are forked off\&. If this option is used +\fIPrivateIPC=\fR +has no effect\&. If this option is used together with +\fIJoinsNamespaceOf=\fR +then it only has an effect if this unit is started before any of the listed units that have +\fIPrivateIPC=\fR +or +\fIIPCNamespacePath=\fR +configured, as otherwise the network namespace of those units is reused\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 248\&. +.RE +.PP +\fIMemoryKSM=\fR +.RS 4 +Takes a boolean argument\&. When set, it enables KSM (kernel samepage merging) for the processes\&. KSM is a memory\-saving de\-duplication feature\&. Anonymous memory pages with identical content can be replaced by a single write\-protected page\&. This feature should only be enabled for jobs that share the same security domain\&. For details, see +\m[blue]\fBKernel Samepage Merging\fR\m[]\&\s-2\u[7]\d\s+2 +in the kernel documentation\&. +.sp +Note that this functionality might not be available, for example if KSM is disabled in the kernel, or the kernel doesn\*(Aqt support controlling KSM at the process level through +\fBprctl\fR(2)\&. +.sp +Added in version 254\&. +.RE +.PP +\fIPrivateUsers=\fR +.RS 4 +Takes a boolean argument\&. If true, sets up a new user namespace for the executed processes and configures a minimal user and group mapping, that maps the +"root" +user and group as well as the unit\*(Aqs own user and group to themselves and everything else to the +"nobody" +user and group\&. This is useful to securely detach the user and group databases used by the unit from the rest of the system, and thus to create an effective sandbox environment\&. All files, directories, processes, IPC objects and other resources owned by users/groups not equaling +"root" +or the unit\*(Aqs own will stay visible from within the unit but appear owned by the +"nobody" +user and group\&. If this mode is enabled, all unit processes are run without privileges in the host user namespace (regardless if the unit\*(Aqs own user/group is +"root" +or not)\&. Specifically this means that the process will have zero process capabilities on the host\*(Aqs user namespace, but full capabilities within the service\*(Aqs user namespace\&. Settings such as +\fICapabilityBoundingSet=\fR +will affect only the latter, and there\*(Aqs no way to acquire additional capabilities in the host\*(Aqs user namespace\&. Defaults to off\&. +.sp +When this setting is set up by a per\-user instance of the service manager, the mapping of the +"root" +user and group to itself is omitted (unless the user manager is root)\&. Additionally, in the per\-user instance manager case, the user namespace will be set up before most other namespaces\&. This means that combining +\fIPrivateUsers=\fR\fBtrue\fR +with other namespaces will enable use of features not normally supported by the per\-user instances of the service manager\&. +.sp +This setting is particularly useful in conjunction with +\fIRootDirectory=\fR/\fIRootImage=\fR, as the need to synchronize the user and group databases in the root directory and on the host is reduced, as the only users and groups who need to be matched are +"root", +"nobody" +and the unit\*(Aqs own user and group\&. +.sp +Note that the implementation of this setting might be impossible (for example if user namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&. +.sp +Added in version 232\&. +.RE +.PP +\fIProtectHostname=\fR +.RS 4 +Takes a boolean argument\&. When set, sets up a new UTS namespace for the executed processes\&. In addition, changing hostname or domainname is prevented\&. Defaults to off\&. +.sp +Note that the implementation of this setting might be impossible (for example if UTS namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security\&. +.sp +Note that when this option is enabled for a service hostname changes no longer propagate from the system into the service, it is hence not suitable for services that need to take notice of system hostname changes dynamically\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 242\&. +.RE +.PP +\fIProtectClock=\fR +.RS 4 +Takes a boolean argument\&. If set, writes to the hardware clock or system clock will be denied\&. Defaults to off\&. Enabling this option removes +\fBCAP_SYS_TIME\fR +and +\fBCAP_WAKE_ALARM\fR +from the capability bounding set for this unit, installs a system call filter to block calls that can set the clock, and +\fIDeviceAllow=char\-rtc r\fR +is implied\&. Note that the system calls are blocked altogether, the filter does not take into account that some of the calls can be used to read the clock state with some parameter combinations\&. Effectively, +/dev/rtc0, +/dev/rtc1, etc\&. are made read\-only to the service\&. See +\fBsystemd.resource-control\fR(5) +for the details about +\fIDeviceAllow=\fR\&. +.sp +It is recommended to turn this on for most services that do not need modify the clock or check its state\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 245\&. +.RE +.PP +\fIProtectKernelTunables=\fR +.RS 4 +Takes a boolean argument\&. If true, kernel variables accessible through +/proc/sys/, +/sys/, +/proc/sysrq\-trigger, +/proc/latency_stats, +/proc/acpi, +/proc/timer_stats, +/proc/fs +and +/proc/irq +will be made read\-only to all processes of the unit\&. Usually, tunable kernel variables should be initialized only at boot\-time, for example with the +\fBsysctl.d\fR(5) +mechanism\&. Few services need to write to these at runtime; it is hence recommended to turn this on for most services\&. For this setting the same restrictions regarding mount propagation and privileges apply as for +\fIReadOnlyPaths=\fR +and related calls, see above\&. Defaults to off\&. Note that this option does not prevent indirect changes to kernel tunables effected by IPC calls to other processes\&. However, +\fIInaccessiblePaths=\fR +may be used to make relevant IPC file system objects inaccessible\&. If +\fIProtectKernelTunables=\fR +is set, +\fIMountAPIVFS=yes\fR +is implied\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 232\&. +.RE +.PP +\fIProtectKernelModules=\fR +.RS 4 +Takes a boolean argument\&. If true, explicit module loading will be denied\&. This allows module load and unload operations to be turned off on modular kernels\&. It is recommended to turn this on for most services that do not need special file systems or extra kernel modules to work\&. Defaults to off\&. Enabling this option removes +\fBCAP_SYS_MODULE\fR +from the capability bounding set for the unit, and installs a system call filter to block module system calls, also +/usr/lib/modules +is made inaccessible\&. For this setting the same restrictions regarding mount propagation and privileges apply as for +\fIReadOnlyPaths=\fR +and related calls, see above\&. Note that limited automatic module loading due to user configuration or kernel mapping tables might still happen as side effect of requested user operations, both privileged and unprivileged\&. To disable module auto\-load feature please see +\fBsysctl.d\fR(5) +\fBkernel\&.modules_disabled\fR +mechanism and +/proc/sys/kernel/modules_disabled +documentation\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 232\&. +.RE +.PP +\fIProtectKernelLogs=\fR +.RS 4 +Takes a boolean argument\&. If true, access to the kernel log ring buffer will be denied\&. It is recommended to turn this on for most services that do not need to read from or write to the kernel log ring buffer\&. Enabling this option removes +\fBCAP_SYSLOG\fR +from the capability bounding set for this unit, and installs a system call filter to block the +\fBsyslog\fR(2) +system call (not to be confused with the libc API +\fBsyslog\fR(3) +for userspace logging)\&. The kernel exposes its log buffer to userspace via +/dev/kmsg +and +/proc/kmsg\&. If enabled, these are made inaccessible to all the processes in the unit\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 244\&. +.RE +.PP +\fIProtectControlGroups=\fR +.RS 4 +Takes a boolean argument\&. If true, the Linux Control Groups (\fBcgroups\fR(7)) hierarchies accessible through +/sys/fs/cgroup/ +will be made read\-only to all processes of the unit\&. Except for container managers no services should require write access to the control groups hierarchies; it is hence recommended to turn this on for most services\&. For this setting the same restrictions regarding mount propagation and privileges apply as for +\fIReadOnlyPaths=\fR +and related calls, see above\&. Defaults to off\&. If +\fIProtectControlGroups=\fR +is set, +\fIMountAPIVFS=yes\fR +is implied\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 232\&. +.RE +.PP +\fIRestrictAddressFamilies=\fR +.RS 4 +Restricts the set of socket address families accessible to the processes of this unit\&. Takes +"none", or a space\-separated list of address family names to allow\-list, such as +\fBAF_UNIX\fR, +\fBAF_INET\fR +or +\fBAF_INET6\fR\&. When +"none" +is specified, then all address families will be denied\&. When prefixed with +"~" +the listed address families will be applied as deny list, otherwise as allow list\&. Note that this restricts access to the +\fBsocket\fR(2) +system call only\&. Sockets passed into the process by other means (for example, by using socket activation with socket units, see +\fBsystemd.socket\fR(5)) are unaffected\&. Also, sockets created with +\fBsocketpair()\fR +(which creates connected AF_UNIX sockets only) are unaffected\&. Note that this option has no effect on 32\-bit x86, s390, s390x, mips, mips\-le, ppc, ppc\-le, ppc64, ppc64\-le and is ignored (but works correctly on other ABIs, including x86\-64)\&. Note that on systems supporting multiple ABIs (such as x86/x86\-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option\&. Specifically, it is recommended to combine this option with +\fISystemCallArchitectures=native\fR +or similar\&. By default, no restrictions apply, all address families are accessible to processes\&. If assigned the empty string, any previous address family restriction changes are undone\&. This setting does not affect commands prefixed with +"+"\&. +.sp +Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive network protocols, such as +\fBAF_PACKET\fR\&. Note that in most cases, the local +\fBAF_UNIX\fR +address family should be included in the configured allow list as it is frequently used for local communication, including for +\fBsyslog\fR(2) +logging\&. +.sp +Added in version 211\&. +.RE +.PP +\fIRestrictFileSystems=\fR +.RS 4 +Restricts the set of filesystems processes of this unit can open files on\&. Takes a space\-separated list of filesystem names\&. Any filesystem listed is made accessible to the unit\*(Aqs processes, access to filesystem types not listed is prohibited (allow\-listing)\&. If the first character of the list is +"~", the effect is inverted: access to the filesystems listed is prohibited (deny\-listing)\&. If the empty string is assigned, access to filesystems is not restricted\&. +.sp +If you specify both types of this option (i\&.e\&. allow\-listing and deny\-listing), the first encountered will take precedence and will dictate the default action (allow access to the filesystem or deny it)\&. Then the next occurrences of this option will add or delete the listed filesystems from the set of the restricted filesystems, depending on its type and the default action\&. +.sp +Example: if a unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictFileSystems=ext4 tmpfs +RestrictFileSystems=ext2 ext4 +.fi +.if n \{\ +.RE +.\} +.sp +then access to +\fBext4\fR, +\fBtmpfs\fR, and +\fBext2\fR +is allowed and access to other filesystems is denied\&. +.sp +Example: if a unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictFileSystems=ext4 tmpfs +RestrictFileSystems=~ext4 +.fi +.if n \{\ +.RE +.\} +.sp +then only access +\fBtmpfs\fR +is allowed\&. +.sp +Example: if a unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictFileSystems=~ext4 tmpfs +RestrictFileSystems=ext4 +.fi +.if n \{\ +.RE +.\} +.sp +then only access to +\fBtmpfs\fR +is denied\&. +.sp +As the number of possible filesystems is large, predefined sets of filesystems are provided\&. A set starts with +"@" +character, followed by name of the set\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&3.\ \&Currently predefined filesystem sets +.TS +allbox tab(:); +lB lB. +T{ +Set +T}:T{ +Description +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +@basic\-api +T}:T{ +Basic filesystem API\&. +T} +T{ +@auxiliary\-api +T}:T{ +Auxiliary filesystem API\&. +T} +T{ +@common\-block +T}:T{ +Common block device filesystems\&. +T} +T{ +@historical\-block +T}:T{ +Historical block device filesystems\&. +T} +T{ +@network +T}:T{ +Well\-known network filesystems\&. +T} +T{ +@privileged\-api +T}:T{ +Privileged filesystem API\&. +T} +T{ +@temporary +T}:T{ +Temporary filesystems: tmpfs, ramfs\&. +T} +T{ +@known +T}:T{ +All known filesystems defined by the kernel\&. This list is defined statically in systemd based on a kernel version that was available when this systemd version was released\&. It will become progressively more out\-of\-date as the kernel is updated\&. +T} +.TE +.sp 1 +Use +\fBsystemd-analyze\fR(1)\*(Aqs +\fBfilesystems\fR +command to retrieve a list of filesystems defined on the local system\&. +.sp +Note that this setting might not be supported on some systems (for example if the LSM eBPF hook is not enabled in the underlying kernel or if not using the unified control group hierarchy)\&. In that case this setting has no effect\&. +.sp +This option cannot be bypassed by prefixing +"+" +to the executable path in the service unit, as it applies to the whole control group\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRestrictNamespaces=\fR +.RS 4 +Restricts access to Linux namespace functionality for the processes of this unit\&. For details about Linux namespaces, see +\fBnamespaces\fR(7)\&. Either takes a boolean argument, or a space\-separated list of namespace type identifiers\&. If false (the default), no restrictions on namespace creation and switching are made\&. If true, access to any kind of namespacing is prohibited\&. Otherwise, a space\-separated list of namespace type identifiers must be specified, consisting of any combination of: +\fBcgroup\fR, +\fBipc\fR, +\fBnet\fR, +\fBmnt\fR, +\fBpid\fR, +\fBuser\fR +and +\fButs\fR\&. Any namespace type listed is made accessible to the unit\*(Aqs processes, access to namespace types not listed is prohibited (allow\-listing)\&. By prepending the list with a single tilde character ("~") the effect may be inverted: only the listed namespace types will be made inaccessible, all unlisted ones are permitted (deny\-listing)\&. If the empty string is assigned, the default namespace restrictions are applied, which is equivalent to false\&. This option may appear more than once, in which case the namespace types are merged by +\fBOR\fR, or by +\fBAND\fR +if the lines are prefixed with +"~" +(see examples below)\&. Internally, this setting limits access to the +\fBunshare\fR(2), +\fBclone\fR(2) +and +\fBsetns\fR(2) +system calls, taking the specified flags parameters into account\&. Note that \(em if this option is used \(em in addition to restricting creation and switching of the specified types of namespaces (or all of them, if true) access to the +\fBsetns()\fR +system call with a zero flags parameter is prohibited\&. This setting is only supported on x86, x86\-64, mips, mips\-le, mips64, mips64\-le, mips64\-n32, mips64\-le\-n32, ppc64, ppc64\-le, s390 and s390x, and enforces no restrictions on other architectures\&. +.sp +Example: if a unit has the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictNamespaces=cgroup ipc +RestrictNamespaces=cgroup net +.fi +.if n \{\ +.RE +.\} +.sp +then +\fBcgroup\fR, +\fBipc\fR, and +\fBnet\fR +are set\&. If the second line is prefixed with +"~", e\&.g\&., +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictNamespaces=cgroup ipc +RestrictNamespaces=~cgroup net +.fi +.if n \{\ +.RE +.\} +.sp +then, only +\fBipc\fR +is set\&. +.sp +Added in version 233\&. +.RE +.PP +\fILockPersonality=\fR +.RS 4 +Takes a boolean argument\&. If set, locks down the +\fBpersonality\fR(2) +system call so that the kernel execution domain may not be changed from the default or the personality selected with +\fIPersonality=\fR +directive\&. This may be useful to improve security, because odd personality emulations may be poorly tested and source of vulnerabilities\&. +.sp +Added in version 235\&. +.RE +.PP +\fIMemoryDenyWriteExecute=\fR +.RS 4 +Takes a boolean argument\&. If set, attempts to create memory mappings that are writable and executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory segments as executable, are prohibited\&. Specifically, a system call filter is added (or preferably, an equivalent kernel check is enabled with +\fBprctl\fR(2)) that rejects +\fBmmap\fR(2) +system calls with both +\fBPROT_EXEC\fR +and +\fBPROT_WRITE\fR +set, +\fBmprotect\fR(2) +or +\fBpkey_mprotect\fR(2) +system calls with +\fBPROT_EXEC\fR +set and +\fBshmat\fR(2) +system calls with +\fBSHM_EXEC\fR +set\&. Note that this option is incompatible with programs and libraries that generate program code dynamically at runtime, including JIT execution engines, executable stacks, and code "trampoline" feature of various C compilers\&. This option improves service security, as it makes harder for software exploits to change running code dynamically\&. However, the protection can be circumvented, if the service can write to a filesystem, which is not mounted with +\fBnoexec\fR +(such as +/dev/shm), or it can use +\fBmemfd_create()\fR\&. This can be prevented by making such file systems inaccessible to the service (e\&.g\&. +\fIInaccessiblePaths=/dev/shm\fR) and installing further system call filters (\fISystemCallFilter=~memfd_create\fR)\&. Note that this feature is fully available on x86\-64, and partially on x86\&. Specifically, the +\fBshmat()\fR +protection is not available on x86\&. Note that on systems supporting multiple ABIs (such as x86/x86\-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option\&. Specifically, it is recommended to combine this option with +\fISystemCallArchitectures=native\fR +or similar\&. +.sp +Added in version 231\&. +.RE +.PP +\fIRestrictRealtime=\fR +.RS 4 +Takes a boolean argument\&. If set, any attempts to enable realtime scheduling in a process of the unit are refused\&. This restricts access to realtime task scheduling policies such as +\fBSCHED_FIFO\fR, +\fBSCHED_RR\fR +or +\fBSCHED_DEADLINE\fR\&. See +\fBsched\fR(7) +for details about these scheduling policies\&. Realtime scheduling policies may be used to monopolize CPU time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial\-of\-Service situations on the system\&. It is hence recommended to restrict access to realtime scheduling to the few programs that actually require them\&. Defaults to off\&. +.sp +Added in version 231\&. +.RE +.PP +\fIRestrictSUIDSGID=\fR +.RS 4 +Takes a boolean argument\&. If set, any attempts to set the set\-user\-ID (SUID) or set\-group\-ID (SGID) bits on files or directories will be denied (for details on these bits see +\fBinode\fR(7))\&. As the SUID/SGID bits are mechanisms to elevate privileges, and allow users to acquire the identity of other users, it is recommended to restrict creation of SUID/SGID files to the few programs that actually require them\&. Note that this restricts marking of any type of file system object with these bits, including both regular files and directories (where the SGID is a different meaning than for files, see documentation)\&. This option is implied if +\fIDynamicUser=\fR +is enabled\&. Defaults to off\&. +.sp +Added in version 242\&. +.RE +.PP +\fIRemoveIPC=\fR +.RS 4 +Takes a boolean parameter\&. If set, all System V and POSIX IPC objects owned by the user and group the processes of this unit are run as are removed when the unit is stopped\&. This setting only has an effect if at least one of +\fIUser=\fR, +\fIGroup=\fR +and +\fIDynamicUser=\fR +are used\&. It has no effect on IPC objects owned by the root user\&. Specifically, this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues\&. If multiple units use the same user or group the IPC objects are removed when the last of these units is stopped\&. This setting is implied if +\fIDynamicUser=\fR +is set\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 232\&. +.RE +.PP +\fIPrivateMounts=\fR +.RS 4 +Takes a boolean parameter\&. If set, the processes of this unit will be run in their own private file system (mount) namespace with all mount propagation from the processes towards the host\*(Aqs main file system namespace turned off\&. This means any file system mount points established or removed by the unit\*(Aqs processes will be private to them and not be visible to the host\&. However, file system mount points established or removed on the host will be propagated to the unit\*(Aqs processes\&. See +\fBmount_namespaces\fR(7) +for details on file system namespaces\&. Defaults to off\&. +.sp +When turned on, this executes three operations for each invoked process: a new +\fBCLONE_NEWNS\fR +namespace is created, after which all existing mounts are remounted to +\fBMS_SLAVE\fR +to disable propagation from the unit\*(Aqs processes to the host (but leaving propagation in the opposite direction in effect)\&. Finally, the mounts are remounted again to the propagation mode configured with +\fIMountFlags=\fR, see below\&. +.sp +File system namespaces are set up individually for each process forked off by the service manager\&. Mounts established in the namespace of the process created by +\fIExecStartPre=\fR +will hence be cleaned up automatically as soon as that process exits and will not be available to subsequent processes forked off for +\fIExecStart=\fR +(and similar applies to the various other commands configured for units)\&. Similarly, +\fIJoinsNamespaceOf=\fR +does not permit sharing kernel mount namespaces between units, it only enables sharing of the +/tmp/ +and +/var/tmp/ +directories\&. +.sp +Other file system namespace unit settings \(em +\fIPrivateMounts=\fR, +\fIPrivateTmp=\fR, +\fIPrivateDevices=\fR, +\fIProtectSystem=\fR, +\fIProtectHome=\fR, +\fIReadOnlyPaths=\fR, +\fIInaccessiblePaths=\fR, +\fIReadWritePaths=\fR, \&... \(em also enable file system namespacing in a fashion equivalent to this option\&. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are used\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.sp +Added in version 239\&. +.RE +.PP +\fIMountFlags=\fR +.RS 4 +Takes a mount propagation setting: +\fBshared\fR, +\fBslave\fR +or +\fBprivate\fR, which controls whether file system mount points in the file system namespaces set up for this unit\*(Aqs processes will receive or propagate mounts and unmounts from other file system namespaces\&. See +\fBmount\fR(2) +for details on mount propagation, and the three propagation flags in particular\&. +.sp +This setting only controls the +\fIfinal\fR +propagation setting in effect on all mount points of the file system namespace created for each process of this unit\&. Other file system namespacing unit settings (see the discussion in +\fIPrivateMounts=\fR +above) will implicitly disable mount and unmount propagation from the unit\*(Aqs processes towards the host by changing the propagation setting of all mount points in the unit\*(Aqs file system namespace to +\fBslave\fR +first\&. Setting this option to +\fBshared\fR +does not reestablish propagation in that case\&. +.sp +If not set \(en but file system namespaces are enabled through another file system namespace unit setting \(en +\fBshared\fR +mount propagation is used, but \(em as mentioned \(em as +\fBslave\fR +is applied first, propagation from the unit\*(Aqs processes to the host is still turned off\&. +.sp +It is not recommended to use +\fBprivate\fR +mount propagation for units, as this means temporary mounts (such as removable media) of the host will stay mounted and thus indefinitely busy in forked off processes, as unmount propagation events won\*(Aqt be received by the file system namespace of the unit\&. +.sp +Usually, it is best to leave this setting unmodified, and use higher level file system namespacing options instead, in particular +\fIPrivateMounts=\fR, see above\&. +.sp +This option is only available for system services, or for services running in per\-user instances of the service manager in which case +\fIPrivateUsers=\fR +is implicitly enabled (requires unprivileged user namespaces support to be enabled in the kernel via the +"kernel\&.unprivileged_userns_clone=" +sysctl)\&. +.RE +.SH "SYSTEM CALL FILTERING" +.PP +\fISystemCallFilter=\fR +.RS 4 +Takes a space\-separated list of system call names\&. If this setting is used, all system calls executed by the unit processes except for the listed ones will result in immediate process termination with the +\fBSIGSYS\fR +signal (allow\-listing)\&. (See +\fISystemCallErrorNumber=\fR +below for changing the default action)\&. If the first character of the list is +"~", the effect is inverted: only the listed system calls will result in immediate process termination (deny\-listing)\&. Deny\-listed system calls and system call groups may optionally be suffixed with a colon (":") and +"errno" +error number (between 0 and 4095) or errno name such as +\fBEPERM\fR, +\fBEACCES\fR +or +\fBEUCLEAN\fR +(see +\fBerrno\fR(3) +for a full list)\&. This value will be returned when a deny\-listed system call is triggered, instead of terminating the processes immediately\&. Special setting +"kill" +can be used to explicitly specify killing\&. This value takes precedence over the one given in +\fISystemCallErrorNumber=\fR, see below\&. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel (\*(Aqseccomp filtering\*(Aq) and is useful for enforcing a minimal sandboxing environment\&. Note that the +\fBexecve()\fR, +\fBexit()\fR, +\fBexit_group()\fR, +\fBgetrlimit()\fR, +\fBrt_sigreturn()\fR, +\fBsigreturn()\fR +system calls and the system calls for querying time and sleeping are implicitly allow\-listed and do not need to be listed explicitly\&. This option may be specified more than once, in which case the filter masks are merged\&. If the empty string is assigned, the filter is reset, all prior assignments will have no effect\&. This does not affect commands prefixed with +"+"\&. +.sp +Note that on systems supporting multiple ABIs (such as x86/x86\-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option\&. Specifically, it is recommended to combine this option with +\fISystemCallArchitectures=native\fR +or similar\&. +.sp +Note that strict system call filters may impact execution and error handling code paths of the service invocation\&. Specifically, access to the +\fBexecve()\fR +system call is required for the execution of the service binary \(em if it is blocked service invocation will necessarily fail\&. Also, if execution of the service binary fails for some reason (for example: missing service executable), the error handling logic might require access to an additional set of system calls in order to process and log this failure correctly\&. It might be necessary to temporarily disable system call filters in order to simplify debugging of such failures\&. +.sp +If you specify both types of this option (i\&.e\&. allow\-listing and deny\-listing), the first encountered will take precedence and will dictate the default action (termination or approval of a system call)\&. Then the next occurrences of this option will add or delete the listed system calls from the set of the filtered system calls, depending of its type and the default action\&. (For example, if you have started with an allow list rule for +\fBread()\fR +and +\fBwrite()\fR, and right after it add a deny list rule for +\fBwrite()\fR, then +\fBwrite()\fR +will be removed from the set\&.) +.sp +As the number of possible system calls is large, predefined sets of system calls are provided\&. A set starts with +"@" +character, followed by name of the set\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&4.\ \&Currently predefined system call sets +.TS +allbox tab(:); +lB lB. +T{ +Set +T}:T{ +Description +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +@aio +T}:T{ +Asynchronous I/O (\fBio_setup\fR(2), \fBio_submit\fR(2), and related calls) +T} +T{ +@basic\-io +T}:T{ +System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (\fBread\fR(2), \fBwrite\fR(2), and related calls) +T} +T{ +@chown +T}:T{ +Changing file ownership (\fBchown\fR(2), \fBfchownat\fR(2), and related calls) +T} +T{ +@clock +T}:T{ +System calls for changing the system clock (\fBadjtimex\fR(2), \fBsettimeofday\fR(2), and related calls) +T} +T{ +@cpu\-emulation +T}:T{ +System calls for CPU emulation functionality (\fBvm86\fR(2) and related calls) +T} +T{ +@debug +T}:T{ +Debugging, performance monitoring and tracing functionality (\fBptrace\fR(2), \fBperf_event_open\fR(2) and related calls) +T} +T{ +@file\-system +T}:T{ +File system operations: opening, creating files and directories for read and write, renaming and removing them, reading file properties, or creating hard and symbolic links +T} +T{ +@io\-event +T}:T{ +Event loop system calls (\fBpoll\fR(2), \fBselect\fR(2), \fBepoll\fR(7), \fBeventfd\fR(2) and related calls) +T} +T{ +@ipc +T}:T{ +Pipes, SysV IPC, POSIX Message Queues and other IPC (\fBmq_overview\fR(7), \fBsvipc\fR(7)) +T} +T{ +@keyring +T}:T{ +Kernel keyring access (\fBkeyctl\fR(2) and related calls) +T} +T{ +@memlock +T}:T{ +Locking of memory in RAM (\fBmlock\fR(2), \fBmlockall\fR(2) and related calls) +T} +T{ +@module +T}:T{ +Loading and unloading of kernel modules (\fBinit_module\fR(2), \fBdelete_module\fR(2) and related calls) +T} +T{ +@mount +T}:T{ +Mounting and unmounting of file systems (\fBmount\fR(2), \fBchroot\fR(2), and related calls) +T} +T{ +@network\-io +T}:T{ +Socket I/O (including local AF_UNIX): \fBsocket\fR(7), \fBunix\fR(7) +T} +T{ +@obsolete +T}:T{ +Unusual, obsolete or unimplemented (\fBcreate_module\fR(2), \fBgtty\fR(2), \&...) +T} +T{ +@pkey +T}:T{ +System calls that deal with memory protection keys (\fBpkeys\fR(7)) +T} +T{ +@privileged +T}:T{ +All system calls which need super\-user capabilities (\fBcapabilities\fR(7)) +T} +T{ +@process +T}:T{ +Process control, execution, namespacing operations (\fBclone\fR(2), \fBkill\fR(2), \fBnamespaces\fR(7), \&...) +T} +T{ +@raw\-io +T}:T{ +Raw I/O port access (\fBioperm\fR(2), \fBiopl\fR(2), \fBpciconfig_read()\fR, \&...) +T} +T{ +@reboot +T}:T{ +System calls for rebooting and reboot preparation (\fBreboot\fR(2), \fBkexec()\fR, \&...) +T} +T{ +@resources +T}:T{ +System calls for changing resource limits, memory and scheduling parameters (\fBsetrlimit\fR(2), \fBsetpriority\fR(2), \&...) +T} +T{ +@sandbox +T}:T{ +System calls for sandboxing programs (\fBseccomp\fR(2), Landlock system calls, \&...) +T} +T{ +@setuid +T}:T{ +System calls for changing user ID and group ID credentials, (\fBsetuid\fR(2), \fBsetgid\fR(2), \fBsetresuid\fR(2), \&...) +T} +T{ +@signal +T}:T{ +System calls for manipulating and handling process signals (\fBsignal\fR(2), \fBsigprocmask\fR(2), \&...) +T} +T{ +@swap +T}:T{ +System calls for enabling/disabling swap devices (\fBswapon\fR(2), \fBswapoff\fR(2)) +T} +T{ +@sync +T}:T{ +Synchronizing files and memory to disk (\fBfsync\fR(2), \fBmsync\fR(2), and related calls) +T} +T{ +@system\-service +T}:T{ +A reasonable set of system calls used by common system services, excluding any special purpose calls\&. This is the recommended starting point for allow\-listing system calls for system services, as it contains what is typically needed by system services, but excludes overly specific interfaces\&. For example, the following APIs are excluded: "@clock", "@mount", "@swap", "@reboot"\&. +T} +T{ +@timer +T}:T{ +System calls for scheduling operations by time (\fBalarm\fR(2), \fBtimer_create\fR(2), \&...) +T} +T{ +@known +T}:T{ +All system calls defined by the kernel\&. This list is defined statically in systemd based on a kernel version that was available when this systemd version was released\&. It will become progressively more out\-of\-date as the kernel is updated\&. +T} +.TE +.sp 1 +Note, that as new system calls are added to the kernel, additional system calls might be added to the groups above\&. Contents of the sets may also change between systemd versions\&. In addition, the list of system calls depends on the kernel version and architecture for which systemd was compiled\&. Use +\fBsystemd\-analyze\ \&syscall\-filter\fR +to list the actual list of system calls in each filter\&. +.sp +Generally, allow\-listing system calls (rather than deny\-listing) is the safer mode of operation\&. It is recommended to enforce system call allow lists for all long\-running system services\&. Specifically, the following lines are a relatively safe basic choice for the majority of system services: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Service] +SystemCallFilter=@system\-service +SystemCallErrorNumber=EPERM +.fi +.if n \{\ +.RE +.\} +.sp +Note that various kernel system calls are defined redundantly: there are multiple system calls for executing the same operation\&. For example, the +\fBpidfd_send_signal()\fR +system call may be used to execute operations similar to what can be done with the older +\fBkill()\fR +system call, hence blocking the latter without the former only provides weak protection\&. Since new system calls are added regularly to the kernel as development progresses, keeping system call deny lists comprehensive requires constant work\&. It is thus recommended to use allow\-listing instead, which offers the benefit that new system calls are by default implicitly blocked until the allow list is updated\&. +.sp +Also note that a number of system calls are required to be accessible for the dynamic linker to work\&. The dynamic linker is required for running most regular programs (specifically: all dynamic ELF binaries, which is how most distributions build packaged programs)\&. This means that blocking these system calls (which include +\fBopen()\fR, +\fBopenat()\fR +or +\fBmmap()\fR) will make most programs typically shipped with generic distributions unusable\&. +.sp +It is recommended to combine the file system namespacing related options with +\fISystemCallFilter=~@mount\fR, in order to prohibit the unit\*(Aqs processes to undo the mappings\&. Specifically these are the options +\fIPrivateTmp=\fR, +\fIPrivateDevices=\fR, +\fIProtectSystem=\fR, +\fIProtectHome=\fR, +\fIProtectKernelTunables=\fR, +\fIProtectControlGroups=\fR, +\fIProtectKernelLogs=\fR, +\fIProtectClock=\fR, +\fIReadOnlyPaths=\fR, +\fIInaccessiblePaths=\fR +and +\fIReadWritePaths=\fR\&. +.sp +Added in version 187\&. +.RE +.PP +\fISystemCallErrorNumber=\fR +.RS 4 +Takes an +"errno" +error number (between 1 and 4095) or errno name such as +\fBEPERM\fR, +\fBEACCES\fR +or +\fBEUCLEAN\fR, to return when the system call filter configured with +\fISystemCallFilter=\fR +is triggered, instead of terminating the process immediately\&. See +\fBerrno\fR(3) +for a full list of error codes\&. When this setting is not used, or when the empty string or the special setting +"kill" +is assigned, the process will be terminated immediately when the filter is triggered\&. +.sp +Added in version 209\&. +.RE +.PP +\fISystemCallArchitectures=\fR +.RS 4 +Takes a space\-separated list of architecture identifiers to include in the system call filter\&. The known architecture identifiers are the same as for +\fIConditionArchitecture=\fR +described in +\fBsystemd.unit\fR(5), as well as +\fBx32\fR, +\fBmips64\-n32\fR, +\fBmips64\-le\-n32\fR, and the special identifier +\fBnative\fR\&. The special identifier +\fBnative\fR +implicitly maps to the native architecture of the system (or more precisely: to the architecture the system manager is compiled for)\&. By default, this option is set to the empty list, i\&.e\&. no filtering is applied\&. +.sp +If this setting is used, processes of this unit will only be permitted to call native system calls, and system calls of the specified architectures\&. For the purposes of this option, the x32 architecture is treated as including x86\-64 system calls\&. However, this setting still fulfills its purpose, as explained below, on x32\&. +.sp +System call filtering is not equally effective on all architectures\&. For example, on x86 filtering of network socket\-related calls is not possible, due to ABI limitations \(em a limitation that x86\-64 does not have, however\&. On systems supporting multiple ABIs at the same time \(em such as x86/x86\-64 \(em it is hence recommended to limit the set of permitted system call architectures so that secondary ABIs may not be used to circumvent the restrictions applied to the native ABI of the system\&. In particular, setting +\fISystemCallArchitectures=native\fR +is a good choice for disabling non\-native ABIs\&. +.sp +System call architectures may also be restricted system\-wide via the +\fISystemCallArchitectures=\fR +option in the global configuration\&. See +\fBsystemd-system.conf\fR(5) +for details\&. +.sp +Added in version 209\&. +.RE +.PP +\fISystemCallLog=\fR +.RS 4 +Takes a space\-separated list of system call names\&. If this setting is used, all system calls executed by the unit processes for the listed ones will be logged\&. If the first character of the list is +"~", the effect is inverted: all system calls except the listed system calls will be logged\&. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel (\*(Aqseccomp filtering\*(Aq) and is useful for auditing or setting up a minimal sandboxing environment\&. This option may be specified more than once, in which case the filter masks are merged\&. If the empty string is assigned, the filter is reset, all prior assignments will have no effect\&. This does not affect commands prefixed with +"+"\&. +.sp +Added in version 247\&. +.RE +.SH "ENVIRONMENT" +.PP +\fIEnvironment=\fR +.RS 4 +Sets environment variables for executed processes\&. Each line is unquoted using the rules described in "Quoting" section in +\fBsystemd.syntax\fR(7) +and becomes a list of variable assignments\&. If you need to assign a value containing spaces or the equals sign to a variable, put quotes around the whole assignment\&. Variable expansion is not performed inside the strings and the +"$" +character has no special meaning\&. Specifier expansion is performed, see the "Specifiers" section in +\fBsystemd.unit\fR(5)\&. +.sp +This option may be specified more than once, in which case all listed variables will be set\&. If the same variable is listed twice, the later setting will override the earlier setting\&. If the empty string is assigned to this option, the list of environment variables is reset, all prior assignments have no effect\&. +.sp +The names of the variables can contain ASCII letters, digits, and the underscore character\&. Variable names cannot be empty or start with a digit\&. In variable values, most characters are allowed, but non\-printable characters are currently rejected\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6" +.fi +.if n \{\ +.RE +.\} +.sp +gives three variables +"VAR1", +"VAR2", +"VAR3" +with the values +"word1 word2", +"word3", +"$word 5 6"\&. +.sp +See +\fBenviron\fR(7) +for details about environment variables\&. +.sp +Note that environment variables are not suitable for passing secrets (such as passwords, key material, \&...) to service processes\&. Environment variables set for a unit are exposed to unprivileged clients via D\-Bus IPC, and generally not understood as being data that requires protection\&. Moreover, environment variables are propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and hence might leak to processes that should not have access to the secret data\&. Use +\fILoadCredential=\fR, +\fILoadCredentialEncrypted=\fR +or +\fISetCredentialEncrypted=\fR +(see below) to pass data to unit processes securely\&. +.RE +.PP +\fIEnvironmentFile=\fR +.RS 4 +Similar to +\fIEnvironment=\fR, but reads the environment variables from a text file\&. The text file should contain newline\-separated variable assignments\&. Empty lines, lines without an +"=" +separator, or lines starting with +";" +or +"#" +will be ignored, which may be used for commenting\&. The file must be encoded with UTF\-8\&. Valid characters are +\m[blue]\fBunicode scalar values\fR\m[]\&\s-2\u[8]\d\s+2 +other than +\m[blue]\fBunicode noncharacters\fR\m[]\&\s-2\u[9]\d\s+2, +\fBU+0000\fR +\fBNUL\fR, and +\fBU+FEFF\fR +\m[blue]\fBunicode byte order mark\fR\m[]\&\s-2\u[10]\d\s+2\&. Control codes other than +\fBNUL\fR +are allowed\&. +.sp +In the file, an unquoted value after the +"=" +is parsed with the same backslash\-escape rules as +\m[blue]\fBPOSIX shell unquoted text\fR\m[]\&\s-2\u[11]\d\s+2, but unlike in a shell, interior whitespace is preserved and quotes after the first non\-whitespace character are preserved\&. Leading and trailing whitespace (space, tab, carriage return) is discarded, but interior whitespace within the line is preserved verbatim\&. A line ending with a backslash will be continued to the following one, with the newline itself discarded\&. A backslash +"\e" +followed by any character other than newline will preserve the following character, so that +"\e\e" +will become the value +"\e"\&. +.sp +In the file, a +"\*(Aq"\-quoted value after the +"=" +can span multiple lines and contain any character verbatim other than single quote, like +\m[blue]\fBPOSIX shell single\-quoted text\fR\m[]\&\s-2\u[12]\d\s+2\&. No backslash\-escape sequences are recognized\&. Leading and trailing whitespace outside of the single quotes is discarded\&. +.sp +In the file, a +"""\-quoted value after the +"=" +can span multiple lines, and the same escape sequences are recognized as in +\m[blue]\fBPOSIX shell double\-quoted text\fR\m[]\&\s-2\u[13]\d\s+2\&. Backslash ("\e") followed by any of +""\e`$" +will preserve that character\&. A backslash followed by newline is a line continuation, and the newline itself is discarded\&. A backslash followed by any other character is ignored; both the backslash and the following character are preserved verbatim\&. Leading and trailing whitespace outside of the double quotes is discarded\&. +.sp +The argument passed should be an absolute filename or wildcard expression, optionally prefixed with +"\-", which indicates that if the file does not exist, it will not be read and no error or warning message is logged\&. This option may be specified more than once in which case all specified files are read\&. If the empty string is assigned to this option, the list of file to read is reset, all prior assignments have no effect\&. +.sp +The files listed with this directive will be read shortly before the process is executed (more specifically, after all processes from a previous unit state terminated\&. This means you can generate these files in one unit state, and read it with this option in the next\&. The files are read from the file system of the service manager, before any file system changes like bind mounts take place)\&. +.sp +Settings from these files override settings made with +\fIEnvironment=\fR\&. If the same variable is set twice from these files, the files will be read in the order they are specified and the later setting will override the earlier setting\&. +.RE +.PP +\fIPassEnvironment=\fR +.RS 4 +Pass environment variables set for the system service manager to executed processes\&. Takes a space\-separated list of variable names\&. This option may be specified more than once, in which case all listed variables will be passed\&. If the empty string is assigned to this option, the list of environment variables to pass is reset, all prior assignments have no effect\&. Variables specified that are not set for the system manager will not be passed and will be silently ignored\&. Note that this option is only relevant for the system service manager, as system services by default do not automatically inherit any environment variables set for the service manager itself\&. However, in case of the user service manager all environment variables are passed to the executed processes anyway, hence this option is without effect for the user service manager\&. +.sp +Variables set for invoked processes due to this setting are subject to being overridden by those configured with +\fIEnvironment=\fR +or +\fIEnvironmentFile=\fR\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PassEnvironment=VAR1 VAR2 VAR3 +.fi +.if n \{\ +.RE +.\} +.sp +passes three variables +"VAR1", +"VAR2", +"VAR3" +with the values set for those variables in PID1\&. +.sp +See +\fBenviron\fR(7) +for details about environment variables\&. +.sp +Added in version 228\&. +.RE +.PP +\fIUnsetEnvironment=\fR +.RS 4 +Explicitly unset environment variable assignments that would normally be passed from the service manager to invoked processes of this unit\&. Takes a space\-separated list of variable names or variable assignments\&. This option may be specified more than once, in which case all listed variables/assignments will be unset\&. If the empty string is assigned to this option, the list of environment variables/assignments to unset is reset\&. If a variable assignment is specified (that is: a variable name, followed by +"=", followed by its value), then any environment variable matching this precise assignment is removed\&. If a variable name is specified (that is a variable name without any following +"=" +or value), then any assignment matching the variable name, regardless of its value is removed\&. Note that the effect of +\fIUnsetEnvironment=\fR +is applied as final step when the environment list passed to executed processes is compiled\&. That means it may undo assignments from any configuration source, including assignments made through +\fIEnvironment=\fR +or +\fIEnvironmentFile=\fR, inherited from the system manager\*(Aqs global set of environment variables, inherited via +\fIPassEnvironment=\fR, set by the service manager itself (such as +\fI$NOTIFY_SOCKET\fR +and such), or set by a PAM module (in case +\fIPAMName=\fR +is used)\&. +.sp +See "Environment Variables in Spawned Processes" below for a description of how those settings combine to form the inherited environment\&. See +\fBenviron\fR(7) +for general information about environment variables\&. +.sp +Added in version 235\&. +.RE +.SH "LOGGING AND STANDARD INPUT/OUTPUT" +.PP +\fIStandardInput=\fR +.RS 4 +Controls where file descriptor 0 (STDIN) of the executed processes is connected to\&. Takes one of +\fBnull\fR, +\fBtty\fR, +\fBtty\-force\fR, +\fBtty\-fail\fR, +\fBdata\fR, +\fBfile:\fR\fB\fIpath\fR\fR, +\fBsocket\fR +or +\fBfd:\fR\fB\fIname\fR\fR\&. +.sp +If +\fBnull\fR +is selected, standard input will be connected to +/dev/null, i\&.e\&. all read attempts by the process will result in immediate EOF\&. +.sp +If +\fBtty\fR +is selected, standard input is connected to a TTY (as configured by +\fITTYPath=\fR, see below) and the executed process becomes the controlling process of the terminal\&. If the terminal is already being controlled by another process, the executed process waits until the current controlling process releases the terminal\&. +.sp +\fBtty\-force\fR +is similar to +\fBtty\fR, but the executed process is forcefully and immediately made the controlling process of the terminal, potentially removing previous controlling processes from the terminal\&. +.sp +\fBtty\-fail\fR +is similar to +\fBtty\fR, but if the terminal already has a controlling process start\-up of the executed process fails\&. +.sp +The +\fBdata\fR +option may be used to configure arbitrary textual or binary data to pass via standard input to the executed process\&. The data to pass is configured via +\fIStandardInputText=\fR/\fIStandardInputData=\fR +(see below)\&. Note that the actual file descriptor type passed (memory file, regular file, UNIX pipe, \&...) might depend on the kernel and available privileges\&. In any case, the file descriptor is read\-only, and when read returns the specified data followed by EOF\&. +.sp +The +\fBfile:\fR\fB\fIpath\fR\fR +option may be used to connect a specific file system object to standard input\&. An absolute path following the +":" +character is expected, which may refer to a regular file, a FIFO or special file\&. If an +\fBAF_UNIX\fR +socket in the file system is specified, a stream socket is connected to it\&. The latter is useful for connecting standard input of processes to arbitrary system services\&. +.sp +The +\fBsocket\fR +option is valid in socket\-activated services only, and requires the relevant socket unit file (see +\fBsystemd.socket\fR(5) +for details) to have +\fIAccept=yes\fR +set, or to specify a single socket only\&. If this option is set, standard input will be connected to the socket the service was activated from, which is primarily useful for compatibility with daemons designed for use with the traditional +\fBinetd\fR(8) +socket activation daemon (\fI$LISTEN_FDS\fR +(and related) environment variables are not passed when +\fBsocket\fR +value is configured)\&. +.sp +The +\fBfd:\fR\fB\fIname\fR\fR +option connects standard input to a specific, named file descriptor provided by a socket unit\&. The name may be specified as part of this option, following a +":" +character (e\&.g\&. +"fd:foobar")\&. If no name is specified, the name +"stdin" +is implied (i\&.e\&. +"fd" +is equivalent to +"fd:stdin")\&. At least one socket unit defining the specified name must be provided via the +\fISockets=\fR +option, and the file descriptor name may differ from the name of its containing socket unit\&. If multiple matches are found, the first one will be used\&. See +\fIFileDescriptorName=\fR +in +\fBsystemd.socket\fR(5) +for more details about named file descriptors and their ordering\&. +.sp +This setting defaults to +\fBnull\fR, unless +\fIStandardInputText=\fR/\fIStandardInputData=\fR +are set, in which case it defaults to +\fBdata\fR\&. +.RE +.PP +\fIStandardOutput=\fR +.RS 4 +Controls where file descriptor 1 (stdout) of the executed processes is connected to\&. Takes one of +\fBinherit\fR, +\fBnull\fR, +\fBtty\fR, +\fBjournal\fR, +\fBkmsg\fR, +\fBjournal+console\fR, +\fBkmsg+console\fR, +\fBfile:\fR\fB\fIpath\fR\fR, +\fBappend:\fR\fB\fIpath\fR\fR, +\fBtruncate:\fR\fB\fIpath\fR\fR, +\fBsocket\fR +or +\fBfd:\fR\fB\fIname\fR\fR\&. +.sp +\fBinherit\fR +duplicates the file descriptor of standard input for standard output\&. +.sp +\fBnull\fR +connects standard output to +/dev/null, i\&.e\&. everything written to it will be lost\&. +.sp +\fBtty\fR +connects standard output to a tty (as configured via +\fITTYPath=\fR, see below)\&. If the TTY is used for output only, the executed process will not become the controlling process of the terminal, and will not fail or wait for other processes to release the terminal\&. +.sp +\fBjournal\fR +connects standard output with the journal, which is accessible via +\fBjournalctl\fR(1)\&. Note that everything that is written to kmsg (see below) is implicitly stored in the journal as well, the specific option listed below is hence a superset of this one\&. (Also note that any external, additional syslog daemons receive their log data from the journal, too, hence this is the option to use when logging shall be processed with such a daemon\&.) +.sp +\fBkmsg\fR +connects standard output with the kernel log buffer which is accessible via +\fBdmesg\fR(1), in addition to the journal\&. The journal daemon might be configured to send all logs to kmsg anyway, in which case this option is no different from +\fBjournal\fR\&. +.sp +\fBjournal+console\fR +and +\fBkmsg+console\fR +work in a similar way as the two options above but copy the output to the system console as well\&. +.sp +The +\fBfile:\fR\fB\fIpath\fR\fR +option may be used to connect a specific file system object to standard output\&. The semantics are similar to the same option of +\fIStandardInput=\fR, see above\&. If +\fIpath\fR +refers to a regular file on the filesystem, it is opened (created if it doesn\*(Aqt exist yet) for writing at the beginning of the file, but without truncating it\&. If standard input and output are directed to the same file path, it is opened only once \(em for reading as well as writing \(em and duplicated\&. This is particularly useful when the specified path refers to an +\fBAF_UNIX\fR +socket in the file system, as in that case only a single stream connection is created for both input and output\&. +.sp +\fBappend:\fR\fB\fIpath\fR\fR +is similar to +\fBfile:\fR\fB\fIpath\fR\fR +above, but it opens the file in append mode\&. +.sp +\fBtruncate:\fR\fB\fIpath\fR\fR +is similar to +\fBfile:\fR\fB\fIpath\fR\fR +above, but it truncates the file when opening it\&. For units with multiple command lines, e\&.g\&. +\fIType=oneshot\fR +services with multiple +\fIExecStart=\fR, or services with +\fIExecCondition=\fR, +\fIExecStartPre=\fR +or +\fIExecStartPost=\fR, the output file is reopened and therefore re\-truncated for each command line\&. If the output file is truncated while another process still has the file open, e\&.g\&. by an +\fIExecReload=\fR +running concurrently with an +\fIExecStart=\fR, and the other process continues writing to the file without adjusting its offset, then the space between the file pointers of the two processes may be filled with +\fBNUL\fR +bytes, producing a sparse file\&. Thus, +\fBtruncate:\fR\fB\fIpath\fR\fR +is typically only useful for units where only one process runs at a time, such as services with a single +\fIExecStart=\fR +and no +\fIExecStartPost=\fR, +\fIExecReload=\fR, +\fIExecStop=\fR +or similar\&. +.sp +\fBsocket\fR +connects standard output to a socket acquired via socket activation\&. The semantics are similar to the same option of +\fIStandardInput=\fR, see above\&. +.sp +The +\fBfd:\fR\fB\fIname\fR\fR +option connects standard output to a specific, named file descriptor provided by a socket unit\&. A name may be specified as part of this option, following a +":" +character (e\&.g\&. +"fd:\fIfoobar\fR")\&. If no name is specified, the name +"stdout" +is implied (i\&.e\&. +"fd" +is equivalent to +"fd:stdout")\&. At least one socket unit defining the specified name must be provided via the +\fISockets=\fR +option, and the file descriptor name may differ from the name of its containing socket unit\&. If multiple matches are found, the first one will be used\&. See +\fIFileDescriptorName=\fR +in +\fBsystemd.socket\fR(5) +for more details about named descriptors and their ordering\&. +.sp +If the standard output (or error output, see below) of a unit is connected to the journal or the kernel log buffer, the unit will implicitly gain a dependency of type +\fIAfter=\fR +on +systemd\-journald\&.socket +(also see the "Implicit Dependencies" section above)\&. Also note that in this case stdout (or stderr, see below) will be an +\fBAF_UNIX\fR +stream socket, and not a pipe or FIFO that can be re\-opened\&. This means when executing shell scripts the construct +\fBecho "hello" > /dev/stderr\fR +for writing text to stderr will not work\&. To mitigate this use the construct +\fBecho "hello" >&2\fR +instead, which is mostly equivalent and avoids this pitfall\&. +.sp +If +\fIStandardInput=\fR +is set to one of +\fBtty\fR, +\fBtty\-force\fR, +\fBtty\-fail\fR, +\fBsocket\fR, or +\fBfd:\fR\fB\fIname\fR\fR, this setting defaults to +\fBinherit\fR\&. +.sp +In other cases, this setting defaults to the value set with +\fIDefaultStandardOutput=\fR +in +\fBsystemd-system.conf\fR(5), which defaults to +\fBjournal\fR\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&. +.RE +.PP +\fIStandardError=\fR +.RS 4 +Controls where file descriptor 2 (stderr) of the executed processes is connected to\&. The available options are identical to those of +\fIStandardOutput=\fR, with some exceptions: if set to +\fBinherit\fR +the file descriptor used for standard output is duplicated for standard error, while +\fBfd:\fR\fB\fIname\fR\fR +will use a default file descriptor name of +"stderr"\&. +.sp +This setting defaults to the value set with +\fIDefaultStandardError=\fR +in +\fBsystemd-system.conf\fR(5), which defaults to +\fBinherit\fR\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&. +.RE +.PP +\fIStandardInputText=\fR, \fIStandardInputData=\fR +.RS 4 +Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to the executed processes\&. These settings have no effect unless +\fIStandardInput=\fR +is set to +\fBdata\fR +(which is the default if +\fIStandardInput=\fR +is not set otherwise, but +\fIStandardInputText=\fR/\fIStandardInputData=\fR +is)\&. Use this option to embed process input data directly in the unit file\&. +.sp +\fIStandardInputText=\fR +accepts arbitrary textual data\&. C\-style escapes for special characters as well as the usual +"%"\-specifiers are resolved\&. Each time this setting is used the specified text is appended to the per\-unit data buffer, followed by a newline character (thus every use appends a new line to the end of the buffer)\&. Note that leading and trailing whitespace of lines configured with this option is removed\&. If an empty line is specified the buffer is cleared (hence, in order to insert an empty line, add an additional +"\en" +to the end or beginning of a line)\&. +.sp +\fIStandardInputData=\fR +accepts arbitrary binary data, encoded in +\m[blue]\fBBase64\fR\m[]\&\s-2\u[14]\d\s+2\&. No escape sequences or specifiers are resolved\&. Any whitespace in the encoded version is ignored during decoding\&. +.sp +Note that +\fIStandardInputText=\fR +and +\fIStandardInputData=\fR +operate on the same data buffer, and may be mixed in order to configure both binary and textual data for the same input stream\&. The textual or binary data is joined strictly in the order the settings appear in the unit file\&. Assigning an empty string to either will reset the data buffer\&. +.sp +Please keep in mind that in order to maintain readability long unit file settings may be split into multiple lines, by suffixing each line (except for the last) with a +"\e" +character (see +\fBsystemd.unit\fR(5) +for details)\&. This is particularly useful for large data configured with these two options\&. Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\&... +StandardInput=data +StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZXMgYW5kIHNvIGRv \e + IEkKQSBmdWxsIGNvbW1pdG1lbnQncyB3aGF0IEnigLJtIHRoaW5raW5nIG9mCllvdSB3b3VsZG4n \e + dCBnZXQgdGhpcyBmcm9tIGFueSBvdGhlciBndXkKSSBqdXN0IHdhbm5hIHRlbGwgeW91IGhvdyBJ \e + J20gZmVlbGluZwpHb3R0YSBtYWtlIHlvdSB1bmRlcnN0YW5kCgpOZXZlciBnb25uYSBnaXZlIHlv \e + dSB1cApOZXZlciBnb25uYSBsZXQgeW91IGRvd24KTmV2ZXIgZ29ubmEgcnVuIGFyb3VuZCBhbmQg \e + ZGVzZXJ0IHlvdQpOZXZlciBnb25uYSBtYWtlIHlvdSBjcnkKTmV2ZXIgZ29ubmEgc2F5IGdvb2Ri \e + eWUKTmV2ZXIgZ29ubmEgdGVsbCBhIGxpZSBhbmQgaHVydCB5b3UK +\&... +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 236\&. +.RE +.PP +\fILogLevelMax=\fR +.RS 4 +Configures filtering by log level of log messages generated by this unit\&. Takes a +\fBsyslog\fR +log level, one of +\fBemerg\fR +(lowest log level, only highest priority messages), +\fBalert\fR, +\fBcrit\fR, +\fBerr\fR, +\fBwarning\fR, +\fBnotice\fR, +\fBinfo\fR, +\fBdebug\fR +(highest log level, also lowest priority messages)\&. See +\fBsyslog\fR(3) +for details\&. By default no filtering is applied (i\&.e\&. the default maximum log level is +\fBdebug\fR)\&. Use this option to configure the logging system to drop log messages of a specific service above the specified level\&. For example, set +\fILogLevelMax=\fR\fBinfo\fR +in order to turn off debug logging of a particularly chatty unit\&. Note that the configured level is applied to any log messages written by any of the processes belonging to this unit, as well as any log messages written by the system manager process (PID 1) in reference to this unit, sent via any supported logging protocol\&. The filtering is applied early in the logging pipeline, before any kind of further processing is done\&. Moreover, messages which pass through this filter successfully might still be dropped by filters applied at a later stage in the logging subsystem\&. For example, +\fIMaxLevelStore=\fR +configured in +\fBjournald.conf\fR(5) +might prohibit messages of higher log levels to be stored on disk, even though the per\-unit +\fILogLevelMax=\fR +permitted it to be processed\&. +.sp +Added in version 236\&. +.RE +.PP +\fILogExtraFields=\fR +.RS 4 +Configures additional log metadata fields to include in all log records generated by processes associated with this unit, including systemd\&. This setting takes one or more journal field assignments in the format +"FIELD=VALUE" +separated by whitespace\&. See +\fBsystemd.journal-fields\fR(7) +for details on the journal field concept\&. Even though the underlying journal implementation permits binary field values, this setting accepts only valid UTF\-8 values\&. To include space characters in a journal field value, enclose the assignment in double quotes (")\&. +The usual specifiers are expanded in all assignments (see below)\&. Note that this setting is not only useful for attaching additional metadata to log records of a unit, but given that all fields and values are indexed may also be used to implement cross\-unit log record matching\&. Assign an empty string to reset the list\&. +.sp +Added in version 236\&. +.RE +.PP +\fILogRateLimitIntervalSec=\fR, \fILogRateLimitBurst=\fR +.RS 4 +Configures the rate limiting that is applied to log messages generated by this unit\&. If, in the time interval defined by +\fILogRateLimitIntervalSec=\fR, more messages than specified in +\fILogRateLimitBurst=\fR +are logged by a service, all further messages within the interval are dropped until the interval is over\&. A message about the number of dropped messages is generated\&. The time specification for +\fILogRateLimitIntervalSec=\fR +may be specified in the following units: "s", "min", "h", "ms", "us"\&. See +\fBsystemd.time\fR(7) +for details\&. The default settings are set by +\fIRateLimitIntervalSec=\fR +and +\fIRateLimitBurst=\fR +configured in +\fBjournald.conf\fR(5)\&. Note that this only applies to log messages that are processed by the logging subsystem, i\&.e\&. by +\fBsystemd-journald.service\fR(8)\&. This means that if you connect a service\*(Aqs stderr directly to a file via +\fIStandardOutput=file:\&...\fR +or a similar setting, the rate limiting will not be applied to messages written that way (but it will be enforced for messages generated via +\fBsyslog\fR(3) +and similar functions)\&. +.sp +Added in version 240\&. +.RE +.PP +\fILogFilterPatterns=\fR +.RS 4 +Define an extended regular expression to filter log messages based on the +\fIMESSAGE=\fR +field of the structured message\&. If the first character of the pattern is +"~", log entries matching the pattern should be discarded\&. This option takes a single pattern as an argument but can be used multiple times to create a list of allowed and denied patterns\&. If the empty string is assigned, the filter is reset, and all prior assignments will have no effect\&. +.sp +Because the +"~" +character is used to define denied patterns, it must be replaced with +"\ex7e" +to allow a message starting with +"~"\&. For example, +"~foobar" +would add a pattern matching +"foobar" +to the deny list, while +"\ex7efoobar" +would add a pattern matching +"~foobar" +to the allow list\&. +.sp +Log messages are tested against denied patterns (if any), then against allowed patterns (if any)\&. If a log message matches any of the denied patterns, it will be discarded, whatever the allowed patterns\&. Then, remaining log messages are tested against allowed patterns\&. Messages matching against none of the allowed pattern are discarded\&. If no allowed patterns are defined, then all messages are processed directly after going through denied filters\&. +.sp +Filtering is based on the unit for which +\fILogFilterPatterns=\fR +is defined, meaning log messages coming from +\fBsystemd\fR(1) +about the unit are not taken into account\&. Filtered log messages won\*(Aqt be forwarded to traditional syslog daemons, the kernel log buffer (kmsg), the systemd console, or sent as wall messages to all logged\-in users\&. +.sp +Added in version 253\&. +.RE +.PP +\fILogNamespace=\fR +.RS 4 +Run the unit\*(Aqs processes in the specified journal namespace\&. Expects a short user\-defined string identifying the namespace\&. If not used the processes of the service are run in the default journal namespace, i\&.e\&. their log stream is collected and processed by +systemd\-journald\&.service\&. If this option is used any log data generated by processes of this unit (regardless if via the +\fBsyslog()\fR, journal native logging or stdout/stderr logging) is collected and processed by an instance of the +systemd\-journald@\&.service +template unit, which manages the specified namespace\&. The log data is stored in a data store independent from the default log namespace\*(Aqs data store\&. See +\fBsystemd-journald.service\fR(8) +for details about journal namespaces\&. +.sp +Internally, journal namespaces are implemented through Linux mount namespacing and over\-mounting the directory that contains the relevant +\fBAF_UNIX\fR +sockets used for logging in the unit\*(Aqs mount namespace\&. Since mount namespaces are used this setting disconnects propagation of mounts from the unit\*(Aqs processes to the host, similarly to how +\fIReadOnlyPaths=\fR +and similar settings describe above work\&. Journal namespaces may hence not be used for services that need to establish mount points on the host\&. +.sp +When this option is used the unit will automatically gain ordering and requirement dependencies on the two socket units associated with the +systemd\-journald@\&.service +instance so that they are automatically established prior to the unit starting up\&. Note that when this option is used log output of this service does not appear in the regular +\fBjournalctl\fR(1) +output, unless the +\fB\-\-namespace=\fR +option is used\&. +.sp +This option is only available for system services and is not supported for services running in per\-user instances of the service manager\&. +.sp +Added in version 245\&. +.RE +.PP +\fISyslogIdentifier=\fR +.RS 4 +Sets the process name ("\fBsyslog\fR +tag") to prefix log lines sent to the logging system or the kernel log buffer with\&. If not set, defaults to the process name of the executed process\&. This option is only useful when +\fIStandardOutput=\fR +or +\fIStandardError=\fR +are set to +\fBjournal\fR +or +\fBkmsg\fR +(or to the same settings in combination with +\fB+console\fR) and only applies to log messages written to stdout or stderr\&. +.RE +.PP +\fISyslogFacility=\fR +.RS 4 +Sets the +\fBsyslog\fR +facility identifier to use when logging\&. One of +\fBkern\fR, +\fBuser\fR, +\fBmail\fR, +\fBdaemon\fR, +\fBauth\fR, +\fBsyslog\fR, +\fBlpr\fR, +\fBnews\fR, +\fBuucp\fR, +\fBcron\fR, +\fBauthpriv\fR, +\fBftp\fR, +\fBlocal0\fR, +\fBlocal1\fR, +\fBlocal2\fR, +\fBlocal3\fR, +\fBlocal4\fR, +\fBlocal5\fR, +\fBlocal6\fR +or +\fBlocal7\fR\&. See +\fBsyslog\fR(3) +for details\&. This option is only useful when +\fIStandardOutput=\fR +or +\fIStandardError=\fR +are set to +\fBjournal\fR +or +\fBkmsg\fR +(or to the same settings in combination with +\fB+console\fR), and only applies to log messages written to stdout or stderr\&. Defaults to +\fBdaemon\fR\&. +.RE +.PP +\fISyslogLevel=\fR +.RS 4 +The default +\fBsyslog\fR +log level to use when logging to the logging system or the kernel log buffer\&. One of +\fBemerg\fR, +\fBalert\fR, +\fBcrit\fR, +\fBerr\fR, +\fBwarning\fR, +\fBnotice\fR, +\fBinfo\fR, +\fBdebug\fR\&. See +\fBsyslog\fR(3) +for details\&. This option is only useful when +\fIStandardOutput=\fR +or +\fIStandardError=\fR +are set to +\fBjournal\fR +or +\fBkmsg\fR +(or to the same settings in combination with +\fB+console\fR), and only applies to log messages written to stdout or stderr\&. Note that individual lines output by executed processes may be prefixed with a different log level which can be used to override the default log level specified here\&. The interpretation of these prefixes may be disabled with +\fISyslogLevelPrefix=\fR, see below\&. For details, see +\fBsd-daemon\fR(3)\&. Defaults to +\fBinfo\fR\&. +.RE +.PP +\fISyslogLevelPrefix=\fR +.RS 4 +Takes a boolean argument\&. If true and +\fIStandardOutput=\fR +or +\fIStandardError=\fR +are set to +\fBjournal\fR +or +\fBkmsg\fR +(or to the same settings in combination with +\fB+console\fR), log lines written by the executed process that are prefixed with a log level will be processed with this log level set but the prefix removed\&. If set to false, the interpretation of these prefixes is disabled and the logged lines are passed on as\-is\&. This only applies to log messages written to stdout or stderr\&. For details about this prefixing see +\fBsd-daemon\fR(3)\&. Defaults to true\&. +.RE +.PP +\fITTYPath=\fR +.RS 4 +Sets the terminal device node to use if standard input, output, or error are connected to a TTY (see above)\&. Defaults to +/dev/console\&. +.RE +.PP +\fITTYReset=\fR +.RS 4 +Reset the terminal device specified with +\fITTYPath=\fR +before and after execution\&. Defaults to +"no"\&. +.RE +.PP +\fITTYVHangup=\fR +.RS 4 +Disconnect all clients which have opened the terminal device specified with +\fITTYPath=\fR +before and after execution\&. Defaults to +"no"\&. +.RE +.PP +\fITTYRows=\fR, \fITTYColumns=\fR +.RS 4 +Configure the size of the TTY specified with +\fITTYPath=\fR\&. If unset or set to the empty string, the kernel default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fITTYVTDisallocate=\fR +.RS 4 +If the terminal device specified with +\fITTYPath=\fR +is a virtual console terminal, try to deallocate the TTY before and after execution\&. This ensures that the screen and scrollback buffer is cleared\&. Defaults to +"no"\&. +.RE +.SH "CREDENTIALS" +.PP +\fILoadCredential=\fR\fIID\fR[:\fIPATH\fR], \fILoadCredentialEncrypted=\fR\fIID\fR[:\fIPATH\fR] +.RS 4 +Pass a credential to the unit\&. Credentials are limited\-size binary or textual objects that may be passed to unit processes\&. They are primarily used for passing cryptographic keys (both public and private) or certificates, user account information or identity information from host to services\&. The data is accessible from the unit\*(Aqs processes via the file system, at a read\-only location that (if possible and permitted) is backed by non\-swappable memory\&. The data is only accessible to the user associated with the unit, via the +\fIUser=\fR/\fIDynamicUser=\fR +settings (as well as the superuser)\&. When available, the location of credentials is exported as the +\fI$CREDENTIALS_DIRECTORY\fR +environment variable to the unit\*(Aqs processes\&. +.sp +The +\fILoadCredential=\fR +setting takes a textual ID to use as name for a credential plus a file system path, separated by a colon\&. The ID must be a short ASCII string suitable as filename in the filesystem, and may be chosen freely by the user\&. If the specified path is absolute it is opened as regular file and the credential data is read from it\&. If the absolute path refers to an +\fBAF_UNIX\fR +stream socket in the file system a connection is made to it (only once at unit start\-up) and the credential data read from the connection, providing an easy IPC integration point for dynamically transferring credentials from other services\&. +.sp +If the specified path is not absolute and itself qualifies as valid credential identifier it is attempted to find a credential that the service manager itself received under the specified name \(em which may be used to propagate credentials from an invoking environment (e\&.g\&. a container manager that invoked the service manager) into a service\&. If no matching system credential is found, the directories +/etc/credstore/, +/run/credstore/ +and +/usr/lib/credstore/ +are searched for files under the credential\*(Aqs name \(em which hence are recommended locations for credential data on disk\&. If +\fILoadCredentialEncrypted=\fR +is used +/run/credstore\&.encrypted/, +/etc/credstore\&.encrypted/, and +/usr/lib/credstore\&.encrypted/ +are searched as well\&. +.sp +If the file system path is omitted it is chosen identical to the credential name, i\&.e\&. this is a terse way to declare credentials to inherit from the service manager into a service\&. This option may be used multiple times, each time defining an additional credential to pass to the unit\&. +.sp +If an absolute path referring to a directory is specified, every file in that directory (recursively) will be loaded as a separate credential\&. The ID for each credential will be the provided ID suffixed with +"_$FILENAME" +(e\&.g\&., +"Key_file1")\&. When loading from a directory, symlinks will be ignored\&. +.sp +The contents of the file/socket may be arbitrary binary or textual data, including newline characters and +\fBNUL\fR +bytes\&. +.sp +The +\fILoadCredentialEncrypted=\fR +setting is identical to +\fILoadCredential=\fR, except that the credential data is decrypted and authenticated before being passed on to the executed processes\&. Specifically, the referenced path should refer to a file or socket with an encrypted credential, as implemented by +\fBsystemd-creds\fR(1)\&. This credential is loaded, decrypted, authenticated and then passed to the application in plaintext form, in the same way a regular credential specified via +\fILoadCredential=\fR +would be\&. A credential configured this way may be symmetrically encrypted/authenticated with a secret key derived from the system\*(Aqs TPM2 security chip, or with a secret key stored in +/var/lib/systemd/credentials\&.secret, or with both\&. Using encrypted and authenticated credentials improves security as credentials are not stored in plaintext and only authenticated and decrypted into plaintext the moment a service requiring them is started\&. Moreover, credentials may be bound to the local hardware and installations, so that they cannot easily be analyzed offline, or be generated externally\&. When +\fIDevicePolicy=\fR +is set to +"closed" +or +"strict", or set to +"auto" +and +\fIDeviceAllow=\fR +is set, or +\fIPrivateDevices=\fR +is set, then this setting adds +/dev/tpmrm0 +with +\fBrw\fR +mode to +\fIDeviceAllow=\fR\&. See +\fBsystemd.resource-control\fR(5) +for the details about +\fIDevicePolicy=\fR +or +\fIDeviceAllow=\fR\&. +.sp +The credential files/IPC sockets must be accessible to the service manager, but don\*(Aqt have to be directly accessible to the unit\*(Aqs processes: the credential data is read and copied into separate, read\-only copies for the unit that are accessible to appropriately privileged processes\&. This is particularly useful in combination with +\fIDynamicUser=\fR +as this way privileged data can be made available to processes running under a dynamic UID (i\&.e\&. not a previously known one) without having to open up access to all users\&. +.sp +In order to reference the path a credential may be read from within a +\fIExecStart=\fR +command line use +"${CREDENTIALS_DIRECTORY}/mycred", e\&.g\&. +"ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred"\&. In order to reference the path a credential may be read from within a +\fIEnvironment=\fR +line use +"%d/mycred", e\&.g\&. +"Environment=MYCREDPATH=%d/mycred"\&. For system services the path may also be referenced as +"/run/credentials/\fIUNITNAME\fR" +in cases where no interpolation is possible, e\&.g\&. configuration files of software that does not yet support credentials natively\&. +\fI$CREDENTIALS_DIRECTORY\fR +is considered the primary interface to look for credentials, though, since it also works for user services\&. +.sp +Currently, an accumulated credential size limit of 1 MB per unit is enforced\&. +.sp +The service manager itself may receive system credentials that can be propagated to services from a hosting container manager or VM hypervisor\&. See the +\m[blue]\fBContainer Interface\fR\m[]\&\s-2\u[15]\d\s+2 +documentation for details about the former\&. For the latter, pass +\m[blue]\fBDMI/SMBIOS\fR\m[]\&\s-2\u[16]\d\s+2 +OEM string table entries (field type 11) with a prefix of +"io\&.systemd\&.credential:" +or +"io\&.systemd\&.credential\&.binary:"\&. In both cases a key/value pair separated by +"=" +is expected, in the latter case the right\-hand side is Base64 decoded when parsed (thus permitting binary data to be passed in)\&. Example +\m[blue]\fBqemu\fR\m[]\&\s-2\u[17]\d\s+2 +switch: +"\-smbios type=11,value=io\&.systemd\&.credential:xx=yy", or +"\-smbios type=11,value=io\&.systemd\&.credential\&.binary:rick=TmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXA="\&. Alternatively, use the +\fBqemu\fR +"fw_cfg" +node +"opt/io\&.systemd\&.credentials/"\&. Example +\fBqemu\fR +switch: +"\-fw_cfg name=opt/io\&.systemd\&.credentials/mycred,string=supersecret"\&. They may also be passed from the UEFI firmware environment via +\fBsystemd-stub\fR(7), from the initrd (see +\fBsystemd\fR(1)), or be specified on the kernel command line using the +"systemd\&.set_credential=" +and +"systemd\&.set_credential_binary=" +switches (see +\fBsystemd\fR(1) +\(en this is not recommended since unprivileged userspace can read the kernel command line)\&. +.sp +If referencing an +\fBAF_UNIX\fR +stream socket to connect to, the connection will originate from an abstract namespace socket, that includes information about the unit and the credential ID in its socket name\&. Use +\fBgetpeername\fR(2) +to query this information\&. The returned socket name is formatted as +\fBNUL\fR +\fIRANDOM\fR +"/unit/" +\fIUNIT\fR +"/" +\fIID\fR, i\&.e\&. a +\fBNUL\fR +byte (as required for abstract namespace socket names), followed by a random string (consisting of alphadecimal characters), followed by the literal string +"/unit/", followed by the requesting unit name, followed by the literal character +"/", followed by the textual credential ID requested\&. Example: +"\e0adf9d86b6eda275e/unit/foobar\&.service/credx" +in case the credential +"credx" +is requested for a unit +"foobar\&.service"\&. This functionality is useful for using a single listening socket to serve credentials to multiple consumers\&. +.sp +For further information see +\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[18]\d\s+2 +documentation\&. +.sp +Added in version 247\&. +.RE +.PP +\fIImportCredential=\fR\fIGLOB\fR +.RS 4 +Pass one or more credentials to the unit\&. Takes a credential name for which we\*(Aqll attempt to find a credential that the service manager itself received under the specified name \(em which may be used to propagate credentials from an invoking environment (e\&.g\&. a container manager that invoked the service manager) into a service\&. If the credential name is a glob, all credentials matching the glob are passed to the unit\&. Matching credentials are searched for in the system credentials, the encrypted system credentials, and under +/etc/credstore/, +/run/credstore/, +/usr/lib/credstore/, +/run/credstore\&.encrypted/, +/etc/credstore\&.encrypted/, and +/usr/lib/credstore\&.encrypted/ +in that order\&. When multiple credentials of the same name are found, the first one found is used\&. +.sp +The globbing expression implements a restrictive subset of +\fBglob\fR(7): only a single trailing +"*" +wildcard may be specified\&. Both +"?" +and +"[]" +wildcards are not permitted, nor are +"*" +wildcards anywhere except at the end of the glob expression\&. +.sp +When multiple credentials of the same name are found, credentials found by +\fILoadCredential=\fR +and +\fILoadCredentialEncrypted=\fR +take priority over credentials found by +\fIImportCredential=\fR\&. +.sp +Added in version 254\&. +.RE +.PP +\fISetCredential=\fR\fIID\fR:\fIVALUE\fR, \fISetCredentialEncrypted=\fR\fIID\fR:\fIVALUE\fR +.RS 4 +The +\fISetCredential=\fR +setting is similar to +\fILoadCredential=\fR +but accepts a literal value to use as data for the credential, instead of a file system path to read the data from\&. Do not use this option for data that is supposed to be secret, as it is accessible to unprivileged processes via IPC\&. It\*(Aqs only safe to use this for user IDs, public key material and similar non\-sensitive data\&. For everything else use +\fILoadCredential=\fR\&. In order to embed binary data into the credential data use C\-style escaping (i\&.e\&. +"\en" +to embed a newline, or +"\ex00" +to embed a +\fBNUL\fR +byte)\&. +.sp +The +\fISetCredentialEncrypted=\fR +setting is identical to +\fISetCredential=\fR +but expects an encrypted credential in literal form as value\&. This allows embedding confidential credentials securely directly in unit files\&. Use +\fBsystemd-creds\fR(1)\*(Aq +\fB\-p\fR +switch to generate suitable +\fISetCredentialEncrypted=\fR +lines directly from plaintext credentials\&. For further details see +\fILoadCredentialEncrypted=\fR +above\&. +.sp +When multiple credentials of the same name are found, credentials found by +\fILoadCredential=\fR, +\fILoadCredentialEncrypted=\fR +and +\fIImportCredential=\fR +take priority over credentials found by +\fISetCredential=\fR\&. As such, +\fISetCredential=\fR +will act as default if no credentials are found by any of the former\&. In this case not being able to retrieve the credential from the path specified in +\fILoadCredential=\fR +or +\fILoadCredentialEncrypted=\fR +is not considered fatal\&. +.sp +Added in version 247\&. +.RE +.SH "SYSTEM V COMPATIBILITY" +.PP +\fIUtmpIdentifier=\fR +.RS 4 +Takes a four character identifier string for an +\fButmp\fR(5) +and wtmp entry for this service\&. This should only be set for services such as +\fBgetty\fR +implementations (such as +\fBagetty\fR(8)) where utmp/wtmp entries must be created and cleared before and after execution, or for services that shall be executed as if they were run by a +\fBgetty\fR +process (see below)\&. If the configured string is longer than four characters, it is truncated and the terminal four characters are used\&. This setting interprets %I style string replacements\&. This setting is unset by default, i\&.e\&. no utmp/wtmp entries are created or cleaned up for this service\&. +.RE +.PP +\fIUtmpMode=\fR +.RS 4 +Takes one of +"init", +"login" +or +"user"\&. If +\fIUtmpIdentifier=\fR +is set, controls which type of +\fButmp\fR(5)/wtmp entries for this service are generated\&. This setting has no effect unless +\fIUtmpIdentifier=\fR +is set too\&. If +"init" +is set, only an +\fBINIT_PROCESS\fR +entry is generated and the invoked process must implement a +\fBgetty\fR\-compatible utmp/wtmp logic\&. If +"login" +is set, first an +\fBINIT_PROCESS\fR +entry, followed by a +\fBLOGIN_PROCESS\fR +entry is generated\&. In this case, the invoked process must implement a +\fBlogin\fR(1)\-compatible utmp/wtmp logic\&. If +"user" +is set, first an +\fBINIT_PROCESS\fR +entry, then a +\fBLOGIN_PROCESS\fR +entry and finally a +\fBUSER_PROCESS\fR +entry is generated\&. In this case, the invoked process may be any process that is suitable to be run as session leader\&. Defaults to +"init"\&. +.sp +Added in version 225\&. +.RE +.SH "ENVIRONMENT VARIABLES IN SPAWNED PROCESSES" +.PP +Processes started by the service manager are executed with an environment variable block assembled from multiple sources\&. Processes started by the system service manager generally do not inherit environment variables set for the service manager itself (but this may be altered via +\fIPassEnvironment=\fR), but processes started by the user service manager instances generally do inherit all environment variables set for the service manager itself\&. +.PP +For each invoked process the list of environment variables set is compiled from the following sources: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Variables globally configured for the service manager, using the +\fIDefaultEnvironment=\fR +setting in +\fBsystemd-system.conf\fR(5), the kernel command line option +\fIsystemd\&.setenv=\fR +understood by +\fBsystemd\fR(1), or via +\fBsystemctl\fR(1) +\fBset\-environment\fR +verb\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Variables defined by the service manager itself (see the list below)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Variables set in the service manager\*(Aqs own environment variable block (subject to +\fIPassEnvironment=\fR +for the system service manager)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Variables set via +\fIEnvironment=\fR +in the unit file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Variables read from files specified via +\fIEnvironmentFile=\fR +in the unit file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Variables set by any PAM modules in case +\fIPAMName=\fR +is in effect, cf\&.\ \&\fBpam_env\fR(8)\&. +.RE +.PP +If the same environment variable is set by multiple of these sources, the later source \(em according to the order of the list above \(em wins\&. Note that as the final step all variables listed in +\fIUnsetEnvironment=\fR +are removed from the compiled environment variable list, immediately before it is passed to the executed process\&. +.PP +The general philosophy is to expose a small curated list of environment variables to processes\&. Services started by the system manager (PID 1) will be started, without additional service\-specific configuration, with just a few environment variables\&. The user manager inherits environment variables as any other system service, but in addition may receive additional environment variables from PAM, and, typically, additional imported variables when the user starts a graphical session\&. It is recommended to keep the environment blocks in both the system and user managers lean\&. Importing all variables inherited by the graphical session or by one of the user shells is strongly discouraged\&. +.PP +Hint: +\fBsystemd\-run \-P env\fR +and +\fBsystemd\-run \-\-user \-P env\fR +print the effective system and user service environment blocks\&. +.SS "Environment Variables Set or Propagated by the Service Manager" +.PP +The following environment variables are propagated by the service manager or generated internally for each invoked process: +.PP +\fI$PATH\fR +.RS 4 +Colon\-separated list of directories to use when launching executables\&. +\fBsystemd\fR +uses a fixed value of +"/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" +in the system manager\&. In case of the user manager, a different path may be configured by the distribution\&. It is recommended to not rely on the order of entries, and have only one program with a given name in +\fI$PATH\fR\&. +.sp +Added in version 208\&. +.RE +.PP +\fI$LANG\fR +.RS 4 +Locale\&. Can be set in +\fBlocale.conf\fR(5) +or on the kernel command line (see +\fBsystemd\fR(1) +and +\fBkernel-command-line\fR(7))\&. +.sp +Added in version 208\&. +.RE +.PP +\fI$USER\fR, \fI$LOGNAME\fR, \fI$HOME\fR, \fI$SHELL\fR +.RS 4 +User name (twice), home directory, and the login shell\&. +\fI$USER\fR +is set unconditionally, while +\fI$HOME\fR, +\fI$LOGNAME\fR, and +\fI$SHELL\fR +are only set for the units that have +\fIUser=\fR +set and +\fISetLoginEnvironment=\fR +unset or set to true\&. For user services, these variables are typically inherited from the user manager itself\&. See +\fBpasswd\fR(5)\&. +.sp +Added in version 208\&. +.RE +.PP +\fI$INVOCATION_ID\fR +.RS 4 +Contains a randomized, unique 128\-bit ID identifying each runtime cycle of the unit, formatted as 32 character hexadecimal string\&. A new ID is assigned each time the unit changes from an inactive state into an activating or active state, and may be used to identify this specific runtime cycle, in particular in data stored offline, such as the journal\&. The same ID is passed to all processes run as part of the unit\&. +.sp +Added in version 232\&. +.RE +.PP +\fI$XDG_RUNTIME_DIR\fR +.RS 4 +The directory to use for runtime objects (such as IPC objects) and volatile state\&. Set for all services run by the user +\fBsystemd\fR +instance, as well as any system services that use +\fIPAMName=\fR +with a PAM stack that includes +\fBpam_systemd\fR\&. See below and +\fBpam_systemd\fR(8) +for more information\&. +.sp +Added in version 208\&. +.RE +.PP +\fI$RUNTIME_DIRECTORY\fR, \fI$STATE_DIRECTORY\fR, \fI$CACHE_DIRECTORY\fR, \fI$LOGS_DIRECTORY\fR, \fI$CONFIGURATION_DIRECTORY\fR +.RS 4 +Absolute paths to the directories defined with +\fIRuntimeDirectory=\fR, +\fIStateDirectory=\fR, +\fICacheDirectory=\fR, +\fILogsDirectory=\fR, and +\fIConfigurationDirectory=\fR +when those settings are used\&. +.sp +Added in version 244\&. +.RE +.PP +\fI$CREDENTIALS_DIRECTORY\fR +.RS 4 +An absolute path to the per\-unit directory with credentials configured via +\fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR\&. The directory is marked read\-only and is placed in unswappable memory (if supported and permitted), and is only accessible to the UID associated with the unit via +\fIUser=\fR +or +\fIDynamicUser=\fR +(and the superuser)\&. +.sp +Added in version 247\&. +.RE +.PP +\fI$MAINPID\fR +.RS 4 +The PID of the unit\*(Aqs main process if it is known\&. This is only set for control processes as invoked by +\fIExecReload=\fR +and similar\&. +.sp +Added in version 209\&. +.RE +.PP +\fI$MANAGERPID\fR +.RS 4 +The PID of the user +\fBsystemd\fR +instance, set for processes spawned by it\&. +.sp +Added in version 208\&. +.RE +.PP +\fI$LISTEN_FDS\fR, \fI$LISTEN_PID\fR, \fI$LISTEN_FDNAMES\fR +.RS 4 +Information about file descriptors passed to a service for socket activation\&. See +\fBsd_listen_fds\fR(3)\&. +.sp +Added in version 208\&. +.RE +.PP +\fI$NOTIFY_SOCKET\fR +.RS 4 +The socket +\fBsd_notify()\fR +talks to\&. See +\fBsd_notify\fR(3)\&. +.sp +Added in version 229\&. +.RE +.PP +\fI$WATCHDOG_PID\fR, \fI$WATCHDOG_USEC\fR +.RS 4 +Information about watchdog keep\-alive notifications\&. See +\fBsd_watchdog_enabled\fR(3)\&. +.sp +Added in version 229\&. +.RE +.PP +\fI$SYSTEMD_EXEC_PID\fR +.RS 4 +The PID of the unit process (e\&.g\&. process invoked by +\fIExecStart=\fR)\&. The child process can use this information to determine whether the process is directly invoked by the service manager or indirectly as a child of another process by comparing this value with the current PID (similarly to the scheme used in +\fBsd_listen_fds\fR(3) +with +\fI$LISTEN_PID\fR +and +\fI$LISTEN_FDS\fR)\&. +.sp +Added in version 248\&. +.RE +.PP +\fI$TERM\fR +.RS 4 +Terminal type, set only for units connected to a terminal (\fIStandardInput=tty\fR, +\fIStandardOutput=tty\fR, or +\fIStandardError=tty\fR)\&. See +\fBtermcap\fR(5)\&. +.sp +Added in version 209\&. +.RE +.PP +\fI$LOG_NAMESPACE\fR +.RS 4 +Contains the name of the selected logging namespace when the +\fILogNamespace=\fR +service setting is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fI$JOURNAL_STREAM\fR +.RS 4 +If the standard output or standard error output of the executed processes are connected to the journal (for example, by setting +\fIStandardError=journal\fR) +\fI$JOURNAL_STREAM\fR +contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a colon (":")\&. This permits invoked processes to safely detect whether their standard output or standard error output are connected to the journal\&. The device and inode numbers of the file descriptors should be compared with the values set in the environment variable to determine whether the process output is still connected to the journal\&. Note that it is generally not sufficient to only check whether +\fI$JOURNAL_STREAM\fR +is set at all as services might invoke external processes replacing their standard output or standard error output, without unsetting the environment variable\&. +.sp +If both standard output and standard error of the executed processes are connected to the journal via a stream socket, this environment variable will contain information about the standard error stream, as that\*(Aqs usually the preferred destination for log data\&. (Note that typically the same stream is used for both standard output and standard error, hence very likely the environment variable contains device and inode information matching both stream file descriptors\&.) +.sp +This environment variable is primarily useful to allow services to optionally upgrade their used log protocol to the native journal protocol (using +\fBsd_journal_print\fR(3) +and other functions) if their standard output or standard error output is connected to the journal anyway, thus enabling delivery of structured metadata along with logged messages\&. +.sp +Added in version 231\&. +.RE +.PP +\fI$SERVICE_RESULT\fR +.RS 4 +Only used for the service unit type\&. This environment variable is passed to all +\fIExecStop=\fR +and +\fIExecStopPost=\fR +processes, and encodes the service "result"\&. Currently, the following values are defined: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&5.\ \&Defined \fI$SERVICE_RESULT\fR values +.TS +allbox tab(:); +lB lB. +T{ +Value +T}:T{ +Meaning +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +"success" +T}:T{ +The service ran successfully and exited cleanly\&. +T} +T{ +"protocol" +T}:T{ +A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its \fIType=\fR setting)\&. +T} +T{ +"timeout" +T}:T{ +One of the steps timed out\&. +T} +T{ +"exit\-code" +T}:T{ +Service process exited with a non\-zero exit code; see \fI$EXIT_CODE\fR below for the actual exit code returned\&. +T} +T{ +"signal" +T}:T{ +A service process was terminated abnormally by a signal, without dumping core\&. See \fI$EXIT_CODE\fR below for the actual signal causing the termination\&. +T} +T{ +"core\-dump" +T}:T{ +A service process terminated abnormally with a signal and dumped core\&. See \fI$EXIT_CODE\fR below for the signal causing the termination\&. +T} +T{ +"watchdog" +T}:T{ +Watchdog keep\-alive ping was enabled for the service, but the deadline was missed\&. +T} +T{ +"exec\-condition" +T}:T{ +Service did not run because \fIExecCondition=\fR failed\&. +T} +T{ +"oom\-kill" +T}:T{ +A service process was terminated by the Out\-Of\-Memory (OOM) killer\&. +T} +T{ +"start\-limit\-hit" +T}:T{ +A start limit was defined for the unit and it was hit, causing the unit to fail to start\&. See \fBsystemd.unit\fR(5)\*(Aqs \fIStartLimitIntervalSec=\fR and \fIStartLimitBurst=\fR for details\&. +T} +T{ +"resources" +T}:T{ +A catch\-all condition in case a system operation failed\&. +T} +.TE +.sp 1 +This environment variable is useful to monitor failure or successful termination of a service\&. Even though this variable is available in both +\fIExecStop=\fR +and +\fIExecStopPost=\fR, it is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services that managed to start up correctly, and the latter covers both services that failed during their start\-up and those which failed during their runtime\&. +.sp +Added in version 232\&. +.RE +.PP +\fI$EXIT_CODE\fR, \fI$EXIT_STATUS\fR +.RS 4 +Only defined for the service unit type\&. These environment variables are passed to all +\fIExecStop=\fR, +\fIExecStopPost=\fR +processes and contain exit status/code information of the main process of the service\&. For the precise definition of the exit code and status, see +\fBwait\fR(2)\&. +\fI$EXIT_CODE\fR +is one of +"exited", +"killed", +"dumped"\&. +\fI$EXIT_STATUS\fR +contains the numeric exit code formatted as string if +\fI$EXIT_CODE\fR +is +"exited", and the signal name in all other cases\&. Note that these environment variables are only set if the service manager succeeded to start and identify the main process of the service\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&6.\ \&Summary of possible service result variable values +.TS +allbox tab(:); +lB lB lB. +T{ +\fI$SERVICE_RESULT\fR +T}:T{ +\fI$EXIT_CODE\fR +T}:T{ +\fI$EXIT_STATUS\fR +T} +.T& +lt lt l +^ lt l +lt lt l +^ l l +lt lt l +^ lt l +lt lt l +lt lt l +lt lt l +lt l l +^ l l +^ l l +lt l l +lt lt l +l l l +l l l +l s s. +T{ +"success" +T}:T{ +"killed" +T}:T{ +"HUP", "INT", "TERM", "PIPE" +T} +:T{ +"exited" +T}:T{ +"0" +T} +T{ +"protocol" +T}:T{ +not set +T}:T{ +not set +T} +:T{ +"exited" +T}:T{ +"0" +T} +T{ +"timeout" +T}:T{ +"killed" +T}:T{ +"TERM", "KILL" +T} +:T{ +"exited" +T}:T{ +"0", "1", "2", "3", \&..., "255" +T} +T{ +"exit\-code" +T}:T{ +"exited" +T}:T{ +"1", "2", "3", \&..., "255" +T} +T{ +"signal" +T}:T{ +"killed" +T}:T{ +"HUP", "INT", "KILL", \&... +T} +T{ +"core\-dump" +T}:T{ +"dumped" +T}:T{ +"ABRT", "SEGV", "QUIT", \&... +T} +T{ +"watchdog" +T}:T{ +"dumped" +T}:T{ +"ABRT" +T} +:T{ +"killed" +T}:T{ +"TERM", "KILL" +T} +:T{ +"exited" +T}:T{ +"0", "1", "2", "3", \&..., "255" +T} +T{ +"exec\-condition" +T}:T{ +"exited" +T}:T{ +"1", "2", "3", "4", \&..., "254" +T} +T{ +"oom\-kill" +T}:T{ +"killed" +T}:T{ +"TERM", "KILL" +T} +T{ +"start\-limit\-hit" +T}:T{ +not set +T}:T{ +not set +T} +T{ +"resources" +T}:T{ +any of the above +T}:T{ +any of the above +T} +T{ +Note: the process may be also terminated by a signal not sent by systemd\&. In particular the process may send an arbitrary signal to itself in a handler for any of the non\-maskable signals\&. Nevertheless, in the "timeout" and "watchdog" rows above only the signals that systemd sends have been included\&. Moreover, using \fISuccessExitStatus=\fR additional exit statuses may be declared to indicate clean termination, which is not reflected by this table\&. +T} +.TE +.sp 1 +Added in version 232\&. +.RE +.PP +\fI$MONITOR_SERVICE_RESULT\fR, \fI$MONITOR_EXIT_CODE\fR, \fI$MONITOR_EXIT_STATUS\fR, \fI$MONITOR_INVOCATION_ID\fR, \fI$MONITOR_UNIT\fR +.RS 4 +Only defined for the service unit type\&. Those environment variables are passed to all +\fIExecStart=\fR +and +\fIExecStartPre=\fR +processes which run in services triggered by +\fIOnFailure=\fR +or +\fIOnSuccess=\fR +dependencies\&. +.sp +Variables +\fI$MONITOR_SERVICE_RESULT\fR, +\fI$MONITOR_EXIT_CODE\fR +and +\fI$MONITOR_EXIT_STATUS\fR +take the same values as for +\fIExecStop=\fR +and +\fIExecStopPost=\fR +processes\&. Variables +\fI$MONITOR_INVOCATION_ID\fR +and +\fI$MONITOR_UNIT\fR +are set to the invocation id and unit name of the service which triggered the dependency\&. +.sp +Note that when multiple services trigger the same unit, those variables will be +\fInot\fR +be passed\&. Consider using a template handler unit for that case instead: +"OnFailure=\fIhandler\fR@%n\&.service" +for non\-templated units, or +"OnFailure=\fIhandler\fR@%p\-%i\&.service" +for templated units\&. +.sp +Added in version 251\&. +.RE +.PP +\fI$PIDFILE\fR +.RS 4 +The path to the configured PID file, in case the process is forked off on behalf of a service that uses the +\fIPIDFile=\fR +setting, see +\fBsystemd.service\fR(5) +for details\&. Service code may use this environment variable to automatically generate a PID file at the location configured in the unit file\&. This field is set to an absolute path in the file system\&. +.sp +Added in version 242\&. +.RE +.PP +\fI$REMOTE_ADDR\fR, \fI$REMOTE_PORT\fR +.RS 4 +If this is a unit started via per\-connection socket activation (i\&.e\&. via a socket unit with +\fIAccept=yes\fR), these environment variables contain the IP address and port number of the remote peer of the socket connection\&. +.sp +Added in version 254\&. +.RE +.PP +\fI$TRIGGER_UNIT\fR, \fI$TRIGGER_PATH\fR, \fI$TRIGGER_TIMER_REALTIME_USEC\fR, \fI$TRIGGER_TIMER_MONOTONIC_USEC\fR +.RS 4 +If the unit was activated dynamically (e\&.g\&.: a corresponding path unit or timer unit), the unit that triggered it and other type\-dependent information will be passed via these variables\&. Note that this information is provided in a best\-effort way\&. For example, multiple triggers happening one after another will be coalesced and only one will be reported, with no guarantee as to which one it will be\&. Because of this, in most cases this variable will be primarily informational, i\&.e\&. useful for debugging purposes, is lossy, and should not be relied upon to propagate a comprehensive reason for activation\&. +.sp +Added in version 252\&. +.RE +.PP +\fI$MEMORY_PRESSURE_WATCH\fR, \fI$MEMORY_PRESSURE_WRITE\fR +.RS 4 +If memory pressure monitoring is enabled for this service unit, the path to watch and the data to write into it\&. See +\m[blue]\fBMemory Pressure Handling\fR\m[]\&\s-2\u[19]\d\s+2 +for details about these variables and the service protocol data they convey\&. +.sp +Added in version 254\&. +.RE +.PP +\fI$FDSTORE\fR +.RS 4 +The maximum number of file descriptors that may be stored in the manager for the service\&. This variable is set when the file descriptor store is enabled for the service, i\&.e\&. +\fIFileDescriptorStoreMax=\fR +is set to a non\-zero value (see +\fBsystemd.service\fR(5) +for details)\&. Applications may check this environment variable before sending file descriptors to the service manager via +\fBsd_pid_notify_with_fds\fR(3)\&. +.sp +Added in version 254\&. +.RE +.PP +For system services, when +\fIPAMName=\fR +is enabled and +\fBpam_systemd\fR +is part of the selected PAM stack, additional environment variables defined by systemd may be set for services\&. Specifically, these are +\fI$XDG_SEAT\fR, +\fI$XDG_VTNR\fR, see +\fBpam_systemd\fR(8) +for details\&. +.SH "PROCESS EXIT CODES" +.PP +When invoking a unit process the service manager possibly fails to apply the execution parameters configured with the settings above\&. In that case the already created service process will exit with a non\-zero exit code before the configured command line is executed\&. (Or in other words, the child process possibly exits with these error codes, after having been created by the +\fBfork\fR(2) +system call, but before the matching +\fBexecve\fR(2) +system call is called\&.) Specifically, exit codes defined by the C library, by the LSB specification and by the systemd service manager itself are used\&. +.PP +The following basic service exit codes are defined by the C library\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&7.\ \&Basic C library exit codes +.TS +allbox tab(:); +lB lB lB. +T{ +Exit Code +T}:T{ +Symbolic Name +T}:T{ +Description +T} +.T& +l l l +l l l. +T{ +0 +T}:T{ +\fBEXIT_SUCCESS\fR +T}:T{ +Generic success code\&. +T} +T{ +1 +T}:T{ +\fBEXIT_FAILURE\fR +T}:T{ +Generic failure or unspecified error\&. +T} +.TE +.sp 1 +.PP +The following service exit codes are defined by the +\m[blue]\fBLSB specification\fR\m[]\&\s-2\u[20]\d\s+2\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&8.\ \&LSB service exit codes +.TS +allbox tab(:); +lB lB lB. +T{ +Exit Code +T}:T{ +Symbolic Name +T}:T{ +Description +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +2 +T}:T{ +\fBEXIT_INVALIDARGUMENT\fR +T}:T{ +Invalid or excess arguments\&. +T} +T{ +3 +T}:T{ +\fBEXIT_NOTIMPLEMENTED\fR +T}:T{ +Unimplemented feature\&. +T} +T{ +4 +T}:T{ +\fBEXIT_NOPERMISSION\fR +T}:T{ +The user has insufficient privileges\&. +T} +T{ +5 +T}:T{ +\fBEXIT_NOTINSTALLED\fR +T}:T{ +The program is not installed\&. +T} +T{ +6 +T}:T{ +\fBEXIT_NOTCONFIGURED\fR +T}:T{ +The program is not configured\&. +T} +T{ +7 +T}:T{ +\fBEXIT_NOTRUNNING\fR +T}:T{ +The program is not running\&. +T} +.TE +.sp 1 +.PP +The LSB specification suggests that error codes 200 and above are reserved for implementations\&. Some of them are used by the service manager to indicate problems during process invocation: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&9.\ \&systemd\-specific exit codes +.TS +allbox tab(:); +lB lB lB. +T{ +Exit Code +T}:T{ +Symbolic Name +T}:T{ +Description +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +200 +T}:T{ +\fBEXIT_CHDIR\fR +T}:T{ +Changing to the requested working directory failed\&. See \fIWorkingDirectory=\fR above\&. +T} +T{ +201 +T}:T{ +\fBEXIT_NICE\fR +T}:T{ +Failed to set up process scheduling priority (nice level)\&. See \fINice=\fR above\&. +T} +T{ +202 +T}:T{ +\fBEXIT_FDS\fR +T}:T{ +Failed to close unwanted file descriptors, or to adjust passed file descriptors\&. +T} +T{ +203 +T}:T{ +\fBEXIT_EXEC\fR +T}:T{ +The actual process execution failed (specifically, the \fBexecve\fR(2) system call)\&. Most likely this is caused by a missing or non\-accessible executable file\&. +T} +T{ +204 +T}:T{ +\fBEXIT_MEMORY\fR +T}:T{ +Failed to perform an action due to memory shortage\&. +T} +T{ +205 +T}:T{ +\fBEXIT_LIMITS\fR +T}:T{ +Failed to adjust resource limits\&. See \fILimitCPU=\fR and related settings above\&. +T} +T{ +206 +T}:T{ +\fBEXIT_OOM_ADJUST\fR +T}:T{ +Failed to adjust the OOM setting\&. See \fIOOMScoreAdjust=\fR above\&. +T} +T{ +207 +T}:T{ +\fBEXIT_SIGNAL_MASK\fR +T}:T{ +Failed to set process signal mask\&. +T} +T{ +208 +T}:T{ +\fBEXIT_STDIN\fR +T}:T{ +Failed to set up standard input\&. See \fIStandardInput=\fR above\&. +T} +T{ +209 +T}:T{ +\fBEXIT_STDOUT\fR +T}:T{ +Failed to set up standard output\&. See \fIStandardOutput=\fR above\&. +T} +T{ +210 +T}:T{ +\fBEXIT_CHROOT\fR +T}:T{ +Failed to change root directory (\fBchroot\fR(2))\&. See \fIRootDirectory=\fR/\fIRootImage=\fR above\&. +T} +T{ +211 +T}:T{ +\fBEXIT_IOPRIO\fR +T}:T{ +Failed to set up IO scheduling priority\&. See \fIIOSchedulingClass=\fR/\fIIOSchedulingPriority=\fR above\&. +T} +T{ +212 +T}:T{ +\fBEXIT_TIMERSLACK\fR +T}:T{ +Failed to set up timer slack\&. See \fITimerSlackNSec=\fR above\&. +T} +T{ +213 +T}:T{ +\fBEXIT_SECUREBITS\fR +T}:T{ +Failed to set process secure bits\&. See \fISecureBits=\fR above\&. +T} +T{ +214 +T}:T{ +\fBEXIT_SETSCHEDULER\fR +T}:T{ +Failed to set up CPU scheduling\&. See \fICPUSchedulingPolicy=\fR/\fICPUSchedulingPriority=\fR above\&. +T} +T{ +215 +T}:T{ +\fBEXIT_CPUAFFINITY\fR +T}:T{ +Failed to set up CPU affinity\&. See \fICPUAffinity=\fR above\&. +T} +T{ +216 +T}:T{ +\fBEXIT_GROUP\fR +T}:T{ +Failed to determine or change group credentials\&. See \fIGroup=\fR/\fISupplementaryGroups=\fR above\&. +T} +T{ +217 +T}:T{ +\fBEXIT_USER\fR +T}:T{ +Failed to determine or change user credentials, or to set up user namespacing\&. See \fIUser=\fR/\fIPrivateUsers=\fR above\&. +T} +T{ +218 +T}:T{ +\fBEXIT_CAPABILITIES\fR +T}:T{ +Failed to drop capabilities, or apply ambient capabilities\&. See \fICapabilityBoundingSet=\fR/\fIAmbientCapabilities=\fR above\&. +T} +T{ +219 +T}:T{ +\fBEXIT_CGROUP\fR +T}:T{ +Setting up the service control group failed\&. +T} +T{ +220 +T}:T{ +\fBEXIT_SETSID\fR +T}:T{ +Failed to create new process session\&. +T} +T{ +221 +T}:T{ +\fBEXIT_CONFIRM\fR +T}:T{ +Execution has been cancelled by the user\&. See the \fIsystemd\&.confirm_spawn=\fR kernel command line setting on \fBkernel-command-line\fR(7) for details\&. +T} +T{ +222 +T}:T{ +\fBEXIT_STDERR\fR +T}:T{ +Failed to set up standard error output\&. See \fIStandardError=\fR above\&. +T} +T{ +224 +T}:T{ +\fBEXIT_PAM\fR +T}:T{ +Failed to set up PAM session\&. See \fIPAMName=\fR above\&. +T} +T{ +225 +T}:T{ +\fBEXIT_NETWORK\fR +T}:T{ +Failed to set up network namespacing\&. See \fIPrivateNetwork=\fR above\&. +T} +T{ +226 +T}:T{ +\fBEXIT_NAMESPACE\fR +T}:T{ +Failed to set up mount, UTS, or IPC namespacing\&. See \fIReadOnlyPaths=\fR, \fIProtectHostname=\fR, \fIPrivateIPC=\fR, and related settings above\&. +T} +T{ +227 +T}:T{ +\fBEXIT_NO_NEW_PRIVILEGES\fR +T}:T{ +Failed to disable new privileges\&. See \fINoNewPrivileges=yes\fR above\&. +T} +T{ +228 +T}:T{ +\fBEXIT_SECCOMP\fR +T}:T{ +Failed to apply system call filters\&. See \fISystemCallFilter=\fR and related settings above\&. +T} +T{ +229 +T}:T{ +\fBEXIT_SELINUX_CONTEXT\fR +T}:T{ +Determining or changing SELinux context failed\&. See \fISELinuxContext=\fR above\&. +T} +T{ +230 +T}:T{ +\fBEXIT_PERSONALITY\fR +T}:T{ +Failed to set up an execution domain (personality)\&. See \fIPersonality=\fR above\&. +T} +T{ +231 +T}:T{ +\fBEXIT_APPARMOR_PROFILE\fR +T}:T{ +Failed to prepare changing AppArmor profile\&. See \fIAppArmorProfile=\fR above\&. +T} +T{ +232 +T}:T{ +\fBEXIT_ADDRESS_FAMILIES\fR +T}:T{ +Failed to restrict address families\&. See \fIRestrictAddressFamilies=\fR above\&. +T} +T{ +233 +T}:T{ +\fBEXIT_RUNTIME_DIRECTORY\fR +T}:T{ +Setting up runtime directory failed\&. See \fIRuntimeDirectory=\fR and related settings above\&. +T} +T{ +235 +T}:T{ +\fBEXIT_CHOWN\fR +T}:T{ +Failed to adjust socket ownership\&. Used for socket units only\&. +T} +T{ +236 +T}:T{ +\fBEXIT_SMACK_PROCESS_LABEL\fR +T}:T{ +Failed to set SMACK label\&. See \fISmackProcessLabel=\fR above\&. +T} +T{ +237 +T}:T{ +\fBEXIT_KEYRING\fR +T}:T{ +Failed to set up kernel keyring\&. +T} +T{ +238 +T}:T{ +\fBEXIT_STATE_DIRECTORY\fR +T}:T{ +Failed to set up unit\*(Aqs state directory\&. See \fIStateDirectory=\fR above\&. +T} +T{ +239 +T}:T{ +\fBEXIT_CACHE_DIRECTORY\fR +T}:T{ +Failed to set up unit\*(Aqs cache directory\&. See \fICacheDirectory=\fR above\&. +T} +T{ +240 +T}:T{ +\fBEXIT_LOGS_DIRECTORY\fR +T}:T{ +Failed to set up unit\*(Aqs logging directory\&. See \fILogsDirectory=\fR above\&. +T} +T{ +241 +T}:T{ +\fBEXIT_CONFIGURATION_DIRECTORY\fR +T}:T{ +Failed to set up unit\*(Aqs configuration directory\&. See \fIConfigurationDirectory=\fR above\&. +T} +T{ +242 +T}:T{ +\fBEXIT_NUMA_POLICY\fR +T}:T{ +Failed to set up unit\*(Aqs NUMA memory policy\&. See \fINUMAPolicy=\fR and \fINUMAMask=\fR above\&. +T} +T{ +243 +T}:T{ +\fBEXIT_CREDENTIALS\fR +T}:T{ +Failed to set up unit\*(Aqs credentials\&. See \fIImportCredential=\fR, \fILoadCredential=\fR and \fISetCredential=\fR above\&. +T} +T{ +245 +T}:T{ +\fBEXIT_BPF\fR +T}:T{ +Failed to apply BPF restrictions\&. See \fIRestrictFileSystems=\fR above\&. +T} +.TE +.sp 1 +.PP +Finally, the BSD operating systems define a set of exit codes, typically defined on Linux systems too: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&10.\ \&BSD exit codes +.TS +allbox tab(:); +lB lB lB. +T{ +Exit Code +T}:T{ +Symbolic Name +T}:T{ +Description +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +64 +T}:T{ +\fBEX_USAGE\fR +T}:T{ +Command line usage error +T} +T{ +65 +T}:T{ +\fBEX_DATAERR\fR +T}:T{ +Data format error +T} +T{ +66 +T}:T{ +\fBEX_NOINPUT\fR +T}:T{ +Cannot open input +T} +T{ +67 +T}:T{ +\fBEX_NOUSER\fR +T}:T{ +Addressee unknown +T} +T{ +68 +T}:T{ +\fBEX_NOHOST\fR +T}:T{ +Host name unknown +T} +T{ +69 +T}:T{ +\fBEX_UNAVAILABLE\fR +T}:T{ +Service unavailable +T} +T{ +70 +T}:T{ +\fBEX_SOFTWARE\fR +T}:T{ +internal software error +T} +T{ +71 +T}:T{ +\fBEX_OSERR\fR +T}:T{ +System error (e\&.g\&., can\*(Aqt fork) +T} +T{ +72 +T}:T{ +\fBEX_OSFILE\fR +T}:T{ +Critical OS file missing +T} +T{ +73 +T}:T{ +\fBEX_CANTCREAT\fR +T}:T{ +Can\*(Aqt create (user) output file +T} +T{ +74 +T}:T{ +\fBEX_IOERR\fR +T}:T{ +Input/output error +T} +T{ +75 +T}:T{ +\fBEX_TEMPFAIL\fR +T}:T{ +Temporary failure; user is invited to retry +T} +T{ +76 +T}:T{ +\fBEX_PROTOCOL\fR +T}:T{ +Remote error in protocol +T} +T{ +77 +T}:T{ +\fBEX_NOPERM\fR +T}:T{ +Permission denied +T} +T{ +78 +T}:T{ +\fBEX_CONFIG\fR +T}:T{ +Configuration error +T} +.TE +.sp 1 +.SH "EXAMPLES" +.PP +\fBExample\ \&3.\ \&\fI$MONITOR_\fR\fI\fI*\fR\fR usage\fR +.PP +A service +myfailer\&.service +which can trigger an +\fIOnFailure=\fR +dependency\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Service which can trigger an OnFailure= dependency +OnFailure=myhandler\&.service + +[Service] +ExecStart=/bin/myprogram + +.fi +.if n \{\ +.RE +.\} +.PP +A service +mysuccess\&.service +which can trigger an +\fIOnSuccess=\fR +dependency\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Service which can trigger an OnSuccess= dependency +OnSuccess=myhandler\&.service + +[Service] +ExecStart=/bin/mysecondprogram + +.fi +.if n \{\ +.RE +.\} +.PP +A service +myhandler\&.service +which can be triggered by any of the above services\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Acts on service failing or succeeding + +[Service] +ExecStart=/bin/bash \-c "echo $MONITOR_SERVICE_RESULT $MONITOR_EXIT_CODE $MONITOR_EXIT_STATUS $MONITOR_INVOCATION_ID $MONITOR_UNIT" + +.fi +.if n \{\ +.RE +.\} +.PP +If +myfailer\&.service +were to run and exit in failure, then +myhandler\&.service +would be triggered and the monitor variables would be set as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +MONITOR_SERVICE_RESULT=exit\-code +MONITOR_EXIT_CODE=exited +MONITOR_EXIT_STATUS=1 +MONITOR_INVOCATION_ID=cc8fdc149b2b4ca698d4f259f4054236 +MONITOR_UNIT=myfailer\&.service + +.fi +.if n \{\ +.RE +.\} +.PP +If +mysuccess\&.service +were to run and exit in success, then +myhandler\&.service +would be triggered and the monitor variables would be set as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +MONITOR_SERVICE_RESULT=success +MONITOR_EXIT_CODE=exited +MONITOR_EXIT_STATUS=0 +MONITOR_INVOCATION_ID=6ab9af147b8c4a3ebe36e7a5f8611697 +MONITOR_UNIT=mysuccess\&.service + +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-analyze\fR(1), +\fBjournalctl\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.unit\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.swap\fR(5), +\fBsystemd.mount\fR(5), +\fBsystemd.kill\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.time\fR(7), +\fBsystemd.directives\fR(7), +\fBtmpfiles.d\fR(5), +\fBexec\fR(3), +\fBfork\fR(2) +.SH "NOTES" +.IP " 1." 4 +Discoverable Partitions Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification +.RE +.IP " 2." 4 +The /proc Filesystem +.RS 4 +\%https://docs.kernel.org/filesystems/proc.html#mount-options +.RE +.IP " 3." 4 +User/Group Name Syntax +.RS 4 +\%https://systemd.io/USER_NAMES +.RE +.IP " 4." 4 +No New Privileges Flag +.RS 4 +\%https://docs.kernel.org/userspace-api/no_new_privs.html +.RE +.IP " 5." 4 +JSON User Record +.RS 4 +\%https://systemd.io/USER_RECORD +.RE +.IP " 6." 4 +The /proc Filesystem +.RS 4 +\%https://docs.kernel.org/filesystems/proc.html +.RE +.IP " 7." 4 +Kernel Samepage Merging +.RS 4 +\%https://docs.kernel.org/admin-guide/mm/ksm.html +.RE +.IP " 8." 4 +unicode scalar values +.RS 4 +\%https://www.unicode.org/glossary/#unicode_scalar_value +.RE +.IP " 9." 4 +unicode noncharacters +.RS 4 +\%https://www.unicode.org/glossary/#noncharacter +.RE +.IP "10." 4 +unicode byte order mark +.RS 4 +\%https://www.unicode.org/glossary/#byte_order_mark +.RE +.IP "11." 4 +POSIX shell unquoted text +.RS 4 +\%https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01 +.RE +.IP "12." 4 +POSIX shell single-quoted text +.RS 4 +\%https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02 +.RE +.IP "13." 4 +POSIX shell double-quoted text +.RS 4 +\%https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03 +.RE +.IP "14." 4 +Base64 +.RS 4 +\%https://tools.ietf.org/html/rfc2045#section-6.8 +.RE +.IP "15." 4 +Container Interface +.RS 4 +\%https://systemd.io/CONTAINER_INTERFACE +.RE +.IP "16." 4 +DMI/SMBIOS +.RS 4 +\%https://www.dmtf.org/standards/smbios +.RE +.IP "17." 4 +qemu +.RS 4 +\%https://www.qemu.org/docs/master/system/index.html +.RE +.IP "18." 4 +System and Service Credentials +.RS 4 +\%https://systemd.io/CREDENTIALS +.RE +.IP "19." 4 +Memory Pressure Handling +.RS 4 +\%https://systemd.io/MEMORY_PRESSURE +.RE +.IP "20." 4 +LSB specification +.RS 4 +\%https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html +.RE diff --git a/upstream/fedora-40/man5/systemd.kill.5 b/upstream/fedora-40/man5/systemd.kill.5 new file mode 100644 index 00000000..f8379e5f --- /dev/null +++ b/upstream/fedora-40/man5/systemd.kill.5 @@ -0,0 +1,225 @@ +'\" t +.TH "SYSTEMD\&.KILL" "5" "" "systemd 255" "systemd.kill" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.kill \- Process killing procedure configuration +.SH "SYNOPSIS" +.PP +\fIservice\fR\&.service, +\fIsocket\fR\&.socket, +\fImount\fR\&.mount, +\fIswap\fR\&.swap, +\fIscope\fR\&.scope +.SH "DESCRIPTION" +.PP +Unit configuration files for services, sockets, mount points, swap devices and scopes share a subset of configuration options which define the killing procedure of processes belonging to the unit\&. +.PP +This man page lists the configuration options shared by these five unit types\&. See +\fBsystemd.unit\fR(5) +for the common options shared by all unit configuration files, and +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.swap\fR(5), +\fBsystemd.mount\fR(5) +and +\fBsystemd.scope\fR(5) +for more information on the configuration file options specific to each unit type\&. +.PP +The kill procedure configuration options are configured in the [Service], [Socket], [Mount] or [Swap] section, depending on the unit type\&. +.SH "OPTIONS" +.PP +\fIKillMode=\fR +.RS 4 +Specifies how processes of this unit shall be killed\&. One of +\fBcontrol\-group\fR, +\fBmixed\fR, +\fBprocess\fR, +\fBnone\fR\&. +.sp +If set to +\fBcontrol\-group\fR, all remaining processes in the control group of this unit will be killed on unit stop (for services: after the stop command is executed, as configured with +\fIExecStop=\fR)\&. If set to +\fBmixed\fR, the +\fBSIGTERM\fR +signal (see below) is sent to the main process while the subsequent +\fBSIGKILL\fR +signal (see below) is sent to all remaining processes of the unit\*(Aqs control group\&. If set to +\fBprocess\fR, only the main process itself is killed (not recommended!)\&. If set to +\fBnone\fR, no process is killed (strongly recommended against!)\&. In this case, only the stop command will be executed on unit stop, but no process will be killed otherwise\&. Processes remaining alive after stop are left in their control group and the control group continues to exist after stop unless empty\&. +.sp +Note that it is not recommended to set +\fIKillMode=\fR +to +\fBprocess\fR +or even +\fBnone\fR, as this allows processes to escape the service manager\*(Aqs lifecycle and resource management, and to remain running even while their service is considered stopped and is assumed to not consume any resources\&. +.sp +Processes will first be terminated via +\fBSIGTERM\fR +(unless the signal to send is changed via +\fIKillSignal=\fR +or +\fIRestartKillSignal=\fR)\&. Optionally, this is immediately followed by a +\fBSIGHUP\fR +(if enabled with +\fISendSIGHUP=\fR)\&. If processes still remain after: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +the main process of a unit has exited (applies to +\fIKillMode=\fR: +\fBmixed\fR) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +the delay configured via the +\fITimeoutStopSec=\fR +has passed (applies to +\fIKillMode=\fR: +\fBcontrol\-group\fR, +\fBmixed\fR, +\fBprocess\fR) +.RE +.sp +the termination request is repeated with the +\fBSIGKILL\fR +signal or the signal specified via +\fIFinalKillSignal=\fR +(unless this is disabled via the +\fISendSIGKILL=\fR +option)\&. See +\fBkill\fR(2) +for more information\&. +.sp +Defaults to +\fBcontrol\-group\fR\&. +.sp +Added in version 187\&. +.RE +.PP +\fIKillSignal=\fR +.RS 4 +Specifies which signal to use when stopping a service\&. This controls the signal that is sent as first step of shutting down a unit (see above), and is usually followed by +\fBSIGKILL\fR +(see above and below)\&. For a list of valid signals, see +\fBsignal\fR(7)\&. Defaults to +\fBSIGTERM\fR\&. +.sp +Note that, right after sending the signal specified in this setting, systemd will always send +\fBSIGCONT\fR, to ensure that even suspended tasks can be terminated cleanly\&. +.sp +Added in version 187\&. +.RE +.PP +\fIRestartKillSignal=\fR +.RS 4 +Specifies which signal to use when restarting a service\&. The same as +\fIKillSignal=\fR +described above, with the exception that this setting is used in a restart job\&. Not set by default, and the value of +\fIKillSignal=\fR +is used\&. +.sp +Added in version 244\&. +.RE +.PP +\fISendSIGHUP=\fR +.RS 4 +Specifies whether to send +\fBSIGHUP\fR +to remaining processes immediately after sending the signal configured with +\fIKillSignal=\fR\&. This is useful to indicate to shells and shell\-like programs that their connection has been severed\&. Takes a boolean value\&. Defaults to +"no"\&. +.sp +Added in version 207\&. +.RE +.PP +\fISendSIGKILL=\fR +.RS 4 +Specifies whether to send +\fBSIGKILL\fR +(or the signal specified by +\fIFinalKillSignal=\fR) to remaining processes after a timeout, if the normal shutdown procedure left processes of the service around\&. When disabled, a +\fIKillMode=\fR +of +\fBcontrol\-group\fR +or +\fBmixed\fR +service will not restart if processes from prior services exist within the control group\&. Takes a boolean value\&. Defaults to +"yes"\&. +.sp +Added in version 187\&. +.RE +.PP +\fIFinalKillSignal=\fR +.RS 4 +Specifies which signal to send to remaining processes after a timeout if +\fISendSIGKILL=\fR +is enabled\&. The signal configured here should be one that is not typically caught and processed by services (\fBSIGTERM\fR +is not suitable)\&. Developers can find it useful to use this to generate a coredump to troubleshoot why a service did not terminate upon receiving the initial +\fBSIGTERM\fR +signal\&. This can be achieved by configuring +\fILimitCORE=\fR +and setting +\fIFinalKillSignal=\fR +to either +\fBSIGQUIT\fR +or +\fBSIGABRT\fR\&. Defaults to +\fBSIGKILL\fR\&. +.sp +Added in version 240\&. +.RE +.PP +\fIWatchdogSignal=\fR +.RS 4 +Specifies which signal to use to terminate the service when the watchdog timeout expires (enabled through +\fIWatchdogSec=\fR)\&. Defaults to +\fBSIGABRT\fR\&. +.sp +Added in version 240\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBjournalctl\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.swap\fR(5), +\fBsystemd.mount\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.directives\fR(7), +\fBkill\fR(2), +\fBsignal\fR(7) diff --git a/upstream/fedora-40/man5/systemd.link.5 b/upstream/fedora-40/man5/systemd.link.5 new file mode 100644 index 00000000..359f1911 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.link.5 @@ -0,0 +1,2045 @@ +'\" t +.TH "SYSTEMD\&.LINK" "5" "" "systemd 255" "systemd.link" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.link \- Network device configuration +.SH "SYNOPSIS" +.PP +\fIlink\fR\&.link +.SH "DESCRIPTION" +.PP +A plain ini\-style text file that encodes configuration for matching network devices, used by +\fBsystemd-udevd\fR(8) +and in particular its +\fBnet_setup_link\fR +builtin\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.PP +The +\&.link +files are read from the files located in the system network directory +/usr/lib/systemd/network +and +/usr/local/lib/systemd/network, the volatile runtime network directory +/run/systemd/network, and the local administration network directory +/etc/systemd/network\&. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. It is recommended that each filename is prefixed with a number smaller than +"70" +(e\&.g\&. +10\-eth0\&.link)\&. Otherwise, the default +\&.link +files or those generated by +\fBsystemd-network-generator.service\fR(8) +may take precedence over user configured files\&. Files in +/etc/ +have the highest priority, files in +/run/ +take precedence over files with the same name in +/usr/lib/\&. This can be used to override a system\-supplied link file with a local file if needed\&. As a special case, an empty file (file size 0) or symlink with the same name pointing to +/dev/null +disables the configuration file entirely (it is "masked")\&. +.PP +Along with the link file +foo\&.link, a "drop\-in" directory +foo\&.link\&.d/ +may exist\&. All files with the suffix +"\&.conf" +from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed\&. This is useful to alter or add configuration settings, without having to modify the main configuration file\&. Each drop\-in file must have appropriate section headers\&. +.PP +In addition to +/etc/systemd/network, drop\-in +"\&.d" +directories can be placed in +/usr/lib/systemd/network +or +/run/systemd/network +directories\&. Drop\-in files in +/etc/ +take precedence over those in +/run/ +which in turn take precedence over those in +/usr/lib/\&. Drop\-in files under any of these directories take precedence over the main link file wherever located\&. +.PP +The link file contains a [Match] section, which determines if a given link file may be applied to a given device, as well as a [Link] section specifying how the device should be configured\&. The first (in lexical order) of the link files that matches a given device is applied\&. Note that a default file +99\-default\&.link +is shipped by the system\&. Any user\-supplied +\&.link +should hence have a lexically earlier name to be considered at all\&. +.PP +See +\fBudevadm\fR(8) +for diagnosing problems with +\&.link +files\&. +.SH "[MATCH] SECTION OPTIONS" +.PP +A link file is said to match an interface if all matches specified by the [Match] section are satisfied\&. When a link file does not contain valid settings in [Match] section, then the file will match all interfaces and +\fBsystemd\-udevd\fR +warns about that\&. Hint: to avoid the warning and to make it clear that all interfaces shall be matched, add the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +OriginalName=* +.fi +.if n \{\ +.RE +.\} +.sp +The first (in alphanumeric order) of the link files that matches a given interface is applied, all later files are ignored, even if they match as well\&. The following keys are accepted: +.PP +\fIMACAddress=\fR +.RS 4 +A whitespace\-separated list of hardware addresses\&. The acceptable formats are: +.PP +\fBcolon\-delimited hexadecimal\fR +.RS 4 +Each field must be one byte\&. E\&.g\&. +"12:34:56:78:90:ab" +or +"AA:BB:CC:DD:EE:FF"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBhyphen\-delimited hexadecimal\fR +.RS 4 +Each field must be one byte\&. E\&.g\&. +"12\-34\-56\-78\-90\-ab" +or +"AA\-BB\-CC\-DD\-EE\-FF"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdot\-delimited hexadecimal\fR +.RS 4 +Each field must be two bytes\&. E\&.g\&. +"1234\&.5678\&.90ab" +or +"AABB\&.CCDD\&.EEFF"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBIPv4 address format\fR +.RS 4 +E\&.g\&. +"127\&.0\&.0\&.1" +or +"192\&.168\&.0\&.1"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBIPv6 address format\fR +.RS 4 +E\&.g\&. +"2001:0db8:85a3::8a2e:0370:7334" +or +"::1"\&. +.sp +Added in version 250\&. +.RE +.sp +The total length of each MAC address must be 4 (for IPv4 tunnel), 6 (for Ethernet), 16 (for IPv6 tunnel), or 20 (for InfiniBand)\&. This option may appear more than once, in which case the lists are merged\&. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset\&. Defaults to unset\&. +.sp +Added in version 211\&. +.RE +.PP +\fIPermanentMACAddress=\fR +.RS 4 +A whitespace\-separated list of hardware\*(Aqs permanent addresses\&. While +\fIMACAddress=\fR +matches the device\*(Aqs current MAC address, this matches the device\*(Aqs permanent MAC address, which may be different from the current one\&. Use full colon\-, hyphen\- or dot\-delimited hexadecimal, or IPv4 or IPv6 address format\&. This option may appear more than once, in which case the lists are merged\&. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPath=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the persistent path, as exposed by the udev property +\fIID_PATH\fR\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDriver=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the driver currently bound to the device, as exposed by the udev property +\fIID_NET_DRIVER\fR +of its parent device, or if that is not set, the driver as exposed by +\fBethtool \-i\fR +of the device itself\&. If the list is prefixed with a "!", the test is inverted\&. +.sp +Added in version 211\&. +.RE +.PP +\fIType=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the device type, as exposed by +\fBnetworkctl list\fR\&. If the list is prefixed with a "!", the test is inverted\&. Some valid values are +"ether", +"loopback", +"wlan", +"wwan"\&. Valid types are named either from the udev +"DEVTYPE" +attribute, or +"ARPHRD_" +macros in +linux/if_arp\&.h, so this is not comprehensive\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKind=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the device kind, as exposed by +\fBnetworkctl status \fR\fB\fIINTERFACE\fR\fR +or +\fBip \-d link show \fR\fB\fIINTERFACE\fR\fR\&. If the list is prefixed with a "!", the test is inverted\&. Some valid values are +"bond", +"bridge", +"gre", +"tun", +"veth"\&. Valid kinds are given by netlink\*(Aqs +"IFLA_INFO_KIND" +attribute, so this is not comprehensive\&. +.sp +Added in version 251\&. +.RE +.PP +\fIProperty=\fR +.RS 4 +A whitespace\-separated list of udev property names with their values after equals sign ("=")\&. If multiple properties are specified, the test results are ANDed\&. If the list is prefixed with a "!", the test is inverted\&. If a value contains white spaces, then please quote whole key and value pair\&. If a value contains quotation, then please escape the quotation with +"\e"\&. +.sp +Example: if a \&.link file has the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \e"quotation\e"" +.fi +.if n \{\ +.RE +.\} +.sp +then, the \&.link file matches only when an interface has all the above three properties\&. +.sp +Added in version 243\&. +.RE +.PP +\fIOriginalName=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the device name, as exposed by the udev property "INTERFACE"\&. This cannot be used to match on names that have already been changed from userspace\&. Caution is advised when matching on kernel\-assigned names, as they are known to be unstable between reboots\&. +.sp +Added in version 218\&. +.RE +.PP +\fIHost=\fR +.RS 4 +Matches against the hostname or machine ID of the host\&. See +\fIConditionHost=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIVirtualization=\fR +.RS 4 +Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation\&. See +\fIConditionVirtualization=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKernelCommandLine=\fR +.RS 4 +Checks whether a specific kernel command line option is set\&. See +\fIConditionKernelCommandLine=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKernelVersion=\fR +.RS 4 +Checks whether the kernel version (as reported by +\fBuname \-r\fR) matches a certain expression\&. See +\fIConditionKernelVersion=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 237\&. +.RE +.PP +\fICredential=\fR +.RS 4 +Checks whether the specified credential was passed to the +systemd\-udevd\&.service +service\&. See +\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[1]\d\s+2 +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 252\&. +.RE +.PP +\fIArchitecture=\fR +.RS 4 +Checks whether the system is running on a specific architecture\&. See +\fIConditionArchitecture=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIFirmware=\fR +.RS 4 +Checks whether the system is running on a machine with the specified firmware\&. See +\fIConditionFirmware=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 249\&. +.RE +.SH "[LINK] SECTION OPTIONS" +.PP +The [Link] section accepts the following keys: +.PP +\fIDescription=\fR +.RS 4 +A description of the device\&. +.sp +Added in version 211\&. +.RE +.PP +\fIAlias=\fR +.RS 4 +The +\fIifalias\fR +interface property is set to this value\&. +.sp +Added in version 211\&. +.RE +.PP +\fIMACAddressPolicy=\fR +.RS 4 +The policy by which the MAC address should be set\&. The available policies are: +.PP +\fBpersistent\fR +.RS 4 +If the hardware has a persistent MAC address, as most hardware should, and if it is used by the kernel, nothing is done\&. Otherwise, a new MAC address is generated which is guaranteed to be the same on every boot for the given machine and the given device, but which is otherwise random\&. This feature depends on ID_NET_NAME_* properties to exist for the link\&. On hardware where these properties are not set, the generation of a persistent MAC address will fail\&. +.sp +Added in version 211\&. +.RE +.PP +\fBrandom\fR +.RS 4 +If the kernel is using a random MAC address, nothing is done\&. Otherwise, a new address is randomly generated each time the device appears, typically at boot\&. Either way, the random address will have the +"unicast" +and +"locally administered" +bits set\&. +.sp +Added in version 211\&. +.RE +.PP +\fBnone\fR +.RS 4 +Keeps the MAC address assigned by the kernel\&. Or use the MAC address specified in +\fIMACAddress=\fR\&. +.sp +Added in version 227\&. +.RE +.sp +An empty string assignment is equivalent to setting +"none"\&. +.sp +Added in version 211\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +The interface MAC address to use\&. For this setting to take effect, +\fIMACAddressPolicy=\fR +must either be unset, empty, or +"none"\&. +.sp +Added in version 211\&. +.RE +.PP +\fINamePolicy=\fR +.RS 4 +An ordered, space\-separated list of policies by which the interface name should be set\&. +\fINamePolicy=\fR +may be disabled by specifying +\fBnet\&.ifnames=0\fR +on the kernel command line\&. Each of the policies may fail, and the first successful one is used\&. The name is not set directly, but is exported to udev as the property +\fBID_NET_NAME\fR, which is, by default, used by a +\fBudev\fR(7), rule to set +\fINAME\fR\&. The available policies are: +.PP +\fBkernel\fR +.RS 4 +If the kernel claims that the name it has set for a device is predictable, then no renaming is performed\&. +.sp +Added in version 216\&. +.RE +.PP +\fBdatabase\fR +.RS 4 +The name is set based on entries in the udev\*(Aqs Hardware Database with the key +\fIID_NET_NAME_FROM_DATABASE\fR\&. +.sp +Added in version 211\&. +.RE +.PP +\fBonboard\fR +.RS 4 +The name is set based on information given by the firmware for on\-board devices, as exported by the udev property +\fIID_NET_NAME_ONBOARD\fR\&. See +\fBsystemd.net-naming-scheme\fR(7)\&. +.sp +Added in version 211\&. +.RE +.PP +\fBslot\fR +.RS 4 +The name is set based on information given by the firmware for hot\-plug devices, as exported by the udev property +\fIID_NET_NAME_SLOT\fR\&. See +\fBsystemd.net-naming-scheme\fR(7)\&. +.sp +Added in version 211\&. +.RE +.PP +\fBpath\fR +.RS 4 +The name is set based on the device\*(Aqs physical location, as exported by the udev property +\fIID_NET_NAME_PATH\fR\&. See +\fBsystemd.net-naming-scheme\fR(7)\&. +.sp +Added in version 211\&. +.RE +.PP +\fBmac\fR +.RS 4 +The name is set based on the device\*(Aqs persistent MAC address, as exported by the udev property +\fIID_NET_NAME_MAC\fR\&. See +\fBsystemd.net-naming-scheme\fR(7)\&. +.sp +Added in version 211\&. +.RE +.PP +\fBkeep\fR +.RS 4 +If the device already had a name given by userspace (as part of creation of the device or a rename), keep it\&. +.sp +Added in version 241\&. +.RE +.sp +Added in version 211\&. +.RE +.PP +\fIName=\fR +.RS 4 +The interface name to use\&. This option has lower precedence than +\fINamePolicy=\fR, so for this setting to take effect, +\fINamePolicy=\fR +must either be unset, empty, disabled, or all policies configured there must fail\&. Also see the example below with +"Name=dmz0"\&. +.sp +Note that specifying a name that the kernel might use for another interface (for example +"eth0") is dangerous because the name assignment done by udev will race with the assignment done by the kernel, and only one interface may use the name\&. Depending on the order of operations, either udev or the kernel will win, making the naming unpredictable\&. It is best to use some different prefix, for example +"internal0"/"external0" +or +"lan0"/"lan1"/"lan3"\&. +.sp +Interface names must have a minimum length of 1 character and a maximum length of 15 characters, and may contain any 7bit ASCII character, with the exception of control characters, +":", +"/" +and +"%"\&. While +"\&." +is an allowed character, it\*(Aqs recommended to avoid it when naming interfaces as various tools (such as +\fBresolvconf\fR(1)) use it as separator character\&. Also, fully numeric interface names are not allowed (in order to avoid ambiguity with interface specification by numeric indexes), as are the special strings +"\&.", +"\&.\&.", +"all" +and +"default"\&. +.sp +Added in version 211\&. +.RE +.PP +\fIAlternativeNamesPolicy=\fR +.RS 4 +A space\-separated list of policies by which the interface\*(Aqs alternative names should be set\&. Each of the policies may fail, and all successful policies are used\&. The available policies are +"database", +"onboard", +"slot", +"path", and +"mac"\&. If the kernel does not support the alternative names, then this setting will be ignored\&. +.sp +Added in version 245\&. +.RE +.PP +\fIAlternativeName=\fR +.RS 4 +The alternative interface name to use\&. This option can be specified multiple times\&. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect\&. If the kernel does not support the alternative names, then this setting will be ignored\&. +.sp +Alternative interface names may be used to identify interfaces in various tools\&. In contrast to the primary name (as configured with +\fIName=\fR +above) there may be multiple alternative names referring to the same interface\&. Alternative names may have a maximum length of 127 characters, in contrast to the 15 allowed for the primary interface name, but otherwise are subject to the same naming constraints\&. +.sp +Added in version 245\&. +.RE +.PP +\fITransmitQueues=\fR +.RS 4 +Specifies the device\*(Aqs number of transmit queues\&. An integer in the range 1\&...4096\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 248\&. +.RE +.PP +\fIReceiveQueues=\fR +.RS 4 +Specifies the device\*(Aqs number of receive queues\&. An integer in the range 1\&...4096\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 248\&. +.RE +.PP +\fITransmitQueueLength=\fR +.RS 4 +Specifies the transmit queue length of the device in number of packets\&. An unsigned integer in the range 0\&...4294967294\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 248\&. +.RE +.PP +\fIMTUBytes=\fR +.RS 4 +The maximum transmission unit in bytes to set for the device\&. The usual suffixes K, M, G are supported and are understood to the base of 1024\&. +.sp +Added in version 211\&. +.RE +.PP +\fIBitsPerSecond=\fR +.RS 4 +The speed to set for the device, the value is rounded down to the nearest Mbps\&. The usual suffixes K, M, G are supported and are understood to the base of 1000\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDuplex=\fR +.RS 4 +The duplex mode to set for the device\&. The accepted values are +\fBhalf\fR +and +\fBfull\fR\&. +.sp +Added in version 211\&. +.RE +.PP +\fIAutoNegotiation=\fR +.RS 4 +Takes a boolean\&. If set to yes, automatic negotiation of transmission parameters is enabled\&. Autonegotiation is a procedure by which two connected ethernet devices choose common transmission parameters, such as speed, duplex mode, and flow control\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Note that if autonegotiation is enabled, speed and duplex settings are read\-only\&. If autonegotiation is disabled, speed and duplex settings are writable if the driver supports multiple link modes\&. +.sp +Added in version 233\&. +.RE +.PP +\fIWakeOnLan=\fR +.RS 4 +The Wake\-on\-LAN policy to set for the device\&. Takes the special value +"off" +which disables Wake\-on\-LAN, or space separated list of the following words: +.PP +\fBphy\fR +.RS 4 +Wake on PHY activity\&. +.sp +Added in version 211\&. +.RE +.PP +\fBunicast\fR +.RS 4 +Wake on unicast messages\&. +.sp +Added in version 235\&. +.RE +.PP +\fBmulticast\fR +.RS 4 +Wake on multicast messages\&. +.sp +Added in version 235\&. +.RE +.PP +\fBbroadcast\fR +.RS 4 +Wake on broadcast messages\&. +.sp +Added in version 235\&. +.RE +.PP +\fBarp\fR +.RS 4 +Wake on ARP\&. +.sp +Added in version 235\&. +.RE +.PP +\fBmagic\fR +.RS 4 +Wake on receipt of a magic packet\&. +.sp +Added in version 211\&. +.RE +.PP +\fBsecureon\fR +.RS 4 +Enable SecureOn password for MagicPacket\&. Implied when +\fIWakeOnLanPassword=\fR +is specified\&. If specified without +\fIWakeOnLanPassword=\fR +option, then the password is read from the credential +"\fILINK\fR\&.link\&.wol\&.password" +(e\&.g\&., +"60\-foo\&.link\&.wol\&.password"), and if the credential not found, then read from +"wol\&.password"\&. See +\fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR +in +\fBsystemd.exec\fR(5) +for details\&. The password in the credential, must be 6 bytes in hex format with each byte separated by a colon (":") like an Ethernet MAC address, e\&.g\&., +"aa:bb:cc:dd:ee:ff"\&. +.sp +Added in version 235\&. +.RE +.sp +Defaults to unset, and the device\*(Aqs default will be used\&. This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIWakeOnLanPassword=\fR +.RS 4 +Specifies the SecureOn password for MagicPacket\&. Takes an absolute path to a regular file or an +\fBAF_UNIX\fR +stream socket, or the plain password\&. When a path to a regular file is specified, the password is read from it\&. When an +\fBAF_UNIX\fR +stream socket is specified, a connection is made to it and the password is read from it\&. The password must be 6 bytes in hex format with each byte separated by a colon (":") like an Ethernet MAC address, e\&.g\&., +"aa:bb:cc:dd:ee:ff"\&. This implies +\fIWakeOnLan=secureon\fR\&. Defaults to unset, and the current value will not be changed\&. +.sp +Added in version 250\&. +.RE +.PP +\fIPort=\fR +.RS 4 +The port option is used to select the device port\&. The supported values are: +.PP +\fBtp\fR +.RS 4 +An Ethernet interface using Twisted\-Pair cable as the medium\&. +.sp +Added in version 234\&. +.RE +.PP +\fBaui\fR +.RS 4 +Attachment Unit Interface (AUI)\&. Normally used with hubs\&. +.sp +Added in version 234\&. +.RE +.PP +\fBbnc\fR +.RS 4 +An Ethernet interface using BNC connectors and co\-axial cable\&. +.sp +Added in version 234\&. +.RE +.PP +\fBmii\fR +.RS 4 +An Ethernet interface using a Media Independent Interface (MII)\&. +.sp +Added in version 234\&. +.RE +.PP +\fBfibre\fR +.RS 4 +An Ethernet interface using Optical Fibre as the medium\&. +.sp +Added in version 234\&. +.RE +.sp +Added in version 234\&. +.RE +.PP +\fIAdvertise=\fR +.RS 4 +This sets what speeds and duplex modes of operation are advertised for auto\-negotiation\&. This implies +"AutoNegotiation=yes"\&. The supported values are: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Supported advertise values +.TS +allbox tab(:); +lB lB lB. +T{ +Advertise +T}:T{ +Speed (Mbps) +T}:T{ +Duplex Mode +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +\fB10baset\-full\fR +T}:T{ +10 +T}:T{ +full +T} +T{ +\fB10baset1l\-full\fR +T}:T{ +10 +T}:T{ +full +T} +T{ +\fB10baset\-half\fR +T}:T{ +10 +T}:T{ +half +T} +T{ +\fB100basefx\-full\fR +T}:T{ +100 +T}:T{ +full +T} +T{ +\fB100baset\-full\fR +T}:T{ +100 +T}:T{ +full +T} +T{ +\fB100baset1\-full\fR +T}:T{ +100 +T}:T{ +full +T} +T{ +\fB100basefx\-half\fR +T}:T{ +100 +T}:T{ +half +T} +T{ +\fB100baset\-half\fR +T}:T{ +100 +T}:T{ +half +T} +T{ +\fB1000basekx\-full\fR +T}:T{ +1000 +T}:T{ +full +T} +T{ +\fB1000baset\-full\fR +T}:T{ +1000 +T}:T{ +full +T} +T{ +\fB1000baset1\-full\fR +T}:T{ +1000 +T}:T{ +full +T} +T{ +\fB1000basex\-full\fR +T}:T{ +1000 +T}:T{ +full +T} +T{ +\fB1000baset\-half\fR +T}:T{ +1000 +T}:T{ +half +T} +T{ +\fB2500baset\-full\fR +T}:T{ +2500 +T}:T{ +full +T} +T{ +\fB2500basex\-full\fR +T}:T{ +2500 +T}:T{ +full +T} +T{ +\fB5000baset\-full\fR +T}:T{ +5000 +T}:T{ +full +T} +T{ +\fB10000baser\-fec\fR +T}:T{ +10000 +T}:T{ +\ \& +T} +T{ +\fB10000basecr\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000baseer\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000basekr\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000basekx4\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000baselr\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000baselrm\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000basesr\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB10000baset\-full\fR +T}:T{ +10000 +T}:T{ +full +T} +T{ +\fB20000basekr2\-full\fR +T}:T{ +20000 +T}:T{ +full +T} +T{ +\fB20000basemld2\-full\fR +T}:T{ +20000 +T}:T{ +full +T} +T{ +\fB25000basecr\-full\fR +T}:T{ +25000 +T}:T{ +full +T} +T{ +\fB25000basekr\-full\fR +T}:T{ +25000 +T}:T{ +full +T} +T{ +\fB25000basesr\-full\fR +T}:T{ +25000 +T}:T{ +full +T} +T{ +\fB40000basecr4\-full\fR +T}:T{ +40000 +T}:T{ +full +T} +T{ +\fB40000basekr4\-full\fR +T}:T{ +40000 +T}:T{ +full +T} +T{ +\fB40000baselr4\-full\fR +T}:T{ +40000 +T}:T{ +full +T} +T{ +\fB40000basesr4\-full\fR +T}:T{ +40000 +T}:T{ +full +T} +T{ +\fB50000basecr\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000basecr2\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000basedr\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000basekr\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000basekr2\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000baselr\-er\-fr\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000basesr\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB50000basesr2\-full\fR +T}:T{ +50000 +T}:T{ +full +T} +T{ +\fB56000basecr4\-full\fR +T}:T{ +56000 +T}:T{ +full +T} +T{ +\fB56000basekr4\-full\fR +T}:T{ +56000 +T}:T{ +full +T} +T{ +\fB56000baselr4\-full\fR +T}:T{ +56000 +T}:T{ +full +T} +T{ +\fB56000basesr4\-full\fR +T}:T{ +56000 +T}:T{ +full +T} +T{ +\fB100000basecr\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basecr2\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basecr4\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basedr\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basedr2\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basekr\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basekr2\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basekr4\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000baselr\-er\-fr\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000baselr2\-er2\-fr2\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000baselr4\-er4\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basesr\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basesr2\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB100000basesr4\-full\fR +T}:T{ +100000 +T}:T{ +full +T} +T{ +\fB200000basecr2\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basecr4\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basedr2\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basedr4\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basekr2\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basekr4\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000baselr2\-er2\-fr2\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000baselr4\-er4\-fr4\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basesr2\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB200000basesr4\-full\fR +T}:T{ +200000 +T}:T{ +full +T} +T{ +\fB400000basecr4\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basecr8\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basedr4\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basedr8\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basekr4\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basekr8\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000baselr4\-er4\-fr4\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000baselr8\-er8\-fr8\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basesr4\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB400000basesr8\-full\fR +T}:T{ +400000 +T}:T{ +full +T} +T{ +\fB800000basecr8\-full\fR +T}:T{ +800000 +T}:T{ +full +T} +T{ +\fB800000basedr8\-2\-full\fR +T}:T{ +800000 +T}:T{ +full +T} +T{ +\fB800000basedr8\-full\fR +T}:T{ +800000 +T}:T{ +full +T} +T{ +\fB800000basekr8\-full\fR +T}:T{ +800000 +T}:T{ +full +T} +T{ +\fB800000basesr8\-full\fR +T}:T{ +800000 +T}:T{ +full +T} +T{ +\fB800000basevr8\-full\fR +T}:T{ +800000 +T}:T{ +full +T} +T{ +\fBasym\-pause\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBaui\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBautonegotiation\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBbackplane\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBbnc\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBfec\-baser\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBfec\-llrs\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBfec\-none\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBfec\-rs\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBfibre\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBmii\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBpause\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +\fBtp\fR +T}:T{ +\ \& +T}:T{ +\ \& +T} +.TE +.sp 1 +By default this is unset, i\&.e\&. all possible modes will be advertised\&. This option may be specified more than once, in which case all specified speeds and modes are advertised\&. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect\&. +.sp +Added in version 240\&. +.RE +.PP +\fIReceiveChecksumOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, hardware offload for checksumming of ingress network packets is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 245\&. +.RE +.PP +\fITransmitChecksumOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, hardware offload for checksumming of egress network packets is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 245\&. +.RE +.PP +\fITCPSegmentationOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, TCP Segmentation Offload (TSO) is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 232\&. +.RE +.PP +\fITCP6SegmentationOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, TCP6 Segmentation Offload (tx\-tcp6\-segmentation) is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 235\&. +.RE +.PP +\fIGenericSegmentationOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, Generic Segmentation Offload (GSO) is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 232\&. +.RE +.PP +\fIGenericReceiveOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, Generic Receive Offload (GRO) is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 232\&. +.RE +.PP +\fIGenericReceiveOffloadHardware=\fR +.RS 4 +Takes a boolean\&. If set to true, hardware accelerated Generic Receive Offload (GRO) is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fILargeReceiveOffload=\fR +.RS 4 +Takes a boolean\&. If set to true, Large Receive Offload (LRO) is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 232\&. +.RE +.PP +\fIReceiveVLANCTAGHardwareAcceleration=\fR +.RS 4 +Takes a boolean\&. If set to true, receive VLAN CTAG hardware acceleration is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fITransmitVLANCTAGHardwareAcceleration=\fR +.RS 4 +Takes a boolean\&. If set to true, transmit VLAN CTAG hardware acceleration is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIReceiveVLANCTAGFilter=\fR +.RS 4 +Takes a boolean\&. If set to true, receive filtering on VLAN CTAGs is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fITransmitVLANSTAGHardwareAcceleration=\fR +.RS 4 +Takes a boolean\&. If set to true, transmit VLAN STAG hardware acceleration is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fINTupleFilter=\fR +.RS 4 +Takes a boolean\&. If set to true, receive N\-tuple filters and actions are enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRxChannels=\fR, \fITxChannels=\fR, \fIOtherChannels=\fR, \fICombinedChannels=\fR +.RS 4 +Specifies the number of receive, transmit, other, or combined channels, respectively\&. Takes an unsigned integer in the range 1\&...4294967295 or +"max"\&. If set to +"max", the advertised maximum value of the hardware will be used\&. When unset, the number will not be changed\&. Defaults to unset\&. +.sp +Added in version 239\&. +.RE +.PP +\fIRxBufferSize=\fR, \fIRxMiniBufferSize=\fR, \fIRxJumboBufferSize=\fR, \fITxBufferSize=\fR +.RS 4 +Specifies the maximum number of pending packets in the NIC receive buffer, mini receive buffer, jumbo receive buffer, or transmit buffer, respectively\&. Takes an unsigned integer in the range 1\&...4294967295 or +"max"\&. If set to +"max", the advertised maximum value of the hardware will be used\&. When unset, the number will not be changed\&. Defaults to unset\&. +.sp +Added in version 244\&. +.RE +.PP +\fIRxFlowControl=\fR +.RS 4 +Takes a boolean\&. When set, enables receive flow control, also known as the ethernet receive PAUSE message (generate and send ethernet PAUSE frames)\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fITxFlowControl=\fR +.RS 4 +Takes a boolean\&. When set, enables transmit flow control, also known as the ethernet transmit PAUSE message (respond to received ethernet PAUSE frames)\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIAutoNegotiationFlowControl=\fR +.RS 4 +Takes a boolean\&. When set, auto negotiation enables the interface to exchange state advertisements with the connected peer so that the two devices can agree on the ethernet PAUSE configuration\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIGenericSegmentOffloadMaxBytes=\fR +.RS 4 +Specifies the maximum size of a Generic Segment Offload (GSO) packet the device should accept\&. The usual suffixes K, M, G are supported and are understood to the base of 1024\&. An unsigned integer in the range 1\&...65536\&. Defaults to unset\&. +.sp +Added in version 248\&. +.RE +.PP +\fIGenericSegmentOffloadMaxSegments=\fR +.RS 4 +Specifies the maximum number of Generic Segment Offload (GSO) segments the device should accept\&. An unsigned integer in the range 1\&...65535\&. Defaults to unset\&. +.sp +Added in version 248\&. +.RE +.PP +\fIUseAdaptiveRxCoalesce=\fR, \fIUseAdaptiveTxCoalesce=\fR +.RS 4 +Boolean properties that, when set, enable/disable adaptive Rx/Tx coalescing if the hardware supports it\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRxCoalesceSec=\fR, \fIRxCoalesceIrqSec=\fR, \fIRxCoalesceLowSec=\fR, \fIRxCoalesceHighSec=\fR, \fITxCoalesceSec=\fR, \fITxCoalesceIrqSec=\fR, \fITxCoalesceLowSec=\fR, \fITxCoalesceHighSec=\fR +.RS 4 +These properties configure the delay before Rx/Tx interrupts are generated after a packet is sent/received\&. The +"Irq" +properties come into effect when the host is servicing an IRQ\&. The +"Low" +and +"High" +properties come into effect when the packet rate drops below the low packet rate threshold or exceeds the high packet rate threshold respectively if adaptive Rx/Tx coalescing is enabled\&. When unset, the kernel\*(Aqs defaults will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRxMaxCoalescedFrames=\fR, \fIRxMaxCoalescedIrqFrames=\fR, \fIRxMaxCoalescedLowFrames=\fR, \fIRxMaxCoalescedHighFrames=\fR, \fITxMaxCoalescedFrames=\fR, \fITxMaxCoalescedIrqFrames=\fR, \fITxMaxCoalescedLowFrames=\fR, \fITxMaxCoalescedHighFrames=\fR +.RS 4 +These properties configure the maximum number of frames that are sent/received before a Rx/Tx interrupt is generated\&. The +"Irq" +properties come into effect when the host is servicing an IRQ\&. The +"Low" +and +"High" +properties come into effect when the packet rate drops below the low packet rate threshold or exceeds the high packet rate threshold respectively if adaptive Rx/Tx coalescing is enabled\&. When unset, the kernel\*(Aqs defaults will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fICoalescePacketRateLow=\fR, \fICoalescePacketRateHigh=\fR +.RS 4 +These properties configure the low and high packet rate (expressed in packets per second) threshold respectively and are used to determine when the corresponding coalescing settings for low and high packet rates come into effect if adaptive Rx/Tx coalescing is enabled\&. If unset, the kernel\*(Aqs defaults will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fICoalescePacketRateSampleIntervalSec=\fR +.RS 4 +Configures how often to sample the packet rate used for adaptive Rx/Tx coalescing\&. This property cannot be zero\&. This lowest time granularity supported by this property is seconds\&. Partial seconds will be rounded up before being passed to the kernel\&. If unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIStatisticsBlockCoalesceSec=\fR +.RS 4 +How long to delay driver in\-memory statistics block updates\&. If the driver does not have an in\-memory statistic block, this property is ignored\&. This property cannot be zero\&. If unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIMDI=\fR +.RS 4 +Specifies the medium dependent interface (MDI) mode for the interface\&. A MDI describes the interface from a physical layer implementation to the physical medium used to carry the transmission\&. Takes one of the following words: +"straight" +(or equivalently: +"mdi"), +"crossover" +(or equivalently: +"mdi\-x", +"mdix"), and +"auto"\&. When +"straight", the MDI straight through mode will be used\&. When +"crossover", the MDI crossover (MDI\-X) mode will be used\&. When +"auto", the MDI status is automatically detected\&. Defaults to unset, and the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fISR\-IOVVirtualFunctions=\fR +.RS 4 +Specifies the number of SR\-IOV virtual functions\&. Takes an integer in the range 0\&...2147483647\&. Defaults to unset, and automatically determined from the values specified in the +\fIVirtualFunction=\fR +settings in the [SR\-IOV] sections\&. +.sp +Added in version 251\&. +.RE +.SH "[SR\-IOV] SECTION OPTIONS" +.PP +The [SR\-IOV] section accepts the following keys\&. Specify several [SR\-IOV] sections to configure several SR\-IOVs\&. SR\-IOV provides the ability to partition a single physical PCI resource into virtual PCI functions which can then be injected into a VM\&. In the case of network VFs, SR\-IOV improves north\-south network performance (that is, traffic with endpoints outside the host machine) by allowing traffic to bypass the host machine\(cqs network stack\&. +.PP +\fIVirtualFunction=\fR +.RS 4 +Specifies a Virtual Function (VF), lightweight PCIe function designed solely to move data in and out\&. Takes an integer in the range 0\&...2147483646\&. This option is compulsory\&. +.sp +Added in version 251\&. +.RE +.PP +\fIVLANId=\fR +.RS 4 +Specifies VLAN ID of the virtual function\&. Takes an integer in the range 1\&...4095\&. +.sp +Added in version 251\&. +.RE +.PP +\fIQualityOfService=\fR +.RS 4 +Specifies quality of service of the virtual function\&. Takes an integer in the range 1\&...4294967294\&. +.sp +Added in version 251\&. +.RE +.PP +\fIVLANProtocol=\fR +.RS 4 +Specifies VLAN protocol of the virtual function\&. Takes +"802\&.1Q" +or +"802\&.1ad"\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMACSpoofCheck=\fR +.RS 4 +Takes a boolean\&. Controls the MAC spoof checking\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fIQueryReceiveSideScaling=\fR +.RS 4 +Takes a boolean\&. Toggle the ability of querying the receive side scaling (RSS) configuration of the virtual function (VF)\&. The VF RSS information like RSS hash key may be considered sensitive on some devices where this information is shared between VF and the physical function (PF)\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fITrust=\fR +.RS 4 +Takes a boolean\&. Allows one to set trust mode of the virtual function (VF)\&. When set, VF users can set a specific feature which may impact security and/or performance\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fILinkState=\fR +.RS 4 +Allows one to set the link state of the virtual function (VF)\&. Takes a boolean or a special value +"auto"\&. Setting to +"auto" +means a reflection of the physical function (PF) link state, +"yes" +lets the VF to communicate with other VFs on this host even if the PF link state is down, +"no" +causes the hardware to drop any packets sent by the VF\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +Specifies the MAC address for the virtual function\&. +.sp +Added in version 251\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&/usr/lib/systemd/network/99\-default\&.link\fR +.PP +The link file +99\-default\&.link +that is shipped with systemd defines the default policies for the interface name, alternative names, and MAC address of links\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Match] +OriginalName=* + +[Link] +NamePolicy=keep kernel database onboard slot path +AlternativeNamesPolicy=database onboard slot path +MACAddressPolicy=persistent +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&/etc/systemd/network/10\-dmz\&.link\fR +.PP +This example assigns the fixed name +"dmz0" +to the interface with the MAC address 00:a0:de:63:7a:e6: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Match] +MACAddress=00:a0:de:63:7a:e6 + +[Link] +Name=dmz0 +.fi +.if n \{\ +.RE +.\} +.PP +\fINamePolicy=\fR +is not set, so +\fIName=\fR +takes effect\&. We use the +"10\-" +prefix to order this file early in the list\&. Note that it needs to be before +99\-default\&.link, i\&.e\&. it needs a numerical prefix, to have any effect at all\&. +.PP +\fBExample\ \&3.\ \&(Re\-)applying a \&.link file to an interface\fR +.PP +After a new \&.link file has been created, or an existing \&.link file modified, the new settings may be applied to the matching interface with the following commands: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ sudo udevadm control \-\-reload +$ sudo ip link set eth0 down +$ sudo udevadm trigger \-\-verbose \-\-settle \-\-action add /sys/class/net/eth0 +.fi +.if n \{\ +.RE +.\} +.PP +You may also need to stop the service that manages the network interface, e\&.g\&. +\fBsystemd-networkd.service\fR(8) +or +NetworkManager\&.service +before the above operation, and then restart the service after that\&. For more details about +\fBudevadm\fR +command, see +\fBudevadm\fR(8)\&. +.PP +\fBExample\ \&4.\ \&Debugging \fINamePolicy=\fR assignments\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ sudo SYSTEMD_LOG_LEVEL=debug udevadm test\-builtin net_setup_link /sys/class/net/hub0 +\&... +Parsed configuration file /usr/lib/systemd/network/99\-default\&.link +Parsed configuration file /etc/systemd/network/10\-eth0\&.link +ID_NET_DRIVER=cdc_ether +Config file /etc/systemd/network/10\-eth0\&.link applies to device hub0 +link_config: autonegotiation is unset or enabled, the speed and duplex are not writable\&. +hub0: Device has name_assign_type=4 +Using default interface naming scheme \*(Aqv240\*(Aq\&. +hub0: Policies didn\*(Aqt yield a name, using specified Name=hub0\&. +ID_NET_LINK_FILE=/etc/systemd/network/10\-eth0\&.link +ID_NET_NAME=hub0 +\&... +.fi +.if n \{\ +.RE +.\} +.PP +Explicit +\fIName=\fR +configuration wins in this case\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +sudo SYSTEMD_LOG_LEVEL=debug udevadm test\-builtin net_setup_link /sys/class/net/enp0s31f6 +\&... +Parsed configuration file /usr/lib/systemd/network/99\-default\&.link +Parsed configuration file /etc/systemd/network/10\-eth0\&.link +Created link configuration context\&. +ID_NET_DRIVER=e1000e +Config file /usr/lib/systemd/network/99\-default\&.link applies to device enp0s31f6 +link_config: autonegotiation is unset or enabled, the speed and duplex are not writable\&. +enp0s31f6: Device has name_assign_type=4 +Using default interface naming scheme \*(Aqv240\*(Aq\&. +enp0s31f6: Policy *keep*: keeping existing userspace name +enp0s31f6: Device has addr_assign_type=0 +enp0s31f6: MAC on the device already matches policy *persistent* +ID_NET_LINK_FILE=/usr/lib/systemd/network/99\-default\&.link +\&... +.fi +.if n \{\ +.RE +.\} +.PP +In this case, the interface was already renamed, so the +\fBkeep\fR +policy specified as the first option in +99\-default\&.link +means that the existing name is preserved\&. If +\fBkeep\fR +was removed, or if were in boot before the renaming has happened, we might get the following instead: +.sp +.if n \{\ +.RS 4 +.\} +.nf +enp0s31f6: Policy *path* yields "enp0s31f6"\&. +enp0s31f6: Device has addr_assign_type=0 +enp0s31f6: MAC on the device already matches policy *persistent* +ID_NET_LINK_FILE=/usr/lib/systemd/network/99\-default\&.link +ID_NET_NAME=enp0s31f6 +\&... +.fi +.if n \{\ +.RE +.\} +.PP +Please note that the details of output are subject to change\&. +.PP +\fBExample\ \&5.\ \&/etc/systemd/network/10\-internet\&.link\fR +.PP +This example assigns the fixed name +"internet0" +to the interface with the device path +"pci\-0000:00:1a\&.0\-*": +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Match] +Path=pci\-0000:00:1a\&.0\-* + +[Link] +Name=internet0 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&6.\ \&/etc/systemd/network/25\-wireless\&.link\fR +.PP +Here\*(Aqs an overly complex example that shows the use of a large number of [Match] and [Link] settings\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Match] +MACAddress=12:34:56:78:9a:bc +Driver=brcmsmac +Path=pci\-0000:02:00\&.0\-* +Type=wlan +Virtualization=no +Host=my\-laptop +Architecture=x86\-64 + +[Link] +Name=wireless0 +MTUBytes=1450 +BitsPerSecond=10M +WakeOnLan=magic +MACAddress=cb:a9:87:65:43:21 +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd-udevd.service\fR(8), +\fBudevadm\fR(8), +\fBsystemd.netdev\fR(5), +\fBsystemd.network\fR(5), +\fBsystemd-network-generator.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +System and Service Credentials +.RS 4 +\%https://systemd.io/CREDENTIALS +.RE diff --git a/upstream/fedora-40/man5/systemd.mount.5 b/upstream/fedora-40/man5/systemd.mount.5 new file mode 100644 index 00000000..62d7fb91 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.mount.5 @@ -0,0 +1,671 @@ +'\" t +.TH "SYSTEMD\&.MOUNT" "5" "" "systemd 255" "systemd.mount" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.mount \- Mount unit configuration +.SH "SYNOPSIS" +.PP +\fImount\fR\&.mount +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.mount" +encodes information about a file system mount point controlled and supervised by systemd\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The mount specific configuration options are configured in the [Mount] section\&. +.PP +Additional options are listed in +\fBsystemd.exec\fR(5), which define the execution environment the +\fBmount\fR(8) +program is executed in, and in +\fBsystemd.kill\fR(5), which define the way the processes are terminated, and in +\fBsystemd.resource-control\fR(5), which configure resource control settings for the processes of the service\&. +.PP +Note that the options +\fIUser=\fR +and +\fIGroup=\fR +are not useful for mount units\&. systemd passes two parameters to +\fBmount\fR(8); the values of +\fIWhat=\fR +and +\fIWhere=\fR\&. When invoked in this way, +\fBmount\fR(8) +does not read any options from +/etc/fstab, and must be run as UID 0\&. +.PP +Mount units must be named after the mount point directories they control\&. Example: the mount point +/home/lennart +must be configured in a unit file +home\-lennart\&.mount\&. For details about the escaping logic used to convert a file system path to a unit name, see +\fBsystemd.unit\fR(5)\&. Note that mount units cannot be templated, nor is possible to add multiple names to a mount unit by creating symlinks to its unit file\&. +.PP +Optionally, a mount unit may be accompanied by an automount unit, to allow on\-demand or parallelized mounting\&. See +\fBsystemd.automount\fR(5)\&. +.PP +Mount points created at runtime (independently of unit files or +/etc/fstab) will be monitored by systemd and appear like any other mount unit in systemd\&. See +/proc/self/mountinfo +description in +\fBproc\fR(5)\&. +.PP +Some file systems have special semantics as API file systems for kernel\-to\-userspace and userspace\-to\-userspace interfaces\&. Some of them may not be changed via mount units, and cannot be disabled\&. For a longer discussion see +\m[blue]\fBAPI File Systems\fR\m[]\&\s-2\u[1]\d\s+2\&. +.PP +The +\fBsystemd-mount\fR(1) +command allows creating +\&.mount +and +\&.automount +units dynamically and transiently from the command line\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If a mount unit is beneath another mount unit in the file system hierarchy, both a requirement dependency and an ordering dependency between both units are created automatically\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Block device backed file systems automatically gain +\fIBindsTo=\fR +and +\fIAfter=\fR +type dependencies on the device unit encapsulating the block device (see below)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If traditional file system quota is enabled for a mount unit, automatic +\fIWants=\fR +and +\fIBefore=\fR +dependencies on +systemd\-quotacheck\&.service +and +quotaon\&.service +are added\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Additional implicit dependencies may be added as result of execution and resource control parameters as documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.resource-control\fR(5)\&. +.RE +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +All mount units acquire automatic +\fIBefore=\fR +and +\fIConflicts=\fR +on +umount\&.target +in order to be stopped during shutdown\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Mount units referring to local file systems automatically gain an +\fIAfter=\fR +dependency on +local\-fs\-pre\&.target, and a +\fIBefore=\fR +dependency on +local\-fs\&.target +unless +\fBnofail\fR +mount option is set\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Network mount units automatically acquire +\fIAfter=\fR +dependencies on +remote\-fs\-pre\&.target, +network\&.target +and +network\-online\&.target, and gain a +\fIBefore=\fR +dependency on +remote\-fs\&.target +unless +\fBnofail\fR +mount option is set\&. Towards the latter a +\fIWants=\fR +unit is added as well\&. +.RE +.PP +Mount units referring to local and network file systems are distinguished by their file system type specification\&. In some cases this is not sufficient (for example network block device based mounts, such as iSCSI), in which case +\fB_netdev\fR +may be added to the mount option string of the unit, which forces systemd to consider the mount unit a network mount\&. +.SH "FSTAB" +.PP +Mount units may either be configured via unit files, or via +/etc/fstab +(see +\fBfstab\fR(5) +for details)\&. Mounts listed in +/etc/fstab +will be converted into native units dynamically at boot and when the configuration of the system manager is reloaded\&. In general, configuring mount points through +/etc/fstab +is the preferred approach to manage mounts for humans\&. For tooling, writing mount units should be preferred over editing +/etc/fstab\&. See +\fBsystemd-fstab-generator\fR(8) +for details about the conversion from +/etc/fstab +to mount units\&. +.PP +The NFS mount option +\fBbg\fR +for NFS background mounts as documented in +\fBnfs\fR(5) +is detected by +\fBsystemd\-fstab\-generator\fR +and the options are transformed so that systemd fulfills the job\-control implications of that option\&. Specifically +\fBsystemd\-fstab\-generator\fR +acts as though +"x\-systemd\&.mount\-timeout=infinity,retry=10000" +was prepended to the option list, and +"fg,nofail" +was appended\&. Depending on specific requirements, it may be appropriate to provide some of these options explicitly, or to make use of the +"x\-systemd\&.automount" +option described below instead of using +"bg"\&. +.PP +When reading +/etc/fstab +a few special mount options are understood by systemd which influence how dependencies are created for mount points\&. systemd will create a dependency of type +\fIWants=\fR +or +\fBRequires=\fR +(see option +\fBnofail\fR +below), from either +local\-fs\&.target +or +remote\-fs\&.target, depending whether the file system is local or remote\&. +.PP +\fBx\-systemd\&.requires=\fR +.RS 4 +Configures a +\fIRequires=\fR +and an +\fIAfter=\fR +dependency between the created mount unit and another systemd unit, such as a device or mount unit\&. The argument should be a unit name, or an absolute path to a device node or mount point\&. This option may be specified more than once\&. This option is particularly useful for mount point declarations that need an additional device to be around (such as an external journal device for journal file systems) or an additional mount to be in place (such as an overlay file system that merges multiple mount points)\&. See +\fIAfter=\fR +and +\fIRequires=\fR +in +\fBsystemd.unit\fR(5) +for details\&. +.sp +Note that this option always applies to the created mount unit only regardless whether +\fBx\-systemd\&.automount\fR +has been specified\&. +.sp +Added in version 220\&. +.RE +.PP +\fBx\-systemd\&.before=\fR, \fBx\-systemd\&.after=\fR +.RS 4 +In the created mount unit, configures a +\fIBefore=\fR +or +\fIAfter=\fR +dependency on another systemd unit, such as a mount unit\&. The argument should be a unit name or an absolute path to a mount point\&. This option may be specified more than once\&. This option is particularly useful for mount point declarations with +\fBnofail\fR +option that are mounted asynchronously but need to be mounted before or after some unit start, for example, before +local\-fs\&.target +unit\&. See +\fIBefore=\fR +and +\fIAfter=\fR +in +\fBsystemd.unit\fR(5) +for details\&. +.sp +Note that these options always apply to the created mount unit only regardless whether +\fBx\-systemd\&.automount\fR +has been specified\&. +.sp +Added in version 233\&. +.RE +.PP +\fBx\-systemd\&.wanted\-by=\fR, \fBx\-systemd\&.required\-by=\fR +.RS 4 +In the created mount unit, configures a +\fIWantedBy=\fR +or +\fIRequiredBy=\fR +dependency on another unit\&. This option may be specified more than once\&. If this is specified, the normal automatic dependencies on the created mount unit, e\&.g\&., +local\-fs\&.target, are not automatically created\&. See +\fIWantedBy=\fR +and +\fIRequiredBy=\fR +in +\fBsystemd.unit\fR(5) +for details\&. +.sp +Added in version 245\&. +.RE +.PP +\fBx\-systemd\&.requires\-mounts\-for=\fR +.RS 4 +Configures a +\fIRequiresMountsFor=\fR +dependency between the created mount unit and other mount units\&. The argument must be an absolute path\&. This option may be specified more than once\&. See +\fIRequiresMountsFor=\fR +in +\fBsystemd.unit\fR(5) +for details\&. +.sp +Added in version 220\&. +.RE +.PP +\fBx\-systemd\&.device\-bound=\fR +.RS 4 +Takes a boolean argument\&. If true or no argument, a +\fIBindsTo=\fR +dependency on the backing device is set\&. If false, the mount unit is not stopped no matter whether the backing device is still present\&. This is useful when the file system is backed by volume managers\&. If not set, and the mount comes from unit fragments, i\&.e\&. generated from +/etc/fstab +by +\fBsystemd-fstab-generator\fR(8) +or loaded from a manually configured mount unit, a combination of +\fIRequires=\fR +and +\fIStopPropagatedFrom=\fR +dependencies is set on the backing device\&. If doesn\*(Aqt, only +\fIRequires=\fR +is used\&. +.sp +Added in version 233\&. +.RE +.PP +\fBx\-systemd\&.automount\fR +.RS 4 +An automount unit will be created for the file system\&. See +\fBsystemd.automount\fR(5) +for details\&. +.sp +Added in version 215\&. +.RE +.PP +\fBx\-systemd\&.idle\-timeout=\fR +.RS 4 +Configures the idle timeout of the automount unit\&. See +\fITimeoutIdleSec=\fR +in +\fBsystemd.automount\fR(5) +for details\&. +.sp +Added in version 220\&. +.RE +.PP +\fBx\-systemd\&.device\-timeout=\fR +.RS 4 +Configure how long systemd should wait for a device to show up before giving up on an entry from +/etc/fstab\&. Specify a time in seconds or explicitly append a unit such as +"s", +"min", +"h", +"ms"\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. +.sp +Added in version 215\&. +.RE +.PP +\fBx\-systemd\&.mount\-timeout=\fR +.RS 4 +Configure how long systemd should wait for the mount command to finish before giving up on an entry from +/etc/fstab\&. Specify a time in seconds or explicitly append a unit such as +"s", +"min", +"h", +"ms"\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. +.sp +See +\fITimeoutSec=\fR +below for details\&. +.sp +Added in version 233\&. +.RE +.PP +\fBx\-systemd\&.makefs\fR +.RS 4 +The file system will be initialized on the device\&. If the device is not "empty", i\&.e\&. it contains any signature, the operation will be skipped\&. It is hence expected that this option remains set even after the device has been initialized\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. +.sp +See +\fBsystemd-makefs@.service\fR(8)\&. +.sp +\fBwipefs\fR(8) +may be used to remove any signatures from a block device to force +\fBx\-systemd\&.makefs\fR +to reinitialize the device\&. +.sp +Added in version 236\&. +.RE +.PP +\fBx\-systemd\&.growfs\fR +.RS 4 +The file system will be grown to occupy the full block device\&. If the file system is already at maximum size, no action will be performed\&. It is hence expected that this option remains set even after the file system has been grown\&. Only certain file system types are supported, see +\fBsystemd-makefs@.service\fR(8) +for details\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. +.sp +Added in version 236\&. +.RE +.PP +\fBx\-systemd\&.pcrfs\fR +.RS 4 +Measures file system identity information (mount point, type, label, UUID, partition label, partition UUID) into PCR 15 after the file system has been mounted\&. This ensures the +\fBsystemd-pcrfs@.service\fR(8) +or +systemd\-pcrfs\-root\&.service +services are pulled in by the mount unit\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. It is also implied for the root and +/usr/ +partitions discovered by +\fBsystemd-gpt-auto-generator\fR(8)\&. +.sp +Added in version 253\&. +.RE +.PP +\fBx\-systemd\&.rw\-only\fR +.RS 4 +If a mount operation fails to mount the file system read\-write, it normally tries mounting the file system read\-only instead\&. This option disables that behaviour, and causes the mount to fail immediately instead\&. This option is translated into the +\fIReadWriteOnly=\fR +setting in a unit file\&. +.sp +Added in version 246\&. +.RE +.PP +\fB_netdev\fR +.RS 4 +Normally the file system type is used to determine if a mount is a "network mount", i\&.e\&. if it should only be started after the network is available\&. Using this option overrides this detection and specifies that the mount requires network\&. +.sp +Network mount units are ordered between +remote\-fs\-pre\&.target +and +remote\-fs\&.target, instead of +local\-fs\-pre\&.target +and +local\-fs\&.target\&. They also pull in +network\-online\&.target +and are ordered after it and +network\&.target\&. +.sp +Added in version 235\&. +.RE +.PP +\fBnoauto\fR, \fBauto\fR +.RS 4 +With +\fBnoauto\fR, the mount unit will not be added as a dependency for +local\-fs\&.target +or +remote\-fs\&.target\&. This means that it will not be mounted automatically during boot, unless it is pulled in by some other unit\&. The +\fBauto\fR +option has the opposite meaning and is the default\&. +.sp +Note that if +\fBx\-systemd\&.automount\fR +(see above) is used, neither +\fBauto\fR +nor +\fBnoauto\fR +have any effect\&. The matching automount unit will be added as a dependency to the appropriate target\&. +.sp +Added in version 215\&. +.RE +.PP +\fBnofail\fR +.RS 4 +With +\fBnofail\fR, this mount will be only wanted, not required, by +local\-fs\&.target +or +remote\-fs\&.target\&. Moreover the mount unit is not ordered before these target units\&. This means that the boot will continue without waiting for the mount unit and regardless whether the mount point can be mounted successfully\&. +.sp +Added in version 215\&. +.RE +.PP +\fBx\-initrd\&.mount\fR +.RS 4 +An additional filesystem to be mounted in the initrd\&. See +initrd\-fs\&.target +description in +\fBsystemd.special\fR(7)\&. This is both an indicator to the initrd to mount this partition early and an indicator to the host to leave the partition mounted until final shutdown\&. Or in other words, if this flag is set it is assumed the mount shall be active during the entire regular runtime of the system, i\&.e\&. established before the initrd transitions into the host all the way until the host transitions to the final shutdown phase\&. +.sp +Added in version 215\&. +.RE +.PP +If a mount point is configured in both +/etc/fstab +and a unit file that is stored below +/usr/, the former will take precedence\&. If the unit file is stored below +/etc/, it will take precedence\&. This means: native unit files take precedence over traditional configuration files, but this is superseded by the rule that configuration in +/etc/ +will always take precedence over configuration in +/usr/\&. +.SH "OPTIONS" +.PP +Mount unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Mount unit files must include a [Mount] section, which carries information about the file system mount points it supervises\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.kill\fR(5)\&. The options specific to the [Mount] section of mount units are the following: +.PP +\fIWhat=\fR +.RS 4 +Takes an absolute path of a device node, file or other resource to mount\&. See +\fBmount\fR(8) +for details\&. If this refers to a device node, a dependency on the respective device unit is automatically created\&. (See +\fBsystemd.device\fR(5) +for more information\&.) This option is mandatory\&. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as +"%%"\&. If this mount is a bind mount and the specified path does not exist yet it is created as directory\&. +.RE +.PP +\fIWhere=\fR +.RS 4 +Takes an absolute path of a file or directory for the mount point; in particular, the destination cannot be a symbolic link\&. If the mount point does not exist at the time of mounting, it is created as either a directory or a file\&. The former is the usual case; the latter is done only if this mount is a bind mount and the source (\fIWhat=\fR) is not a directory\&. This string must be reflected in the unit filename\&. (See above\&.) This option is mandatory\&. +.RE +.PP +\fIType=\fR +.RS 4 +Takes a string for the file system type\&. See +\fBmount\fR(8) +for details\&. This setting is optional\&. +.RE +.PP +\fIOptions=\fR +.RS 4 +Mount options to use when mounting\&. This takes a comma\-separated list of options\&. This setting is optional\&. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as +"%%"\&. +.RE +.PP +\fISloppyOptions=\fR +.RS 4 +Takes a boolean argument\&. If true, parsing of the options specified in +\fIOptions=\fR +is relaxed, and unknown mount options are tolerated\&. This corresponds with +\fBmount\fR(8)\*(Aqs +\fI\-s\fR +switch\&. Defaults to off\&. +.sp +Added in version 215\&. +.RE +.PP +\fILazyUnmount=\fR +.RS 4 +Takes a boolean argument\&. If true, detach the filesystem from the filesystem hierarchy at time of the unmount operation, and clean up all references to the filesystem as soon as they are not busy anymore\&. This corresponds with +\fBumount\fR(8)\*(Aqs +\fI\-l\fR +switch\&. Defaults to off\&. +.sp +Added in version 232\&. +.RE +.PP +\fIReadWriteOnly=\fR +.RS 4 +Takes a boolean argument\&. If false, a mount point that shall be mounted read\-write but cannot be mounted so is retried to be mounted read\-only\&. If true the operation will fail immediately after the read\-write mount attempt did not succeed\&. This corresponds with +\fBmount\fR(8)\*(Aqs +\fI\-w\fR +switch\&. Defaults to off\&. +.sp +Added in version 246\&. +.RE +.PP +\fIForceUnmount=\fR +.RS 4 +Takes a boolean argument\&. If true, force an unmount (in case of an unreachable NFS system)\&. This corresponds with +\fBumount\fR(8)\*(Aqs +\fI\-f\fR +switch\&. Defaults to off\&. +.sp +Added in version 232\&. +.RE +.PP +\fIDirectoryMode=\fR +.RS 4 +Directories of mount points (and any parent directories) are automatically created if needed\&. This option specifies the file system access mode used when creating these directories\&. Takes an access mode in octal notation\&. Defaults to 0755\&. +.RE +.PP +\fITimeoutSec=\fR +.RS 4 +Configures the time to wait for the mount command to finish\&. If a command does not exit within the configured time, the mount will be considered failed and be shut down again\&. All commands still running will be terminated forcibly via +\fBSIGTERM\fR, and after another delay of this time with +\fBSIGKILL\fR\&. (See +\fBKillMode=\fR +in +\fBsystemd.kill\fR(5)\&.) Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass 0 to disable the timeout logic\&. The default value is set from +\fIDefaultTimeoutStartSec=\fR +option in +\fBsystemd-system.conf\fR(5)\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.kill\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.device\fR(5), +\fBproc\fR(5), +\fBmount\fR(8), +\fBsystemd-fstab-generator\fR(8), +\fBsystemd.directives\fR(7), +\fBsystemd-mount\fR(1) +.SH "NOTES" +.IP " 1." 4 +API File Systems +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems +.RE diff --git a/upstream/fedora-40/man5/systemd.netdev.5 b/upstream/fedora-40/man5/systemd.netdev.5 new file mode 100644 index 00000000..4cbedb2f --- /dev/null +++ b/upstream/fedora-40/man5/systemd.netdev.5 @@ -0,0 +1,2746 @@ +'\" t +.TH "SYSTEMD\&.NETDEV" "5" "" "systemd 255" "systemd.network" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.netdev \- Virtual Network Device configuration +.SH "SYNOPSIS" +.PP +\fInetdev\fR\&.netdev +.SH "DESCRIPTION" +.PP +A plain ini\-style text file that encodes configuration about a virtual network device, used by +\fBsystemd-networkd\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.PP +The main Virtual Network Device file must have the extension +\&.netdev; other extensions are ignored\&. Virtual network devices are created as soon as networkd is started\&. If a netdev with the specified name already exists, networkd will use that as\-is rather than create its own\&. Note that the settings of the pre\-existing netdev will not be changed by networkd\&. +.PP +The +\&.netdev +files are read from the files located in the system network directory +/usr/lib/systemd/network +and +/usr/local/lib/systemd/network, the volatile runtime network directory +/run/systemd/network +and the local administration network directory +/etc/systemd/network\&. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. It is recommended that each filename is prefixed with a number smaller than +"70" +(e\&.g\&. +10\-vlan\&.netdev)\&. Otherwise, +\&.netdev +files generated by +\fBsystemd-network-generator.service\fR(8) +may take precedence over user configured files\&. Files in +/etc/ +have the highest priority, files in +/run/ +take precedence over files with the same name in +/usr/lib/\&. This can be used to override a system\-supplied configuration file with a local file if needed\&. As a special case, an empty file (file size 0) or symlink with the same name pointing to +/dev/null +disables the configuration file entirely (it is "masked")\&. +.PP +Along with the netdev file +foo\&.netdev, a "drop\-in" directory +foo\&.netdev\&.d/ +may exist\&. All files with the suffix +"\&.conf" +from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed\&. This is useful to alter or add configuration settings, without having to modify the main configuration file\&. Each drop\-in file must have appropriate section headers\&. +.PP +In addition to +/etc/systemd/network, drop\-in +"\&.d" +directories can be placed in +/usr/lib/systemd/network +or +/run/systemd/network +directories\&. Drop\-in files in +/etc/ +take precedence over those in +/run/ +which in turn take precedence over those in +/usr/lib/\&. Drop\-in files under any of these directories take precedence over the main netdev file wherever located\&. (Of course, since +/run/ +is temporary and +/usr/lib/ +is for vendors, it is unlikely drop\-ins should be used in either of those places\&.) +.SH "SUPPORTED NETDEV KINDS" +.PP +The following kinds of virtual network devices may be configured in +\&.netdev +files: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Supported kinds of virtual network devices +.TS +allbox tab(:); +lB lB. +T{ +Kind +T}:T{ +Description +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +\fIbond\fR +T}:T{ +A bond device is an aggregation of all its slave devices\&. See \m[blue]\fBLinux Ethernet Bonding Driver HOWTO\fR\m[]\&\s-2\u[1]\d\s+2 for details\&. +T} +T{ +\fIbridge\fR +T}:T{ +A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch\&. +T} +T{ +\fIdummy\fR +T}:T{ +A dummy device drops all packets sent to it\&. +T} +T{ +\fIgre\fR +T}:T{ +A Level 3 GRE tunnel over IPv4\&. See \m[blue]\fBRFC 2784\fR\m[]\&\s-2\u[2]\d\s+2 for details\&. Name "gre0" should not be used, as the kernel creates a device with this name when the corresponding kernel module is loaded\&. +T} +T{ +\fIgretap\fR +T}:T{ +A Level 2 GRE tunnel over IPv4\&. Name "gretap0" should not be used, as the kernel creates a device with this name when the corresponding kernel module is loaded\&. +T} +T{ +\fIerspan\fR +T}:T{ +ERSPAN mirrors traffic on one or more source ports and delivers the mirrored traffic to one or more destination ports on another switch\&. The traffic is encapsulated in generic routing encapsulation (GRE) and is therefore routable across a layer 3 network between the source switch and the destination switch\&. Name "erspan0" should not be used, as the kernel creates a device with this name when the corresponding kernel module is loaded\&. +T} +T{ +\fIip6gre\fR +T}:T{ +A Level 3 GRE tunnel over IPv6\&. +T} +T{ +\fIip6tnl\fR +T}:T{ +An IPv4 or IPv6 tunnel over IPv6 +T} +T{ +\fIip6gretap\fR +T}:T{ +A Level 2 GRE tunnel over IPv6\&. +T} +T{ +\fIipip\fR +T}:T{ +An IPv4 over IPv4 tunnel\&. +T} +T{ +\fIipvlan\fR +T}:T{ +An IPVLAN device is a stacked device which receives packets from its underlying device based on IP address filtering\&. +T} +T{ +\fIipvtap\fR +T}:T{ +An IPVTAP device is a stacked device which receives packets from its underlying device based on IP address filtering and can be accessed using the tap user space interface\&. +T} +T{ +\fImacvlan\fR +T}:T{ +A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering\&. +T} +T{ +\fImacvtap\fR +T}:T{ +A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering\&. +T} +T{ +\fIsit\fR +T}:T{ +An IPv6 over IPv4 tunnel\&. +T} +T{ +\fItap\fR +T}:T{ +A persistent Level 2 tunnel between a network device and a device node\&. +T} +T{ +\fItun\fR +T}:T{ +A persistent Level 3 tunnel between a network device and a device node\&. +T} +T{ +\fIveth\fR +T}:T{ +An Ethernet tunnel between a pair of network devices\&. +T} +T{ +\fIvlan\fR +T}:T{ +A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging\&. See \m[blue]\fBIEEE 802\&.1Q\fR\m[]\&\s-2\u[3]\d\s+2 for details\&. +T} +T{ +\fIvti\fR +T}:T{ +An IPv4 over IPSec tunnel\&. +T} +T{ +\fIvti6\fR +T}:T{ +An IPv6 over IPSec tunnel\&. +T} +T{ +\fIvxlan\fR +T}:T{ +A virtual extensible LAN (vxlan), for connecting Cloud computing deployments\&. +T} +T{ +\fIgeneve\fR +T}:T{ +A GEneric NEtwork Virtualization Encapsulation (GENEVE) netdev driver\&. +T} +T{ +\fIl2tp\fR +T}:T{ +A Layer 2 Tunneling Protocol (L2TP) is a tunneling protocol used to support virtual private networks (VPNs) or as part of the delivery of services by ISPs\&. It does not provide any encryption or confidentiality by itself +T} +T{ +\fImacsec\fR +T}:T{ +Media Access Control Security (MACsec) is an 802\&.1AE IEEE industry\-standard security technology that provides secure communication for all traffic on Ethernet links\&. MACsec provides point\-to\-point security on Ethernet links between directly connected nodes and is capable of identifying and preventing most security threats\&. +T} +T{ +\fIvrf\fR +T}:T{ +A Virtual Routing and Forwarding (\m[blue]\fBVRF\fR\m[]\&\s-2\u[4]\d\s+2) interface to create separate routing and forwarding domains\&. +T} +T{ +\fIvcan\fR +T}:T{ +The virtual CAN driver (vcan)\&. Similar to the network loopback devices, vcan offers a virtual local CAN interface\&. +T} +T{ +\fIvxcan\fR +T}:T{ +The virtual CAN tunnel driver (vxcan)\&. Similar to the virtual ethernet driver veth, vxcan implements a local CAN traffic tunnel between two virtual CAN network devices\&. When creating a vxcan, two vxcan devices are created as pair\&. When one end receives the packet it appears on its pair and vice versa\&. The vxcan can be used for cross namespace communication\&. +T} +T{ +\fIwireguard\fR +T}:T{ +WireGuard Secure Network Tunnel\&. +T} +T{ +\fInlmon\fR +T}:T{ +A Netlink monitor device\&. Use an nlmon device when you want to monitor system Netlink messages\&. +T} +T{ +\fIfou\fR +T}:T{ +Foo\-over\-UDP tunneling\&. +T} +T{ +\fIxfrm\fR +T}:T{ +A virtual tunnel interface like vti/vti6 but with several advantages\&. +T} +T{ +\fIifb\fR +T}:T{ +The Intermediate Functional Block (ifb) pseudo network interface acts as a QoS concentrator for multiple different sources of traffic\&. +T} +T{ +\fIbareudp\fR +T}:T{ +Bare UDP tunnels provide a generic L3 encapsulation support for tunnelling different L3 protocols like MPLS, IP etc\&. inside of a UDP tunnel\&. +T} +T{ +\fIbatadv\fR +T}:T{ +\m[blue]\fBB\&.A\&.T\&.M\&.A\&.N\&. Advanced\fR\m[]\&\s-2\u[5]\d\s+2 is a routing protocol for multi\-hop mobile ad\-hoc networks which operates on layer 2\&. +T} +T{ +\fIipoib\fR +T}:T{ +An IP over Infiniband subinterface\&. +T} +T{ +\fIwlan\fR +T}:T{ +A virtual wireless network (WLAN) interface\&. +T} +.TE +.sp 1 +.SH "[MATCH] SECTION OPTIONS" +.PP +A virtual network device is only created if the [Match] section matches the current environment, or if the section is empty\&. The following keys are accepted: +.PP +\fIHost=\fR +.RS 4 +Matches against the hostname or machine ID of the host\&. See +\fIConditionHost=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIVirtualization=\fR +.RS 4 +Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation\&. See +\fIConditionVirtualization=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKernelCommandLine=\fR +.RS 4 +Checks whether a specific kernel command line option is set\&. See +\fIConditionKernelCommandLine=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKernelVersion=\fR +.RS 4 +Checks whether the kernel version (as reported by +\fBuname \-r\fR) matches a certain expression\&. See +\fIConditionKernelVersion=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 237\&. +.RE +.PP +\fICredential=\fR +.RS 4 +Checks whether the specified credential was passed to the +systemd\-udevd\&.service +service\&. See +\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[6]\d\s+2 +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 252\&. +.RE +.PP +\fIArchitecture=\fR +.RS 4 +Checks whether the system is running on a specific architecture\&. See +\fIConditionArchitecture=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIFirmware=\fR +.RS 4 +Checks whether the system is running on a machine with the specified firmware\&. See +\fIConditionFirmware=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 249\&. +.RE +.SH "[NETDEV] SECTION OPTIONS" +.PP +The [NetDev] section accepts the following keys: +.PP +\fIDescription=\fR +.RS 4 +A free\-form description of the netdev\&. +.sp +Added in version 215\&. +.RE +.PP +\fIName=\fR +.RS 4 +The interface name used when creating the netdev\&. This setting is compulsory\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKind=\fR +.RS 4 +The netdev kind\&. This setting is compulsory\&. See the +"Supported netdev kinds" +section for the valid keys\&. +.sp +Added in version 211\&. +.RE +.PP +\fIMTUBytes=\fR +.RS 4 +The maximum transmission unit in bytes to set for the device\&. The usual suffixes K, M, G are supported and are understood to the base of 1024\&. For +"tun" +or +"tap" +devices, +\fIMTUBytes=\fR +setting is not currently supported in [NetDev] section\&. Please specify it in [Link] section of corresponding +\fBsystemd.network\fR(5) +files\&. +.sp +Added in version 215\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +Specifies the MAC address to use for the device, or takes the special value +"none"\&. When +"none", +\fBsystemd\-networkd\fR +does not request the MAC address for the device, and the kernel will assign a random MAC address\&. For +"tun", +"tap", or +"l2tp" +devices, the +\fIMACAddress=\fR +setting in the [NetDev] section is not supported and will be ignored\&. Please specify it in the [Link] section of the corresponding +\fBsystemd.network\fR(5) +file\&. If this option is not set, +"vlan" +device inherits the MAC address of the master interface\&. For other kind of netdevs, if this option is not set, then the MAC address is generated based on the interface name and the +\fBmachine-id\fR(5)\&. +.sp +Note, even if +"none" +is specified, +\fBsystemd\-udevd\fR +will assign the persistent MAC address for the device, as +99\-default\&.link +has +\fIMACAddressPolicy=persistent\fR\&. So, it is also necessary to create a custom \&.link file for the device, if the MAC address assignment is not desired\&. +.sp +Added in version 215\&. +.RE +.SH "[BRIDGE] SECTION OPTIONS" +.PP +The [Bridge] section only applies for netdevs of kind +"bridge", and accepts the following keys: +.PP +\fIHelloTimeSec=\fR +.RS 4 +HelloTimeSec specifies the number of seconds between two hello packets sent out by the root bridge and the designated bridges\&. Hello packets are used to communicate information about the topology throughout the entire bridged local area network\&. +.sp +Added in version 227\&. +.RE +.PP +\fIMaxAgeSec=\fR +.RS 4 +MaxAgeSec specifies the number of seconds of maximum message age\&. If the last seen (received) hello packet is more than this number of seconds old, the bridge in question will start the takeover procedure in attempt to become the Root Bridge itself\&. +.sp +Added in version 227\&. +.RE +.PP +\fIForwardDelaySec=\fR +.RS 4 +ForwardDelaySec specifies the number of seconds spent in each of the Listening and Learning states before the Forwarding state is entered\&. +.sp +Added in version 227\&. +.RE +.PP +\fIAgeingTimeSec=\fR +.RS 4 +This specifies the number of seconds a MAC Address will be kept in the forwarding database after having a packet received from this MAC Address\&. +.sp +Added in version 232\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +The priority of the bridge\&. An integer between 0 and 65535\&. A lower value means higher priority\&. The bridge having the lowest priority will be elected as root bridge\&. +.sp +Added in version 232\&. +.RE +.PP +\fIGroupForwardMask=\fR +.RS 4 +A 16\-bit bitmask represented as an integer which allows forwarding of link local frames with 802\&.1D reserved addresses (01:80:C2:00:00:0X)\&. A logical AND is performed between the specified bitmask and the exponentiation of 2^X, the lower nibble of the last octet of the MAC address\&. For example, a value of 8 would allow forwarding of frames addressed to 01:80:C2:00:00:03 (802\&.1X PAE)\&. +.sp +Added in version 235\&. +.RE +.PP +\fIDefaultPVID=\fR +.RS 4 +This specifies the default port VLAN ID of a newly attached bridge port\&. Set this to an integer in the range 1\&...4094 or +"none" +to disable the PVID\&. +.sp +Added in version 232\&. +.RE +.PP +\fIMulticastQuerier=\fR +.RS 4 +Takes a boolean\&. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel\&. If enabled, the kernel will send general ICMP queries from a zero source address\&. This feature should allow faster convergence on startup, but it causes some multicast\-aware switches to misbehave and disrupt forwarding of multicast packets\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 230\&. +.RE +.PP +\fIMulticastSnooping=\fR +.RS 4 +Takes a boolean\&. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel\&. If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic between hosts and multicast routers\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 230\&. +.RE +.PP +\fIVLANFiltering=\fR +.RS 4 +Takes a boolean\&. This setting controls the IFLA_BR_VLAN_FILTERING option in the kernel\&. If enabled, the bridge will be started in VLAN\-filtering mode\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 231\&. +.RE +.PP +\fIVLANProtocol=\fR +.RS 4 +Allows setting the protocol used for VLAN filtering\&. Takes +\fB802\&.1q\fR +or, +\fB802\&.1ad\fR, and defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fISTP=\fR +.RS 4 +Takes a boolean\&. This enables the bridge\*(Aqs Spanning Tree Protocol (STP)\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 232\&. +.RE +.PP +\fIMulticastIGMPVersion=\fR +.RS 4 +Allows changing bridge\*(Aqs multicast Internet Group Management Protocol (IGMP) version\&. Takes an integer 2 or 3\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.SH "[VLAN] SECTION OPTIONS" +.PP +The [VLAN] section only applies for netdevs of kind +"vlan", and accepts the following key: +.PP +\fIId=\fR +.RS 4 +The VLAN ID to use\&. An integer in the range 0\&...4094\&. This setting is compulsory\&. +.sp +Added in version 211\&. +.RE +.PP +\fIProtocol=\fR +.RS 4 +Allows setting the protocol used for the VLAN interface\&. Takes +"802\&.1q" +or, +"802\&.1ad", and defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 248\&. +.RE +.PP +\fIGVRP=\fR +.RS 4 +Takes a boolean\&. The Generic VLAN Registration Protocol (GVRP) is a protocol that allows automatic learning of VLANs on a network\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 234\&. +.RE +.PP +\fIMVRP=\fR +.RS 4 +Takes a boolean\&. Multiple VLAN Registration Protocol (MVRP) formerly known as GARP VLAN Registration Protocol (GVRP) is a standards\-based Layer 2 network protocol, for automatic configuration of VLAN information on switches\&. It was defined in the 802\&.1ak amendment to 802\&.1Q\-2005\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 234\&. +.RE +.PP +\fILooseBinding=\fR +.RS 4 +Takes a boolean\&. The VLAN loose binding mode, in which only the operational state is passed from the parent to the associated VLANs, but the VLAN device state is not changed\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 234\&. +.RE +.PP +\fIReorderHeader=\fR +.RS 4 +Takes a boolean\&. When enabled, the VLAN reorder header is used and VLAN interfaces behave like physical interfaces\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 234\&. +.RE +.PP +\fIEgressQOSMaps=\fR, \fIIngressQOSMaps=\fR +.RS 4 +Defines a mapping of Linux internal packet priority (\fBSO_PRIORITY\fR) to VLAN header PCP field for outgoing and incoming frames, respectively\&. Takes a whitespace\-separated list of integer pairs, where each integer must be in the range 1\&...4294967294, in the format +"from"\-"to", e\&.g\&., +"21\-7 45\-5"\&. Note that +"from" +must be greater than or equal to +"to"\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 248\&. +.RE +.SH "[MACVLAN] SECTION OPTIONS" +.PP +The [MACVLAN] section only applies for netdevs of kind +"macvlan", and accepts the following key: +.PP +\fIMode=\fR +.RS 4 +The MACVLAN mode to use\&. The supported options are +"private", +"vepa", +"bridge", +"passthru", and +"source"\&. +.sp +Added in version 211\&. +.RE +.PP +\fISourceMACAddress=\fR +.RS 4 +A whitespace\-separated list of remote hardware addresses allowed on the MACVLAN\&. This option only has an effect in source mode\&. Use full colon\-, hyphen\- or dot\-delimited hexadecimal\&. This option may appear more than once, in which case the lists are merged\&. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIBroadcastMulticastQueueLength=\fR +.RS 4 +Specifies the length of the receive queue for broadcast/multicast packets\&. An unsigned integer in the range 0\&...4294967294\&. Defaults to unset\&. +.sp +Added in version 248\&. +.RE +.SH "[MACVTAP] SECTION OPTIONS" +.PP +The [MACVTAP] section applies for netdevs of kind +"macvtap" +and accepts the same keys as [MACVLAN]\&. +.SH "[IPVLAN] SECTION OPTIONS" +.PP +The [IPVLAN] section only applies for netdevs of kind +"ipvlan", and accepts the following key: +.PP +\fIMode=\fR +.RS 4 +The IPVLAN mode to use\&. The supported options are +"L2","L3" +and +"L3S"\&. +.sp +Added in version 219\&. +.RE +.PP +\fIFlags=\fR +.RS 4 +The IPVLAN flags to use\&. The supported options are +"bridge","private" +and +"vepa"\&. +.sp +Added in version 237\&. +.RE +.SH "[IPVTAP] SECTION OPTIONS" +.PP +The [IPVTAP] section only applies for netdevs of kind +"ipvtap" +and accepts the same keys as [IPVLAN]\&. +.SH "[VXLAN] SECTION OPTIONS" +.PP +The [VXLAN] section only applies for netdevs of kind +"vxlan", and accepts the following keys: +.PP +\fIVNI=\fR +.RS 4 +The VXLAN Network Identifier (or VXLAN Segment ID)\&. Takes a number in the range 1\&...16777215\&. +.sp +Added in version 243\&. +.RE +.PP +\fIRemote=\fR +.RS 4 +Configures destination IP address\&. +.sp +Added in version 233\&. +.RE +.PP +\fILocal=\fR +.RS 4 +Configures local IP address\&. It must be an address on the underlying interface of the VXLAN interface, or one of the special values +"ipv4_link_local", +"ipv6_link_local", +"dhcp4", +"dhcp6", and +"slaac"\&. If one of the special values is specified, an address which matches the corresponding type on the underlying interface will be used\&. Defaults to unset\&. +.sp +Added in version 233\&. +.RE +.PP +\fIGroup=\fR +.RS 4 +Configures VXLAN multicast group IP address\&. All members of a VXLAN must use the same multicast group address\&. +.sp +Added in version 243\&. +.RE +.PP +\fITOS=\fR +.RS 4 +The Type Of Service byte value for a vxlan interface\&. +.sp +Added in version 215\&. +.RE +.PP +\fITTL=\fR +.RS 4 +A fixed Time To Live N on Virtual eXtensible Local Area Network packets\&. Takes +"inherit" +or a number in the range 0\&...255\&. 0 is a special value meaning inherit the inner protocol\*(Aqs TTL value\&. +"inherit" +means that it will inherit the outer protocol\*(Aqs TTL value\&. +.sp +Added in version 215\&. +.RE +.PP +\fIMacLearning=\fR +.RS 4 +Takes a boolean\&. When true, enables dynamic MAC learning to discover remote MAC addresses\&. +.sp +Added in version 215\&. +.RE +.PP +\fIFDBAgeingSec=\fR +.RS 4 +The lifetime of Forwarding Database entry learnt by the kernel, in seconds\&. +.sp +Added in version 218\&. +.RE +.PP +\fIMaximumFDBEntries=\fR +.RS 4 +Configures maximum number of FDB entries\&. +.sp +Added in version 228\&. +.RE +.PP +\fIReduceARPProxy=\fR +.RS 4 +Takes a boolean\&. When true, bridge\-connected VXLAN tunnel endpoint answers ARP requests from the local bridge on behalf of remote +\m[blue]\fBDistributed Overlay Virtual Ethernet (DOVE)\fR\m[]\&\s-2\u[7]\d\s+2 +clients\&. Defaults to false\&. +.sp +Added in version 233\&. +.RE +.PP +\fIL2MissNotification=\fR +.RS 4 +Takes a boolean\&. When true, enables netlink LLADDR miss notifications\&. +.sp +Added in version 218\&. +.RE +.PP +\fIL3MissNotification=\fR +.RS 4 +Takes a boolean\&. When true, enables netlink IP address miss notifications\&. +.sp +Added in version 218\&. +.RE +.PP +\fIRouteShortCircuit=\fR +.RS 4 +Takes a boolean\&. When true, route short circuiting is turned on\&. +.sp +Added in version 218\&. +.RE +.PP +\fIUDPChecksum=\fR +.RS 4 +Takes a boolean\&. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on\&. +.sp +Added in version 220\&. +.RE +.PP +\fIUDP6ZeroChecksumTx=\fR +.RS 4 +Takes a boolean\&. When true, sending zero checksums in VXLAN/IPv6 is turned on\&. +.sp +Added in version 220\&. +.RE +.PP +\fIUDP6ZeroChecksumRx=\fR +.RS 4 +Takes a boolean\&. When true, receiving zero checksums in VXLAN/IPv6 is turned on\&. +.sp +Added in version 220\&. +.RE +.PP +\fIRemoteChecksumTx=\fR +.RS 4 +Takes a boolean\&. When true, remote transmit checksum offload of VXLAN is turned on\&. +.sp +Added in version 232\&. +.RE +.PP +\fIRemoteChecksumRx=\fR +.RS 4 +Takes a boolean\&. When true, remote receive checksum offload in VXLAN is turned on\&. +.sp +Added in version 232\&. +.RE +.PP +\fIGroupPolicyExtension=\fR +.RS 4 +Takes a boolean\&. When true, it enables Group Policy VXLAN extension security label mechanism across network peers based on VXLAN\&. For details about the Group Policy VXLAN, see the +\m[blue]\fBVXLAN Group Policy\fR\m[]\&\s-2\u[8]\d\s+2 +document\&. Defaults to false\&. +.sp +Added in version 224\&. +.RE +.PP +\fIGenericProtocolExtension=\fR +.RS 4 +Takes a boolean\&. When true, Generic Protocol Extension extends the existing VXLAN protocol to provide protocol typing, OAM, and versioning capabilities\&. For details about the VXLAN GPE Header, see the +\m[blue]\fBGeneric Protocol Extension for VXLAN\fR\m[]\&\s-2\u[9]\d\s+2 +document\&. If destination port is not specified and Generic Protocol Extension is set then default port of 4790 is used\&. Defaults to false\&. +.sp +Added in version 243\&. +.RE +.PP +\fIDestinationPort=\fR +.RS 4 +Configures the default destination UDP port\&. If the destination port is not specified then Linux kernel default will be used\&. Set to 4789 to get the IANA assigned value\&. +.sp +Added in version 229\&. +.RE +.PP +\fIPortRange=\fR +.RS 4 +Configures the source port range for the VXLAN\&. The kernel assigns the source UDP port based on the flow to help the receiver to do load balancing\&. When this option is not set, the normal range of local UDP ports is used\&. +.sp +Added in version 229\&. +.RE +.PP +\fIFlowLabel=\fR +.RS 4 +Specifies the flow label to use in outgoing packets\&. The valid range is 0\-1048575\&. +.sp +Added in version 234\&. +.RE +.PP +\fIIPDoNotFragment=\fR +.RS 4 +Allows setting the IPv4 Do not Fragment (DF) bit in outgoing packets, or to inherit its value from the IPv4 inner header\&. Takes a boolean value, or +"inherit"\&. Set to +"inherit" +if the encapsulated protocol is IPv6\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.PP +\fIIndependent=\fR +.RS 4 +Takes a boolean\&. When true, the vxlan interface is created without any underlying network interface\&. Defaults to false, which means that a \&.network file that requests this VXLAN interface using +\fIVXLAN=\fR +is required for the VXLAN to be created\&. +.sp +Added in version 247\&. +.RE +.SH "[GENEVE] SECTION OPTIONS" +.PP +The [GENEVE] section only applies for netdevs of kind +"geneve", and accepts the following keys: +.PP +\fIId=\fR +.RS 4 +Specifies the Virtual Network Identifier (VNI) to use, a number between 0 and 16777215\&. This field is mandatory\&. +.sp +Added in version 234\&. +.RE +.PP +\fIRemote=\fR +.RS 4 +Specifies the unicast destination IP address to use in outgoing packets\&. +.sp +Added in version 234\&. +.RE +.PP +\fITOS=\fR +.RS 4 +Specifies the TOS value to use in outgoing packets\&. Takes a number between 1 and 255\&. +.sp +Added in version 234\&. +.RE +.PP +\fITTL=\fR +.RS 4 +Accepts the same values as in the [VXLAN] section, except that when unset or set to 0, the kernel\*(Aqs default will be used, meaning that packet TTL will be set from +/proc/sys/net/ipv4/ip_default_ttl\&. +.sp +Added in version 234\&. +.RE +.PP +\fIUDPChecksum=\fR +.RS 4 +Takes a boolean\&. When true, specifies that UDP checksum is calculated for transmitted packets over IPv4\&. +.sp +Added in version 234\&. +.RE +.PP +\fIUDP6ZeroChecksumTx=\fR +.RS 4 +Takes a boolean\&. When true, skip UDP checksum calculation for transmitted packets over IPv6\&. +.sp +Added in version 234\&. +.RE +.PP +\fIUDP6ZeroChecksumRx=\fR +.RS 4 +Takes a boolean\&. When true, allows incoming UDP packets over IPv6 with zero checksum field\&. +.sp +Added in version 234\&. +.RE +.PP +\fIDestinationPort=\fR +.RS 4 +Specifies destination port\&. Defaults to 6081\&. If not set or assigned the empty string, the default port of 6081 is used\&. +.sp +Added in version 234\&. +.RE +.PP +\fIFlowLabel=\fR +.RS 4 +Specifies the flow label to use in outgoing packets\&. +.sp +Added in version 234\&. +.RE +.PP +\fIIPDoNotFragment=\fR +.RS 4 +Accepts the same key as in [VXLAN] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIInheritInnerProtocol=\fR +.RS 4 +Takes a boolean\&. When true, inner Layer 3 protocol is set as Protocol Type in the GENEVE header instead of Ethernet\&. Defaults to false\&. +.sp +Added in version 254\&. +.RE +.SH "[BAREUDP] SECTION OPTIONS" +.PP +The [BareUDP] section only applies for netdevs of kind +"bareudp", and accepts the following keys: +.PP +\fIDestinationPort=\fR +.RS 4 +Specifies the destination UDP port (in range 1\&...65535)\&. This is mandatory\&. +.sp +Added in version 247\&. +.RE +.PP +\fIEtherType=\fR +.RS 4 +Specifies the L3 protocol\&. Takes one of +"ipv4", +"ipv6", +"mpls\-uc" +or +"mpls\-mc"\&. This is mandatory\&. +.sp +Added in version 247\&. +.RE +.SH "[L2TP] SECTION OPTIONS" +.PP +The [L2TP] section only applies for netdevs of kind +"l2tp", and accepts the following keys: +.PP +\fITunnelId=\fR +.RS 4 +Specifies the tunnel identifier\&. Takes an number in the range 1\&...4294967295\&. The value used must match the +"PeerTunnelId=" +value being used at the peer\&. This setting is compulsory\&. +.sp +Added in version 242\&. +.RE +.PP +\fIPeerTunnelId=\fR +.RS 4 +Specifies the peer tunnel id\&. Takes a number in the range 1\&...4294967295\&. The value used must match the +"TunnelId=" +value being used at the peer\&. This setting is compulsory\&. +.sp +Added in version 242\&. +.RE +.PP +\fIRemote=\fR +.RS 4 +Specifies the IP address of the remote peer\&. This setting is compulsory\&. +.sp +Added in version 242\&. +.RE +.PP +\fILocal=\fR +.RS 4 +Specifies the IP address of a local interface\&. Takes an IP address, or the special values +"auto", +"static", or +"dynamic"\&. Optionally a name of a local interface can be specified after +"@", e\&.g\&. +"192\&.168\&.0\&.1@eth0" +or +"auto@eth0"\&. When an address is specified, then a local or specified interface must have the address, and the remote address must be accessible through the local address\&. If +"auto", then one of the addresses on a local or specified interface which is accessible to the remote address will be used\&. Similarly, if +"static" +or +"dynamic" +is set, then one of the static or dynamic addresses will be used\&. Defaults to +"auto"\&. +.sp +Added in version 242\&. +.RE +.PP +\fIEncapsulationType=\fR +.RS 4 +Specifies the encapsulation type of the tunnel\&. Takes one of +"udp" +or +"ip"\&. +.sp +Added in version 242\&. +.RE +.PP +\fIUDPSourcePort=\fR +.RS 4 +Specifies the UDP source port to be used for the tunnel\&. When UDP encapsulation is selected it\*(Aqs mandatory\&. Ignored when IP encapsulation is selected\&. +.sp +Added in version 242\&. +.RE +.PP +\fIUDPDestinationPort=\fR +.RS 4 +Specifies destination port\&. When UDP encapsulation is selected it\*(Aqs mandatory\&. Ignored when IP encapsulation is selected\&. +.sp +Added in version 245\&. +.RE +.PP +\fIUDPChecksum=\fR +.RS 4 +Takes a boolean\&. When true, specifies that UDP checksum is calculated for transmitted packets over IPv4\&. +.sp +Added in version 242\&. +.RE +.PP +\fIUDP6ZeroChecksumTx=\fR +.RS 4 +Takes a boolean\&. When true, skip UDP checksum calculation for transmitted packets over IPv6\&. +.sp +Added in version 242\&. +.RE +.PP +\fIUDP6ZeroChecksumRx=\fR +.RS 4 +Takes a boolean\&. When true, allows incoming UDP packets over IPv6 with zero checksum field\&. +.sp +Added in version 242\&. +.RE +.SH "[L2TPSESSION] SECTION OPTIONS" +.PP +The [L2TPSession] section only applies for netdevs of kind +"l2tp", and accepts the following keys: +.PP +\fIName=\fR +.RS 4 +Specifies the name of the session\&. This setting is compulsory\&. +.sp +Added in version 242\&. +.RE +.PP +\fISessionId=\fR +.RS 4 +Specifies the session identifier\&. Takes an number in the range 1\&...4294967295\&. The value used must match the +"SessionId=" +value being used at the peer\&. This setting is compulsory\&. +.sp +Added in version 242\&. +.RE +.PP +\fIPeerSessionId=\fR +.RS 4 +Specifies the peer session identifier\&. Takes an number in the range 1\&...4294967295\&. The value used must match the +"PeerSessionId=" +value being used at the peer\&. This setting is compulsory\&. +.sp +Added in version 242\&. +.RE +.PP +\fILayer2SpecificHeader=\fR +.RS 4 +Specifies layer2specific header type of the session\&. One of +"none" +or +"default"\&. Defaults to +"default"\&. +.sp +Added in version 242\&. +.RE +.SH "[MACSEC] SECTION OPTIONS" +.PP +The [MACsec] section only applies for network devices of kind +"macsec", and accepts the following keys: +.PP +\fIPort=\fR +.RS 4 +Specifies the port to be used for the MACsec transmit channel\&. The port is used to make secure channel identifier (SCI)\&. Takes a value between 1 and 65535\&. Defaults to unset\&. +.sp +Added in version 243\&. +.RE +.PP +\fIEncrypt=\fR +.RS 4 +Takes a boolean\&. When true, enable encryption\&. Defaults to unset\&. +.sp +Added in version 243\&. +.RE +.SH "[MACSECRECEIVECHANNEL] SECTION OPTIONS" +.PP +The [MACsecReceiveChannel] section only applies for network devices of kind +"macsec", and accepts the following keys: +.PP +\fIPort=\fR +.RS 4 +Specifies the port to be used for the MACsec receive channel\&. The port is used to make secure channel identifier (SCI)\&. Takes a value between 1 and 65535\&. This option is compulsory, and is not set by default\&. +.sp +Added in version 243\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +Specifies the MAC address to be used for the MACsec receive channel\&. The MAC address used to make secure channel identifier (SCI)\&. This setting is compulsory, and is not set by default\&. +.sp +Added in version 243\&. +.RE +.SH "[MACSECTRANSMITASSOCIATION] SECTION OPTIONS" +.PP +The [MACsecTransmitAssociation] section only applies for network devices of kind +"macsec", and accepts the following keys: +.PP +\fIPacketNumber=\fR +.RS 4 +Specifies the packet number to be used for replay protection and the construction of the initialization vector (along with the secure channel identifier [SCI])\&. Takes a value between 1\-4,294,967,295\&. Defaults to unset\&. +.sp +Added in version 243\&. +.RE +.PP +\fIKeyId=\fR +.RS 4 +Specifies the identification for the key\&. Takes a number between 0\-255\&. This option is compulsory, and is not set by default\&. +.sp +Added in version 243\&. +.RE +.PP +\fIKey=\fR +.RS 4 +Specifies the encryption key used in the transmission channel\&. The same key must be configured on the peer\(cqs matching receive channel\&. This setting is compulsory, and is not set by default\&. Takes a 128\-bit key encoded in a hexadecimal string, for example +"dffafc8d7b9a43d5b9a3dfbbf6a30c16"\&. +.sp +Added in version 243\&. +.RE +.PP +\fIKeyFile=\fR +.RS 4 +Takes an absolute path to a file which contains a 128\-bit key encoded in a hexadecimal string, which will be used in the transmission channel\&. When this option is specified, +\fIKey=\fR +is ignored\&. Note that the file must be readable by the user +"systemd\-network", so it should be, e\&.g\&., owned by +"root:systemd\-network" +with a +"0640" +file mode\&. If the path refers to an +\fBAF_UNIX\fR +stream socket in the file system a connection is made to it and the key read from it\&. +.sp +Added in version 243\&. +.RE +.PP +\fIActivate=\fR +.RS 4 +Takes a boolean\&. If enabled, then the security association is activated\&. Defaults to unset\&. +.sp +Added in version 243\&. +.RE +.PP +\fIUseForEncoding=\fR +.RS 4 +Takes a boolean\&. If enabled, then the security association is used for encoding\&. Only one [MACsecTransmitAssociation] section can enable this option\&. When enabled, +\fIActivate=yes\fR +is implied\&. Defaults to unset\&. +.sp +Added in version 243\&. +.RE +.SH "[MACSECRECEIVEASSOCIATION] SECTION OPTIONS" +.PP +The [MACsecReceiveAssociation] section only applies for network devices of kind +"macsec", and accepts the following keys: +.PP +\fIPort=\fR +.RS 4 +Accepts the same key as in [MACsecReceiveChannel] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +Accepts the same key as in [MACsecReceiveChannel] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIPacketNumber=\fR +.RS 4 +Accepts the same key as in [MACsecTransmitAssociation] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIKeyId=\fR +.RS 4 +Accepts the same key as in [MACsecTransmitAssociation] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIKey=\fR +.RS 4 +Accepts the same key as in [MACsecTransmitAssociation] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIKeyFile=\fR +.RS 4 +Accepts the same key as in [MACsecTransmitAssociation] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fIActivate=\fR +.RS 4 +Accepts the same key as in [MACsecTransmitAssociation] section\&. +.sp +Added in version 243\&. +.RE +.SH "[TUNNEL] SECTION OPTIONS" +.PP +The [Tunnel] section only applies for netdevs of kind +"ipip", +"sit", +"gre", +"gretap", +"ip6gre", +"ip6gretap", +"vti", +"vti6", +"ip6tnl", and +"erspan" +and accepts the following keys: +.PP +\fIExternal=\fR +.RS 4 +Takes a boolean value\&. When true, then the tunnel is externally controlled, which is also known as collect metadata mode, and most settings below like +\fILocal=\fR +or +\fIRemote=\fR +are ignored\&. This implies +\fIIndependent=\fR\&. Defaults to false\&. +.sp +Added in version 251\&. +.RE +.PP +\fILocal=\fR +.RS 4 +A static local address for tunneled packets\&. It must be an address on another interface of this host, or one of the special values +"any", +"ipv4_link_local", +"ipv6_link_local", +"dhcp4", +"dhcp6", and +"slaac"\&. If one of the special values except for +"any" +is specified, an address which matches the corresponding type on the underlying interface will be used\&. Defaults to +"any"\&. +.sp +Added in version 215\&. +.RE +.PP +\fIRemote=\fR +.RS 4 +The remote endpoint of the tunnel\&. Takes an IP address or the special value +"any"\&. +.sp +Added in version 215\&. +.RE +.PP +\fITOS=\fR +.RS 4 +The Type Of Service byte value for a tunnel interface\&. For details about the TOS, see the +\m[blue]\fBType of Service in the Internet Protocol Suite\fR\m[]\&\s-2\u[10]\d\s+2 +document\&. +.sp +Added in version 215\&. +.RE +.PP +\fITTL=\fR +.RS 4 +A fixed Time To Live N on tunneled packets\&. N is a number in the range 1\&...255\&. 0 is a special value meaning that packets inherit the TTL value\&. The default value for IPv4 tunnels is 0 (inherit)\&. The default value for IPv6 tunnels is 64\&. +.sp +Added in version 215\&. +.RE +.PP +\fIDiscoverPathMTU=\fR +.RS 4 +Takes a boolean\&. When true, enables Path MTU Discovery on the tunnel\&. When +\fIIgnoreDontFragment=\fR +is enabled, defaults to false\&. Otherwise, defaults to true\&. +.sp +Added in version 215\&. +.RE +.PP +\fIIgnoreDontFragment=\fR +.RS 4 +Takes a boolean\&. When true, enables IPv4 Don\*(Aqt Fragment (DF) suppression on the tunnel\&. Defaults to false\&. Note that if +\fIIgnoreDontFragment=\fR +is set to true, +\fIDiscoverPathMTU=\fR +cannot be set to true\&. Only applicable to GRE, GRETAP, and ERSPAN tunnels\&. +.sp +Added in version 254\&. +.RE +.PP +\fIIPv6FlowLabel=\fR +.RS 4 +Configures the 20\-bit flow label (see +\m[blue]\fBRFC 6437\fR\m[]\&\s-2\u[11]\d\s+2) field in the IPv6 header (see +\m[blue]\fBRFC 2460\fR\m[]\&\s-2\u[12]\d\s+2), which is used by a node to label packets of a flow\&. It is only used for IPv6 tunnels\&. A flow label of zero is used to indicate packets that have not been labeled\&. It can be configured to a value in the range 0\&...0xFFFFF, or be set to +"inherit", in which case the original flowlabel is used\&. +.sp +Added in version 223\&. +.RE +.PP +\fICopyDSCP=\fR +.RS 4 +Takes a boolean\&. When true, the Differentiated Service Code Point (DSCP) field will be copied to the inner header from outer header during the decapsulation of an IPv6 tunnel packet\&. DSCP is a field in an IP packet that enables different levels of service to be assigned to network traffic\&. Defaults to +"no"\&. +.sp +Added in version 223\&. +.RE +.PP +\fIEncapsulationLimit=\fR +.RS 4 +The Tunnel Encapsulation Limit option specifies how many additional levels of encapsulation are permitted to be prepended to the packet\&. For example, a Tunnel Encapsulation Limit option containing a limit value of zero means that a packet carrying that option may not enter another tunnel before exiting the current tunnel\&. (see +\m[blue]\fBRFC 2473\fR\m[]\&\s-2\u[13]\d\s+2)\&. The valid range is 0\&...255 and +"none"\&. Defaults to 4\&. +.sp +Added in version 226\&. +.RE +.PP +\fIKey=\fR +.RS 4 +The +\fIKey=\fR +parameter specifies the same key to use in both directions (\fIInputKey=\fR +and +\fIOutputKey=\fR)\&. The +\fIKey=\fR +is either a number or an IPv4 address\-like dotted quad\&. It is used as mark\-configured SAD/SPD entry as part of the lookup key (both in data and control path) in IP XFRM (framework used to implement IPsec protocol)\&. See +\m[blue]\fBip\-xfrm \(em transform configuration\fR\m[]\&\s-2\u[14]\d\s+2 +for details\&. It is only used for VTI/VTI6, GRE, GRETAP, and ERSPAN tunnels\&. +.sp +Added in version 231\&. +.RE +.PP +\fIInputKey=\fR +.RS 4 +The +\fIInputKey=\fR +parameter specifies the key to use for input\&. The format is same as +\fIKey=\fR\&. It is only used for VTI/VTI6, GRE, GRETAP, and ERSPAN tunnels\&. +.sp +Added in version 231\&. +.RE +.PP +\fIOutputKey=\fR +.RS 4 +The +\fIOutputKey=\fR +parameter specifies the key to use for output\&. The format is same as +\fIKey=\fR\&. It is only used for VTI/VTI6, GRE, GRETAP, and ERSPAN tunnels\&. +.sp +Added in version 231\&. +.RE +.PP +\fIMode=\fR +.RS 4 +An +"ip6tnl" +tunnel can be in one of three modes +"ip6ip6" +for IPv6 over IPv6, +"ipip6" +for IPv4 over IPv6 or +"any" +for either\&. +.sp +Added in version 219\&. +.RE +.PP +\fIIndependent=\fR +.RS 4 +Takes a boolean\&. When false (the default), the tunnel is always created over some network device, and a \&.network file that requests this tunnel using +\fITunnel=\fR +is required for the tunnel to be created\&. When true, the tunnel is created independently of any network as "tunnel@NONE"\&. +.sp +Added in version 235\&. +.RE +.PP +\fIAssignToLoopback=\fR +.RS 4 +Takes a boolean\&. If set to +"yes", the loopback interface +"lo" +is used as the underlying device of the tunnel interface\&. Defaults to +"no"\&. +.sp +Added in version 243\&. +.RE +.PP +\fIAllowLocalRemote=\fR +.RS 4 +Takes a boolean\&. When true allows tunnel traffic on +\fIip6tnl\fR +devices where the remote endpoint is a local host address\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 237\&. +.RE +.PP +\fIFooOverUDP=\fR +.RS 4 +Takes a boolean\&. Specifies whether +\fIFooOverUDP=\fR +tunnel is to be configured\&. Defaults to false\&. This takes effects only for IPIP, SIT, GRE, and GRETAP tunnels\&. For more detail information see +\m[blue]\fBFoo over UDP\fR\m[]\&\s-2\u[15]\d\s+2 +.sp +Added in version 240\&. +.RE +.PP +\fIFOUDestinationPort=\fR +.RS 4 +This setting specifies the UDP destination port for encapsulation\&. This field is mandatory when +\fIFooOverUDP=yes\fR, and is not set by default\&. +.sp +Added in version 240\&. +.RE +.PP +\fIFOUSourcePort=\fR +.RS 4 +This setting specifies the UDP source port for encapsulation\&. Defaults to +\fB0\fR +\(em that is, the source port for packets is left to the network stack to decide\&. +.sp +Added in version 240\&. +.RE +.PP +\fIEncapsulation=\fR +.RS 4 +Accepts the same key as in the [FooOverUDP] section\&. +.sp +Added in version 240\&. +.RE +.PP +\fIIPv6RapidDeploymentPrefix=\fR +.RS 4 +Reconfigure the tunnel for +\m[blue]\fBIPv6 Rapid Deployment\fR\m[]\&\s-2\u[16]\d\s+2, also known as 6rd\&. The value is an ISP\-specific IPv6 prefix with a non\-zero length\&. Only applicable to SIT tunnels\&. +.sp +Added in version 240\&. +.RE +.PP +\fIISATAP=\fR +.RS 4 +Takes a boolean\&. If set, configures the tunnel as Intra\-Site Automatic Tunnel Addressing Protocol (ISATAP) tunnel\&. Only applicable to SIT tunnels\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 240\&. +.RE +.PP +\fISerializeTunneledPackets=\fR +.RS 4 +Takes a boolean\&. If set to yes, then packets are serialized\&. Only applies for GRE, GRETAP, and ERSPAN tunnels\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 240\&. +.RE +.PP +\fIERSPANVersion=\fR +.RS 4 +Specifies the ERSPAN version number\&. Takes 0 for version 0 (a\&.k\&.a\&. type I), 1 for version 1 (a\&.k\&.a\&. type II), or 2 for version 2 (a\&.k\&.a\&. type III)\&. Defaults to 1\&. +.sp +Added in version 252\&. +.RE +.PP +\fIERSPANIndex=\fR +.RS 4 +Specifies the ERSPAN v1 index field for the interface\&. Takes an integer in the range 0\&...1048575, which is associated with the ERSPAN traffic\*(Aqs source port and direction\&. Only used when +\fIERSPANVersion=1\fR\&. Defaults to 0\&. +.sp +Added in version 240\&. +.RE +.PP +\fIERSPANDirection=\fR +.RS 4 +Specifies the ERSPAN v2 mirrored traffic\*(Aqs direction\&. Takes +"ingress" +or +"egress"\&. Only used when +\fIERSPANVersion=2\fR\&. Defaults to +"ingress"\&. +.sp +Added in version 252\&. +.RE +.PP +\fIERSPANHardwareId=\fR +.RS 4 +Specifies an unique identifier of the ERSPAN v2 engine\&. Takes an integer in the range 0\&...63\&. Only used when +\fIERSPANVersion=2\fR\&. Defaults to 0\&. +.sp +Added in version 252\&. +.RE +.SH "[FOOOVERUDP] SECTION OPTIONS" +.PP +The [FooOverUDP] section only applies for netdevs of kind +"fou" +and accepts the following keys: +.PP +\fIEncapsulation=\fR +.RS 4 +Specifies the encapsulation mechanism used to store networking packets of various protocols inside the UDP packets\&. Supports the following values: +"FooOverUDP" +provides the simplest no\-frills model of UDP encapsulation, it simply encapsulates packets directly in the UDP payload\&. +"GenericUDPEncapsulation" +is a generic and extensible encapsulation, it allows encapsulation of packets for any IP protocol and optional data as part of the encapsulation\&. For more detailed information see +\m[blue]\fBGeneric UDP Encapsulation\fR\m[]\&\s-2\u[17]\d\s+2\&. Defaults to +"FooOverUDP"\&. +.sp +Added in version 240\&. +.RE +.PP +\fIPort=\fR +.RS 4 +Specifies the port number where the encapsulated packets will arrive\&. Those packets will be removed and manually fed back into the network stack with the encapsulation removed to be sent to the real destination\&. This option is mandatory\&. +.sp +Added in version 240\&. +.RE +.PP +\fIPeerPort=\fR +.RS 4 +Specifies the peer port number\&. Defaults to unset\&. Note that when peer port is set +"Peer=" +address is mandatory\&. +.sp +Added in version 243\&. +.RE +.PP +\fIProtocol=\fR +.RS 4 +The +\fIProtocol=\fR +specifies the protocol number of the packets arriving at the UDP port\&. When +\fIEncapsulation=FooOverUDP\fR, this field is mandatory and is not set by default\&. Takes an IP protocol name such as +"gre" +or +"ipip", or an integer within the range 1\&...255\&. When +\fIEncapsulation=GenericUDPEncapsulation\fR, this must not be specified\&. +.sp +Added in version 240\&. +.RE +.PP +\fIPeer=\fR +.RS 4 +Configures peer IP address\&. Note that when peer address is set +"PeerPort=" +is mandatory\&. +.sp +Added in version 243\&. +.RE +.PP +\fILocal=\fR +.RS 4 +Configures local IP address\&. +.sp +Added in version 243\&. +.RE +.SH "[PEER] SECTION OPTIONS" +.PP +The [Peer] section only applies for netdevs of kind +"veth" +and accepts the following keys: +.PP +\fIName=\fR +.RS 4 +The interface name used when creating the netdev\&. This setting is compulsory\&. +.sp +Added in version 215\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +The peer MACAddress, if not set, it is generated in the same way as the MAC address of the main interface\&. +.sp +Added in version 215\&. +.RE +.SH "[VXCAN] SECTION OPTIONS" +.PP +The [VXCAN] section only applies for netdevs of kind +"vxcan" +and accepts the following key: +.PP +\fIPeer=\fR +.RS 4 +The peer interface name used when creating the netdev\&. This setting is compulsory\&. +.sp +Added in version 236\&. +.RE +.SH "[TUN] SECTION OPTIONS" +.PP +The [Tun] section only applies for netdevs of kind +"tun", and accepts the following keys: +.PP +\fIMultiQueue=\fR +.RS 4 +Takes a boolean\&. Configures whether to use multiple file descriptors (queues) to parallelize packets sending and receiving\&. Defaults to +"no"\&. +.sp +Added in version 215\&. +.RE +.PP +\fIPacketInfo=\fR +.RS 4 +Takes a boolean\&. Configures whether packets should be prepended with four extra bytes (two flag bytes and two protocol bytes)\&. If disabled, it indicates that the packets will be pure IP packets\&. Defaults to +"no"\&. +.sp +Added in version 215\&. +.RE +.PP +\fIVNetHeader=\fR +.RS 4 +Takes a boolean\&. Configures IFF_VNET_HDR flag for a tun or tap device\&. It allows sending and receiving larger Generic Segmentation Offload (GSO) packets\&. This may increase throughput significantly\&. Defaults to +"no"\&. +.sp +Added in version 223\&. +.RE +.PP +\fIUser=\fR +.RS 4 +User to grant access to the +/dev/net/tun +device\&. +.sp +Added in version 215\&. +.RE +.PP +\fIGroup=\fR +.RS 4 +Group to grant access to the +/dev/net/tun +device\&. +.sp +Added in version 215\&. +.RE +.PP +\fIKeepCarrier=\fR +.RS 4 +Takes a boolean\&. If enabled, to make the interface maintain its carrier status, the file descriptor of the interface is kept open\&. This may be useful to keep the interface in running state, for example while the backing process is temporarily shutdown\&. Defaults to +"no"\&. +.sp +Added in version 252\&. +.RE +.SH "[TAP] SECTION OPTIONS" +.PP +The [Tap] section only applies for netdevs of kind +"tap", and accepts the same keys as the [Tun] section\&. +.SH "[WIREGUARD] SECTION OPTIONS" +.PP +The [WireGuard] section accepts the following keys: +.PP +\fIPrivateKey=\fR +.RS 4 +The Base64 encoded private key for the interface\&. It can be generated using the +\fBwg genkey\fR +command (see +\fBwg\fR(8))\&. This option or +\fIPrivateKeyFile=\fR +is mandatory to use WireGuard\&. Note that because this information is secret, you may want to set the permissions of the \&.netdev file to be owned by +"root:systemd\-network" +with a +"0640" +file mode\&. +.sp +Added in version 237\&. +.RE +.PP +\fIPrivateKeyFile=\fR +.RS 4 +Takes an absolute path to a file which contains the Base64 encoded private key for the interface\&. When this option is specified, then +\fIPrivateKey=\fR +is ignored\&. Note that the file must be readable by the user +"systemd\-network", so it should be, e\&.g\&., owned by +"root:systemd\-network" +with a +"0640" +file mode\&. If the path refers to an +\fBAF_UNIX\fR +stream socket in the file system a connection is made to it and the key read from it\&. +.sp +Added in version 242\&. +.RE +.PP +\fIListenPort=\fR +.RS 4 +Sets UDP port for listening\&. Takes either value between 1 and 65535 or +"auto"\&. If +"auto" +is specified, the port is automatically generated based on interface name\&. Defaults to +"auto"\&. +.sp +Added in version 237\&. +.RE +.PP +\fIFirewallMark=\fR +.RS 4 +Sets a firewall mark on outgoing WireGuard packets from this interface\&. Takes a number between 1 and 4294967295\&. +.sp +Added in version 243\&. +.RE +.PP +\fIRouteTable=\fR +.RS 4 +The table identifier for the routes to the addresses specified in the +\fIAllowedIPs=\fR\&. Takes a negative boolean value, one of the predefined names +"default", +"main", and +"local", names defined in +\fIRouteTable=\fR +in +\fBnetworkd.conf\fR(5), or a number in the range 1\&...4294967295\&. When +"off" +the routes to the addresses specified in the +\fIAllowedIPs=\fR +setting will not be configured\&. Defaults to false\&. This setting will be ignored when the same setting is specified in the [WireGuardPeer] section\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +The priority of the routes to the addresses specified in the +\fIAllowedIPs=\fR\&. Takes an integer in the range 0\&...4294967295\&. Defaults to 0 for IPv4 addresses, and 1024 for IPv6 addresses\&. This setting will be ignored when the same setting is specified in the [WireGuardPeer] section\&. +.sp +Added in version 250\&. +.RE +.SH "[WIREGUARDPEER] SECTION OPTIONS" +.PP +The [WireGuardPeer] section accepts the following keys: +.PP +\fIPublicKey=\fR +.RS 4 +Sets a Base64 encoded public key calculated by +\fBwg pubkey\fR +(see +\fBwg\fR(8)) from a private key, and usually transmitted out of band to the author of the configuration file\&. This option is mandatory for this section\&. +.sp +Added in version 237\&. +.RE +.PP +\fIPresharedKey=\fR +.RS 4 +Optional preshared key for the interface\&. It can be generated by the +\fBwg genpsk\fR +command\&. This option adds an additional layer of symmetric\-key cryptography to be mixed into the already existing public\-key cryptography, for post\-quantum resistance\&. Note that because this information is secret, you may want to set the permissions of the \&.netdev file to be owned by +"root:systemd\-network" +with a +"0640" +file mode\&. +.sp +Added in version 237\&. +.RE +.PP +\fIPresharedKeyFile=\fR +.RS 4 +Takes an absolute path to a file which contains the Base64 encoded preshared key for the peer\&. When this option is specified, then +\fIPresharedKey=\fR +is ignored\&. Note that the file must be readable by the user +"systemd\-network", so it should be, e\&.g\&., owned by +"root:systemd\-network" +with a +"0640" +file mode\&. If the path refers to an +\fBAF_UNIX\fR +stream socket in the file system a connection is made to it and the key read from it\&. +.sp +Added in version 242\&. +.RE +.PP +\fIAllowedIPs=\fR +.RS 4 +Sets a comma\-separated list of IP (v4 or v6) addresses with CIDR masks from which this peer is allowed to send incoming traffic and to which outgoing traffic for this peer is directed\&. This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. +.sp +The catch\-all 0\&.0\&.0\&.0/0 may be specified for matching all IPv4 addresses, and ::/0 may be specified for matching all IPv6 addresses\&. +.sp +Note that this only affects +\fIrouting inside the network interface itself\fR, i\&.e\&. the packets that pass through the tunnel itself\&. To cause packets to be sent via the tunnel in the first place, an appropriate route needs to be added as well \(em either in the +"[Routes]" +section on the +"\&.network" +matching the wireguard interface, or externally to +systemd\-networkd\&. +.sp +Added in version 237\&. +.RE +.PP +\fIEndpoint=\fR +.RS 4 +Sets an endpoint IP address or hostname, followed by a colon, and then a port number\&. IPv6 address must be in the square brackets\&. For example, +"111\&.222\&.333\&.444:51820" +for IPv4 and +"[1111:2222::3333]:51820" +for IPv6 address\&. This endpoint will be updated automatically once to the most recent source IP address and port of correctly authenticated packets from the peer at configuration time\&. +.sp +Added in version 237\&. +.RE +.PP +\fIPersistentKeepalive=\fR +.RS 4 +Sets a seconds interval, between 1 and 65535 inclusive, of how often to send an authenticated empty packet to the peer for the purpose of keeping a stateful firewall or NAT mapping valid persistently\&. For example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds\&. If set to 0 or "off", this option is disabled\&. By default or when unspecified, this option is off\&. Most users will not need this\&. +.sp +Added in version 237\&. +.RE +.PP +\fIRouteTable=\fR +.RS 4 +The table identifier for the routes to the addresses specified in the +\fIAllowedIPs=\fR\&. Takes a negative boolean value, one of the predefined names +"default", +"main", and +"local", names defined in +\fIRouteTable=\fR +in +\fBnetworkd.conf\fR(5), or a number in the range 1\&...4294967295\&. Defaults to unset, and the value specified in the same setting in the [WireGuard] section will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +The priority of the routes to the addresses specified in the +\fIAllowedIPs=\fR\&. Takes an integer in the range 0\&...4294967295\&. Defaults to unset, and the value specified in the same setting in the [WireGuard] section will be used\&. +.sp +Added in version 250\&. +.RE +.SH "[BOND] SECTION OPTIONS" +.PP +The [Bond] section accepts the following key: +.PP +\fIMode=\fR +.RS 4 +Specifies one of the bonding policies\&. The default is +"balance\-rr" +(round robin)\&. Possible values are +"balance\-rr", +"active\-backup", +"balance\-xor", +"broadcast", +"802\&.3ad", +"balance\-tlb", and +"balance\-alb"\&. +.sp +Added in version 216\&. +.RE +.PP +\fITransmitHashPolicy=\fR +.RS 4 +Selects the transmit hash policy to use for slave selection in balance\-xor, 802\&.3ad, and tlb modes\&. Possible values are +"layer2", +"layer3+4", +"layer2+3", +"encap2+3", and +"encap3+4"\&. +.sp +Added in version 216\&. +.RE +.PP +\fILACPTransmitRate=\fR +.RS 4 +Specifies the rate with which link partner transmits Link Aggregation Control Protocol Data Unit packets in 802\&.3ad mode\&. Possible values are +"slow", which requests partner to transmit LACPDUs every 30 seconds, and +"fast", which requests partner to transmit LACPDUs every second\&. The default value is +"slow"\&. +.sp +Added in version 216\&. +.RE +.PP +\fIMIIMonitorSec=\fR +.RS 4 +Specifies the frequency that Media Independent Interface link monitoring will occur\&. A value of zero disables MII link monitoring\&. This value is rounded down to the nearest millisecond\&. The default value is 0\&. +.sp +Added in version 216\&. +.RE +.PP +\fIUpDelaySec=\fR +.RS 4 +Specifies the delay before a link is enabled after a link up status has been detected\&. This value is rounded down to a multiple of +\fIMIIMonitorSec=\fR\&. The default value is 0\&. +.sp +Added in version 216\&. +.RE +.PP +\fIDownDelaySec=\fR +.RS 4 +Specifies the delay before a link is disabled after a link down status has been detected\&. This value is rounded down to a multiple of +\fIMIIMonitorSec=\fR\&. The default value is 0\&. +.sp +Added in version 216\&. +.RE +.PP +\fILearnPacketIntervalSec=\fR +.RS 4 +Specifies the number of seconds between instances where the bonding driver sends learning packets to each slave peer switch\&. The valid range is 1\&...0x7fffffff; the default value is 1\&. This option has an effect only for the balance\-tlb and balance\-alb modes\&. +.sp +Added in version 220\&. +.RE +.PP +\fIAdSelect=\fR +.RS 4 +Specifies the 802\&.3ad aggregation selection logic to use\&. Possible values are +"stable", +"bandwidth" +and +"count"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIAdActorSystemPriority=\fR +.RS 4 +Specifies the 802\&.3ad actor system priority\&. Takes a number in the range 1\&...65535\&. +.sp +Added in version 240\&. +.RE +.PP +\fIAdUserPortKey=\fR +.RS 4 +Specifies the 802\&.3ad user defined portion of the port key\&. Takes a number in the range 0\&...1023\&. +.sp +Added in version 240\&. +.RE +.PP +\fIAdActorSystem=\fR +.RS 4 +Specifies the 802\&.3ad system MAC address\&. This cannot be a null or multicast address\&. +.sp +Added in version 240\&. +.RE +.PP +\fIFailOverMACPolicy=\fR +.RS 4 +Specifies whether the active\-backup mode should set all slaves to the same MAC address at the time of enslavement or, when enabled, to perform special handling of the bond\*(Aqs MAC address in accordance with the selected policy\&. The default policy is none\&. Possible values are +"none", +"active" +and +"follow"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIARPValidate=\fR +.RS 4 +Specifies whether or not ARP probes and replies should be validated in any mode that supports ARP monitoring, or whether non\-ARP traffic should be filtered (disregarded) for link monitoring purposes\&. Possible values are +"none", +"active", +"backup" +and +"all"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIARPIntervalSec=\fR +.RS 4 +Specifies the ARP link monitoring frequency\&. A value of 0 disables ARP monitoring\&. The default value is 0, and the default unit seconds\&. +.sp +Added in version 220\&. +.RE +.PP +\fIARPIPTargets=\fR +.RS 4 +Specifies the IP addresses to use as ARP monitoring peers when +\fIARPIntervalSec=\fR +is greater than 0\&. These are the targets of the ARP request sent to determine the health of the link to the targets\&. Specify these values in IPv4 dotted decimal format\&. At least one IP address must be given for ARP monitoring to function\&. The maximum number of targets that can be specified is 16\&. The default value is no IP addresses\&. +.sp +Added in version 220\&. +.RE +.PP +\fIARPAllTargets=\fR +.RS 4 +Specifies the quantity of +\fIARPIPTargets=\fR +that must be reachable in order for the ARP monitor to consider a slave as being up\&. This option affects only active\-backup mode for slaves with ARPValidate enabled\&. Possible values are +"any" +and +"all"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIPrimaryReselectPolicy=\fR +.RS 4 +Specifies the reselection policy for the primary slave\&. This affects how the primary slave is chosen to become the active slave when failure of the active slave or recovery of the primary slave occurs\&. This option is designed to prevent flip\-flopping between the primary slave and other slaves\&. Possible values are +"always", +"better" +and +"failure"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIResendIGMP=\fR +.RS 4 +Specifies the number of IGMP membership reports to be issued after a failover event\&. One membership report is issued immediately after the failover, subsequent packets are sent in each 200ms interval\&. The valid range is 0\&...255\&. Defaults to 1\&. A value of 0 prevents the IGMP membership report from being issued in response to the failover event\&. +.sp +Added in version 220\&. +.RE +.PP +\fIPacketsPerSlave=\fR +.RS 4 +Specify the number of packets to transmit through a slave before moving to the next one\&. When set to 0, then a slave is chosen at random\&. The valid range is 0\&...65535\&. Defaults to 1\&. This option only has effect when in balance\-rr mode\&. +.sp +Added in version 220\&. +.RE +.PP +\fIGratuitousARP=\fR +.RS 4 +Specify the number of peer notifications (gratuitous ARPs and unsolicited IPv6 Neighbor Advertisements) to be issued after a failover event\&. As soon as the link is up on the new slave, a peer notification is sent on the bonding device and each VLAN sub\-device\&. This is repeated at each link monitor interval (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is greater than 1\&. The valid range is 0\&...255\&. The default value is 1\&. These options affect only the active\-backup mode\&. +.sp +Added in version 220\&. +.RE +.PP +\fIAllSlavesActive=\fR +.RS 4 +Takes a boolean\&. Specifies that duplicate frames (received on inactive ports) should be dropped when false, or delivered when true\&. Normally, bonding will drop duplicate frames (received on inactive ports), which is desirable for most users\&. But there are some times it is nice to allow duplicate frames to be delivered\&. The default value is false (drop duplicate frames received on inactive ports)\&. +.sp +Added in version 220\&. +.RE +.PP +\fIDynamicTransmitLoadBalancing=\fR +.RS 4 +Takes a boolean\&. Specifies if dynamic shuffling of flows is enabled\&. Applies only for balance\-tlb mode\&. Defaults to unset\&. +.sp +Added in version 240\&. +.RE +.PP +\fIMinLinks=\fR +.RS 4 +Specifies the minimum number of links that must be active before asserting carrier\&. The default value is 0\&. +.sp +Added in version 220\&. +.RE +.PP +For more detail information see +\m[blue]\fBLinux Ethernet Bonding Driver HOWTO\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "[XFRM] SECTION OPTIONS" +.PP +The [Xfrm] section accepts the following keys: +.PP +\fIInterfaceId=\fR +.RS 4 +Sets the ID/key of the xfrm interface which needs to be associated with a SA/policy\&. Can be decimal or hexadecimal, valid range is 1\-0xffffffff\&. This is mandatory\&. +.sp +Added in version 243\&. +.RE +.PP +\fIIndependent=\fR +.RS 4 +Takes a boolean\&. If false (the default), the xfrm interface must have an underlying device which can be used for hardware offloading\&. +.sp +Added in version 243\&. +.RE +.PP +For more detail information see +\m[blue]\fBVirtual XFRM Interfaces\fR\m[]\&\s-2\u[18]\d\s+2\&. +.SH "[VRF] SECTION OPTIONS" +.PP +The [VRF] section only applies for netdevs of kind +"vrf" +and accepts the following key: +.PP +\fITable=\fR +.RS 4 +The numeric routing table identifier\&. This setting is compulsory\&. +.sp +Added in version 243\&. +.RE +.SH "[BATMANADVANCED] SECTION OPTIONS" +.PP +The [BatmanAdvanced] section only applies for netdevs of kind +"batadv" +and accepts the following keys: +.PP +\fIGatewayMode=\fR +.RS 4 +Takes one of +"off", +"server", or +"client"\&. A batman\-adv node can either run in server mode (sharing its internet connection with the mesh) or in client mode (searching for the most suitable internet connection in the mesh) or having the gateway support turned off entirely (which is the default setting)\&. +.sp +Added in version 248\&. +.RE +.PP +\fIAggregation=\fR +.RS 4 +Takes a boolean value\&. Enables or disables aggregation of originator messages\&. Defaults to true\&. +.sp +Added in version 248\&. +.RE +.PP +\fIBridgeLoopAvoidance=\fR +.RS 4 +Takes a boolean value\&. Enables or disables avoidance of loops on bridges\&. Defaults to true\&. +.sp +Added in version 248\&. +.RE +.PP +\fIDistributedArpTable=\fR +.RS 4 +Takes a boolean value\&. Enables or disables the distributed ARP table\&. Defaults to true\&. +.sp +Added in version 248\&. +.RE +.PP +\fIFragmentation=\fR +.RS 4 +Takes a boolean value\&. Enables or disables fragmentation\&. Defaults to true\&. +.sp +Added in version 248\&. +.RE +.PP +\fIHopPenalty=\fR +.RS 4 +The hop penalty setting allows one to modify +\fBbatctl\fR(8) +preference for multihop routes vs\&. short routes\&. This integer value is applied to the TQ (Transmit Quality) of each forwarded OGM (Originator Message), thereby propagating the cost of an extra hop (the packet has to be received and retransmitted which costs airtime)\&. A higher hop penalty will make it more unlikely that other nodes will choose this node as intermediate hop towards any given destination\&. The default hop penalty of \*(Aq15\*(Aq is a reasonable value for most setups and probably does not need to be changed\&. However, mobile nodes could choose a value of 255 (maximum value) to avoid being chosen as a router by other nodes\&. The minimum value is 0\&. +.sp +Added in version 248\&. +.RE +.PP +\fIOriginatorIntervalSec=\fR +.RS 4 +The value specifies the interval in seconds, unless another time unit is specified in which batman\-adv floods the network with its protocol information\&. See +\fBsystemd.time\fR(7) +for more information\&. +.sp +Added in version 248\&. +.RE +.PP +\fIGatewayBandwidthDown=\fR +.RS 4 +If the node is a server, this parameter is used to inform other nodes in the network about this node\*(Aqs internet connection download bandwidth in bits per second\&. Just enter any number suffixed with K, M, G or T (base 1000) and the batman\-adv module will propagate the entered value in the mesh\&. +.sp +Added in version 248\&. +.RE +.PP +\fIGatewayBandwidthUp=\fR +.RS 4 +If the node is a server, this parameter is used to inform other nodes in the network about this node\*(Aqs internet connection upload bandwidth in bits per second\&. Just enter any number suffixed with K, M, G or T (base 1000) and the batman\-adv module will propagate the entered value in the mesh\&. +.sp +Added in version 248\&. +.RE +.PP +\fIRoutingAlgorithm=\fR +.RS 4 +This can be either +"batman\-v" +or +"batman\-iv" +and describes which routing_algo of +\fBbatctl\fR(8) +to use\&. The algorithm cannot be changed after interface creation\&. Defaults to +"batman\-v"\&. +.sp +Added in version 248\&. +.RE +.SH "[IPOIB] SECTION OPTIONS" +.PP +The [IPoIB] section only applies for netdevs of kind +"ipoib" +and accepts the following keys: +.PP +\fIPartitionKey=\fR +.RS 4 +Takes an integer in the range 1\&...0xffff, except for 0x8000\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIMode=\fR +.RS 4 +Takes one of the special values +"datagram" +or +"connected"\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +When +"datagram", the Infiniband unreliable datagram (UD) transport is used, and so the interface MTU is equal to the IB L2 MTU minus the IPoIB encapsulation header (4 bytes)\&. For example, in a typical IB fabric with a 2K MTU, the IPoIB MTU will be 2048 \- 4 = 2044 bytes\&. +.sp +When +"connected", the Infiniband reliable connected (RC) transport is used\&. Connected mode takes advantage of the connected nature of the IB transport and allows an MTU up to the maximal IP packet size of 64K, which reduces the number of IP packets needed for handling large UDP datagrams, TCP segments, etc and increases the performance for large messages\&. +.sp +Added in version 250\&. +.RE +.PP +\fIIgnoreUserspaceMulticastGroup=\fR +.RS 4 +Takes an boolean value\&. When true, the kernel ignores multicast groups handled by userspace\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.SH "[WLAN] SECTION OPTIONS" +.PP +The [WLAN] section only applies to WLAN interfaces, and accepts the following keys: +.PP +\fIPhysicalDevice=\fR +.RS 4 +Specifies the name or index of the physical WLAN device (e\&.g\&. +"0" +or +"phy0")\&. The list of the physical WLAN devices that exist on the host can be obtained by +\fBiw phy\fR +command\&. This option is mandatory\&. +.sp +Added in version 251\&. +.RE +.PP +\fIType=\fR +.RS 4 +Specifies the type of the interface\&. Takes one of the +"ad\-hoc", +"station", +"ap", +"ap\-vlan", +"wds", +"monitor", +"mesh\-point", +"p2p\-client", +"p2p\-go", +"p2p\-device", +"ocb", and +"nan"\&. This option is mandatory\&. +.sp +Added in version 251\&. +.RE +.PP +\fIWDS=\fR +.RS 4 +Enables the Wireless Distribution System (WDS) mode on the interface\&. The mode is also known as the +"4 address mode"\&. Takes a boolean value\&. Defaults to unset, and the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&/etc/systemd/network/25\-bridge\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=bridge0 +Kind=bridge +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&/etc/systemd/network/25\-vlan1\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Match] +Virtualization=no + +[NetDev] +Name=vlan1 +Kind=vlan + +[VLAN] +Id=1 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&/etc/systemd/network/25\-ipip\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=ipip\-tun +Kind=ipip +MTUBytes=1480 + +[Tunnel] +Local=192\&.168\&.223\&.238 +Remote=192\&.169\&.224\&.239 +TTL=64 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&/etc/systemd/network/1\-fou\-tunnel\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=fou\-tun +Kind=fou + +[FooOverUDP] +Port=5555 +Protocol=4 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&5.\ \&/etc/systemd/network/25\-fou\-ipip\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=ipip\-tun +Kind=ipip + +[Tunnel] +Independent=yes +Local=10\&.65\&.208\&.212 +Remote=10\&.65\&.208\&.211 +FooOverUDP=yes +FOUDestinationPort=5555 + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&6.\ \&/etc/systemd/network/25\-tap\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=tap\-test +Kind=tap + +[Tap] +MultiQueue=yes +PacketInfo=yes +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&7.\ \&/etc/systemd/network/25\-sit\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=sit\-tun +Kind=sit +MTUBytes=1480 + +[Tunnel] +Local=10\&.65\&.223\&.238 +Remote=10\&.65\&.223\&.239 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&8.\ \&/etc/systemd/network/25\-6rd\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=6rd\-tun +Kind=sit +MTUBytes=1480 + +[Tunnel] +Local=10\&.65\&.223\&.238 +IPv6RapidDeploymentPrefix=2602::/24 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&9.\ \&/etc/systemd/network/25\-gre\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=gre\-tun +Kind=gre +MTUBytes=1480 + +[Tunnel] +Local=10\&.65\&.223\&.238 +Remote=10\&.65\&.223\&.239 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&10.\ \&/etc/systemd/network/25\-ip6gre\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=ip6gre\-tun +Kind=ip6gre + +[Tunnel] +Key=123 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&11.\ \&/etc/systemd/network/25\-vti\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=vti\-tun +Kind=vti +MTUBytes=1480 + +[Tunnel] +Local=10\&.65\&.223\&.238 +Remote=10\&.65\&.223\&.239 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&12.\ \&/etc/systemd/network/25\-veth\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=veth\-test +Kind=veth + +[Peer] +Name=veth\-peer +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&13.\ \&/etc/systemd/network/25\-bond\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=bond1 +Kind=bond + +[Bond] +Mode=802\&.3ad +TransmitHashPolicy=layer3+4 +MIIMonitorSec=1s +LACPTransmitRate=fast +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&14.\ \&/etc/systemd/network/25\-dummy\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=dummy\-test +Kind=dummy +MACAddress=12:34:56:78:9a:bc +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&15.\ \&/etc/systemd/network/25\-vrf\&.netdev\fR +.PP +Create a VRF interface with table 42\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=vrf\-test +Kind=vrf + +[VRF] +Table=42 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&16.\ \&/etc/systemd/network/25\-macvtap\&.netdev\fR +.PP +Create a MacVTap device\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=macvtap\-test +Kind=macvtap + +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&17.\ \&/etc/systemd/network/25\-wireguard\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=wg0 +Kind=wireguard + +[WireGuard] +PrivateKey=EEGlnEPYJV//kbvvIqxKkQwOiS+UENyPncC4bF46ong= +ListenPort=51820 + +[WireGuardPeer] +PublicKey=RDf+LSpeEre7YEIKaxg+wbpsNV7du+ktR99uBEtIiCA= +AllowedIPs=fd31:bf08:57cb::/48,192\&.168\&.26\&.0/24 +Endpoint=wireguard\&.example\&.com:51820 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&18.\ \&/etc/systemd/network/27\-xfrm\&.netdev\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +[NetDev] +Name=xfrm0 +Kind=xfrm + +[Xfrm] +Independent=yes +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-networkd\fR(8), +\fBsystemd.link\fR(5), +\fBsystemd.network\fR(5), +\fBsystemd-network-generator.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +Linux Ethernet Bonding Driver HOWTO +.RS 4 +\%https://docs.kernel.org/networking/bonding.html +.RE +.IP " 2." 4 +RFC 2784 +.RS 4 +\%https://tools.ietf.org/html/rfc2784 +.RE +.IP " 3." 4 +IEEE 802.1Q +.RS 4 +\%http://www.ieee802.org/1/pages/802.1Q.html +.RE +.IP " 4." 4 +VRF +.RS 4 +\%https://docs.kernel.org/networking/vrf.html +.RE +.IP " 5." 4 +B.A.T.M.A.N. Advanced +.RS 4 +\%https://www.open-mesh.org/projects/open-mesh/wiki +.RE +.IP " 6." 4 +System and Service Credentials +.RS 4 +\%https://systemd.io/CREDENTIALS +.RE +.IP " 7." 4 +Distributed Overlay Virtual Ethernet (DOVE) +.RS 4 +\%https://en.wikipedia.org/wiki/Distributed_Overlay_Virtual_Ethernet +.RE +.IP " 8." 4 +VXLAN Group Policy +.RS 4 +\%https://tools.ietf.org/html/draft-smith-vxlan-group-policy +.RE +.IP " 9." 4 +Generic Protocol Extension for VXLAN +.RS 4 +\%https://tools.ietf.org/html/draft-ietf-nvo3-vxlan-gpe-07 +.RE +.IP "10." 4 +Type of Service in the Internet Protocol Suite +.RS 4 +\%http://tools.ietf.org/html/rfc1349 +.RE +.IP "11." 4 +RFC 6437 +.RS 4 +\%https://tools.ietf.org/html/rfc6437 +.RE +.IP "12." 4 +RFC 2460 +.RS 4 +\%https://tools.ietf.org/html/rfc2460 +.RE +.IP "13." 4 +RFC 2473 +.RS 4 +\%https://tools.ietf.org/html/rfc2473#section-4.1.1 +.RE +.IP "14." 4 +ip-xfrm \(em transform configuration +.RS 4 +\%https://man7.org/linux/man-pages/man8/ip-xfrm.8.html +.RE +.IP "15." 4 +Foo over UDP +.RS 4 +\%https://lwn.net/Articles/614348 +.RE +.IP "16." 4 +IPv6 Rapid Deployment +.RS 4 +\%https://tools.ietf.org/html/rfc5569 +.RE +.IP "17." 4 +Generic UDP Encapsulation +.RS 4 +\%https://lwn.net/Articles/615044 +.RE +.IP "18." 4 +Virtual XFRM Interfaces +.RS 4 +\%https://lwn.net/Articles/757391 +.RE diff --git a/upstream/fedora-40/man5/systemd.network.5 b/upstream/fedora-40/man5/systemd.network.5 new file mode 100644 index 00000000..49b3eb68 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.network.5 @@ -0,0 +1,6230 @@ +'\" t +.TH "SYSTEMD\&.NETWORK" "5" "" "systemd 255" "systemd.network" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.network \- Network configuration +.SH "SYNOPSIS" +.PP +\fInetwork\fR\&.network +.SH "DESCRIPTION" +.PP +A plain ini\-style text file that encodes network configuration for matching network interfaces, used by +\fBsystemd-networkd\fR(8)\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.PP +The main network file must have the extension +\&.network; other extensions are ignored\&. Networks are applied to links whenever the links appear\&. +.PP +The +\&.network +files are read from the files located in the system network directories +/usr/lib/systemd/network +and +/usr/local/lib/systemd/network, the volatile runtime network directory +/run/systemd/network +and the local administration network directory +/etc/systemd/network\&. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. It is recommended that each filename is prefixed with a number smaller than +"70" +(e\&.g\&. +10\-eth0\&.network)\&. Otherwise, the default +\&.network +files or those generated by +\fBsystemd-network-generator.service\fR(8) +may take precedence over user configured files\&. Files in +/etc/ +have the highest priority, files in +/run/ +take precedence over files with the same name under +/usr/\&. This can be used to override a system\-supplied configuration file with a local file if needed\&. As a special case, an empty file (file size 0) or symlink with the same name pointing to +/dev/null +disables the configuration file entirely (it is "masked")\&. +.PP +Along with the network file +foo\&.network, a "drop\-in" directory +foo\&.network\&.d/ +may exist\&. All files with the suffix +"\&.conf" +from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed\&. This is useful to alter or add configuration settings, without having to modify the main configuration file\&. Each drop\-in file must have appropriate section headers\&. +.PP +In addition to +/etc/systemd/network, drop\-in +"\&.d" +directories can be placed in +/usr/lib/systemd/network +or +/run/systemd/network +directories\&. Drop\-in files in +/etc/ +take precedence over those in +/run/ +which in turn take precedence over those in +/usr/lib/\&. Drop\-in files under any of these directories take precedence over the main network file wherever located\&. +.SH "[MATCH] SECTION OPTIONS" +.PP +The network file contains a [Match] section, which determines if a given network file may be applied to a given interface; and a [Network] section specifying how the interface should be configured\&. The first (in alphanumeric order) of the network files that matches a given interface is applied, all later files are ignored, even if they match as well\&. +.PP +Note that any network interfaces that have the +\fIID_NET_MANAGED_BY=\fR +udev property set will never be matched by any \&.network files \(en unless the property\*(Aqs value is the string +"io\&.systemd\&.Network" +\(en even if the [Match] section would otherwise match\&. This may be used to exclude specific network interfaces from +\fBsystemd\-networkd\fR\*(Aqs management, while keeping the [Match] section generic\&. The +\fIID_NET_MANAGED_BY=\fR +property thus declares intended +\fIownership\fR +of the device, and permits ensuring that concurrent network management implementations do not compete for management of specific devices\&. +.PP +A network file is said to match a network interface if all matches specified by the [Match] section are satisfied\&. When a network file does not contain valid settings in [Match] section, then the file will match all interfaces and +\fBsystemd\-networkd\fR +warns about that\&. Hint: to avoid the warning and to make it clear that all interfaces shall be matched, add the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Name=* +.fi +.if n \{\ +.RE +.\} +.sp +The following keys are accepted: +.PP +\fIMACAddress=\fR +.RS 4 +A whitespace\-separated list of hardware addresses\&. The acceptable formats are: +.PP +\fBcolon\-delimited hexadecimal\fR +.RS 4 +Each field must be one byte\&. E\&.g\&. +"12:34:56:78:90:ab" +or +"AA:BB:CC:DD:EE:FF"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBhyphen\-delimited hexadecimal\fR +.RS 4 +Each field must be one byte\&. E\&.g\&. +"12\-34\-56\-78\-90\-ab" +or +"AA\-BB\-CC\-DD\-EE\-FF"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdot\-delimited hexadecimal\fR +.RS 4 +Each field must be two bytes\&. E\&.g\&. +"1234\&.5678\&.90ab" +or +"AABB\&.CCDD\&.EEFF"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBIPv4 address format\fR +.RS 4 +E\&.g\&. +"127\&.0\&.0\&.1" +or +"192\&.168\&.0\&.1"\&. +.sp +Added in version 250\&. +.RE +.PP +\fBIPv6 address format\fR +.RS 4 +E\&.g\&. +"2001:0db8:85a3::8a2e:0370:7334" +or +"::1"\&. +.sp +Added in version 250\&. +.RE +.sp +The total length of each MAC address must be 4 (for IPv4 tunnel), 6 (for Ethernet), 16 (for IPv6 tunnel), or 20 (for InfiniBand)\&. This option may appear more than once, in which case the lists are merged\&. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset\&. Defaults to unset\&. +.sp +Added in version 211\&. +.RE +.PP +\fIPermanentMACAddress=\fR +.RS 4 +A whitespace\-separated list of hardware\*(Aqs permanent addresses\&. While +\fIMACAddress=\fR +matches the device\*(Aqs current MAC address, this matches the device\*(Aqs permanent MAC address, which may be different from the current one\&. Use full colon\-, hyphen\- or dot\-delimited hexadecimal, or IPv4 or IPv6 address format\&. This option may appear more than once, in which case the lists are merged\&. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPath=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the persistent path, as exposed by the udev property +\fIID_PATH\fR\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDriver=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the driver currently bound to the device, as exposed by the udev property +\fIID_NET_DRIVER\fR +of its parent device, or if that is not set, the driver as exposed by +\fBethtool \-i\fR +of the device itself\&. If the list is prefixed with a "!", the test is inverted\&. +.sp +Added in version 211\&. +.RE +.PP +\fIType=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the device type, as exposed by +\fBnetworkctl list\fR\&. If the list is prefixed with a "!", the test is inverted\&. Some valid values are +"ether", +"loopback", +"wlan", +"wwan"\&. Valid types are named either from the udev +"DEVTYPE" +attribute, or +"ARPHRD_" +macros in +linux/if_arp\&.h, so this is not comprehensive\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKind=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the device kind, as exposed by +\fBnetworkctl status \fR\fB\fIINTERFACE\fR\fR +or +\fBip \-d link show \fR\fB\fIINTERFACE\fR\fR\&. If the list is prefixed with a "!", the test is inverted\&. Some valid values are +"bond", +"bridge", +"gre", +"tun", +"veth"\&. Valid kinds are given by netlink\*(Aqs +"IFLA_INFO_KIND" +attribute, so this is not comprehensive\&. +.sp +Added in version 251\&. +.RE +.PP +\fIProperty=\fR +.RS 4 +A whitespace\-separated list of udev property names with their values after equals sign ("=")\&. If multiple properties are specified, the test results are ANDed\&. If the list is prefixed with a "!", the test is inverted\&. If a value contains white spaces, then please quote whole key and value pair\&. If a value contains quotation, then please escape the quotation with +"\e"\&. +.sp +Example: if a \&.link file has the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \e"quotation\e"" +.fi +.if n \{\ +.RE +.\} +.sp +then, the \&.link file matches only when an interface has all the above three properties\&. +.sp +Added in version 243\&. +.RE +.PP +\fIName=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the device name, as exposed by the udev property +"INTERFACE", or device\*(Aqs alternative names\&. If the list is prefixed with a "!", the test is inverted\&. +.sp +Added in version 211\&. +.RE +.PP +\fIWLANInterfaceType=\fR +.RS 4 +A whitespace\-separated list of wireless network type\&. Supported values are +"ad\-hoc", +"station", +"ap", +"ap\-vlan", +"wds", +"monitor", +"mesh\-point", +"p2p\-client", +"p2p\-go", +"p2p\-device", +"ocb", and +"nan"\&. If the list is prefixed with a "!", the test is inverted\&. +.sp +Added in version 244\&. +.RE +.PP +\fISSID=\fR +.RS 4 +A whitespace\-separated list of shell\-style globs matching the SSID of the currently connected wireless LAN\&. If the list is prefixed with a "!", the test is inverted\&. +.sp +Added in version 244\&. +.RE +.PP +\fIBSSID=\fR +.RS 4 +A whitespace\-separated list of hardware address of the currently connected wireless LAN\&. Use full colon\-, hyphen\- or dot\-delimited hexadecimal\&. See the example in +\fIMACAddress=\fR\&. This option may appear more than once, in which case the lists are merged\&. If the empty string is assigned to this option, the list is reset\&. +.sp +Added in version 244\&. +.RE +.PP +\fIHost=\fR +.RS 4 +Matches against the hostname or machine ID of the host\&. See +\fIConditionHost=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIVirtualization=\fR +.RS 4 +Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation\&. See +\fIConditionVirtualization=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKernelCommandLine=\fR +.RS 4 +Checks whether a specific kernel command line option is set\&. See +\fIConditionKernelCommandLine=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIKernelVersion=\fR +.RS 4 +Checks whether the kernel version (as reported by +\fBuname \-r\fR) matches a certain expression\&. See +\fIConditionKernelVersion=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 237\&. +.RE +.PP +\fICredential=\fR +.RS 4 +Checks whether the specified credential was passed to the +systemd\-udevd\&.service +service\&. See +\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[1]\d\s+2 +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 252\&. +.RE +.PP +\fIArchitecture=\fR +.RS 4 +Checks whether the system is running on a specific architecture\&. See +\fIConditionArchitecture=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 211\&. +.RE +.PP +\fIFirmware=\fR +.RS 4 +Checks whether the system is running on a machine with the specified firmware\&. See +\fIConditionFirmware=\fR +in +\fBsystemd.unit\fR(5) +for details\&. When prefixed with an exclamation mark ("!"), the result is negated\&. If an empty string is assigned, the previously assigned value is cleared\&. +.sp +Added in version 249\&. +.RE +.SH "[LINK] SECTION OPTIONS" +.PP +The [Link] section accepts the following keys: +.PP +\fIMACAddress=\fR +.RS 4 +The hardware address to set for the device\&. +.sp +Added in version 218\&. +.RE +.PP +\fIMTUBytes=\fR +.RS 4 +The maximum transmission unit in bytes to set for the device\&. The usual suffixes K, M, G, are supported and are understood to the base of 1024\&. +.sp +Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value\&. +.sp +Added in version 218\&. +.RE +.PP +\fIARP=\fR +.RS 4 +Takes a boolean\&. If set to true, the ARP (low\-level Address Resolution Protocol) for this interface is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +For example, disabling ARP is useful when creating multiple MACVLAN or VLAN virtual interfaces atop a single lower\-level physical interface, which will then only serve as a link/"bridge" device aggregating traffic to the same physical link and not participate in the network otherwise\&. Defaults to unset\&. +.sp +Added in version 232\&. +.RE +.PP +\fIMulticast=\fR +.RS 4 +Takes a boolean\&. If set to true, the multicast flag on the device is enabled\&. Defaults to unset\&. +.sp +Added in version 239\&. +.RE +.PP +\fIAllMulticast=\fR +.RS 4 +Takes a boolean\&. If set to true, the driver retrieves all multicast packets from the network\&. This happens when multicast routing is enabled\&. Defaults to unset\&. +.sp +Added in version 239\&. +.RE +.PP +\fIPromiscuous=\fR +.RS 4 +Takes a boolean\&. If set to true, promiscuous mode of the interface is enabled\&. Defaults to unset\&. +.sp +If this is set to false for the underlying link of a +"passthru" +mode MACVLAN/MACVTAP, the virtual interface will be created with the +"nopromisc" +flag set\&. +.sp +Added in version 248\&. +.RE +.PP +\fIUnmanaged=\fR +.RS 4 +Takes a boolean\&. When +"yes", no attempts are made to bring up or configure matching links, equivalent to when there are no matching network files\&. Defaults to +"no"\&. +.sp +This is useful for preventing later matching network files from interfering with certain interfaces that are fully controlled by other applications\&. +.sp +Added in version 233\&. +.RE +.PP +\fIGroup=\fR +.RS 4 +Link groups are similar to port ranges found in managed switches\&. When network interfaces are added to a numbered group, operations on all the interfaces from that group can be performed at once\&. Takes an unsigned integer in the range 0\&...2147483647\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRequiredForOnline=\fR +.RS 4 +Takes a boolean or a minimum operational state and an optional maximum operational state\&. Please see +\fBnetworkctl\fR(1) +for possible operational states\&. When +"yes", the network is deemed required when determining whether the system is online (including when running +\fBsystemd\-networkd\-wait\-online\fR)\&. When +"no", the network is ignored when determining the online state\&. When a minimum operational state and an optional maximum operational state are set, +"yes" +is implied, and this controls the minimum and maximum operational state required for the network interface to be considered online\&. +.sp +Defaults to +"yes" +when +\fIActivationPolicy=\fR +is not set, or set to +"up", +"always\-up", or +"bound"\&. Defaults to +"no" +when +\fIActivationPolicy=\fR +is set to +"manual" +or +"down"\&. This is forced to +"no" +when +\fIActivationPolicy=\fR +is set to +"always\-down"\&. +.sp +The network will be brought up normally (as configured by +\fIActivationPolicy=\fR), but in the event that there is no address being assigned by DHCP or the cable is not plugged in, the link will simply remain offline and be skipped automatically by +\fBsystemd\-networkd\-wait\-online\fR +if +"RequiredForOnline=no"\&. +.sp +Added in version 236\&. +.RE +.PP +\fIRequiredFamilyForOnline=\fR +.RS 4 +Takes an address family\&. When specified, an IP address in the given family is deemed required when determining whether the link is online (including when running +\fBsystemd\-networkd\-wait\-online\fR)\&. Takes one of +"ipv4", +"ipv6", +"both", or +"any"\&. Defaults to +"any"\&. Note that this option has no effect if +"RequiredForOnline=no", or if +"RequiredForOnline=" +specifies a minimum operational state below +"degraded"\&. +.sp +Added in version 249\&. +.RE +.PP +\fIActivationPolicy=\fR +.RS 4 +Specifies the policy for +\fBsystemd\-networkd\fR +managing the link administrative state\&. Specifically, this controls how +\fBsystemd\-networkd\fR +changes the network device\*(Aqs +"IFF_UP" +flag, which is sometimes controlled by system administrators by running e\&.g\&., +\fBip link set dev eth0 up\fR +or +\fBip link set dev eth0 down\fR, and can also be changed with +\fBnetworkctl up eth0\fR +or +\fBnetworkctl down eth0\fR\&. +.sp +Takes one of +"up", +"always\-up", +"manual", +"always\-down", +"down", or +"bound"\&. When +"manual", +\fBsystemd\-networkd\fR +will not change the link\*(Aqs admin state automatically; the system administrator must bring the interface up or down manually, as desired\&. When +"up" +(the default) or +"always\-up", or +"down" +or +"always\-down", +\fBsystemd\-networkd\fR +will set the link up or down, respectively, when the interface is (re)configured\&. When +"always\-up" +or +"always\-down", +\fBsystemd\-networkd\fR +will set the link up or down, respectively, any time +\fBsystemd\-networkd\fR +detects a change in the administrative state\&. When +\fIBindCarrier=\fR +is also set, this is automatically set to +"bound" +and any other value is ignored\&. +.sp +When the policy is set to +"down" +or +"manual", the default value of +\fIRequiredForOnline=\fR +is +"no"\&. When the policy is set to +"always\-down", the value of +\fIRequiredForOnline=\fR +forced to +"no"\&. +.sp +The administrative state is not the same as the carrier state, so using +"always\-up" +does not mean the link will never lose carrier\&. The link carrier depends on both the administrative state as well as the network device\*(Aqs physical connection\&. However, to avoid reconfiguration failures, when using +"always\-up", +\fIIgnoreCarrierLoss=\fR +is forced to true\&. +.sp +Added in version 248\&. +.RE +.SH "[SR\-IOV] SECTION OPTIONS" +.PP +The [SR\-IOV] section accepts the following keys\&. Specify several [SR\-IOV] sections to configure several SR\-IOVs\&. SR\-IOV provides the ability to partition a single physical PCI resource into virtual PCI functions which can then be injected into a VM\&. In the case of network VFs, SR\-IOV improves north\-south network performance (that is, traffic with endpoints outside the host machine) by allowing traffic to bypass the host machine\(cqs network stack\&. +.PP +\fIVirtualFunction=\fR +.RS 4 +Specifies a Virtual Function (VF), lightweight PCIe function designed solely to move data in and out\&. Takes an integer in the range 0\&...2147483646\&. This option is compulsory\&. +.sp +Added in version 251\&. +.RE +.PP +\fIVLANId=\fR +.RS 4 +Specifies VLAN ID of the virtual function\&. Takes an integer in the range 1\&...4095\&. +.sp +Added in version 251\&. +.RE +.PP +\fIQualityOfService=\fR +.RS 4 +Specifies quality of service of the virtual function\&. Takes an integer in the range 1\&...4294967294\&. +.sp +Added in version 251\&. +.RE +.PP +\fIVLANProtocol=\fR +.RS 4 +Specifies VLAN protocol of the virtual function\&. Takes +"802\&.1Q" +or +"802\&.1ad"\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMACSpoofCheck=\fR +.RS 4 +Takes a boolean\&. Controls the MAC spoof checking\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fIQueryReceiveSideScaling=\fR +.RS 4 +Takes a boolean\&. Toggle the ability of querying the receive side scaling (RSS) configuration of the virtual function (VF)\&. The VF RSS information like RSS hash key may be considered sensitive on some devices where this information is shared between VF and the physical function (PF)\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fITrust=\fR +.RS 4 +Takes a boolean\&. Allows one to set trust mode of the virtual function (VF)\&. When set, VF users can set a specific feature which may impact security and/or performance\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fILinkState=\fR +.RS 4 +Allows one to set the link state of the virtual function (VF)\&. Takes a boolean or a special value +"auto"\&. Setting to +"auto" +means a reflection of the physical function (PF) link state, +"yes" +lets the VF to communicate with other VFs on this host even if the PF link state is down, +"no" +causes the hardware to drop any packets sent by the VF\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMACAddress=\fR +.RS 4 +Specifies the MAC address for the virtual function\&. +.sp +Added in version 251\&. +.RE +.SH "[NETWORK] SECTION OPTIONS" +.PP +The [Network] section accepts the following keys: +.PP +\fIDescription=\fR +.RS 4 +A description of the device\&. This is only used for presentation purposes\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDHCP=\fR +.RS 4 +Enables DHCPv4 and/or DHCPv6 client support\&. Accepts +"yes", +"no", +"ipv4", or +"ipv6"\&. Defaults to +"no"\&. +.sp +Note that DHCPv6 will by default be triggered by Router Advertisements, if reception is enabled, regardless of this parameter\&. By explicitly enabling DHCPv6 support here, the DHCPv6 client will be started in the mode specified by the +\fIWithoutRA=\fR +setting in the [DHCPv6] section, regardless of the presence of routers on the link, or what flags the routers pass\&. See +\fIIPv6AcceptRA=\fR\&. +.sp +Furthermore, note that by default the domain name specified through DHCP is not used for name resolution\&. See option +\fBUseDomains=\fR +below\&. +.sp +See the [DHCPv4] or [DHCPv6] sections below for further configuration options for the DHCP client support\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDHCPServer=\fR +.RS 4 +Takes a boolean\&. If set to +"yes", DHCPv4 server will be started\&. Defaults to +"no"\&. Further settings for the DHCP server may be set in the [DHCPServer] section described below\&. +.sp +Added in version 215\&. +.RE +.PP +\fILinkLocalAddressing=\fR +.RS 4 +Enables link\-local address autoconfiguration\&. Accepts +\fByes\fR, +\fBno\fR, +\fBipv4\fR, and +\fBipv6\fR\&. An IPv6 link\-local address is configured when +\fByes\fR +or +\fBipv6\fR\&. An IPv4 link\-local address is configured when +\fByes\fR +or +\fBipv4\fR +and when DHCPv4 autoconfiguration has been unsuccessful for some time\&. (IPv4 link\-local address autoconfiguration will usually happen in parallel with repeated attempts to acquire a DHCPv4 lease)\&. +.sp +Defaults to +\fBno\fR +when +\fIKeepMaster=\fR +or +\fIBridge=\fR +is set or when the specified +\fIMACVLAN=\fR/\fIMACVTAP=\fR +has +\fIMode=passthru\fR, or +\fBipv6\fR +otherwise\&. +.sp +Added in version 219\&. +.RE +.PP +\fIIPv6LinkLocalAddressGenerationMode=\fR +.RS 4 +Specifies how IPv6 link\-local address is generated\&. Takes one of +"eui64", +"none", +"stable\-privacy" +and +"random"\&. When unset, +"stable\-privacy" +is used if +\fIIPv6StableSecretAddress=\fR +is specified, and if not, +"eui64" +is used\&. Note that if +\fILinkLocalAddressing=\fR +is +"no" +or +"ipv4", then +\fIIPv6LinkLocalAddressGenerationMode=\fR +will be ignored\&. Also, even if +\fILinkLocalAddressing=\fR +is +"yes" +or +"ipv6", setting +\fIIPv6LinkLocalAddressGenerationMode=none\fR +disables to configure an IPv6 link\-local address\&. +.sp +Added in version 246\&. +.RE +.PP +\fIIPv6StableSecretAddress=\fR +.RS 4 +Takes an IPv6 address\&. The specified address will be used as a stable secret for generating IPv6 link\-local address\&. If this setting is specified, and +\fIIPv6LinkLocalAddressGenerationMode=\fR +is unset, then +\fIIPv6LinkLocalAddressGenerationMode=stable\-privacy\fR +is implied\&. If this setting is not specified, and +"stable\-privacy" +is set to +\fIIPv6LinkLocalAddressGenerationMode=\fR, then a stable secret address will be generated from the local machine ID and the interface name\&. +.sp +Added in version 249\&. +.RE +.PP +\fIIPv4LLStartAddress=\fR +.RS 4 +Specifies the first IPv4 link\-local address to try\&. Takes an IPv4 address for example 169\&.254\&.1\&.2, from the link\-local address range: 169\&.254\&.0\&.0/16 except for 169\&.254\&.0\&.0/24 and 169\&.254\&.255\&.0/24\&. This setting may be useful if the device should always have the same address as long as there is no address conflict\&. When unset, a random address will be automatically selected\&. Defaults to unset\&. +.sp +Added in version 252\&. +.RE +.PP +\fIIPv4LLRoute=\fR +.RS 4 +Takes a boolean\&. If set to true, sets up the route needed for non\-IPv4LL hosts to communicate with IPv4LL\-only hosts\&. Defaults to false\&. +.sp +Added in version 216\&. +.RE +.PP +\fIDefaultRouteOnDevice=\fR +.RS 4 +Takes a boolean\&. If set to true, sets up the IPv4 default route bound to the interface\&. Defaults to false\&. This is useful when creating routes on point\-to\-point interfaces\&. This is equivalent to e\&.g\&. the following, +.sp +.if n \{\ +.RS 4 +.\} +.nf +ip route add default dev veth99 +.fi +.if n \{\ +.RE +.\} +.sp +or, +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Route] +Gateway=0\&.0\&.0\&.0 +.fi +.if n \{\ +.RE +.\} +.sp +Currently, there are no way to specify e\&.g\&., the table for the route configured by this setting\&. To configure the default route with such an additional property, please use the following instead: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Route] +Gateway=0\&.0\&.0\&.0 +Table=1234 +.fi +.if n \{\ +.RE +.\} +.sp +If you\*(Aqd like to create an IPv6 default route bound to the interface, please use the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Route] +Gateway=:: +Table=1234 +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 243\&. +.RE +.PP +\fILLMNR=\fR +.RS 4 +Takes a boolean or +"resolve"\&. When true, enables +\m[blue]\fBLink\-Local Multicast Name Resolution\fR\m[]\&\s-2\u[2]\d\s+2 +on the link\&. When set to +"resolve", only resolution is enabled, but not host registration and announcement\&. Defaults to true\&. This setting is read by +\fBsystemd-resolved.service\fR(8)\&. +.sp +Added in version 216\&. +.RE +.PP +\fIMulticastDNS=\fR +.RS 4 +Takes a boolean or +"resolve"\&. When true, enables +\m[blue]\fBMulticast DNS\fR\m[]\&\s-2\u[3]\d\s+2 +support on the link\&. When set to +"resolve", only resolution is enabled, but not host or service registration and announcement\&. Defaults to false\&. This setting is read by +\fBsystemd-resolved.service\fR(8)\&. +.sp +Added in version 229\&. +.RE +.PP +\fIDNSOverTLS=\fR +.RS 4 +Takes a boolean or +"opportunistic"\&. When true, enables +\m[blue]\fBDNS\-over\-TLS\fR\m[]\&\s-2\u[4]\d\s+2 +support on the link\&. When set to +"opportunistic", compatibility with non\-DNS\-over\-TLS servers is increased, by automatically turning off DNS\-over\-TLS servers in this case\&. This option defines a per\-interface setting for +\fBresolved.conf\fR(5)\*(Aqs global +\fIDNSOverTLS=\fR +option\&. Defaults to unset, and the global setting will be used\&. This setting is read by +\fBsystemd-resolved.service\fR(8)\&. +.sp +Added in version 239\&. +.RE +.PP +\fIDNSSEC=\fR +.RS 4 +Takes a boolean or +"allow\-downgrade"\&. When true, enables +\m[blue]\fBDNSSEC\fR\m[]\&\s-2\u[5]\d\s+2 +DNS validation support on the link\&. When set to +"allow\-downgrade", compatibility with non\-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case\&. This option defines a per\-interface setting for +\fBresolved.conf\fR(5)\*(Aqs global +\fIDNSSEC=\fR +option\&. Defaults to unset, and the global setting will be used\&. This setting is read by +\fBsystemd-resolved.service\fR(8)\&. +.sp +Added in version 229\&. +.RE +.PP +\fIDNSSECNegativeTrustAnchors=\fR +.RS 4 +A space\-separated list of DNSSEC negative trust anchor domains\&. If specified and DNSSEC is enabled, look\-ups done via the interface\*(Aqs DNS server will be subject to the list of negative trust anchors, and not require authentication for the specified domains, or anything below it\&. Use this to disable DNSSEC authentication for specific private domains, that cannot be proven valid using the Internet DNS hierarchy\&. Defaults to the empty list\&. This setting is read by +\fBsystemd-resolved.service\fR(8)\&. +.sp +Added in version 229\&. +.RE +.PP +\fILLDP=\fR +.RS 4 +Controls support for Ethernet LLDP packet reception\&. LLDP is a link\-layer protocol commonly implemented on professional routers and bridges which announces which physical port a system is connected to, as well as other related data\&. Accepts a boolean or the special value +"routers\-only"\&. When true, incoming LLDP packets are accepted and a database of all LLDP neighbors maintained\&. If +"routers\-only" +is set only LLDP data of various types of routers is collected and LLDP data about other types of devices ignored (such as stations, telephones and others)\&. If false, LLDP reception is disabled\&. Defaults to +"routers\-only"\&. Use +\fBnetworkctl\fR(1) +to query the collected neighbor data\&. LLDP is only available on Ethernet links\&. See +\fIEmitLLDP=\fR +below for enabling LLDP packet emission from the local system\&. +.sp +Added in version 219\&. +.RE +.PP +\fIEmitLLDP=\fR +.RS 4 +Controls support for Ethernet LLDP packet emission\&. Accepts a boolean parameter or the special values +"nearest\-bridge", +"non\-tpmr\-bridge" +and +"customer\-bridge"\&. Defaults to false, which turns off LLDP packet emission\&. If not false, a short LLDP packet with information about the local system is sent out in regular intervals on the link\&. The LLDP packet will contain information about the local hostname, the local machine ID (as stored in +\fBmachine-id\fR(5)) and the local interface name, as well as the pretty hostname of the system (as set in +\fBmachine-info\fR(5))\&. LLDP emission is only available on Ethernet links\&. Note that this setting passes data suitable for identification of host to the network and should thus not be enabled on untrusted networks, where such identification data should not be made available\&. Use this option to permit other systems to identify on which interfaces they are connected to this system\&. The three special values control propagation of the LLDP packets\&. The +"nearest\-bridge" +setting permits propagation only to the nearest connected bridge, +"non\-tpmr\-bridge" +permits propagation across Two\-Port MAC Relays, but not any other bridges, and +"customer\-bridge" +permits propagation until a customer bridge is reached\&. For details about these concepts, see +\m[blue]\fBIEEE 802\&.1AB\-2016\fR\m[]\&\s-2\u[6]\d\s+2\&. Note that configuring this setting to true is equivalent to +"nearest\-bridge", the recommended and most restricted level of propagation\&. See +\fILLDP=\fR +above for an option to enable LLDP reception\&. +.sp +Added in version 230\&. +.RE +.PP +\fIBindCarrier=\fR +.RS 4 +A link name or a list of link names\&. When set, controls the behavior of the current link\&. When all links in the list are in an operational down state, the current link is brought down\&. When at least one link has carrier, the current interface is brought up\&. +.sp +This forces +\fIActivationPolicy=\fR +to be set to +"bound"\&. +.sp +Added in version 220\&. +.RE +.PP +\fIAddress=\fR +.RS 4 +A static IPv4 or IPv6 address and its prefix length, separated by a +"/" +character\&. Specify this key more than once to configure several addresses\&. The format of the address must be as described in +\fBinet_pton\fR(3)\&. This is a short\-hand for an [Address] section only containing an Address key (see below)\&. This option may be specified more than once\&. +.sp +If the specified address is +"0\&.0\&.0\&.0" +(for IPv4) or +"::" +(for IPv6), a new address range of the requested size is automatically allocated from a system\-wide pool of unused ranges\&. Note that the prefix length must be equal or larger than 8 for IPv4, and 64 for IPv6\&. The allocated range is checked against all current network interfaces and all known network configuration files to avoid address range conflicts\&. The default system\-wide pool consists of 192\&.168\&.0\&.0/16, 172\&.16\&.0\&.0/12 and 10\&.0\&.0\&.0/8 for IPv4, and fd00::/8 for IPv6\&. This functionality is useful to manage a large number of dynamically created network interfaces with the same network configuration and automatic address range assignment\&. +.sp +Added in version 211\&. +.RE +.PP +\fIGateway=\fR +.RS 4 +The gateway address, which must be in the format described in +\fBinet_pton\fR(3)\&. This is a short\-hand for a [Route] section only containing a +\fIGateway=\fR +key\&. This option may be specified more than once\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDNS=\fR +.RS 4 +A DNS server address, which must be in the format described in +\fBinet_pton\fR(3)\&. This option may be specified more than once\&. Each address can optionally take a port number separated with +":", a network interface name or index separated with +"%", and a Server Name Indication (SNI) separated with +"#"\&. When IPv6 address is specified with a port number, then the address must be in the square brackets\&. That is, the acceptable full formats are +"111\&.222\&.333\&.444:9953%ifname#example\&.com" +for IPv4 and +"[1111:2222::3333]:9953%ifname#example\&.com" +for IPv6\&. If an empty string is assigned, then the all previous assignments are cleared\&. This setting is read by +\fBsystemd-resolved.service\fR(8)\&. +.sp +Added in version 211\&. +.RE +.PP +\fIDomains=\fR +.RS 4 +A whitespace\-separated list of domains which should be resolved using the DNS servers on this link\&. Each item in the list should be a domain name, optionally prefixed with a tilde ("~")\&. The domains with the prefix are called "routing\-only domains"\&. The domains without the prefix are called "search domains" and are first used as search suffixes for extending single\-label hostnames (hostnames containing no dots) to become fully qualified domain names (FQDNs)\&. If a single\-label hostname is resolved on this interface, each of the specified search domains are appended to it in turn, converting it into a fully qualified domain name, until one of them may be successfully resolved\&. +.sp +Both "search" and "routing\-only" domains are used for routing of DNS queries: look\-ups for hostnames ending in those domains (hence also single label names, if any "search domains" are listed), are routed to the DNS servers configured for this interface\&. The domain routing logic is particularly useful on multi\-homed hosts with DNS servers serving particular private DNS zones on each interface\&. +.sp +The "routing\-only" domain +"~\&." +(the tilde indicating definition of a routing domain, the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special effect\&. It causes all DNS traffic which does not match another configured domain routing entry to be routed to DNS servers specified for this interface\&. This setting is useful to prefer a certain set of DNS servers if a link on which they are connected is available\&. +.sp +This setting is read by +\fBsystemd-resolved.service\fR(8)\&. "Search domains" correspond to the +\fIdomain\fR +and +\fIsearch\fR +entries in +\fBresolv.conf\fR(5)\&. Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain name servers limited to a specific link\&. +.sp +Added in version 216\&. +.RE +.PP +\fIDNSDefaultRoute=\fR +.RS 4 +Takes a boolean argument\&. If true, this link\*(Aqs configured DNS servers are used for resolving domain names that do not match any link\*(Aqs configured +\fIDomains=\fR +setting\&. If false, this link\*(Aqs configured DNS servers are never used for such domains, and are exclusively used for resolving names that match at least one of the domains configured on this link\&. If not specified defaults to an automatic mode: queries not matching any link\*(Aqs configured domains will be routed to this link if it has no routing\-only domains configured\&. +.sp +Added in version 240\&. +.RE +.PP +\fINTP=\fR +.RS 4 +An NTP server address (either an IP address, or a hostname)\&. This option may be specified more than once\&. This setting is read by +\fBsystemd-timesyncd.service\fR(8)\&. +.sp +Added in version 216\&. +.RE +.PP +\fIIPForward=\fR +.RS 4 +Configures IP packet forwarding for the system\&. If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table\&. Takes a boolean, or the values +"ipv4" +or +"ipv6", which only enable IP packet forwarding for the specified address family\&. This controls the +net\&.ipv4\&.ip_forward +and +net\&.ipv6\&.conf\&.all\&.forwarding +sysctl options of the network interface (see +\m[blue]\fBIP Sysctl\fR\m[]\&\s-2\u[7]\d\s+2 +for details about sysctl options)\&. Defaults to +"no"\&. +.sp +Note: this setting controls a global kernel option, and does so one way only: if a network that has this setting enabled is set up the global setting is turned on\&. However, it is never turned off again, even after all networks with this setting enabled are shut down again\&. +.sp +To allow IP packet forwarding only between specific network interfaces use a firewall\&. +.sp +Added in version 219\&. +.RE +.PP +\fIIPMasquerade=\fR +.RS 4 +Configures IP masquerading for the network interface\&. If enabled, packets forwarded from the network interface will be appear as coming from the local host\&. Takes one of +"ipv4", +"ipv6", +"both", or +"no"\&. Defaults to +"no"\&. If enabled, this automatically sets +\fIIPForward=\fR +to one of +"ipv4", +"ipv6" +or +"yes"\&. +.sp +Note\&. Any positive boolean values such as +"yes" +or +"true" +are now deprecated\&. Please use one of the values in the above\&. +.sp +Added in version 219\&. +.RE +.PP +\fIIPv6PrivacyExtensions=\fR +.RS 4 +Configures use of stateless temporary addresses that change over time (see +\m[blue]\fBRFC 4941\fR\m[]\&\s-2\u[8]\d\s+2, Privacy Extensions for Stateless Address Autoconfiguration in IPv6)\&. Takes a boolean or the special values +"prefer\-public" +and +"kernel"\&. When true, enables the privacy extensions and prefers temporary addresses over public addresses\&. When +"prefer\-public", enables the privacy extensions, but prefers public addresses over temporary addresses\&. When false, the privacy extensions remain disabled\&. When +"kernel", the kernel\*(Aqs default setting will be left in place\&. When unspecified, the value specified in the same setting in +\fBnetworkd.conf\fR(5), which defaults to +"no", will be used\&. +.sp +Added in version 222\&. +.RE +.PP +\fIIPv6AcceptRA=\fR +.RS 4 +Takes a boolean\&. Controls IPv6 Router Advertisement (RA) reception support for the interface\&. If true, RAs are accepted; if false, RAs are ignored\&. When RAs are accepted, they may trigger the start of the DHCPv6 client if the relevant flags are set in the RA data, or if no routers are found on the link\&. The default is to disable RA reception for bridge devices or when IP forwarding is enabled, and to enable it otherwise\&. Cannot be enabled on devices aggregated in a bond device or when link\-local addressing is disabled\&. +.sp +Further settings for the IPv6 RA support may be configured in the [IPv6AcceptRA] section, see below\&. +.sp +Also see +\m[blue]\fBIP Sysctl\fR\m[]\&\s-2\u[7]\d\s+2 +in the kernel documentation regarding +"accept_ra", but note that systemd\*(Aqs setting of +\fB1\fR +(i\&.e\&. true) corresponds to kernel\*(Aqs setting of +\fB2\fR\&. +.sp +Note that kernel\*(Aqs implementation of the IPv6 RA protocol is always disabled, regardless of this setting\&. If this option is enabled, a userspace implementation of the IPv6 RA protocol is used, and the kernel\*(Aqs own implementation remains disabled, since +\fBsystemd\-networkd\fR +needs to know all details supplied in the advertisements, and these are not available from the kernel if the kernel\*(Aqs own implementation is used\&. +.sp +Added in version 231\&. +.RE +.PP +\fIIPv6DuplicateAddressDetection=\fR +.RS 4 +Configures the amount of IPv6 Duplicate Address Detection (DAD) probes to send\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 228\&. +.RE +.PP +\fIIPv6HopLimit=\fR +.RS 4 +Configures IPv6 Hop Limit\&. Takes an integer in the range 1\&...255\&. For each router that forwards the packet, the hop limit is decremented by 1\&. When the hop limit field reaches zero, the packet is discarded\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 228\&. +.RE +.PP +\fIIPv4ReversePathFilter=\fR +.RS 4 +Configure IPv4 Reverse Path Filtering\&. If enabled, when an IPv4 packet is received, the machine will first check whether the +\fIsource\fR +of the packet would be routed through the interface it came in\&. If there is no route to the source on that interface, the machine will drop the packet\&. Takes one of +"no", +"strict", or +"loose"\&. When +"no", no source validation will be done\&. When +"strict", mode each incoming packet is tested against the FIB and if the incoming interface is not the best reverse path, the packet check will fail\&. By default failed packets are discarded\&. When +"loose", mode each incoming packet\*(Aqs source address is tested against the FIB\&. The packet is dropped only if the source address is not reachable via any interface on that router\&. See +\m[blue]\fBRFC 3704\fR\m[]\&\s-2\u[9]\d\s+2\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 255\&. +.RE +.PP +\fIIPv4AcceptLocal=\fR +.RS 4 +Takes a boolean\&. Accept packets with local source addresses\&. In combination with suitable routing, this can be used to direct packets between two local interfaces over the wire and have them accepted properly\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIIPv4RouteLocalnet=\fR +.RS 4 +Takes a boolean\&. When true, the kernel does not consider loopback addresses as martian source or destination while routing\&. This enables the use of 127\&.0\&.0\&.0/8 for local routing purposes\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 248\&. +.RE +.PP +\fIIPv4ProxyARP=\fR +.RS 4 +Takes a boolean\&. Configures proxy ARP for IPv4\&. Proxy ARP is the technique in which one host, usually a router, answers ARP requests intended for another machine\&. By "faking" its identity, the router accepts responsibility for routing packets to the "real" destination\&. See +\m[blue]\fBRFC 1027\fR\m[]\&\s-2\u[9]\d\s+2\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 233\&. +.RE +.PP +\fIIPv6ProxyNDP=\fR +.RS 4 +Takes a boolean\&. Configures proxy NDP for IPv6\&. Proxy NDP (Neighbor Discovery Protocol) is a technique for IPv6 to allow routing of addresses to a different destination when peers expect them to be present on a certain physical link\&. In this case a router answers Neighbour Advertisement messages intended for another machine by offering its own MAC address as destination\&. Unlike proxy ARP for IPv4, it is not enabled globally, but will only send Neighbour Advertisement messages for addresses in the IPv6 neighbor proxy table, which can also be shown by +\fBip \-6 neighbour show proxy\fR\&. systemd\-networkd will control the per\-interface `proxy_ndp` switch for each configured interface depending on this option\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 234\&. +.RE +.PP +\fIIPv6ProxyNDPAddress=\fR +.RS 4 +An IPv6 address, for which Neighbour Advertisement messages will be proxied\&. This option may be specified more than once\&. systemd\-networkd will add the +\fIIPv6ProxyNDPAddress=\fR +entries to the kernel\*(Aqs IPv6 neighbor proxy table\&. This setting implies +\fIIPv6ProxyNDP=yes\fR +but has no effect if +\fIIPv6ProxyNDP=\fR +has been set to false\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 233\&. +.RE +.PP +\fIIPv6SendRA=\fR +.RS 4 +Whether to enable or disable Router Advertisement sending on a link\&. Takes a boolean value\&. When enabled, prefixes configured in [IPv6Prefix] sections and routes configured in the [IPv6RoutePrefix] sections are distributed as defined in the [IPv6SendRA] section\&. If +\fIDHCPPrefixDelegation=\fR +is enabled, then the delegated prefixes are also distributed\&. See +\fIDHCPPrefixDelegation=\fR +setting and the [IPv6SendRA], [IPv6Prefix], [IPv6RoutePrefix], and [DHCPPrefixDelegation] sections for more configuration options\&. +.sp +Added in version 247\&. +.RE +.PP +\fIDHCPPrefixDelegation=\fR +.RS 4 +Takes a boolean value\&. When enabled, requests subnet prefixes on another link via the DHCPv6 protocol or via the 6RD option in the DHCPv4 protocol\&. An address within each delegated prefix will be assigned, and the prefixes will be announced through IPv6 Router Advertisement if +\fIIPv6SendRA=\fR +is enabled\&. This behaviour can be configured in the [DHCPPrefixDelegation] section\&. Defaults to disabled\&. +.sp +Added in version 250\&. +.RE +.PP +\fIIPv6MTUBytes=\fR +.RS 4 +Configures IPv6 maximum transmission unit (MTU)\&. An integer greater than or equal to 1280 bytes\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 239\&. +.RE +.PP +\fIKeepMaster=\fR +.RS 4 +Takes a boolean value\&. When enabled, the current master interface index will not be changed, and +\fIBatmanAdvanced=\fR, +\fIBond=\fR, +\fIBridge=\fR, and +\fIVRF=\fR +settings are ignored\&. This may be useful when a netdev with a master interface is created by another program, e\&.g\&. +\fBsystemd-nspawn\fR(1)\&. Defaults to false\&. +.sp +Added in version 250\&. +.RE +.PP +\fIBatmanAdvanced=\fR, \fIBond=\fR, \fIBridge=\fR, \fIVRF=\fR +.RS 4 +The name of the B\&.A\&.T\&.M\&.A\&.N\&. Advanced, bond, bridge, or VRF interface to add the link to\&. See +\fBsystemd.netdev\fR(5)\&. +.sp +Added in version 211\&. +.RE +.PP +\fIIPoIB=\fR, \fIIPVLAN=\fR, \fIIPVTAP=\fR, \fIMACsec=\fR, \fIMACVLAN=\fR, \fIMACVTAP=\fR, \fITunnel=\fR, \fIVLAN=\fR, \fIVXLAN=\fR, \fIXfrm=\fR +.RS 4 +The name of an IPoIB, IPVLAN, IPVTAP, MACsec, MACVLAN, MACVTAP, tunnel, VLAN, VXLAN, or Xfrm to be created on the link\&. See +\fBsystemd.netdev\fR(5)\&. This option may be specified more than once\&. +.sp +Added in version 211\&. +.RE +.PP +\fIActiveSlave=\fR +.RS 4 +Takes a boolean\&. Specifies the new active slave\&. The +"ActiveSlave=" +option is only valid for following modes: +"active\-backup", +"balance\-alb", and +"balance\-tlb"\&. Defaults to false\&. +.sp +Added in version 235\&. +.RE +.PP +\fIPrimarySlave=\fR +.RS 4 +Takes a boolean\&. Specifies which slave is the primary device\&. The specified device will always be the active slave while it is available\&. Only when the primary is off\-line will alternate devices be used\&. This is useful when one slave is preferred over another, e\&.g\&. when one slave has higher throughput than another\&. The +"PrimarySlave=" +option is only valid for following modes: +"active\-backup", +"balance\-alb", and +"balance\-tlb"\&. Defaults to false\&. +.sp +Added in version 235\&. +.RE +.PP +\fIConfigureWithoutCarrier=\fR +.RS 4 +Takes a boolean\&. Allows networkd to configure a specific link even if it has no carrier\&. Defaults to false\&. If enabled, and the +\fIIgnoreCarrierLoss=\fR +setting is not explicitly set, then it is enabled as well\&. +.sp +Added in version 235\&. +.RE +.PP +\fIIgnoreCarrierLoss=\fR +.RS 4 +Takes a boolean or a timespan\&. When true, +\fBsystemd\-networkd\fR +retains both the static and dynamic configuration of the interface even if its carrier is lost\&. When false, +\fBsystemd\-networkd\fR +drops both the static and dynamic configuration of the interface\&. When a timespan is specified, +\fBsystemd\-networkd\fR +waits for the specified timespan, and ignores the carrier loss if the link regain its carrier within the timespan\&. Setting 0 seconds is equivalent to +"no", and +"infinite" +is equivalent to +"yes"\&. +.sp +Setting a finite timespan may be useful when e\&.g\&. in the following cases: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A wireless interface connecting to a network which has multiple access points with the same SSID\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Enslaving a wireless interface to a bond interface, which may disconnect from the connected access point and causes its carrier to be lost\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The driver of the interface resets when the MTU is changed\&. +.RE +.sp +When +\fIBond=\fR +is specified to a wireless interface, defaults to 3 seconds\&. When the DHCPv4 client is enabled and +\fIUseMTU=\fR +in the [DHCPv4] section enabled, defaults to 5 seconds\&. Otherwise, defaults to the value specified with +\fIConfigureWithoutCarrier=\fR\&. When +\fIActivationPolicy=\fR +is set to +"always\-up", this is forced to +"yes", and ignored any user specified values\&. +.sp +Added in version 242\&. +.RE +.PP +\fIKeepConfiguration=\fR +.RS 4 +Takes a boolean or one of +"static", +"dhcp\-on\-stop", +"dhcp"\&. When +"static", +\fBsystemd\-networkd\fR +will not drop static addresses and routes on starting up process\&. When set to +"dhcp\-on\-stop", +\fBsystemd\-networkd\fR +will not drop addresses and routes on stopping the daemon\&. When +"dhcp", the addresses and routes provided by a DHCP server will never be dropped even if the DHCP lease expires\&. This is contrary to the DHCP specification, but may be the best choice if, e\&.g\&., the root filesystem relies on this connection\&. The setting +"dhcp" +implies +"dhcp\-on\-stop", and +"yes" +implies +"dhcp" +and +"static"\&. Defaults to +"dhcp\-on\-stop" +when +\fBsystemd\-networkd\fR +is running in initrd, +"yes" +when the root filesystem is a network filesystem, and +"no" +otherwise\&. +.sp +Added in version 243\&. +.RE +.SH "[ADDRESS] SECTION OPTIONS" +.PP +An [Address] section accepts the following keys\&. Specify several [Address] sections to configure several addresses\&. +.PP +\fIAddress=\fR +.RS 4 +As in the [Network] section\&. This setting is mandatory\&. Each [Address] section can contain one +\fIAddress=\fR +setting\&. +.sp +Added in version 211\&. +.RE +.PP +\fIPeer=\fR +.RS 4 +The peer address in a point\-to\-point connection\&. Accepts the same format as the +\fIAddress=\fR +setting\&. +.sp +Added in version 216\&. +.RE +.PP +\fIBroadcast=\fR +.RS 4 +Takes an IPv4 address or boolean value\&. The address must be in the format described in +\fBinet_pton\fR(3)\&. If set to true, then the IPv4 broadcast address will be derived from the +\fIAddress=\fR +setting\&. If set to false, then the broadcast address will not be set\&. Defaults to true, except for wireguard interfaces, where it default to false\&. +.sp +Added in version 211\&. +.RE +.PP +\fILabel=\fR +.RS 4 +Specifies the label for the IPv4 address\&. The label must be a 7\-bit ASCII string with a length of 1\&...15 characters\&. Defaults to unset\&. +.sp +Added in version 211\&. +.RE +.PP +\fIPreferredLifetime=\fR +.RS 4 +Allows the default "preferred lifetime" of the address to be overridden\&. Only three settings are accepted: +"forever", +"infinity", which is the default and means that the address never expires, and +"0", which means that the address is considered immediately "expired" and will not be used, unless explicitly requested\&. A setting of +\fBPreferredLifetime=0\fR +is useful for addresses which are added to be used only by a specific application, which is then configured to use them explicitly\&. +.sp +Added in version 230\&. +.RE +.PP +\fIScope=\fR +.RS 4 +The scope of the address, which can be +"global" +(valid everywhere on the network, even through a gateway), +"link" +(only valid on this device, will not traverse a gateway) or +"host" +(only valid within the device itself, e\&.g\&. 127\&.0\&.0\&.1) or an integer in the range 0\&...255\&. Defaults to +"global"\&. IPv4 only \- IPv6 scope is automatically assigned by the kernel and cannot be set manually\&. +.sp +Added in version 235\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +The metric of the prefix route, which is pointing to the subnet of the configured IP address, taking the configured prefix length into account\&. Takes an unsigned integer in the range 0\&...4294967295\&. When unset or set to 0, the kernel\*(Aqs default value is used\&. This setting will be ignored when +\fIAddPrefixRoute=\fR +is false\&. +.sp +Added in version 246\&. +.RE +.PP +\fIHomeAddress=\fR +.RS 4 +Takes a boolean\&. Designates this address the "home address" as defined in +\m[blue]\fBRFC 6275\fR\m[]\&\s-2\u[10]\d\s+2\&. Supported only on IPv6\&. Defaults to false\&. +.sp +Added in version 232\&. +.RE +.PP +\fIDuplicateAddressDetection=\fR +.RS 4 +Takes one of +"ipv4", +"ipv6", +"both", or +"none"\&. When +"ipv4", performs IPv4 Address Conflict Detection\&. See +\m[blue]\fBRFC 5227\fR\m[]\&\s-2\u[11]\d\s+2\&. When +"ipv6", performs IPv6 Duplicate Address Detection\&. See +\m[blue]\fBRFC 4862\fR\m[]\&\s-2\u[12]\d\s+2\&. Defaults to +"ipv4" +for IPv4 link\-local addresses, +"ipv6" +for IPv6 addresses, and +"none" +otherwise\&. +.sp +Added in version 232\&. +.RE +.PP +\fIManageTemporaryAddress=\fR +.RS 4 +Takes a boolean\&. If true the kernel manage temporary addresses created from this one as template on behalf of Privacy Extensions +\m[blue]\fBRFC 3041\fR\m[]\&\s-2\u[13]\d\s+2\&. For this to become active, the use_tempaddr sysctl setting has to be set to a value greater than zero\&. The given address needs to have a prefix length of 64\&. This flag allows using privacy extensions in a manually configured network, just like if stateless auto\-configuration was active\&. Defaults to false\&. +.sp +Added in version 232\&. +.RE +.PP +\fIAddPrefixRoute=\fR +.RS 4 +Takes a boolean\&. When true, the prefix route for the address is automatically added\&. Defaults to true\&. +.sp +Added in version 245\&. +.RE +.PP +\fIAutoJoin=\fR +.RS 4 +Takes a boolean\&. Joining multicast group on ethernet level via +\fBip maddr\fR +command would not work if we have an Ethernet switch that does IGMP snooping since the switch would not replicate multicast packets on ports that did not have IGMP reports for the multicast addresses\&. Linux vxlan interfaces created via +\fBip link add vxlan\fR +or networkd\*(Aqs netdev kind vxlan have the group option that enables them to do the required join\&. By extending +\fBip address\fR +command with option +"autojoin" +we can get similar functionality for openvswitch (OVS) vxlan interfaces as well as other tunneling mechanisms that need to receive multicast traffic\&. Defaults to +"no"\&. +.sp +Added in version 232\&. +.RE +.PP +\fINetLabel=\fR\fIlabel\fR +.RS 4 +This setting provides a method for integrating static and dynamic network configuration into Linux +\m[blue]\fBNetLabel\fR\m[]\&\s-2\u[14]\d\s+2 +subsystem rules, used by +\m[blue]\fBLinux Security Modules (LSMs)\fR\m[]\&\s-2\u[15]\d\s+2 +for network access control\&. The label, with suitable LSM rules, can be used to control connectivity of (for example) a service with peers in the local network\&. At least with SELinux, only the ingress can be controlled but not egress\&. The benefit of using this setting is that it may be possible to apply interface independent part of NetLabel configuration at very early stage of system boot sequence, at the time when the network interfaces are not available yet, with +\fBnetlabelctl\fR(8), and the per\-interface configuration with +\fBsystemd\-networkd\fR +once the interfaces appear later\&. Currently this feature is only implemented for SELinux\&. +.sp +The option expects a single NetLabel label\&. The label must conform to lexical restrictions of LSM labels\&. When an interface is configured with IP addresses, the addresses and subnetwork masks will be appended to the +\m[blue]\fBNetLabel Fallback Peer Labeling\fR\m[]\&\s-2\u[16]\d\s+2 +rules\&. They will be removed when the interface is deconfigured\&. Failures to manage the labels will be ignored\&. +.sp +Warning: Once labeling is enabled for network traffic, a lot of LSM access control points in Linux networking stack go from dormant to active\&. Care should be taken to avoid getting into a situation where for example remote connectivity is broken, when the security policy hasn\*(Aqt been updated to consider LSM per\-packet access controls and no rules would allow any network traffic\&. Also note that additional configuration with +\fBnetlabelctl\fR(8) +is needed\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Address] +NetLabel=system_u:object_r:localnet_peer_t:s0 +.fi +.if n \{\ +.RE +.\} +.sp +With the example rules applying for interface +"eth0", when the interface is configured with an IPv4 address of 10\&.0\&.0\&.123/8, +\fBsystemd\-networkd\fR +performs the equivalent of +\fBnetlabelctl\fR +operation +.sp +.if n \{\ +.RS 4 +.\} +.nf +netlabelctl unlbl add interface eth0 address:10\&.0\&.0\&.0/8 label:system_u:object_r:localnet_peer_t:s0 +.fi +.if n \{\ +.RE +.\} +.sp +and the reverse operation when the IPv4 address is deconfigured\&. The configuration can be used with LSM rules; in case of SELinux to allow a SELinux domain to receive data from objects of SELinux +"peer" +class\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +type localnet_peer_t; +allow my_server_t localnet_peer_t:peer recv; +.fi +.if n \{\ +.RE +.\} +.sp +The effect of the above configuration and rules (in absence of other rules as may be the case) is to only allow +"my_server_t" +(and nothing else) to receive data from local subnet 10\&.0\&.0\&.0/8 of interface +"eth0"\&. +.sp +Added in version 252\&. +.RE +.PP +\fINFTSet=\fR\fIsource\fR:\fIfamily\fR:\fItable\fR:\fIset\fR +.RS 4 +This setting provides a method for integrating network configuration into firewall rules with +\m[blue]\fBNFT\fR\m[]\&\s-2\u[17]\d\s+2 +sets\&. The benefit of using the setting is that static network configuration (or dynamically obtained network addresses, see similar directives in other sections) can be used in firewall rules with the indirection of NFT set types\&. For example, access could be granted for hosts in the local subnetwork only\&. Firewall rules using IP address of an interface are also instantly updated when the network configuration changes, for example via DHCP\&. +.sp +This option expects a whitespace separated list of NFT set definitions\&. Each definition consists of a colon\-separated tuple of source type (one of +"address", +"prefix" +or +"ifindex"), NFT address family (one of +"arp", +"bridge", +"inet", +"ip", +"ip6", or +"netdev"), table name and set name\&. The names of tables and sets must conform to lexical restrictions of NFT table names\&. The type of the element used in the NFT filter must match the type implied by the directive ("address", +"prefix" +or +"ifindex") and address type (IPv4 or IPv6) as shown in the table below\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Defined \fIsource type\fR values +.TS +allbox tab(:); +lB lB lB. +T{ +Source type +T}:T{ +Description +T}:T{ +Corresponding NFT type name +T} +.T& +l l l +l l l +l l l. +T{ +"address" +T}:T{ +host IP address +T}:T{ +"ipv4_addr" or "ipv6_addr" +T} +T{ +"prefix" +T}:T{ +network prefix +T}:T{ +"ipv4_addr" or "ipv6_addr", with "flags interval" +T} +T{ +"ifindex" +T}:T{ +interface index +T}:T{ +"iface_index" +T} +.TE +.sp 1 +When an interface is configured with IP addresses, the addresses, subnetwork masks or interface index will be appended to the NFT sets\&. The information will be removed when the interface is deconfigured\&. +\fBsystemd\-networkd\fR +only inserts elements to (or removes from) the sets, so the related NFT rules, tables and sets must be prepared elsewhere in advance\&. Failures to manage the sets will be ignored\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Address] +NFTSet=prefix:netdev:filter:eth_ipv4_prefix +.fi +.if n \{\ +.RE +.\} +.sp +Corresponding NFT rules: +.sp +.if n \{\ +.RS 4 +.\} +.nf +table netdev filter { + set eth_ipv4_prefix { + type ipv4_addr + flags interval + } + chain eth_ingress { + type filter hook ingress device "eth0" priority filter; policy drop; + ip daddr != @eth_ipv4_prefix drop + accept + } +} +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 255\&. +.RE +.SH "[NEIGHBOR] SECTION OPTIONS" +.PP +A [Neighbor] section accepts the following keys\&. The neighbor section adds a permanent, static entry to the neighbor table (IPv6) or ARP table (IPv4) for the given hardware address on the links matched for the network\&. Specify several [Neighbor] sections to configure several static neighbors\&. +.PP +\fIAddress=\fR +.RS 4 +The IP address of the neighbor\&. +.sp +Added in version 240\&. +.RE +.PP +\fILinkLayerAddress=\fR +.RS 4 +The link layer address (MAC address or IP address) of the neighbor\&. +.sp +Added in version 243\&. +.RE +.SH "[IPV6ADDRESSLABEL] SECTION OPTIONS" +.PP +An [IPv6AddressLabel] section accepts the following keys\&. Specify several [IPv6AddressLabel] sections to configure several address labels\&. IPv6 address labels are used for address selection\&. See +\m[blue]\fBRFC 3484\fR\m[]\&\s-2\u[18]\d\s+2\&. Precedence is managed by userspace, and only the label itself is stored in the kernel\&. +.PP +\fILabel=\fR +.RS 4 +The label for the prefix, an unsigned integer in the range 0\&...4294967294\&. 0xffffffff is reserved\&. This setting is mandatory\&. +.sp +Added in version 234\&. +.RE +.PP +\fIPrefix=\fR +.RS 4 +IPv6 prefix is an address with a prefix length, separated by a slash +"/" +character\&. This setting is mandatory\&. +.sp +Added in version 234\&. +.RE +.SH "[ROUTINGPOLICYRULE] SECTION OPTIONS" +.PP +An [RoutingPolicyRule] section accepts the following settings\&. Specify several [RoutingPolicyRule] sections to configure several rules\&. +.PP +\fITypeOfService=\fR +.RS 4 +This specifies the Type of Service (ToS) field of packets to match; it takes an unsigned integer in the range 0\&...255\&. The field can be used to specify precedence (the first 3 bits) and ToS (the next 3 bits)\&. The field can be also used to specify Differentiated Services Code Point (DSCP) (the first 6 bits) and Explicit Congestion Notification (ECN) (the last 2 bits)\&. See +\m[blue]\fBType of Service\fR\m[]\&\s-2\u[19]\d\s+2 +and +\m[blue]\fBDifferentiated services\fR\m[]\&\s-2\u[20]\d\s+2 +for more details\&. +.sp +Added in version 235\&. +.RE +.PP +\fIFrom=\fR +.RS 4 +Specifies the source address prefix to match\&. Possibly followed by a slash and the prefix length\&. +.sp +Added in version 235\&. +.RE +.PP +\fITo=\fR +.RS 4 +Specifies the destination address prefix to match\&. Possibly followed by a slash and the prefix length\&. +.sp +Added in version 235\&. +.RE +.PP +\fIFirewallMark=\fR +.RS 4 +Specifies the iptables firewall mark value to match (a number in the range 1\&...4294967295)\&. Optionally, the firewall mask (also a number between 1\&...4294967295) can be suffixed with a slash ("/"), e\&.g\&., +"7/255"\&. +.sp +Added in version 235\&. +.RE +.PP +\fITable=\fR +.RS 4 +Specifies the routing table identifier to look up if the rule selector matches\&. Takes one of predefined names +"default", +"main", and +"local", and names defined in +\fIRouteTable=\fR +in +\fBnetworkd.conf\fR(5), or a number between 1 and 4294967295\&. Defaults to +"main"\&. +.sp +Added in version 235\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +Specifies the priority of this rule\&. +\fIPriority=\fR +is an integer in the range 0\&...4294967295\&. Higher number means lower priority, and rules get processed in order of increasing number\&. Defaults to unset, and the kernel will pick a value dynamically\&. +.sp +Added in version 235\&. +.RE +.PP +\fIIncomingInterface=\fR +.RS 4 +Specifies incoming device to match\&. If the interface is loopback, the rule only matches packets originating from this host\&. +.sp +Added in version 236\&. +.RE +.PP +\fIOutgoingInterface=\fR +.RS 4 +Specifies the outgoing device to match\&. The outgoing interface is only available for packets originating from local sockets that are bound to a device\&. +.sp +Added in version 236\&. +.RE +.PP +\fISourcePort=\fR +.RS 4 +Specifies the source IP port or IP port range match in forwarding information base (FIB) rules\&. A port range is specified by the lower and upper port separated by a dash\&. Defaults to unset\&. +.sp +Added in version 240\&. +.RE +.PP +\fIDestinationPort=\fR +.RS 4 +Specifies the destination IP port or IP port range match in forwarding information base (FIB) rules\&. A port range is specified by the lower and upper port separated by a dash\&. Defaults to unset\&. +.sp +Added in version 240\&. +.RE +.PP +\fIIPProtocol=\fR +.RS 4 +Specifies the IP protocol to match in forwarding information base (FIB) rules\&. Takes IP protocol name such as +"tcp", +"udp" +or +"sctp", or IP protocol number such as +"6" +for +"tcp" +or +"17" +for +"udp"\&. Defaults to unset\&. +.sp +Added in version 240\&. +.RE +.PP +\fIInvertRule=\fR +.RS 4 +A boolean\&. Specifies whether the rule is to be inverted\&. Defaults to false\&. +.sp +Added in version 240\&. +.RE +.PP +\fIFamily=\fR +.RS 4 +Takes a special value +"ipv4", +"ipv6", or +"both"\&. By default, the address family is determined by the address specified in +\fITo=\fR +or +\fIFrom=\fR\&. If neither +\fITo=\fR +nor +\fIFrom=\fR +are specified, then defaults to +"ipv4"\&. +.sp +Added in version 243\&. +.RE +.PP +\fIUser=\fR +.RS 4 +Takes a username, a user ID, or a range of user IDs separated by a dash\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fISuppressPrefixLength=\fR +.RS 4 +Takes a number +\fIN\fR +in the range 0\&...128 and rejects routing decisions that have a prefix length of +\fIN\fR +or less\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fISuppressInterfaceGroup=\fR +.RS 4 +Takes an integer in the range 0\&...2147483647 and rejects routing decisions that have an interface with the same group id\&. It has the same meaning as +\fBsuppress_ifgroup\fR +in +\fBip rule\fR\&. Defaults to unset\&. +.sp +Added in version 250\&. +.RE +.PP +\fIType=\fR +.RS 4 +Specifies Routing Policy Database (RPDB) rule type\&. Takes one of +"blackhole", +"unreachable" +or +"prohibit"\&. +.sp +Added in version 248\&. +.RE +.SH "[NEXTHOP] SECTION OPTIONS" +.PP +The [NextHop] section is used to manipulate entries in the kernel\*(Aqs "nexthop" tables\&. The [NextHop] section accepts the following settings\&. Specify several [NextHop] sections to configure several hops\&. +.PP +\fIId=\fR +.RS 4 +The id of the next hop\&. Takes an integer in the range 1\&...4294967295\&. If unspecified, then automatically chosen by kernel\&. +.sp +Added in version 244\&. +.RE +.PP +\fIGateway=\fR +.RS 4 +As in the [Network] section\&. +.sp +Added in version 244\&. +.RE +.PP +\fIFamily=\fR +.RS 4 +Takes one of the special values +"ipv4" +or +"ipv6"\&. By default, the family is determined by the address specified in +\fIGateway=\fR\&. If +\fIGateway=\fR +is not specified, then defaults to +"ipv4"\&. +.sp +Added in version 248\&. +.RE +.PP +\fIOnLink=\fR +.RS 4 +Takes a boolean\&. If set to true, the kernel does not have to check if the gateway is reachable directly by the current machine (i\&.e\&., attached to the local network), so that we can insert the nexthop in the kernel table without it being complained about\&. Defaults to +"no"\&. +.sp +Added in version 248\&. +.RE +.PP +\fIBlackhole=\fR +.RS 4 +Takes a boolean\&. If enabled, packets to the corresponding routes are discarded silently, and +\fIGateway=\fR +cannot be specified\&. Defaults to +"no"\&. +.sp +Added in version 248\&. +.RE +.PP +\fIGroup=\fR +.RS 4 +Takes a whitespace separated list of nexthop IDs\&. Each ID must be in the range 1\&...4294967295\&. Optionally, each nexthop ID can take a weight after a colon ("\fIid\fR[:\fIweight\fR]")\&. The weight must be in the range 1\&...255\&. If the weight is not specified, then it is assumed that the weight is 1\&. This setting cannot be specified with +\fIGateway=\fR, +\fIFamily=\fR, +\fIBlackhole=\fR\&. This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. Defaults to unset\&. +.sp +Added in version 249\&. +.RE +.SH "[ROUTE] SECTION OPTIONS" +.PP +The [Route] section accepts the following settings\&. Specify several [Route] sections to configure several routes\&. +.PP +\fIGateway=\fR +.RS 4 +Takes the gateway address or the special values +"_dhcp4" +and +"_ipv6ra"\&. If +"_dhcp4" +or +"_ipv6ra" +is set, then the gateway address provided by DHCPv4 or IPv6 RA is used\&. +.sp +Added in version 211\&. +.RE +.PP +\fIGatewayOnLink=\fR +.RS 4 +Takes a boolean\&. If set to true, the kernel does not have to check if the gateway is reachable directly by the current machine (i\&.e\&., attached to the local network), so that we can insert the route in the kernel table without it being complained about\&. Defaults to +"no"\&. +.sp +Added in version 234\&. +.RE +.PP +\fIDestination=\fR +.RS 4 +The destination prefix of the route\&. Possibly followed by a slash and the prefix length\&. If omitted, a full\-length host route is assumed\&. +.sp +Added in version 211\&. +.RE +.PP +\fISource=\fR +.RS 4 +The source prefix of the route\&. Possibly followed by a slash and the prefix length\&. If omitted, a full\-length host route is assumed\&. +.sp +Added in version 218\&. +.RE +.PP +\fIMetric=\fR +.RS 4 +The metric of the route\&. Takes an unsigned integer in the range 0\&...4294967295\&. Defaults to unset, and the kernel\*(Aqs default will be used\&. +.sp +Added in version 216\&. +.RE +.PP +\fIIPv6Preference=\fR +.RS 4 +Specifies the route preference as defined in +\m[blue]\fBRFC 4191\fR\m[]\&\s-2\u[21]\d\s+2 +for Router Discovery messages\&. Which can be one of +"low" +the route has a lowest priority, +"medium" +the route has a default priority or +"high" +the route has a highest priority\&. +.sp +Added in version 234\&. +.RE +.PP +\fIScope=\fR +.RS 4 +The scope of the IPv4 route, which can be +"global", +"site", +"link", +"host", or +"nowhere": +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"global" +means the route can reach hosts more than one hop away\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"site" +means an interior route in the local autonomous system\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"link" +means the route can only reach hosts on the local network (one hop away)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"host" +means the route will not leave the local machine (used for internal addresses like 127\&.0\&.0\&.1)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"nowhere" +means the destination doesn\*(Aqt exist\&. +.RE +.sp +For IPv4 route, defaults to +"host" +if +\fIType=\fR +is +"local" +or +"nat", and +"link" +if +\fIType=\fR +is +"broadcast", +"multicast", +"anycast", or +"unicast"\&. In other cases, defaults to +"global"\&. The value is not used for IPv6\&. +.sp +Added in version 219\&. +.RE +.PP +\fIPreferredSource=\fR +.RS 4 +The preferred source address of the route\&. The address must be in the format described in +\fBinet_pton\fR(3)\&. +.sp +Added in version 227\&. +.RE +.PP +\fITable=\fR +.RS 4 +The table identifier for the route\&. Takes one of predefined names +"default", +"main", and +"local", and names defined in +\fIRouteTable=\fR +in +\fBnetworkd.conf\fR(5), or a number between 1 and 4294967295\&. The table can be retrieved using +\fBip route show table \fR\fB\fInum\fR\fR\&. If unset and +\fIType=\fR +is +"local", +"broadcast", +"anycast", or +"nat", then +"local" +is used\&. In other cases, defaults to +"main"\&. +.sp +Added in version 230\&. +.RE +.PP +\fIHopLimit=\fR +.RS 4 +Configures per route hop limit\&. Takes an integer in the range 1\&...255\&. See also +\fIIPv6HopLimit=\fR\&. +.sp +Added in version 255\&. +.RE +.PP +\fIProtocol=\fR +.RS 4 +The protocol identifier for the route\&. Takes a number between 0 and 255 or the special values +"kernel", +"boot", +"static", +"ra" +and +"dhcp"\&. Defaults to +"static"\&. +.sp +Added in version 234\&. +.RE +.PP +\fIType=\fR +.RS 4 +Specifies the type for the route\&. Takes one of +"unicast", +"local", +"broadcast", +"anycast", +"multicast", +"blackhole", +"unreachable", +"prohibit", +"throw", +"nat", and +"xresolve"\&. If +"unicast", a regular route is defined, i\&.e\&. a route indicating the path to take to a destination network address\&. If +"blackhole", packets to the defined route are discarded silently\&. If +"unreachable", packets to the defined route are discarded and the ICMP message "Host Unreachable" is generated\&. If +"prohibit", packets to the defined route are discarded and the ICMP message "Communication Administratively Prohibited" is generated\&. If +"throw", route lookup in the current routing table will fail and the route selection process will return to Routing Policy Database (RPDB)\&. Defaults to +"unicast"\&. +.sp +Added in version 235\&. +.RE +.PP +\fIInitialCongestionWindow=\fR +.RS 4 +The TCP initial congestion window is used during the start of a TCP connection\&. During the start of a TCP session, when a client requests a resource, the server\*(Aqs initial congestion window determines how many packets will be sent during the initial burst of data without waiting for acknowledgement\&. Takes a number between 1 and 1023\&. Note that 100 is considered an extremely large value for this option\&. When unset, the kernel\*(Aqs default (typically 10) will be used\&. +.sp +Added in version 237\&. +.RE +.PP +\fIInitialAdvertisedReceiveWindow=\fR +.RS 4 +The TCP initial advertised receive window is the amount of receive data (in bytes) that can initially be buffered at one time on a connection\&. The sending host can send only that amount of data before waiting for an acknowledgment and window update from the receiving host\&. Takes a number between 1 and 1023\&. Note that 100 is considered an extremely large value for this option\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 237\&. +.RE +.PP +\fIQuickAck=\fR +.RS 4 +Takes a boolean\&. When true, the TCP quick ACK mode for the route is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 237\&. +.RE +.PP +\fIFastOpenNoCookie=\fR +.RS 4 +Takes a boolean\&. When true enables TCP fastopen without a cookie on a per\-route basis\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.PP +\fITTLPropagate=\fR +.RS 4 +Takes a boolean\&. When true enables TTL propagation at Label Switched Path (LSP) egress\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.PP +\fIMTUBytes=\fR +.RS 4 +The maximum transmission unit in bytes to set for the route\&. The usual suffixes K, M, G, are supported and are understood to the base of 1024\&. +.sp +Added in version 239\&. +.RE +.PP +\fITCPAdvertisedMaximumSegmentSize=\fR +.RS 4 +Specifies the Path MSS (in bytes) hints given on TCP layer\&. The usual suffixes K, M, G, are supported and are understood to the base of 1024\&. An unsigned integer in the range 1\&...4294967294\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 248\&. +.RE +.PP +\fITCPCongestionControlAlgorithm=\fR +.RS 4 +Specifies the TCP congestion control algorithm for the route\&. Takes a name of the algorithm, e\&.g\&. +"bbr", +"dctcp", or +"vegas"\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 252\&. +.RE +.PP +\fITCPRetransmissionTimeoutSec=\fR +.RS 4 +Specifies the TCP Retransmission Timeout (RTO) for the route\&. Takes time values in seconds\&. This value specifies the timeout of an alive TCP connection, when retransmissions remain unacknowledged\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 255\&. +.RE +.PP +\fIMultiPathRoute=\fR\fI\fIaddress\fR\fR\fI[@\fR\fI\fIname\fR\fR\fI] [\fR\fI\fIweight\fR\fR\fI]\fR +.RS 4 +Configures multipath route\&. Multipath routing is the technique of using multiple alternative paths through a network\&. Takes gateway address\&. Optionally, takes a network interface name or index separated with +"@", and a weight in 1\&.\&.256 for this multipath route separated with whitespace\&. This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. +.sp +Added in version 245\&. +.RE +.PP +\fINextHop=\fR +.RS 4 +Specifies the nexthop id\&. Takes an unsigned integer in the range 1\&...4294967295\&. If set, the corresponding [NextHop] section must be configured\&. Defaults to unset\&. +.sp +Added in version 248\&. +.RE +.SH "[DHCPV4] SECTION OPTIONS" +.PP +The [DHCPv4] section configures the DHCPv4 client, if it is enabled with the +\fIDHCP=\fR +setting described above: +.PP +\fIRequestAddress=\fR +.RS 4 +Takes an IPv4 address\&. When specified, the Requested IP Address option (option code 50) is added with it to the initial DHCPDISCOVER message sent by the DHCP client\&. Defaults to unset, and an already assigned dynamic address to the interface is automatically picked\&. +.sp +Added in version 255\&. +.RE +.PP +\fISendHostname=\fR +.RS 4 +When true (the default), the machine\*(Aqs hostname (or the value specified with +\fIHostname=\fR, described below) will be sent to the DHCP server\&. Note that the hostname must consist only of 7\-bit ASCII lower\-case characters and no spaces or dots, and be formatted as a valid DNS domain name\&. Otherwise, the hostname is not sent even if this option is true\&. +.sp +Added in version 215\&. +.RE +.PP +\fIHostname=\fR +.RS 4 +Use this value for the hostname which is sent to the DHCP server, instead of machine\*(Aqs hostname\&. Note that the specified hostname must consist only of 7\-bit ASCII lower\-case characters and no spaces or dots, and be formatted as a valid DNS domain name\&. +.sp +Added in version 223\&. +.RE +.PP +\fIMUDURL=\fR +.RS 4 +When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to the DHCPv4 server\&. Takes a URL of length up to 255 characters\&. A superficial verification that the string is a valid URL will be performed\&. DHCPv4 clients are intended to have at most one MUD URL associated with them\&. See +\m[blue]\fBRFC 8520\fR\m[]\&\s-2\u[22]\d\s+2\&. +.sp +MUD is an embedded software standard defined by the IETF that allows IoT device makers to advertise device specifications, including the intended communication patterns for their device when it connects to the network\&. The network can then use this to author a context\-specific access policy, so the device functions only within those parameters\&. +.sp +Added in version 246\&. +.RE +.PP +\fIClientIdentifier=\fR +.RS 4 +The DHCPv4 client identifier to use\&. Takes one of +\fBmac\fR +or +\fBduid\fR\&. If set to +\fBmac\fR, the MAC address of the link is used\&. If set to +\fBduid\fR, an RFC4361\-compliant Client ID, which is the combination of IAID and DUID, is used\&. IAID can be configured by +\fIIAID=\fR\&. DUID can be configured by +\fIDUIDType=\fR +and +\fIDUIDRawData=\fR\&. Defaults to +\fBduid\fR\&. +.sp +Added in version 220\&. +.RE +.PP +\fIVendorClassIdentifier=\fR +.RS 4 +The vendor class identifier used to identify vendor type and configuration\&. +.sp +Added in version 216\&. +.RE +.PP +\fIUserClass=\fR +.RS 4 +A DHCPv4 client can use UserClass option to identify the type or category of user or applications it represents\&. The information contained in this option is a string that represents the user class of which the client is a member\&. Each class sets an identifying string of information to be used by the DHCP service to classify clients\&. Takes a whitespace\-separated list of strings\&. +.sp +Added in version 239\&. +.RE +.PP +\fIDUIDType=\fR +.RS 4 +Override the global +\fIDUIDType=\fR +setting for this network\&. See +\fBnetworkd.conf\fR(5) +for a description of possible values\&. +.sp +Added in version 230\&. +.RE +.PP +\fIDUIDRawData=\fR +.RS 4 +Override the global +\fIDUIDRawData=\fR +setting for this network\&. See +\fBnetworkd.conf\fR(5) +for a description of possible values\&. +.sp +Added in version 230\&. +.RE +.PP +\fIIAID=\fR +.RS 4 +The DHCP Identity Association Identifier (IAID) for the interface, a 32\-bit unsigned integer\&. +.sp +Added in version 230\&. +.RE +.PP +\fIRapidCommit=\fR +.RS 4 +Takes a boolean\&. The DHCPv4 client can obtain configuration parameters from a DHCPv4 server through a rapid two\-message exchange (discover and ack)\&. When the rapid commit option is set by both the DHCPv4 client and the DHCPv4 server, the two\-message exchange is used\&. Otherwise, the four\-message exchange (discover, offer, request, and ack) is used\&. The two\-message exchange provides faster client configuration\&. See +\m[blue]\fBRFC 4039\fR\m[]\&\s-2\u[23]\d\s+2 +for details\&. Defaults to true when +\fIAnonymize=no\fR +and neither +\fIAllowList=\fR +nor +\fIDenyList=\fR +is specified, and false otherwise\&. +.sp +Added in version 255\&. +.RE +.PP +\fIAnonymize=\fR +.RS 4 +Takes a boolean\&. When true, the options sent to the DHCP server will follow the +\m[blue]\fBRFC 7844\fR\m[]\&\s-2\u[24]\d\s+2 +(Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information\&. Defaults to false\&. +.sp +This option should only be set to true when +\fIMACAddressPolicy=\fR +is set to +\fBrandom\fR +(see +\fBsystemd.link\fR(5))\&. +.sp +When true, +\fIClientIdentifier=mac\fR, +\fIRapidCommit=no\fR, +\fISendHostname=no\fR, +\fIUse6RD=no\fR, +\fIUseCaptivePortal=no\fR, +\fIUseMTU=no\fR, +\fIUseNTP=no\fR, +\fIUseSIP=no\fR, and +\fIUseTimezone=no\fR +are implied and these settings in the \&.network file are silently ignored\&. Also, +\fIHostname=\fR, +\fIMUDURL=\fR, +\fIRequestAddress\fR, +\fIRequestOptions=\fR, +\fISendOption=\fR, +\fISendVendorOption=\fR, +\fIUserClass=\fR, and +\fIVendorClassIdentifier=\fR +are silently ignored\&. +.sp +With this option enabled DHCP requests will mimic those generated by Microsoft Windows, in order to reduce the ability to fingerprint and recognize installations\&. This means DHCP request sizes will grow and lease data will be more comprehensive than normally, though most of the requested data is not actually used\&. +.sp +Added in version 235\&. +.RE +.PP +\fIRequestOptions=\fR +.RS 4 +Sets request options to be sent to the server in the DHCPv4 request options list\&. A whitespace\-separated list of integers in the range 1\&...254\&. Defaults to unset\&. +.sp +Added in version 244\&. +.RE +.PP +\fISendOption=\fR +.RS 4 +Send an arbitrary raw option in the DHCPv4 request\&. Takes a DHCP option number, data type and data separated with a colon ("\fIoption\fR:\fItype\fR:\fIvalue\fR")\&. The option number must be an integer in the range 1\&...254\&. The type takes one of +"uint8", +"uint16", +"uint32", +"ipv4address", or +"string"\&. Special characters in the data string may be escaped using +\m[blue]\fBC\-style escapes\fR\m[]\&\s-2\u[25]\d\s+2\&. This setting can be specified multiple times\&. If an empty string is specified, then all options specified earlier are cleared\&. Defaults to unset\&. +.sp +Added in version 244\&. +.RE +.PP +\fISendVendorOption=\fR +.RS 4 +Send an arbitrary vendor option in the DHCPv4 request\&. Takes a DHCP option number, data type and data separated with a colon ("\fIoption\fR:\fItype\fR:\fIvalue\fR")\&. The option number must be an integer in the range 1\&...254\&. The type takes one of +"uint8", +"uint16", +"uint32", +"ipv4address", or +"string"\&. Special characters in the data string may be escaped using +\m[blue]\fBC\-style escapes\fR\m[]\&\s-2\u[25]\d\s+2\&. This setting can be specified multiple times\&. If an empty string is specified, then all options specified earlier are cleared\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIIPServiceType=\fR +.RS 4 +Takes one of the special values +"none", +"CS6", or +"CS4"\&. When +"none" +no IP service type is set to the packet sent from the DHCPv4 client\&. When +"CS6" +(network control) or +"CS4" +(realtime), the corresponding service type will be set\&. Defaults to +"CS6"\&. +.sp +Added in version 244\&. +.RE +.PP +\fISocketPriority=\fR +.RS 4 +The Linux socket option +\fBSO_PRIORITY\fR +applied to the raw IP socket used for initial DHCPv4 messages\&. Unset by default\&. Usual values range from 0 to 6\&. More details about +\fBSO_PRIORITY\fR +socket option in +\fBsocket\fR(7)\&. Can be used in conjunction with [VLAN] section +\fIEgressQOSMaps=\fR +setting of \&.netdev file to set the 802\&.1Q VLAN ethernet tagged header priority, see +\fBsystemd.netdev\fR(5)\&. +.sp +Added in version 253\&. +.RE +.PP +\fILabel=\fR +.RS 4 +Specifies the label for the IPv4 address received from the DHCP server\&. The label must be a 7\-bit ASCII string with a length of 1\&...15 characters\&. Defaults to unset\&. +.sp +Added in version 250\&. +.RE +.PP +\fIUseDNS=\fR +.RS 4 +When true (the default), the DNS servers received from the DHCP server will be used\&. +.sp +This corresponds to the +\fBnameserver\fR +option in +\fBresolv.conf\fR(5)\&. +.sp +Added in version 211\&. +.RE +.PP +\fIRoutesToDNS=\fR +.RS 4 +When true, the routes to the DNS servers received from the DHCP server will be configured\&. When +\fIUseDNS=\fR +is disabled, this setting is ignored\&. Defaults to true\&. +.sp +Added in version 243\&. +.RE +.PP +\fIUseNTP=\fR +.RS 4 +When true (the default), the NTP servers received from the DHCP server will be used by +systemd\-timesyncd\&.service\&. +.sp +Added in version 220\&. +.RE +.PP +\fIRoutesToNTP=\fR +.RS 4 +When true, the routes to the NTP servers received from the DHCP server will be configured\&. When +\fIUseNTP=\fR +is disabled, this setting is ignored\&. Defaults to true\&. +.sp +Added in version 249\&. +.RE +.PP +\fIUseSIP=\fR +.RS 4 +When true (the default), the SIP servers received from the DHCP server will be collected and made available to client programs\&. +.sp +Added in version 244\&. +.RE +.PP +\fIUseCaptivePortal=\fR +.RS 4 +When true (the default), the captive portal advertised by the DHCP server will be recorded and made available to client programs and displayed in the +\fBnetworkctl\fR(1) +status output per\-link\&. +.sp +Added in version 254\&. +.RE +.PP +\fIUseMTU=\fR +.RS 4 +When true, the interface maximum transmission unit from the DHCP server will be used on the current link\&. If +\fIMTUBytes=\fR +is set, then this setting is ignored\&. Defaults to false\&. +.sp +Note, some drivers will reset the interfaces if the MTU is changed\&. For such interfaces, please try to use +\fIIgnoreCarrierLoss=\fR +with a short timespan, e\&.g\&. +"3 seconds"\&. +.sp +Added in version 211\&. +.RE +.PP +\fIUseHostname=\fR +.RS 4 +When true (the default), the hostname received from the DHCP server will be set as the transient hostname of the system\&. +.sp +Added in version 211\&. +.RE +.PP +\fIUseDomains=\fR +.RS 4 +Takes a boolean, or the special value +\fBroute\fR\&. When true, the domain name received from the DHCP server will be used as DNS search domain over this link, similarly to the effect of the +\fBDomains=\fR +setting\&. If set to +\fBroute\fR, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching, similarly to the effect of the +\fBDomains=\fR +setting when the argument is prefixed with +"~"\&. Defaults to false\&. +.sp +It is recommended to enable this option only on trusted networks, as setting this affects resolution of all hostnames, in particular of single\-label names\&. It is generally safer to use the supplied domain only as routing domain, rather than as search domain, in order to not have it affect local resolution of single\-label names\&. +.sp +When set to true, this setting corresponds to the +\fBdomain\fR +option in +\fBresolv.conf\fR(5)\&. +.sp +Added in version 216\&. +.RE +.PP +\fIUseRoutes=\fR +.RS 4 +When true (the default), the static routes will be requested from the DHCP server and added to the routing table with a metric of 1024, and a scope of +\fBglobal\fR, +\fBlink\fR +or +\fBhost\fR, depending on the route\*(Aqs destination and gateway\&. If the destination is on the local host, e\&.g\&., 127\&.x\&.x\&.x, or the same as the link\*(Aqs own address, the scope will be set to +\fBhost\fR\&. Otherwise if the gateway is null (a direct route), a +\fBlink\fR +scope will be used\&. For anything else, scope defaults to +\fBglobal\fR\&. +.sp +Added in version 215\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +Set the routing metric for routes specified by the DHCP server (including the prefix route added for the specified prefix)\&. Takes an unsigned integer in the range 0\&...4294967295\&. Defaults to 1024\&. +.sp +Added in version 217\&. +.RE +.PP +\fIRouteTable=\fR\fI\fInum\fR\fR +.RS 4 +The table identifier for DHCP routes\&. Takes one of predefined names +"default", +"main", and +"local", and names defined in +\fIRouteTable=\fR +in +\fBnetworkd.conf\fR(5), or a number between 1\&...4294967295\&. +.sp +When used in combination with +\fIVRF=\fR, the VRF\*(Aqs routing table is used when this parameter is not specified\&. +.sp +Added in version 232\&. +.RE +.PP +\fIRouteMTUBytes=\fR +.RS 4 +Specifies the MTU for the DHCP routes\&. Please see the [Route] section for further details\&. +.sp +Added in version 245\&. +.RE +.PP +\fIQuickAck=\fR +.RS 4 +Takes a boolean\&. When true, the TCP quick ACK mode is enabled for the routes configured by the acquired DHCPv4 lease\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 253\&. +.RE +.PP +\fIInitialCongestionWindow=\fR +.RS 4 +As in the [Route] section\&. +.sp +Added in version 255\&. +.RE +.PP +\fIInitialAdvertisedReceiveWindow=\fR +.RS 4 +As in the [Route] section\&. +.sp +Added in version 255\&. +.RE +.PP +\fIUseGateway=\fR +.RS 4 +When true, and the DHCP server provides a Router option, the default gateway based on the router address will be configured\&. Defaults to unset, and the value specified with +\fIUseRoutes=\fR +will be used\&. +.sp +Note, when the server provides both the Router and Classless Static Routes option, and +\fIUseRoutes=\fR +is enabled, the Router option is always ignored regardless of this setting\&. See +\m[blue]\fBRFC 3442\fR\m[]\&\s-2\u[26]\d\s+2\&. +.sp +Added in version 246\&. +.RE +.PP +\fIUseTimezone=\fR +.RS 4 +When true, the timezone received from the DHCP server will be set as timezone of the local system\&. Defaults to false\&. +.sp +Added in version 226\&. +.RE +.PP +\fIUse6RD=\fR +.RS 4 +When true, subnets of the received IPv6 prefix are assigned to downstream interfaces which enables +\fIDHCPPrefixDelegation=\fR\&. See also +\fIDHCPPrefixDelegation=\fR +in the [Network] section, the [DHCPPrefixDelegation] section, and +\m[blue]\fBRFC 5969\fR\m[]\&\s-2\u[27]\d\s+2\&. Defaults to false\&. +.sp +Added in version 250\&. +.RE +.PP +\fIIPv6OnlyMode=\fR +.RS 4 +When true, the DHCPv4 configuration will be delayed by the timespan provided by the DHCP server and skip to configure dynamic IPv4 network connectivity if IPv6 connectivity is provided within the timespan\&. See +\m[blue]\fBRFC 8925\fR\m[]\&\s-2\u[28]\d\s+2\&. Defaults to true when +\fIIPv6AcceptRA=\fR +is enabled or DHCPv6 client is enabled (i\&.e\&., +\fIDHCP=yes\fR), and false otherwise\&. +.sp +Added in version 255\&. +.RE +.PP +\fIFallbackLeaseLifetimeSec=\fR +.RS 4 +Allows one to set DHCPv4 lease lifetime when DHCPv4 server does not send the lease lifetime\&. Takes one of +"forever" +or +"infinity"\&. If specified, the acquired address never expires\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRequestBroadcast=\fR +.RS 4 +Request the server to use broadcast messages before the IP address has been configured\&. This is necessary for devices that cannot receive RAW packets, or that cannot receive packets at all before an IP address has been configured\&. On the other hand, this must not be enabled on networks where broadcasts are filtered out\&. +.sp +Added in version 216\&. +.RE +.PP +\fIMaxAttempts=\fR +.RS 4 +Specifies how many times the DHCPv4 client configuration should be attempted\&. Takes a number or +"infinity"\&. Defaults to +"infinity"\&. Note that the time between retries is increased exponentially, up to approximately one per minute, so the network will not be overloaded even if this number is high\&. The default is suitable in most circumstances\&. +.sp +Added in version 243\&. +.RE +.PP +\fIListenPort=\fR +.RS 4 +Set the port from which the DHCP client packets originate\&. +.sp +Added in version 233\&. +.RE +.PP +\fIDenyList=\fR +.RS 4 +A whitespace\-separated list of IPv4 addresses\&. Each address can optionally take a prefix length after +"/"\&. DHCP offers from servers in the list are rejected\&. Note that if +\fIAllowList=\fR +is configured then +\fIDenyList=\fR +is ignored\&. +.sp +Note that this filters only DHCP offers, so the filtering may not work when +\fIRapidCommit=\fR +is enabled\&. See also +\fIRapidCommit=\fR +in the above\&. +.sp +Added in version 246\&. +.RE +.PP +\fIAllowList=\fR +.RS 4 +A whitespace\-separated list of IPv4 addresses\&. Each address can optionally take a prefix length after +"/"\&. DHCP offers from servers in the list are accepted\&. +.sp +Note that this filters only DHCP offers, so the filtering may not work when +\fIRapidCommit=\fR +is enabled\&. See also +\fIRapidCommit=\fR +in the above\&. +.sp +Added in version 246\&. +.RE +.PP +\fISendRelease=\fR +.RS 4 +When true, the DHCPv4 client sends a DHCP release packet when it stops\&. Defaults to true\&. +.sp +Added in version 243\&. +.RE +.PP +\fISendDecline=\fR +.RS 4 +A boolean\&. When true, +\fBsystemd\-networkd\fR +performs IPv4 Duplicate Address Detection to the acquired address by the DHCPv4 client\&. If duplicate is detected, the DHCPv4 client rejects the address by sending a +\fBDHCPDECLINE\fR +packet to the DHCP server, and tries to obtain an IP address again\&. See +\m[blue]\fBRFC 5227\fR\m[]\&\s-2\u[11]\d\s+2\&. Defaults to false\&. +.sp +Added in version 245\&. +.RE +.PP +\fINetLabel=\fR +.RS 4 +This applies the NetLabel for the addresses received with DHCP, like +\fINetLabel=\fR +in [Address] section applies it to statically configured addresses\&. See +\fINetLabel=\fR +in [Address] section for more details\&. +.sp +Added in version 252\&. +.RE +.PP +\fINFTSet=\fR +.RS 4 +This applies the NFT set for the network configuration received with DHCP, like +\fINFTSet=\fR +in [Address] section applies it to static configuration\&. See +\fINFTSet=\fR +in [Address] section for more details\&. For +"address" +or +"prefix" +source types, the type of the element used in the NFT filter must be +"ipv4_addr"\&. +.sp +Added in version 255\&. +.RE +.SH "[DHCPV6] SECTION OPTIONS" +.PP +The [DHCPv6] section configures the DHCPv6 client, if it is enabled with the +\fIDHCP=\fR +setting described above, or invoked by the IPv6 Router Advertisement: +.PP +\fIMUDURL=\fR, \fIIAID=\fR, \fIDUIDType=\fR, \fIDUIDRawData=\fR, \fIRequestOptions=\fR +.RS 4 +As in the [DHCPv4] section\&. +.sp +Added in version 246\&. +.RE +.PP +\fISendOption=\fR +.RS 4 +As in the [DHCPv4] section, however because DHCPv6 uses 16\-bit fields to store option numbers, the option number is an integer in the range 1\&...65536\&. +.sp +Added in version 246\&. +.RE +.PP +\fISendVendorOption=\fR +.RS 4 +Send an arbitrary vendor option in the DHCPv6 request\&. Takes an enterprise identifier, DHCP option number, data type, and data separated with a colon ("\fIenterprise identifier\fR:\fIoption\fR:\fItype\fR:\fIvalue\fR")\&. Enterprise identifier is an unsigned integer in the range 1\&...4294967294\&. The option number must be an integer in the range 1\&...254\&. Data type takes one of +"uint8", +"uint16", +"uint32", +"ipv4address", +"ipv6address", or +"string"\&. Special characters in the data string may be escaped using +\m[blue]\fBC\-style escapes\fR\m[]\&\s-2\u[25]\d\s+2\&. This setting can be specified multiple times\&. If an empty string is specified, then all options specified earlier are cleared\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIUserClass=\fR +.RS 4 +A DHCPv6 client can use User Class option to identify the type or category of user or applications it represents\&. The information contained in this option is a string that represents the user class of which the client is a member\&. Each class sets an identifying string of information to be used by the DHCP service to classify clients\&. Special characters in the data string may be escaped using +\m[blue]\fBC\-style escapes\fR\m[]\&\s-2\u[25]\d\s+2\&. This setting can be specified multiple times\&. If an empty string is specified, then all options specified earlier are cleared\&. Takes a whitespace\-separated list of strings\&. Note that currently +\fBNUL\fR +bytes are not allowed\&. +.sp +Added in version 246\&. +.RE +.PP +\fIVendorClass=\fR +.RS 4 +A DHCPv6 client can use VendorClass option to identify the vendor that manufactured the hardware on which the client is running\&. The information contained in the data area of this option is contained in one or more opaque fields that identify details of the hardware configuration\&. Takes a whitespace\-separated list of strings\&. +.sp +Added in version 246\&. +.RE +.PP +\fIPrefixDelegationHint=\fR +.RS 4 +Takes an IPv6 address with prefix length in the same format as the +\fIAddress=\fR +in the [Network] section\&. The DHCPv6 client will include a prefix hint in the DHCPv6 solicitation sent to the server\&. The prefix length must be in the range 1\&...128\&. Defaults to unset\&. +.sp +Added in version 244\&. +.RE +.PP +\fIRapidCommit=\fR +.RS 4 +Takes a boolean\&. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through a rapid two\-message exchange (solicit and reply)\&. When the rapid commit option is set by both the DHCPv6 client and the DHCPv6 server, the two\-message exchange is used\&. Otherwise, the four\-message exchange (solicit, advertise, request, and reply) is used\&. The two\-message exchange provides faster client configuration\&. See +\m[blue]\fBRFC 3315\fR\m[]\&\s-2\u[29]\d\s+2 +for details\&. Defaults to true, and the two\-message exchange will be used if the server support it\&. +.sp +Added in version 252\&. +.RE +.PP +\fISendHostname=\fR +.RS 4 +When true (the default), the machine\*(Aqs hostname (or the value specified with +\fIHostname=\fR, described below) will be sent to the DHCPv6 server\&. Note that the hostname must consist only of 7\-bit ASCII lower\-case characters and no spaces or dots, and be formatted as a valid DNS domain name\&. Otherwise, the hostname is not sent even if this option is true\&. +.sp +Added in version 255\&. +.RE +.PP +\fIHostname=\fR +.RS 4 +Use this value for the hostname which is sent to the DHCPv6 server, instead of machine\*(Aqs hostname\&. Note that the specified hostname must consist only of 7\-bit ASCII lower\-case characters and no spaces or dots, and be formatted as a valid DNS domain name\&. +.sp +Added in version 255\&. +.RE +.PP +\fIUseAddress=\fR +.RS 4 +When true (the default), the IP addresses provided by the DHCPv6 server will be assigned\&. +.sp +Added in version 248\&. +.RE +.PP +\fIUseCaptivePortal=\fR +.RS 4 +When true (the default), the captive portal advertised by the DHCPv6 server will be recorded and made available to client programs and displayed in the +\fBnetworkctl\fR(1) +status output per\-link\&. +.sp +Added in version 254\&. +.RE +.PP +\fIUseDelegatedPrefix=\fR +.RS 4 +When true (the default), the client will request the DHCPv6 server to delegate prefixes\&. If the server provides prefixes to be delegated, then subnets of the prefixes are assigned to the interfaces that have +\fIDHCPPrefixDelegation=yes\fR\&. See also the +\fIDHCPPrefixDelegation=\fR +setting in the [Network] section, settings in the [DHCPPrefixDelegation] section, and +\m[blue]\fBRFC 8415\fR\m[]\&\s-2\u[30]\d\s+2\&. +.sp +Added in version 250\&. +.RE +.PP +\fIUseDNS=\fR, \fIUseNTP=\fR, \fIUseHostname=\fR, \fIUseDomains=\fR, \fINetLabel=\fR, \fISendRelease=\fR +.RS 4 +As in the [DHCPv4] section\&. +.sp +Added in version 243\&. +.RE +.PP +\fINFTSet=\fR +.RS 4 +This applies the NFT set for the network configuration received with DHCP, like +\fINFTSet=\fR +in [Address] section applies it to static configuration\&. See +\fINFTSet=\fR +in [Address] section for more details\&. For +"address" +or +"prefix" +source types, the type of the element used in the NFT filter must be +"ipv6_addr"\&. +.sp +Added in version 255\&. +.RE +.PP +\fIWithoutRA=\fR +.RS 4 +Allows DHCPv6 client to start without router advertisements\*(Aqs +"managed" +or +"other configuration" +flag\&. Takes one of +"no", +"solicit", or +"information\-request"\&. If this is not specified, +"solicit" +is used when +\fIDHCPPrefixDelegation=\fR +is enabled and +\fIUplinkInterface=:self\fR +is specified in the [DHCPPrefixDelegation] section\&. Otherwise, defaults to +"no", and the DHCPv6 client will be started when an RA is received\&. See also the +\fIDHCPv6Client=\fR +setting in the [IPv6AcceptRA] section\&. +.sp +Added in version 246\&. +.RE +.SH "[DHCPPREFIXDELEGATION] SECTION OPTIONS" +.PP +The [DHCPPrefixDelegation] section configures subnet prefixes of the delegated prefixes acquired by a DHCPv6 client or by a DHCPv4 client through the 6RD option on another interface\&. The settings in this section are used only when the +\fIDHCPPrefixDelegation=\fR +setting in the [Network] section is enabled\&. +.PP +\fIUplinkInterface=\fR +.RS 4 +Specifies the name or the index of the uplink interface, or one of the special values +":self" +and +":auto"\&. When +":self", the interface itself is considered the uplink interface, and +\fIWithoutRA=solicit\fR +is implied if the setting is not explicitly specified\&. When +":auto", the first link which acquired prefixes to be delegated from the DHCPv6 or DHCPv4 server is selected\&. Defaults to +":auto"\&. +.sp +Added in version 250\&. +.RE +.PP +\fISubnetId=\fR +.RS 4 +Configure a specific subnet ID on the interface from a (previously) received prefix delegation\&. You can either set "auto" (the default) or a specific subnet ID (as defined in +\m[blue]\fBRFC 4291\fR\m[]\&\s-2\u[31]\d\s+2, section 2\&.5\&.4), in which case the allowed value is hexadecimal, from 0 to 0x7fffffffffffffff inclusive\&. +.sp +Added in version 246\&. +.RE +.PP +\fIAnnounce=\fR +.RS 4 +Takes a boolean\&. When enabled, and +\fIIPv6SendRA=\fR +in [Network] section is enabled, the delegated prefixes are distributed through the IPv6 Router Advertisement\&. This setting will be ignored when the +\fIDHCPPrefixDelegation=\fR +setting is enabled on the upstream interface\&. Defaults to yes\&. +.sp +Added in version 247\&. +.RE +.PP +\fIAssign=\fR +.RS 4 +Takes a boolean\&. Specifies whether to add an address from the delegated prefixes which are received from the WAN interface by the DHCPv6 Prefix Delegation\&. When true (on LAN interface), the EUI\-64 algorithm will be used by default to form an interface identifier from the delegated prefixes\&. See also +\fIToken=\fR +setting below\&. Defaults to yes\&. +.sp +Added in version 246\&. +.RE +.PP +\fIToken=\fR +.RS 4 +Specifies an optional address generation mode for assigning an address in each delegated prefix\&. This accepts the same syntax as +\fIToken=\fR +in the [IPv6AcceptRA] section\&. If +\fIAssign=\fR +is set to false, then this setting will be ignored\&. Defaults to unset, which means the EUI\-64 algorithm will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIManageTemporaryAddress=\fR +.RS 4 +As in the [Address] section, but defaults to true\&. +.sp +Added in version 248\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +The metric of the route to the delegated prefix subnet\&. Takes an unsigned integer in the range 0\&...4294967295\&. When set to 0, the kernel\*(Aqs default value is used\&. Defaults to 256\&. +.sp +Added in version 249\&. +.RE +.PP +\fINetLabel=\fR +.RS 4 +This applies the NetLabel for the addresses received with DHCP, like +\fINetLabel=\fR +in [Address] section applies it to statically configured addresses\&. See +\fINetLabel=\fR +in [Address] section for more details\&. +.sp +Added in version 252\&. +.RE +.PP +\fINFTSet=\fR +.RS 4 +This applies the NFT set for the network configuration received with DHCP, like +\fINFTSet=\fR +in [Address] section applies it to static configuration\&. See +\fINFTSet=\fR +in [Address] section for more details\&. For +"address" +or +"prefix" +source types, the type of the element used in the NFT filter must be +"ipv6_addr"\&. +.sp +Added in version 255\&. +.RE +.SH "[IPV6ACCEPTRA] SECTION OPTIONS" +.PP +The [IPv6AcceptRA] section configures the IPv6 Router Advertisement (RA) client, if it is enabled with the +\fIIPv6AcceptRA=\fR +setting described above: +.PP +\fIToken=\fR +.RS 4 +Specifies an optional address generation mode for the Stateless Address Autoconfiguration (SLAAC)\&. The following values are supported: +.PP +\fBeui64\fR +.RS 4 +The EUI\-64 algorithm will be used to generate an address for that prefix\&. Only supported by Ethernet or InfiniBand interfaces\&. +.sp +Added in version 250\&. +.RE +.PP +\fBstatic:\fR\fB\fIADDRESS\fR\fR +.RS 4 +An IPv6 address must be specified after a colon (":"), and the lower bits of the supplied address are combined with the upper bits of a prefix received in a Router Advertisement (RA) message to form a complete address\&. Note that if multiple prefixes are received in an RA message, or in multiple RA messages, addresses will be formed from each of them using the supplied address\&. This mode implements SLAAC but uses a static interface identifier instead of an identifier generated by using the EUI\-64 algorithm\&. Because the interface identifier is static, if Duplicate Address Detection detects that the computed address is a duplicate (in use by another node on the link), then this mode will fail to provide an address for that prefix\&. If an IPv6 address without mode is specified, then +"static" +mode is assumed\&. +.sp +Added in version 250\&. +.RE +.PP +\fBprefixstable[:\fR\fB\fIADDRESS\fR\fR\fB][,\fR\fB\fIUUID\fR\fR\fB]\fR +.RS 4 +The algorithm specified in +\m[blue]\fBRFC 7217\fR\m[]\&\s-2\u[32]\d\s+2 +will be used to generate interface identifiers\&. This mode can optionally take an IPv6 address separated with a colon (":")\&. If an IPv6 address is specified, then an interface identifier is generated only when a prefix received in an RA message matches the supplied address\&. +.sp +This mode can also optionally take a non\-null UUID in the format which +\fBsd_id128_from_string()\fR +accepts, e\&.g\&. +"86b123b969ba4b7eb8b3d8605123525a" +or +"86b123b9\-69ba\-4b7e\-b8b3\-d8605123525a"\&. If a UUID is specified, the value is used as the secret key to generate interface identifiers\&. If not specified, then an application specific ID generated with the system\*(Aqs machine\-ID will be used as the secret key\&. See +\fBsd-id128\fR(3), +\fBsd_id128_from_string\fR(3), and +\fBsd_id128_get_machine\fR(3)\&. +.sp +Note that the +"prefixstable" +algorithm uses both the interface name and MAC address as input to the hash to compute the interface identifier, so if either of those are changed the resulting interface identifier (and address) will be changed, even if the prefix received in the RA message has not been changed\&. +.sp +Added in version 250\&. +.RE +.sp +If no address generation mode is specified (which is the default), or a received prefix does not match any of the addresses provided in +"prefixstable" +mode, then the EUI\-64 algorithm will be used for Ethernet or InfiniBand interfaces, otherwise +"prefixstable" +will be used to form an interface identifier for that prefix\&. +.sp +This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. +.sp +Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Token=eui64 +Token=::1a:2b:3c:4d +Token=static:::1a:2b:3c:4d +Token=prefixstable +Token=prefixstable:2002:da8:1:: +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 250\&. +.RE +.PP +\fIUseDNS=\fR +.RS 4 +When true (the default), the DNS servers received in the Router Advertisement will be used\&. +.sp +This corresponds to the +\fBnameserver\fR +option in +\fBresolv.conf\fR(5)\&. +.sp +Added in version 231\&. +.RE +.PP +\fIUseDomains=\fR +.RS 4 +Takes a boolean, or the special value +"route"\&. When true, the domain name received via IPv6 Router Advertisement (RA) will be used as DNS search domain over this link, similarly to the effect of the +\fBDomains=\fR +setting\&. If set to +"route", the domain name received via IPv6 RA will be used for routing DNS queries only, but not for searching, similarly to the effect of the +\fBDomains=\fR +setting when the argument is prefixed with +"~"\&. Defaults to false\&. +.sp +It is recommended to enable this option only on trusted networks, as setting this affects resolution of all hostnames, in particular of single\-label names\&. It is generally safer to use the supplied domain only as routing domain, rather than as search domain, in order to not have it affect local resolution of single\-label names\&. +.sp +When set to true, this setting corresponds to the +\fBdomain\fR +option in +\fBresolv.conf\fR(5)\&. +.sp +Added in version 231\&. +.RE +.PP +\fIRouteTable=\fR\fI\fInum\fR\fR +.RS 4 +The table identifier for the routes received in the Router Advertisement\&. Takes one of predefined names +"default", +"main", and +"local", and names defined in +\fIRouteTable=\fR +in +\fBnetworkd.conf\fR(5), or a number between 1\&...4294967295\&. +.sp +When used in combination with +\fIVRF=\fR, the VRF\*(Aqs routing table is used when this parameter is not specified\&. +.sp +Added in version 232\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +Set the routing metric for the routes received in the Router Advertisement\&. Takes an unsigned integer in the range 0\&...4294967295, or three unsigned integer separated with +":", in that case the first one is used when the router preference is high, the second is for medium preference, and the last is for low preference ("\fIhigh\fR:\fImedium\fR:\fIlow\fR")\&. Defaults to +"512:1024:2048"\&. +.sp +Added in version 249\&. +.RE +.PP +\fIQuickAck=\fR +.RS 4 +Takes a boolean\&. When true, the TCP quick ACK mode is enabled for the routes configured by the received RAs\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 253\&. +.RE +.PP +\fIUseMTU=\fR +.RS 4 +Takes a boolean\&. When true, the MTU received in the Router Advertisement will be used\&. Defaults to true\&. +.sp +Added in version 250\&. +.RE +.PP +\fIUseHopLimit=\fR +.RS 4 +Takes a boolean\&. When true, the hop limit received in the Router Advertisement will be set to routes configured based on the advertisement\&. See also +\fIIPv6HopLimit=\fR\&. Defaults to true\&. +.sp +Added in version 255\&. +.RE +.PP +\fIUseICMP6RateLimit=\fR +.RS 4 +Takes a boolean\&. When true, the ICMP6 rate limit received in the Router Advertisement will be set to ICMP6 rate limit based on the advertisement\&. Defaults to true\&. +.sp +Added in version 255\&. +.RE +.PP +\fIUseGateway=\fR +.RS 4 +When true (the default), the router address will be configured as the default gateway\&. +.sp +Added in version 250\&. +.RE +.PP +\fIUseRoutePrefix=\fR +.RS 4 +When true (the default), the routes corresponding to the route prefixes received in the Router Advertisement will be configured\&. +.sp +Added in version 250\&. +.RE +.PP +\fIUseCaptivePortal=\fR +.RS 4 +When true (the default), the captive portal received in the Router Advertisement will be recorded and made available to client programs and displayed in the +\fBnetworkctl\fR(1) +status output per\-link\&. +.sp +Added in version 254\&. +.RE +.PP +\fIUsePREF64=\fR +.RS 4 +When true, the IPv6 PREF64 (or NAT64) prefixes received in the Router Advertisement will be recorded and made available to client programs and displayed in the +\fBnetworkctl\fR(1) +status output per\-link\&. See +\m[blue]\fBRFC 8781\fR\m[]\&\s-2\u[33]\d\s+2\&. Defaults to false\&. +.sp +Added in version 255\&. +.RE +.PP +\fIUseAutonomousPrefix=\fR +.RS 4 +When true (the default), the autonomous prefix received in the Router Advertisement will be used and take precedence over any statically configured ones\&. +.sp +Added in version 242\&. +.RE +.PP +\fIUseOnLinkPrefix=\fR +.RS 4 +When true (the default), the onlink prefix received in the Router Advertisement will be used and takes precedence over any statically configured ones\&. +.sp +Added in version 242\&. +.RE +.PP +\fIRouterDenyList=\fR +.RS 4 +A whitespace\-separated list of IPv6 router addresses\&. Each address can optionally take a prefix length after +"/"\&. Any information advertised by the listed router is ignored\&. +.sp +Added in version 248\&. +.RE +.PP +\fIRouterAllowList=\fR +.RS 4 +A whitespace\-separated list of IPv6 router addresses\&. Each address can optionally take a prefix length after +"/"\&. Only information advertised by the listed router is accepted\&. Note that if +\fIRouterAllowList=\fR +is configured then +\fIRouterDenyList=\fR +is ignored\&. +.sp +Added in version 248\&. +.RE +.PP +\fIPrefixDenyList=\fR +.RS 4 +A whitespace\-separated list of IPv6 prefixes\&. Each prefix can optionally take its prefix length after +"/"\&. IPv6 prefixes supplied via router advertisements in the list are ignored\&. +.sp +Added in version 248\&. +.RE +.PP +\fIPrefixAllowList=\fR +.RS 4 +A whitespace\-separated list of IPv6 prefixes\&. Each prefix can optionally take its prefix length after +"/"\&. IPv6 prefixes supplied via router advertisements in the list are allowed\&. Note that if +\fIPrefixAllowList=\fR +is configured then +\fIPrefixDenyList=\fR +is ignored\&. +.sp +Added in version 248\&. +.RE +.PP +\fIRouteDenyList=\fR +.RS 4 +A whitespace\-separated list of IPv6 route prefixes\&. Each prefix can optionally take its prefix length after +"/"\&. IPv6 route prefixes supplied via router advertisements in the list are ignored\&. +.sp +Added in version 248\&. +.RE +.PP +\fIRouteAllowList=\fR +.RS 4 +A whitespace\-separated list of IPv6 route prefixes\&. Each prefix can optionally take its prefix length after +"/"\&. IPv6 route prefixes supplied via router advertisements in the list are allowed\&. Note that if +\fIRouteAllowList=\fR +is configured then +\fIRouteDenyList=\fR +is ignored\&. +.sp +Added in version 248\&. +.RE +.PP +\fIDHCPv6Client=\fR +.RS 4 +Takes a boolean, or the special value +"always"\&. When true, the DHCPv6 client will be started in +"solicit" +mode if the RA has the +"managed" +flag or +"information\-request" +mode if the RA lacks the +"managed" +flag but has the +"other configuration" +flag\&. If set to +"always", the DHCPv6 client will be started in +"solicit" +mode when an RA is received, even if neither the +"managed" +nor the +"other configuration" +flag is set in the RA\&. This will be ignored when +\fIWithoutRA=\fR +in the [DHCPv6] section is enabled, or +\fIUplinkInterface=:self\fR +in the [DHCPPrefixDelegation] section is specified\&. Defaults to true\&. +.sp +Added in version 246\&. +.RE +.PP +\fINetLabel=\fR +.RS 4 +This applies the NetLabel for the addresses received with RA, like +\fINetLabel=\fR +in [Address] section applies it to statically configured addresses\&. See +\fINetLabel=\fR +in [Address] section for more details\&. +.sp +Added in version 252\&. +.RE +.PP +\fINFTSet=\fR +.RS 4 +This applies the NFT set for the network configuration received with RA, like +\fINFTSet=\fR +in [Address] section applies it to static configuration\&. See +\fINFTSet=\fR +in [Address] section for more details\&. For +"address" +or +"prefix" +source types, the type of the element used in the NFT filter must be +"ipv6_addr"\&. +.sp +Added in version 255\&. +.RE +.SH "[DHCPSERVER] SECTION OPTIONS" +.PP +The [DHCPServer] section contains settings for the DHCP server, if enabled via the +\fIDHCPServer=\fR +option described above: +.PP +\fIServerAddress=\fR +.RS 4 +Specifies the server address for the DHCP server\&. Takes an IPv4 address with prefix length separated with a slash, e\&.g\&. +"192\&.168\&.0\&.1/24"\&. Defaults to unset, and one of static IPv4 addresses configured in [Network] or [Address] section will be automatically selected\&. This setting may be useful when the interface on which the DHCP server is running has multiple static IPv4 addresses\&. +.sp +This implies +\fIAddress=\fR +in [Network] or [Address] section with the same address and prefix length\&. That is, +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Network] +DHCPServer=yes +Address=192\&.168\&.0\&.1/24 +Address=192\&.168\&.0\&.2/24 +[DHCPServer] +ServerAddress=192\&.168\&.0\&.1/24 +.fi +.if n \{\ +.RE +.\} +.sp +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Network] +DHCPServer=yes +[Address] +Address=192\&.168\&.0\&.1/24 +[Address] +Address=192\&.168\&.0\&.2/24 +[DHCPServer] +ServerAddress=192\&.168\&.0\&.1/24 +.fi +.if n \{\ +.RE +.\} +.sp +are equivalent to the following\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Network] +DHCPServer=yes +Address=192\&.168\&.0\&.2/24 +[DHCPServer] +ServerAddress=192\&.168\&.0\&.1/24 +.fi +.if n \{\ +.RE +.\} +.sp +Since version 255, like the +\fIAddress=\fR +setting in [Network] or [Address] section, this also supports a null address, e\&.g\&. +"0\&.0\&.0\&.0/24", and an unused address will be automatically selected\&. For more details about the automatic address selection, see +\fIAddress=\fR +setting in [Network] section in the above\&. +.sp +Added in version 249\&. +.RE +.PP +\fIPoolOffset=\fR, \fIPoolSize=\fR +.RS 4 +Configures the pool of addresses to hand out\&. The pool is a contiguous sequence of IP addresses in the subnet configured for the server address, which does not include the subnet nor the broadcast address\&. +\fIPoolOffset=\fR +takes the offset of the pool from the start of subnet, or zero to use the default value\&. +\fIPoolSize=\fR +takes the number of IP addresses in the pool or zero to use the default value\&. By default, the pool starts at the first address after the subnet address and takes up the rest of the subnet, excluding the broadcast address\&. If the pool includes the server address (the default), this is reserved and not handed out to clients\&. +.sp +Added in version 226\&. +.RE +.PP +\fIDefaultLeaseTimeSec=\fR, \fIMaxLeaseTimeSec=\fR +.RS 4 +Control the default and maximum DHCP lease time to pass to clients\&. These settings take time values in seconds or another common time unit, depending on the suffix\&. The default lease time is used for clients that did not ask for a specific lease time\&. If a client asks for a lease time longer than the maximum lease time, it is automatically shortened to the specified time\&. The default lease time defaults to 1h, the maximum lease time to 12h\&. Shorter lease times are beneficial if the configuration data in DHCP leases changes frequently and clients shall learn the new settings with shorter latencies\&. Longer lease times reduce the generated DHCP network traffic\&. +.sp +Added in version 226\&. +.RE +.PP +\fIUplinkInterface=\fR +.RS 4 +Specifies the name or the index of the uplink interface, or one of the special values +":none" +and +":auto"\&. When emitting DNS, NTP, or SIP servers is enabled but no servers are specified, the servers configured in the uplink interface will be emitted\&. When +":auto", the link which has a default gateway with the highest priority will be automatically selected\&. When +":none", no uplink interface will be selected\&. Defaults to +":auto"\&. +.sp +Added in version 249\&. +.RE +.PP +\fIEmitDNS=\fR, \fIDNS=\fR +.RS 4 +\fIEmitDNS=\fR +takes a boolean\&. Configures whether the DHCP leases handed out to clients shall contain DNS server information\&. Defaults to +"yes"\&. The DNS servers to pass to clients may be configured with the +\fIDNS=\fR +option, which takes a list of IPv4 addresses, or special value +"_server_address" +which will be converted to the address used by the DHCP server\&. +.sp +If the +\fIEmitDNS=\fR +option is enabled but no servers configured, the servers are automatically propagated from an "uplink" interface that has appropriate servers set\&. The "uplink" interface is determined by the default route of the system with the highest priority\&. Note that this information is acquired at the time the lease is handed out, and does not take uplink interfaces into account that acquire DNS server information at a later point\&. If no suitable uplink interface is found the DNS server data from +/etc/resolv\&.conf +is used\&. Also, note that the leases are not refreshed if the uplink network configuration changes\&. To ensure clients regularly acquire the most current uplink DNS server information, it is thus advisable to shorten the DHCP lease time via +\fIMaxLeaseTimeSec=\fR +described above\&. +.sp +This setting can be specified multiple times\&. If an empty string is specified, then all DNS servers specified earlier are cleared\&. +.sp +Added in version 226\&. +.RE +.PP +\fIEmitNTP=\fR, \fINTP=\fR, \fIEmitSIP=\fR, \fISIP=\fR, \fIEmitPOP3=\fR, \fIPOP3=\fR, \fIEmitSMTP=\fR, \fISMTP=\fR, \fIEmitLPR=\fR, \fILPR=\fR +.RS 4 +Similar to the +\fIEmitDNS=\fR +and +\fIDNS=\fR +settings described above, these settings configure whether and what server information for the indicate protocol shall be emitted as part of the DHCP lease\&. The same syntax, propagation semantics and defaults apply as for +\fIEmitDNS=\fR +and +\fIDNS=\fR\&. +.sp +Added in version 226\&. +.RE +.PP +\fIEmitRouter=\fR, \fIRouter=\fR +.RS 4 +The +\fIEmitRouter=\fR +setting takes a boolean value, and configures whether the DHCP lease should contain the router option\&. The +\fIRouter=\fR +setting takes an IPv4 address, and configures the router address to be emitted\&. When the +\fIRouter=\fR +setting is not specified, then the server address will be used for the router option\&. When the +\fIEmitRouter=\fR +setting is disabled, the +\fIRouter=\fR +setting will be ignored\&. The +\fIEmitRouter=\fR +setting defaults to true, and the +\fIRouter=\fR +setting defaults to unset\&. +.sp +Added in version 230\&. +.RE +.PP +\fIEmitTimezone=\fR, \fITimezone=\fR +.RS 4 +Takes a boolean\&. Configures whether the DHCP leases handed out to clients shall contain timezone information\&. Defaults to +"yes"\&. The +\fITimezone=\fR +setting takes a timezone string (such as +"Europe/Berlin" +or +"UTC") to pass to clients\&. If no explicit timezone is set, the system timezone of the local host is propagated, as determined by the +/etc/localtime +symlink\&. +.sp +Added in version 226\&. +.RE +.PP +\fIBootServerAddress=\fR +.RS 4 +Takes an IPv4 address of the boot server used by e\&.g\&. PXE boot systems\&. When specified, this address is sent in the +\fBsiaddr\fR +field of the DHCP message header\&. See +\m[blue]\fBRFC 2131\fR\m[]\&\s-2\u[34]\d\s+2 +for more details\&. Defaults to unset\&. +.sp +Added in version 251\&. +.RE +.PP +\fIBootServerName=\fR +.RS 4 +Takes a name of the boot server used by e\&.g\&. PXE boot systems\&. When specified, this name is sent in the DHCP option 66 ("TFTP server name")\&. See +\m[blue]\fBRFC 2132\fR\m[]\&\s-2\u[35]\d\s+2 +for more details\&. Defaults to unset\&. +.sp +Note that typically setting one of +\fIBootServerName=\fR +or +\fIBootServerAddress=\fR +is sufficient, but both can be set too, if desired\&. +.sp +Added in version 251\&. +.RE +.PP +\fIBootFilename=\fR +.RS 4 +Takes a path or URL to a file loaded by e\&.g\&. a PXE boot loader\&. When specified, this path is sent in the DHCP option 67 ("Bootfile name")\&. See +\m[blue]\fBRFC 2132\fR\m[]\&\s-2\u[35]\d\s+2 +for more details\&. Defaults to unset\&. +.sp +Added in version 251\&. +.RE +.PP +\fIIPv6OnlyPreferredSec=\fR +.RS 4 +Takes a timespan\&. Controls the +\m[blue]\fBRFC 8925\fR\m[]\&\s-2\u[28]\d\s+2 +IPv6\-Only Preferred option\&. Specifies the DHCPv4 option to indicate that a host supports an IPv6\-only mode and is willing to forgo obtaining an IPv4 address if the network provides IPv6 connectivity\&. Defaults to unset, and not send the option\&. The minimum allowed value is 300 seconds\&. +.sp +Added in version 255\&. +.RE +.PP +\fISendOption=\fR +.RS 4 +Send a raw option with value via DHCPv4 server\&. Takes a DHCP option number, data type and data ("\fIoption\fR:\fItype\fR:\fIvalue\fR")\&. The option number is an integer in the range 1\&...254\&. The type takes one of +"uint8", +"uint16", +"uint32", +"ipv4address", +"ipv6address", or +"string"\&. Special characters in the data string may be escaped using +\m[blue]\fBC\-style escapes\fR\m[]\&\s-2\u[25]\d\s+2\&. This setting can be specified multiple times\&. If an empty string is specified, then all options specified earlier are cleared\&. Defaults to unset\&. +.sp +Added in version 244\&. +.RE +.PP +\fISendVendorOption=\fR +.RS 4 +Send a vendor option with value via DHCPv4 server\&. Takes a DHCP option number, data type and data ("\fIoption\fR:\fItype\fR:\fIvalue\fR")\&. The option number is an integer in the range 1\&...254\&. The type takes one of +"uint8", +"uint16", +"uint32", +"ipv4address", or +"string"\&. Special characters in the data string may be escaped using +\m[blue]\fBC\-style escapes\fR\m[]\&\s-2\u[25]\d\s+2\&. This setting can be specified multiple times\&. If an empty string is specified, then all options specified earlier are cleared\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIBindToInterface=\fR +.RS 4 +Takes a boolean value\&. When +"yes", DHCP server socket will be bound to its network interface and all socket communication will be restricted to this interface\&. Defaults to +"yes", except if +\fIRelayTarget=\fR +is used (see below), in which case it defaults to +"no"\&. +.sp +Added in version 249\&. +.RE +.PP +\fIRelayTarget=\fR +.RS 4 +Takes an IPv4 address, which must be in the format described in +\fBinet_pton\fR(3)\&. Turns this DHCP server into a DHCP relay agent\&. See +\m[blue]\fBRFC 1542\fR\m[]\&\s-2\u[36]\d\s+2\&. The address is the address of DHCP server or another relay agent to forward DHCP messages to and from\&. +.sp +Added in version 249\&. +.RE +.PP +\fIRelayAgentCircuitId=\fR +.RS 4 +Specifies value for Agent Circuit ID suboption of Relay Agent Information option\&. Takes a string, which must be in the format +"string:\fIvalue\fR", where +"\fIvalue\fR" +should be replaced with the value of the suboption\&. Defaults to unset (means no Agent Circuit ID suboption is generated)\&. Ignored if +\fIRelayTarget=\fR +is not specified\&. +.sp +Added in version 249\&. +.RE +.PP +\fIRelayAgentRemoteId=\fR +.RS 4 +Specifies value for Agent Remote ID suboption of Relay Agent Information option\&. Takes a string, which must be in the format +"string:\fIvalue\fR", where +"\fIvalue\fR" +should be replaced with the value of the suboption\&. Defaults to unset (means no Agent Remote ID suboption is generated)\&. Ignored if +\fIRelayTarget=\fR +is not specified\&. +.sp +Added in version 249\&. +.RE +.PP +\fIRapidCommit=\fR +.RS 4 +Takes a boolean\&. When true, the server supports +\m[blue]\fBRFC 4039\fR\m[]\&\s-2\u[37]\d\s+2\&. When a client sends a DHCPDISCOVER message with the Rapid Commit option to the server, then the server will reply with a DHCPACK message to the client, instead of DHCPOFFER\&. Defaults to true\&. +.sp +Added in version 255\&. +.RE +.SH "[DHCPSERVERSTATICLEASE] SECTION OPTIONS" +.PP +The +"[DHCPServerStaticLease]" +section configures a static DHCP lease to assign a fixed IPv4 address to a specific device based on its MAC address\&. This section can be specified multiple times\&. +.PP +\fIMACAddress=\fR +.RS 4 +The hardware address of a device to match\&. This key is mandatory\&. +.sp +Added in version 249\&. +.RE +.PP +\fIAddress=\fR +.RS 4 +The IPv4 address that should be assigned to the device that was matched with +\fIMACAddress=\fR\&. This key is mandatory\&. +.sp +Added in version 249\&. +.RE +.SH "[IPV6SENDRA] SECTION OPTIONS" +.PP +The [IPv6SendRA] section contains settings for sending IPv6 Router Advertisements and whether to act as a router, if enabled via the +\fIIPv6SendRA=\fR +option described above\&. IPv6 network prefixes or routes are defined with one or more [IPv6Prefix] or [IPv6RoutePrefix] sections\&. +.PP +\fIManaged=\fR, \fIOtherInformation=\fR +.RS 4 +Takes a boolean\&. Controls whether a DHCPv6 server is used to acquire IPv6 addresses on the network link when +\fIManaged=\fR +is set to +"true" +or if only additional network information can be obtained via DHCPv6 for the network link when +\fIOtherInformation=\fR +is set to +"true"\&. Both settings default to +"false", which means that a DHCPv6 server is not being used\&. +.sp +Added in version 235\&. +.RE +.PP +\fIRouterLifetimeSec=\fR +.RS 4 +Takes a timespan\&. Configures the IPv6 router lifetime in seconds\&. The value must be 0 seconds, or between 4 seconds and 9000 seconds\&. When set to 0, the host is not acting as a router\&. Defaults to 1800 seconds (30 minutes)\&. +.sp +Added in version 235\&. +.RE +.PP +\fIRetransmitSec=\fR +.RS 4 +Takes a timespan\&. Configures the retransmit time, used by clients to retransmit Neighbor Solicitation messages on address resolution and the Neighbor Unreachability Detection algorithm\&. An integer the default unit of seconds, in the range 0\&...4294967295 msec\&. Defaults to 0\&. +.sp +Added in version 255\&. +.RE +.PP +\fIRouterPreference=\fR +.RS 4 +Configures IPv6 router preference if +\fIRouterLifetimeSec=\fR +is non\-zero\&. Valid values are +"high", +"medium" +and +"low", with +"normal" +and +"default" +added as synonyms for +"medium" +just to make configuration easier\&. See +\m[blue]\fBRFC 4191\fR\m[]\&\s-2\u[21]\d\s+2 +for details\&. Defaults to +"medium"\&. +.sp +Added in version 235\&. +.RE +.PP +\fIHopLimit=\fR +.RS 4 +Configures hop limit\&. Takes an integer in the range 0\&...255\&. See also +\fIIPv6HopLimit=\fR\&. +.sp +Added in version 255\&. +.RE +.PP +\fIUplinkInterface=\fR +.RS 4 +Specifies the name or the index of the uplink interface, or one of the special values +":none" +and +":auto"\&. When emitting DNS servers or search domains is enabled but no servers are specified, the servers configured in the uplink interface will be emitted\&. When +":auto", the value specified to the same setting in the [DHCPPrefixDelegation] section will be used if +\fIDHCPPrefixDelegation=\fR +is enabled, otherwise the link which has a default gateway with the highest priority will be automatically selected\&. When +":none", no uplink interface will be selected\&. Defaults to +":auto"\&. +.sp +Added in version 250\&. +.RE +.PP +\fIEmitDNS=\fR, \fIDNS=\fR +.RS 4 +\fIDNS=\fR +specifies a list of recursive DNS server IPv6 addresses that are distributed via Router Advertisement messages when +\fIEmitDNS=\fR +is true\&. +\fIDNS=\fR +also takes special value +"_link_local"; in that case the IPv6 link\-local address is distributed\&. If +\fIDNS=\fR +is empty, DNS servers are read from the [Network] section\&. If the [Network] section does not contain any DNS servers either, DNS servers from the uplink interface specified in +\fIUplinkInterface=\fR +will be used\&. When +\fIEmitDNS=\fR +is false, no DNS server information is sent in Router Advertisement messages\&. +\fIEmitDNS=\fR +defaults to true\&. +.sp +Added in version 235\&. +.RE +.PP +\fIEmitDomains=\fR, \fIDomains=\fR +.RS 4 +A list of DNS search domains distributed via Router Advertisement messages when +\fIEmitDomains=\fR +is true\&. If +\fIDomains=\fR +is empty, DNS search domains are read from the [Network] section\&. If the [Network] section does not contain any DNS search domains either, DNS search domains from the uplink interface specified in +\fIUplinkInterface=\fR +will be used\&. When +\fIEmitDomains=\fR +is false, no DNS search domain information is sent in Router Advertisement messages\&. +\fIEmitDomains=\fR +defaults to true\&. +.sp +Added in version 235\&. +.RE +.PP +\fIDNSLifetimeSec=\fR +.RS 4 +Lifetime in seconds for the DNS server addresses listed in +\fIDNS=\fR +and search domains listed in +\fIDomains=\fR\&. Defaults to 3600 seconds (one hour)\&. +.sp +Added in version 235\&. +.RE +.PP +\fIHomeAgent=\fR +.RS 4 +Takes a boolean\&. Specifies that IPv6 router advertisements which indicates to hosts that the router acts as a Home Agent and includes a Home Agent Option\&. Defaults to false\&. See +\m[blue]\fBRFC 6275\fR\m[]\&\s-2\u[10]\d\s+2 +for further details\&. +.sp +Added in version 255\&. +.RE +.PP +\fIHomeAgentLifetimeSec=\fR +.RS 4 +Takes a timespan\&. Specifies the lifetime of the Home Agent\&. An integer the default unit of seconds, in the range 1\&...65535\&. Defaults to the value set to +\fIRouterLifetimeSec=\fR\&. +.sp +Added in version 255\&. +.RE +.PP +\fIHomeAgentPreference=\fR +.RS 4 +Configures IPv6 Home Agent preference\&. Takes an integer in the range 0\&...65535\&. Defaults to 0\&. +.sp +Added in version 255\&. +.RE +.SH "[IPV6PREFIX] SECTION OPTIONS" +.PP +One or more [IPv6Prefix] sections contain the IPv6 prefixes that are announced via Router Advertisements\&. See +\m[blue]\fBRFC 4861\fR\m[]\&\s-2\u[38]\d\s+2 +for further details\&. +.PP +\fIAddressAutoconfiguration=\fR, \fIOnLink=\fR +.RS 4 +Takes a boolean to specify whether IPv6 addresses can be autoconfigured with this prefix and whether the prefix can be used for onlink determination\&. Both settings default to +"true" +in order to ease configuration\&. +.sp +Added in version 235\&. +.RE +.PP +\fIPrefix=\fR +.RS 4 +The IPv6 prefix that is to be distributed to hosts\&. Similarly to configuring static IPv6 addresses, the setting is configured as an IPv6 prefix and its prefix length, separated by a +"/" +character\&. Use multiple [IPv6Prefix] sections to configure multiple IPv6 prefixes since prefix lifetimes, address autoconfiguration and onlink status may differ from one prefix to another\&. +.sp +Added in version 235\&. +.RE +.PP +\fIPreferredLifetimeSec=\fR, \fIValidLifetimeSec=\fR +.RS 4 +Preferred and valid lifetimes for the prefix measured in seconds\&. +\fIPreferredLifetimeSec=\fR +defaults to 1800 seconds (30 minutes) and +\fIValidLifetimeSec=\fR +defaults to 3600 seconds (one hour)\&. +.sp +Added in version 235\&. +.RE +.PP +\fIAssign=\fR +.RS 4 +Takes a boolean\&. When true, adds an address from the prefix\&. Default to false\&. +.sp +Added in version 246\&. +.RE +.PP +\fIToken=\fR +.RS 4 +Specifies an optional address generation mode for assigning an address in each prefix\&. This accepts the same syntax as +\fIToken=\fR +in the [IPv6AcceptRA] section\&. If +\fIAssign=\fR +is set to false, then this setting will be ignored\&. Defaults to unset, which means the EUI\-64 algorithm will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRouteMetric=\fR +.RS 4 +The metric of the prefix route\&. Takes an unsigned integer in the range 0\&...4294967295\&. When unset or set to 0, the kernel\*(Aqs default value is used\&. This setting is ignored when +\fIAssign=\fR +is false\&. +.sp +Added in version 249\&. +.RE +.SH "[IPV6ROUTEPREFIX] SECTION OPTIONS" +.PP +One or more [IPv6RoutePrefix] sections contain the IPv6 prefix routes that are announced via Router Advertisements\&. See +\m[blue]\fBRFC 4191\fR\m[]\&\s-2\u[21]\d\s+2 +for further details\&. +.PP +\fIRoute=\fR +.RS 4 +The IPv6 route that is to be distributed to hosts\&. Similarly to configuring static IPv6 routes, the setting is configured as an IPv6 prefix routes and its prefix route length, separated by a +"/" +character\&. Use multiple [IPv6RoutePrefix] sections to configure multiple IPv6 prefix routes\&. +.sp +Added in version 244\&. +.RE +.PP +\fILifetimeSec=\fR +.RS 4 +Lifetime for the route prefix measured in seconds\&. +\fILifetimeSec=\fR +defaults to 3600 seconds (one hour)\&. +.sp +Added in version 244\&. +.RE +.SH "[IPV6PREF64PREFIX] SECTION OPTIONS" +.PP +One or more [IPv6PREF64Prefix] sections contain the IPv6 PREF64 (or NAT64) prefixes that are announced via Router Advertisements\&. See +\m[blue]\fBRFC 8781\fR\m[]\&\s-2\u[33]\d\s+2 +for further details\&. +.PP +\fIPrefix=\fR +.RS 4 +The IPv6 PREF64 (or NAT64) prefix that is to be distributed to hosts\&. The setting holds an IPv6 prefix that should be set up for NAT64 translation (PLAT) to allow 464XLAT on the network segment\&. Use multiple [IPv6PREF64Prefix] sections to configure multiple IPv6 prefixes since prefix lifetime may differ from one prefix to another\&. The prefix is an address with a prefix length, separated by a slash +"/" +character\&. Valid NAT64 prefix length are 96, 64, 56, 48, 40, and 32 bits\&. +.sp +Added in version 255\&. +.RE +.PP +\fILifetimeSec=\fR +.RS 4 +Lifetime for the prefix measured in seconds\&. Should be greater than or equal to +\fIRouterLifetimeSec=\fR\&. +\fILifetimeSec=\fR +defaults to 1800 seconds\&. +.sp +Added in version 255\&. +.RE +.SH "[BRIDGE] SECTION OPTIONS" +.PP +The [Bridge] section accepts the following keys: +.PP +\fIUnicastFlood=\fR +.RS 4 +Takes a boolean\&. Controls whether the bridge should flood traffic for which an FDB entry is missing and the destination is unknown through this port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 223\&. +.RE +.PP +\fIMulticastFlood=\fR +.RS 4 +Takes a boolean\&. Controls whether the bridge should flood traffic for which an MDB entry is missing and the destination is unknown through this port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 242\&. +.RE +.PP +\fIMulticastToUnicast=\fR +.RS 4 +Takes a boolean\&. Multicast to unicast works on top of the multicast snooping feature of the bridge\&. Which means unicast copies are only delivered to hosts which are interested in it\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 240\&. +.RE +.PP +\fINeighborSuppression=\fR +.RS 4 +Takes a boolean\&. Configures whether ARP and ND neighbor suppression is enabled for this port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 242\&. +.RE +.PP +\fILearning=\fR +.RS 4 +Takes a boolean\&. Configures whether MAC address learning is enabled for this port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 242\&. +.RE +.PP +\fIHairPin=\fR +.RS 4 +Takes a boolean\&. Configures whether traffic may be sent back out of the port on which it was received\&. When this flag is false, then the bridge will not forward traffic back out of the receiving port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 223\&. +.RE +.PP +\fIIsolated=\fR +.RS 4 +Takes a boolean\&. Configures whether this port is isolated or not\&. Within a bridge, isolated ports can only communicate with non\-isolated ports\&. When set to true, this port can only communicate with other ports whose Isolated setting is false\&. When set to false, this port can communicate with any other ports\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 251\&. +.RE +.PP +\fIUseBPDU=\fR +.RS 4 +Takes a boolean\&. Configures whether STP Bridge Protocol Data Units will be processed by the bridge port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 223\&. +.RE +.PP +\fIFastLeave=\fR +.RS 4 +Takes a boolean\&. This flag allows the bridge to immediately stop multicast traffic on a port that receives an IGMP Leave message\&. It is only used with IGMP snooping if enabled on the bridge\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 223\&. +.RE +.PP +\fIAllowPortToBeRoot=\fR +.RS 4 +Takes a boolean\&. Configures whether a given port is allowed to become a root port\&. Only used when STP is enabled on the bridge\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 223\&. +.RE +.PP +\fIProxyARP=\fR +.RS 4 +Takes a boolean\&. Configures whether proxy ARP to be enabled on this port\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.PP +\fIProxyARPWiFi=\fR +.RS 4 +Takes a boolean\&. Configures whether proxy ARP to be enabled on this port which meets extended requirements by IEEE 802\&.11 and Hotspot 2\&.0 specifications\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.PP +\fIMulticastRouter=\fR +.RS 4 +Configures this port for having multicast routers attached\&. A port with a multicast router will receive all multicast traffic\&. Takes one of +"no" +to disable multicast routers on this port, +"query" +to let the system detect the presence of routers, +"permanent" +to permanently enable multicast traffic forwarding on this port, or +"temporary" +to enable multicast routers temporarily on this port, not depending on incoming queries\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 243\&. +.RE +.PP +\fICost=\fR +.RS 4 +Sets the "cost" of sending packets of this interface\&. Each port in a bridge may have a different speed and the cost is used to decide which link to use\&. Faster interfaces should have lower costs\&. It is an integer value between 1 and 65535\&. +.sp +Added in version 218\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +Sets the "priority" of sending packets on this interface\&. Each port in a bridge may have a different priority which is used to decide which link to use\&. Lower value means higher priority\&. It is an integer value between 0 to 63\&. Networkd does not set any default, meaning the kernel default value of 32 is used\&. +.sp +Added in version 234\&. +.RE +.SH "[BRIDGEFDB] SECTION OPTIONS" +.PP +The [BridgeFDB] section manages the forwarding database table of a port and accepts the following keys\&. Specify several [BridgeFDB] sections to configure several static MAC table entries\&. +.PP +\fIMACAddress=\fR +.RS 4 +As in the [Network] section\&. This key is mandatory\&. +.sp +Added in version 219\&. +.RE +.PP +\fIDestination=\fR +.RS 4 +Takes an IP address of the destination VXLAN tunnel endpoint\&. +.sp +Added in version 243\&. +.RE +.PP +\fIVLANId=\fR +.RS 4 +The VLAN ID for the new static MAC table entry\&. If omitted, no VLAN ID information is appended to the new static MAC table entry\&. +.sp +Added in version 219\&. +.RE +.PP +\fIVNI=\fR +.RS 4 +The VXLAN Network Identifier (or VXLAN Segment ID) to use to connect to the remote VXLAN tunnel endpoint\&. Takes a number in the range 1\&...16777215\&. Defaults to unset\&. +.sp +Added in version 243\&. +.RE +.PP +\fIAssociatedWith=\fR +.RS 4 +Specifies where the address is associated with\&. Takes one of +"use", +"self", +"master" +or +"router"\&. +"use" +means the address is in use\&. User space can use this option to indicate to the kernel that the fdb entry is in use\&. +"self" +means the address is associated with the port drivers fdb\&. Usually hardware\&. +"master" +means the address is associated with master devices fdb\&. +"router" +means the destination address is associated with a router\&. Note that it\*(Aqs valid if the referenced device is a VXLAN type device and has route shortcircuit enabled\&. Defaults to +"self"\&. +.sp +Added in version 243\&. +.RE +.PP +\fIOutgoingInterface=\fR +.RS 4 +Specifies the name or index of the outgoing interface for the VXLAN device driver to reach the remote VXLAN tunnel endpoint\&. Defaults to unset\&. +.sp +Added in version 249\&. +.RE +.SH "[BRIDGEMDB] SECTION OPTIONS" +.PP +The [BridgeMDB] section manages the multicast membership entries forwarding database table of a port and accepts the following keys\&. Specify several [BridgeMDB] sections to configure several permanent multicast membership entries\&. +.PP +\fIMulticastGroupAddress=\fR +.RS 4 +Specifies the IPv4 or IPv6 multicast group address to add\&. This setting is mandatory\&. +.sp +Added in version 247\&. +.RE +.PP +\fIVLANId=\fR +.RS 4 +The VLAN ID for the new entry\&. Valid ranges are 0 (no VLAN) to 4094\&. Optional, defaults to 0\&. +.sp +Added in version 247\&. +.RE +.SH "[LLDP] SECTION OPTIONS" +.PP +The [LLDP] section manages the Link Layer Discovery Protocol (LLDP) and accepts the following keys: +.PP +\fIMUDURL=\fR +.RS 4 +When configured, the specified Manufacturer Usage Descriptions (MUD) URL will be sent in LLDP packets\&. The syntax and semantics are the same as for +\fIMUDURL=\fR +in the [DHCPv4] section described above\&. +.sp +The MUD URLs received via LLDP packets are saved and can be read using the +\fBsd_lldp_neighbor_get_mud_url()\fR +function\&. +.sp +Added in version 246\&. +.RE +.SH "[CAN] SECTION OPTIONS" +.PP +The [CAN] section manages the Controller Area Network (CAN bus) and accepts the following keys: +.PP +\fIBitRate=\fR +.RS 4 +The bitrate of CAN device in bits per second\&. The usual SI prefixes (K, M) with the base of 1000 can be used here\&. Takes a number in the range 1\&...4294967295\&. +.sp +Added in version 239\&. +.RE +.PP +\fISamplePoint=\fR +.RS 4 +Optional sample point in percent with one decimal (e\&.g\&. +"75%", +"87\&.5%") or permille (e\&.g\&. +"875‰")\&. This will be ignored when +\fIBitRate=\fR +is unspecified\&. +.sp +Added in version 239\&. +.RE +.PP +\fITimeQuantaNSec=\fR, \fIPropagationSegment=\fR, \fIPhaseBufferSegment1=\fR, \fIPhaseBufferSegment2=\fR, \fISyncJumpWidth=\fR +.RS 4 +Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the synchronization jump width, which allow one to define the CAN bit\-timing in a hardware independent format as proposed by the Bosch CAN 2\&.0 Specification\&. +\fITimeQuantaNSec=\fR +takes a timespan in nanoseconds\&. +\fIPropagationSegment=\fR, +\fIPhaseBufferSegment1=\fR, +\fIPhaseBufferSegment2=\fR, and +\fISyncJumpWidth=\fR +take number of time quantum specified in +\fITimeQuantaNSec=\fR +and must be an unsigned integer in the range 0\&...4294967295\&. These settings except for +\fISyncJumpWidth=\fR +will be ignored when +\fIBitRate=\fR +is specified\&. +.sp +Added in version 250\&. +.RE +.PP +\fIDataBitRate=\fR, \fIDataSamplePoint=\fR +.RS 4 +The bitrate and sample point for the data phase, if CAN\-FD is used\&. These settings are analogous to the +\fIBitRate=\fR +and +\fISamplePoint=\fR +keys\&. +.sp +Added in version 246\&. +.RE +.PP +\fIDataTimeQuantaNSec=\fR, \fIDataPropagationSegment=\fR, \fIDataPhaseBufferSegment1=\fR, \fIDataPhaseBufferSegment2=\fR, \fIDataSyncJumpWidth=\fR +.RS 4 +Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the synchronization jump width for the data phase, if CAN\-FD is used\&. These settings are analogous to the +\fITimeQuantaNSec=\fR +or related settings\&. +.sp +Added in version 250\&. +.RE +.PP +\fIFDMode=\fR +.RS 4 +Takes a boolean\&. When +"yes", CAN\-FD mode is enabled for the interface\&. Note, that a bitrate and optional sample point should also be set for the CAN\-FD data phase using the +\fIDataBitRate=\fR +and +\fIDataSamplePoint=\fR +keys, or +\fIDataTimeQuanta=\fR +and related settings\&. +.sp +Added in version 246\&. +.RE +.PP +\fIFDNonISO=\fR +.RS 4 +Takes a boolean\&. When +"yes", non\-ISO CAN\-FD mode is enabled for the interface\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRestartSec=\fR +.RS 4 +Automatic restart delay time\&. If set to a non\-zero value, a restart of the CAN controller will be triggered automatically in case of a bus\-off condition after the specified delay time\&. Subsecond delays can be specified using decimals (e\&.g\&. +"0\&.1s") or a +"ms" +or +"us" +postfix\&. Using +"infinity" +or +"0" +will turn the automatic restart off\&. By default automatic restart is disabled\&. +.sp +Added in version 239\&. +.RE +.PP +\fITermination=\fR +.RS 4 +Takes a boolean or a termination resistor value in ohm in the range 0\&...65535\&. When +"yes", the termination resistor is set to 120 ohm\&. When +"no" +or +"0" +is set, the termination resistor is disabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fITripleSampling=\fR +.RS 4 +Takes a boolean\&. When +"yes", three samples (instead of one) are used to determine the value of a received bit by majority rule\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 242\&. +.RE +.PP +\fIBusErrorReporting=\fR +.RS 4 +Takes a boolean\&. When +"yes", reporting of CAN bus errors is activated (those include single bit, frame format, and bit stuffing errors, unable to send dominant bit, unable to send recessive bit, bus overload, active error announcement, error occurred on transmission)\&. When unset, the kernel\*(Aqs default will be used\&. Note: in case of a CAN bus with a single CAN device, sending a CAN frame may result in a huge number of CAN bus errors\&. +.sp +Added in version 248\&. +.RE +.PP +\fIListenOnly=\fR +.RS 4 +Takes a boolean\&. When +"yes", listen\-only mode is enabled\&. When the interface is in listen\-only mode, the interface neither transmit CAN frames nor send ACK bit\&. Listen\-only mode is important to debug CAN networks without interfering with the communication or acknowledge the CAN frame\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 246\&. +.RE +.PP +\fILoopback=\fR +.RS 4 +Takes a boolean\&. When +"yes", loopback mode is enabled\&. When the loopback mode is enabled, the interface treats messages transmitted by itself as received messages\&. The loopback mode is important to debug CAN networks\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIOneShot=\fR +.RS 4 +Takes a boolean\&. When +"yes", one\-shot mode is enabled\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIPresumeAck=\fR +.RS 4 +Takes a boolean\&. When +"yes", the interface will ignore missing CAN ACKs\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIClassicDataLengthCode=\fR +.RS 4 +Takes a boolean\&. When +"yes", the interface will handle the 4bit data length code (DLC)\&. When unset, the kernel\*(Aqs default will be used\&. +.sp +Added in version 250\&. +.RE +.SH "[IPOIB] SECTION OPTIONS" +.PP +The [IPoIB] section manages the IP over Infiniband and accepts the following keys: +.PP +\fIMode=\fR +.RS 4 +Takes one of the special values +"datagram" +or +"connected"\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +When +"datagram", the Infiniband unreliable datagram (UD) transport is used, and so the interface MTU is equal to the IB L2 MTU minus the IPoIB encapsulation header (4 bytes)\&. For example, in a typical IB fabric with a 2K MTU, the IPoIB MTU will be 2048 \- 4 = 2044 bytes\&. +.sp +When +"connected", the Infiniband reliable connected (RC) transport is used\&. Connected mode takes advantage of the connected nature of the IB transport and allows an MTU up to the maximal IP packet size of 64K, which reduces the number of IP packets needed for handling large UDP datagrams, TCP segments, etc and increases the performance for large messages\&. +.sp +Added in version 250\&. +.RE +.PP +\fIIgnoreUserspaceMulticastGroup=\fR +.RS 4 +Takes an boolean value\&. When true, the kernel ignores multicast groups handled by userspace\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.SH "[QDISC] SECTION OPTIONS" +.PP +The [QDisc] section manages the traffic control queueing discipline (qdisc)\&. +.PP +\fIParent=\fR +.RS 4 +Specifies the parent Queueing Discipline (qdisc)\&. Takes one of +"clsact" +or +"ingress"\&. This is mandatory\&. +.sp +Added in version 244\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.SH "[NETWORKEMULATOR] SECTION OPTIONS" +.PP +The [NetworkEmulator] section manages the queueing discipline (qdisc) of the network emulator\&. It can be used to configure the kernel packet scheduler and simulate packet delay and loss for UDP or TCP applications, or limit the bandwidth usage of a particular service to simulate internet connections\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIDelaySec=\fR +.RS 4 +Specifies the fixed amount of delay to be added to all packets going out of the interface\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIDelayJitterSec=\fR +.RS 4 +Specifies the chosen delay to be added to the packets outgoing to the network interface\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the maximum number of packets the qdisc may hold queued at a time\&. An unsigned integer in the range 0\&...4294967294\&. Defaults to 1000\&. +.sp +Added in version 245\&. +.RE +.PP +\fILossRate=\fR +.RS 4 +Specifies an independent loss probability to be added to the packets outgoing from the network interface\&. Takes a percentage value, suffixed with "%"\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIDuplicateRate=\fR +.RS 4 +Specifies that the chosen percent of packets is duplicated before queuing them\&. Takes a percentage value, suffixed with "%"\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.SH "[TOKENBUCKETFILTER] SECTION OPTIONS" +.PP +The [TokenBucketFilter] section manages the queueing discipline (qdisc) of token bucket filter (tbf)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fILatencySec=\fR +.RS 4 +Specifies the latency parameter, which specifies the maximum amount of time a packet can sit in the Token Bucket Filter (TBF)\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fILimitBytes=\fR +.RS 4 +Takes the number of bytes that can be queued waiting for tokens to become available\&. When the size is suffixed with K, M, or G, it is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIBurstBytes=\fR +.RS 4 +Specifies the size of the bucket\&. This is the maximum amount of bytes that tokens can be available for instantaneous transfer\&. When the size is suffixed with K, M, or G, it is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRate=\fR +.RS 4 +Specifies the device specific bandwidth\&. When suffixed with K, M, or G, the specified bandwidth is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIMPUBytes=\fR +.RS 4 +The Minimum Packet Unit (MPU) determines the minimal token usage (specified in bytes) for a packet\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to zero\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPeakRate=\fR +.RS 4 +Takes the maximum depletion rate of the bucket\&. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.PP +\fIMTUBytes=\fR +.RS 4 +Specifies the size of the peakrate bucket\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.SH "[PIE] SECTION OPTIONS" +.PP +The [PIE] section manages the queueing discipline (qdisc) of Proportional Integral controller\-Enhanced (PIE)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the queue size in number of packets\&. When this limit is reached, incoming packets are dropped\&. An unsigned integer in the range 1\&...4294967294\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[FLOWQUEUEPIE] SECTION OPTIONS" +.PP +The +"[FlowQueuePIE]" +section manages the queueing discipline (qdisc) of Flow Queue Proportional Integral controller\-Enhanced (fq_pie)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the queue size in number of packets\&. When this limit is reached, incoming packets are dropped\&. An unsigned integer ranges 1 to 4294967294\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 247\&. +.RE +.SH "[STOCHASTICFAIRBLUE] SECTION OPTIONS" +.PP +The [StochasticFairBlue] section manages the queueing discipline (qdisc) of stochastic fair blue (sfb)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the queue size in number of packets\&. When this limit is reached, incoming packets are dropped\&. An unsigned integer in the range 0\&...4294967294\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[STOCHASTICFAIRNESSQUEUEING] SECTION OPTIONS" +.PP +The [StochasticFairnessQueueing] section manages the queueing discipline (qdisc) of stochastic fairness queueing (sfq)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPerturbPeriodSec=\fR +.RS 4 +Specifies the interval in seconds for queue algorithm perturbation\&. Defaults to unset\&. +.sp +Added in version 245\&. +.RE +.SH "[BFIFO] SECTION OPTIONS" +.PP +The [BFIFO] section manages the queueing discipline (qdisc) of Byte limited Packet First In First Out (bfifo)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fILimitBytes=\fR +.RS 4 +Specifies the hard limit in bytes on the FIFO buffer size\&. The size limit prevents overflow in case the kernel is unable to dequeue packets as quickly as it receives them\&. When this limit is reached, incoming packets are dropped\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset and kernel default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[PFIFO] SECTION OPTIONS" +.PP +The [PFIFO] section manages the queueing discipline (qdisc) of Packet First In First Out (pfifo)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the number of packets in the FIFO queue\&. The size limit prevents overflow in case the kernel is unable to dequeue packets as quickly as it receives them\&. When this limit is reached, incoming packets are dropped\&. An unsigned integer in the range 0\&...4294967294\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[PFIFOHEADDROP] SECTION OPTIONS" +.PP +The [PFIFOHeadDrop] section manages the queueing discipline (qdisc) of Packet First In First Out Head Drop (pfifo_head_drop)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +As in [PFIFO] section\&. +.sp +Added in version 246\&. +.RE +.SH "[PFIFOFAST] SECTION OPTIONS" +.PP +The [PFIFOFast] section manages the queueing discipline (qdisc) of Packet First In First Out Fast (pfifo_fast)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.SH "[CAKE] SECTION OPTIONS" +.PP +The [CAKE] section manages the queueing discipline (qdisc) of Common Applications Kept Enhanced (CAKE)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIBandwidth=\fR +.RS 4 +Specifies the shaper bandwidth\&. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIAutoRateIngress=\fR +.RS 4 +Takes a boolean value\&. Enables automatic capacity estimation based on traffic arriving at this qdisc\&. This is most likely to be useful with cellular links, which tend to change quality randomly\&. If this setting is enabled, the +\fIBandwidth=\fR +setting is used as an initial estimate\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIOverheadBytes=\fR +.RS 4 +Specifies that bytes to be addeded to the size of each packet\&. Bytes may be negative\&. Takes an integer in the range \-64\&...256\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIMPUBytes=\fR +.RS 4 +Rounds each packet (including overhead) up to the specified bytes\&. Takes an integer in the range 1\&...256\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fICompensationMode=\fR +.RS 4 +Takes one of +"none", +"atm", or +"ptm"\&. Specifies the compensation mode for overhead calculation\&. When +"none", no compensation is taken into account\&. When +"atm", enables the compensation for ATM cell framing, which is normally found on ADSL links\&. When +"ptm", enables the compensation for PTM encoding, which is normally found on VDSL2 links and uses a 64b/65b encoding scheme\&. Defaults to unset and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIUseRawPacketSize=\fR +.RS 4 +Takes a boolean value\&. When true, the packet size reported by the Linux kernel will be used, instead of the underlying IP packet size\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIFlowIsolationMode=\fR +.RS 4 +CAKE places packets from different flows into different queues, then packets from each queue are delivered fairly\&. This specifies whether the fairness is based on source address, destination address, individual flows, or any combination of those\&. The available values are: +.PP +\fBnone\fR +.RS 4 +The flow isolation is disabled, and all traffic passes through a single queue\&. +.sp +Added in version 250\&. +.RE +.PP +\fBsrc\-host\fR +.RS 4 +Flows are defined only by source address\&. Equivalent to the +"srchost" +option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdst\-host\fR +.RS 4 +Flows are defined only by destination address\&. Equivalent to the +"dsthost" +option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.PP +\fBhosts\fR +.RS 4 +Flows are defined by source\-destination host pairs\&. Equivalent to the same option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.PP +\fBflows\fR +.RS 4 +Flows are defined by the entire 5\-tuple of source address, destination address, transport protocol, source port and destination port\&. Equivalent to the same option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdual\-src\-host\fR +.RS 4 +Flows are defined by the 5\-tuple (see +"flows" +in the above), and fairness is applied first over source addresses, then over individual flows\&. Equivalent to the +"dual\-srchost" +option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdual\-dst\-host\fR +.RS 4 +Flows are defined by the 5\-tuple (see +"flows" +in the above), and fairness is applied first over destination addresses, then over individual flows\&. Equivalent to the +"dual\-dsthost" +option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.PP +\fBtriple\fR +.RS 4 +Flows are defined by the 5\-tuple (see +"flows"), and fairness is applied over source and destination addresses, and also over individual flows\&. Equivalent to the +"triple\-isolate" +option for +\fBtc qdisc\fR +command\&. See also +\fBtc-cake\fR(8)\&. +.sp +Added in version 250\&. +.RE +.sp +Defaults to unset and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fINAT=\fR +.RS 4 +Takes a boolean value\&. When true, CAKE performs a NAT lookup before applying flow\-isolation rules, to determine the true addresses and port numbers of the packet, to improve fairness between hosts inside the NAT\&. This has no practical effect when +\fIFlowIsolationMode=\fR +is +"none" +or +"flows", or if NAT is performed on a different host\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIPriorityQueueingPreset=\fR +.RS 4 +CAKE divides traffic into +"tins", and each tin has its own independent set of flow\-isolation queues, bandwidth threshold, and priority\&. This specifies the preset of tin profiles\&. The available values are: +.PP +\fBbesteffort\fR +.RS 4 +Disables priority queueing by placing all traffic in one tin\&. +.sp +Added in version 250\&. +.RE +.PP +\fBprecedence\fR +.RS 4 +Enables priority queueing based on the legacy interpretation of TOS +"Precedence" +field\&. Use of this preset on the modern Internet is firmly discouraged\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdiffserv8\fR +.RS 4 +Enables priority queueing based on the Differentiated Service ("DiffServ") field with eight tins: Background Traffic, High Throughput, Best Effort, Video Streaming, Low Latency Transactions, Interactive Shell, Minimum Latency, and Network Control\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdiffserv4\fR +.RS 4 +Enables priority queueing based on the Differentiated Service ("DiffServ") field with four tins: Background Traffic, Best Effort, Streaming Media, and Latency Sensitive\&. +.sp +Added in version 250\&. +.RE +.PP +\fBdiffserv3\fR +.RS 4 +Enables priority queueing based on the Differentiated Service ("DiffServ") field with three tins: Background Traffic, Best Effort, and Latency Sensitive\&. +.sp +Added in version 250\&. +.RE +.sp +Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIFirewallMark=\fR +.RS 4 +Takes an integer in the range 1\&...4294967295\&. When specified, firewall\-mark\-based overriding of CAKE\*(Aqs tin selection is enabled\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIWash=\fR +.RS 4 +Takes a boolean value\&. When true, CAKE clears the DSCP fields, except for ECN bits, of any packet passing through CAKE\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fISplitGSO=\fR +.RS 4 +Takes a boolean value\&. When true, CAKE will split General Segmentation Offload (GSO) super\-packets into their on\-the\-wire components and dequeue them individually\&. Defaults to unset, and the kernel\*(Aqs default is used\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRTTSec=\fR +.RS 4 +Specifies the RTT for the filter\&. Takes a timespan\&. Typical values are e\&.g\&. 100us for extremely high\-performance 10GigE+ networks like datacentre, 1ms for non\-WiFi LAN connections, 100ms for typical internet connections\&. Defaults to unset, and the kernel\*(Aqs default will be used\&. +.sp +Added in version 253\&. +.RE +.PP +\fIAckFilter=\fR +.RS 4 +Takes a boolean value, or special value +"aggressive"\&. If enabled, ACKs in each flow are queued and redundant ACKs to the upstream are dropped\&. If yes, the filter will always keep at least two redundant ACKs in the queue, while in +"aggressive" +mode, it will filter down to a single ACK\&. This may improve download throughput on links with very asymmetrical rate limits\&. Defaults to unset, and the kernel\*(Aqs default will be used\&. +.sp +Added in version 253\&. +.RE +.SH "[CONTROLLEDDELAY] SECTION OPTIONS" +.PP +The [ControlledDelay] section manages the queueing discipline (qdisc) of controlled delay (CoDel)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the queue size in number of packets\&. When this limit is reached, incoming packets are dropped\&. An unsigned integer in the range 0\&...4294967294\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fITargetSec=\fR +.RS 4 +Takes a timespan\&. Specifies the acceptable minimum standing/persistent queue delay\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIIntervalSec=\fR +.RS 4 +Takes a timespan\&. This is used to ensure that the measured minimum delay does not become too stale\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIECN=\fR +.RS 4 +Takes a boolean\&. This can be used to mark packets instead of dropping them\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fICEThresholdSec=\fR +.RS 4 +Takes a timespan\&. This sets a threshold above which all packets are marked with ECN Congestion Experienced (CE)\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.SH "[DEFICITROUNDROBINSCHEDULER] SECTION OPTIONS" +.PP +The [DeficitRoundRobinScheduler] section manages the queueing discipline (qdisc) of Deficit Round Robin Scheduler (DRR)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.SH "[DEFICITROUNDROBINSCHEDULERCLASS] SECTION OPTIONS" +.PP +The [DeficitRoundRobinSchedulerClass] section manages the traffic control class of Deficit Round Robin Scheduler (DRR)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", or a qdisc identifier\&. The qdisc identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIClassId=\fR +.RS 4 +Configures the unique identifier of the class\&. It is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to unset\&. +.RE +.PP +\fIQuantumBytes=\fR +.RS 4 +Specifies the amount of bytes a flow is allowed to dequeue before the scheduler moves to the next class\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to the MTU of the interface\&. +.sp +Added in version 246\&. +.RE +.SH "[ENHANCEDTRANSMISSIONSELECTION] SECTION OPTIONS" +.PP +The [EnhancedTransmissionSelection] section manages the queueing discipline (qdisc) of Enhanced Transmission Selection (ETS)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIBands=\fR +.RS 4 +Specifies the number of bands\&. An unsigned integer in the range 1\&...16\&. This value has to be at least large enough to cover the strict bands specified through the +\fIStrictBands=\fR +and bandwidth\-sharing bands specified in +\fIQuantumBytes=\fR\&. +.sp +Added in version 246\&. +.RE +.PP +\fIStrictBands=\fR +.RS 4 +Specifies the number of bands that should be created in strict mode\&. An unsigned integer in the range 1\&...16\&. +.sp +Added in version 246\&. +.RE +.PP +\fIQuantumBytes=\fR +.RS 4 +Specifies the white\-space separated list of quantum used in band\-sharing bands\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. +.sp +Added in version 246\&. +.RE +.PP +\fIPriorityMap=\fR +.RS 4 +The priority map maps the priority of a packet to a band\&. The argument is a whitespace separated list of numbers\&. The first number indicates which band the packets with priority 0 should be put to, the second is for priority 1, and so on\&. There can be up to 16 numbers in the list\&. If there are fewer, the default band that traffic with one of the unmentioned priorities goes to is the last one\&. Each band number must be in the range 0\&...255\&. This setting can be specified multiple times\&. If an empty string is assigned, then the all previous assignments are cleared\&. +.sp +Added in version 246\&. +.RE +.SH "[GENERICRANDOMEARLYDETECTION] SECTION OPTIONS" +.PP +The [GenericRandomEarlyDetection] section manages the queueing discipline (qdisc) of Generic Random Early Detection (GRED)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIVirtualQueues=\fR +.RS 4 +Specifies the number of virtual queues\&. Takes an integer in the range 1\&...16\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIDefaultVirtualQueue=\fR +.RS 4 +Specifies the number of default virtual queue\&. This must be less than +\fIVirtualQueue=\fR\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIGenericRIO=\fR +.RS 4 +Takes a boolean\&. It turns on the RIO\-like buffering scheme\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[FAIRQUEUEINGCONTROLLEDDELAY] SECTION OPTIONS" +.PP +The [FairQueueingControlledDelay] section manages the queueing discipline (qdisc) of fair queuing controlled delay (FQ\-CoDel)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the real queue size\&. When this limit is reached, incoming packets are dropped\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIMemoryLimitBytes=\fR +.RS 4 +Specifies the limit on the total number of bytes that can be queued in this FQ\-CoDel instance\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIFlows=\fR +.RS 4 +Specifies the number of flows into which the incoming packets are classified\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fITargetSec=\fR +.RS 4 +Takes a timespan\&. Specifies the acceptable minimum standing/persistent queue delay\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIIntervalSec=\fR +.RS 4 +Takes a timespan\&. This is used to ensure that the measured minimum delay does not become too stale\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIQuantumBytes=\fR +.RS 4 +Specifies the number of bytes used as the "deficit" in the fair queuing algorithm timespan\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIECN=\fR +.RS 4 +Takes a boolean\&. This can be used to mark packets instead of dropping them\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fICEThresholdSec=\fR +.RS 4 +Takes a timespan\&. This sets a threshold above which all packets are marked with ECN Congestion Experienced (CE)\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.SH "[FAIRQUEUEING] SECTION OPTIONS" +.PP +The [FairQueueing] section manages the queueing discipline (qdisc) of fair queue traffic policing (FQ)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the real queue size\&. When this limit is reached, incoming packets are dropped\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIFlowLimit=\fR +.RS 4 +Specifies the hard limit on the maximum number of packets queued per flow\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIQuantumBytes=\fR +.RS 4 +Specifies the credit per dequeue RR round, i\&.e\&. the amount of bytes a flow is allowed to dequeue at once\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIInitialQuantumBytes=\fR +.RS 4 +Specifies the initial sending rate credit, i\&.e\&. the amount of bytes a new flow is allowed to dequeue initially\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIMaximumRate=\fR +.RS 4 +Specifies the maximum sending rate of a flow\&. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIBuckets=\fR +.RS 4 +Specifies the size of the hash table used for flow lookups\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIOrphanMask=\fR +.RS 4 +Takes an unsigned integer\&. For packets not owned by a socket, fq is able to mask a part of hash and reduce number of buckets associated with the traffic\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fIPacing=\fR +.RS 4 +Takes a boolean, and enables or disables flow pacing\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.PP +\fICEThresholdSec=\fR +.RS 4 +Takes a timespan\&. This sets a threshold above which all packets are marked with ECN Congestion Experienced (CE)\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 245\&. +.RE +.SH "[TRIVIALLINKEQUALIZER] SECTION OPTIONS" +.PP +The [TrivialLinkEqualizer] section manages the queueing discipline (qdisc) of trivial link equalizer (teql)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIId=\fR +.RS 4 +Specifies the interface ID +"N" +of teql\&. Defaults to +"0"\&. Note that when teql is used, currently, the module +\fBsch_teql\fR +with +\fBmax_equalizers=N+1\fR +option must be loaded before +\fBsystemd\-networkd\fR +is started\&. +.sp +Added in version 245\&. +.RE +.SH "[HIERARCHYTOKENBUCKET] SECTION OPTIONS" +.PP +The [HierarchyTokenBucket] section manages the queueing discipline (qdisc) of hierarchy token bucket (htb)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIDefaultClass=\fR +.RS 4 +Takes the minor id in hexadecimal of the default class\&. Unclassified traffic gets sent to the class\&. Defaults to unset\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRateToQuantum=\fR +.RS 4 +Takes an unsigned integer\&. The DRR quantums are calculated by dividing the value configured in +\fIRate=\fR +by +\fIRateToQuantum=\fR\&. +.sp +Added in version 246\&. +.RE +.SH "[HIERARCHYTOKENBUCKETCLASS] SECTION OPTIONS" +.PP +The [HierarchyTokenBucketClass] section manages the traffic control class of hierarchy token bucket (htb)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", or a qdisc identifier\&. The qdisc identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIClassId=\fR +.RS 4 +Configures the unique identifier of the class\&. It is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to unset\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +Specifies the priority of the class\&. In the round\-robin process, classes with the lowest priority field are tried for packets first\&. +.sp +Added in version 246\&. +.RE +.PP +\fIQuantumBytes=\fR +.RS 4 +Specifies how many bytes to serve from leaf at once\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. +.sp +Added in version 246\&. +.RE +.PP +\fIMTUBytes=\fR +.RS 4 +Specifies the maximum packet size we create\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. +.sp +Added in version 246\&. +.RE +.PP +\fIOverheadBytes=\fR +.RS 4 +Takes an unsigned integer which specifies per\-packet size overhead used in rate computations\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRate=\fR +.RS 4 +Specifies the maximum rate this class and all its children are guaranteed\&. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000\&. This setting is mandatory\&. +.sp +Added in version 246\&. +.RE +.PP +\fICeilRate=\fR +.RS 4 +Specifies the maximum rate at which a class can send, if its parent has bandwidth to spare\&. When suffixed with K, M, or G, the specified size is parsed as Kilobits, Megabits, or Gigabits, respectively, to the base of 1000\&. When unset, the value specified with +\fIRate=\fR +is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIBufferBytes=\fR +.RS 4 +Specifies the maximum bytes burst which can be accumulated during idle period\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. +.sp +Added in version 246\&. +.RE +.PP +\fICeilBufferBytes=\fR +.RS 4 +Specifies the maximum bytes burst for ceil which can be accumulated during idle period\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. +.sp +Added in version 246\&. +.RE +.SH "[HEAVYHITTERFILTER] SECTION OPTIONS" +.PP +The [HeavyHitterFilter] section manages the queueing discipline (qdisc) of Heavy Hitter Filter (hhf)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.PP +\fIPacketLimit=\fR +.RS 4 +Specifies the hard limit on the queue size in number of packets\&. When this limit is reached, incoming packets are dropped\&. An unsigned integer in the range 0\&...4294967294\&. Defaults to unset and kernel\*(Aqs default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[QUICKFAIRQUEUEING] SECTION OPTIONS" +.PP +The [QuickFairQueueing] section manages the queueing discipline (qdisc) of Quick Fair Queueing (QFQ)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", +"clsact", +"ingress" +or a class identifier\&. The class identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIHandle=\fR +.RS 4 +Configures the major number of unique identifier of the qdisc, known as the handle\&. Takes a hexadecimal number in the range 0x1\(en0xffff\&. Defaults to unset\&. +.RE +.SH "[QUICKFAIRQUEUEINGCLASS] SECTION OPTIONS" +.PP +The [QuickFairQueueingClass] section manages the traffic control class of Quick Fair Queueing (qfq)\&. +.PP +\fIParent=\fR +.RS 4 +Configures the parent Queueing Discipline (qdisc)\&. Takes one of +"root", or a qdisc identifier\&. The qdisc identifier is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to +"root"\&. +.RE +.PP +\fIClassId=\fR +.RS 4 +Configures the unique identifier of the class\&. It is specified as the major and minor numbers in hexadecimal in the range 0x1\(en0xffff separated with a colon ("major:minor")\&. Defaults to unset\&. +.RE +.PP +\fIWeight=\fR +.RS 4 +Specifies the weight of the class\&. Takes an integer in the range 1\&...1023\&. Defaults to unset in which case the kernel default is used\&. +.sp +Added in version 246\&. +.RE +.PP +\fIMaxPacketBytes=\fR +.RS 4 +Specifies the maximum packet size in bytes for the class\&. When suffixed with K, M, or G, the specified size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024\&. When unset, the kernel default is used\&. +.sp +Added in version 246\&. +.RE +.SH "[BRIDGEVLAN] SECTION OPTIONS" +.PP +The [BridgeVLAN] section manages the VLAN ID configuration of a bridge port and accepts the following keys\&. Specify several [BridgeVLAN] sections to configure several VLAN entries\&. The +\fIVLANFiltering=\fR +option has to be enabled, see the [Bridge] section in +\fBsystemd.netdev\fR(5)\&. +.PP +\fIVLAN=\fR +.RS 4 +The VLAN ID allowed on the port\&. This can be either a single ID or a range M\-N\&. Takes an integer in the range 1\&...4094\&. +.sp +Added in version 231\&. +.RE +.PP +\fIEgressUntagged=\fR +.RS 4 +The VLAN ID specified here will be used to untag frames on egress\&. Configuring +\fIEgressUntagged=\fR +implicates the use of +\fIVLAN=\fR +above and will enable the VLAN ID for ingress as well\&. This can be either a single ID or a range M\-N\&. +.sp +Added in version 231\&. +.RE +.PP +\fIPVID=\fR +.RS 4 +The Port VLAN ID specified here is assigned to all untagged frames at ingress\&. +\fIPVID=\fR +can be used only once\&. Configuring +\fIPVID=\fR +implicates the use of +\fIVLAN=\fR +above and will enable the VLAN ID for ingress as well\&. +.sp +Added in version 231\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Static network configuration\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/50\-static\&.network +[Match] +Name=enp2s0 + +[Network] +Address=192\&.168\&.0\&.15/24 +Gateway=192\&.168\&.0\&.1 +.fi +.if n \{\ +.RE +.\} +.PP +This brings interface +"enp2s0" +up with a static address\&. The specified gateway will be used for a default route\&. +.PP +\fBExample\ \&2.\ \&DHCP on ethernet links\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/80\-dhcp\&.network +[Match] +Name=en* + +[Network] +DHCP=yes +.fi +.if n \{\ +.RE +.\} +.PP +This will enable DHCPv4 and DHCPv6 on all interfaces with names starting with +"en" +(i\&.e\&. ethernet interfaces)\&. +.PP +\fBExample\ \&3.\ \&IPv6 Prefix Delegation (DHCPv6 PD)\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/55\-dhcpv6\-pd\-upstream\&.network +[Match] +Name=enp1s0 + +[Network] +DHCP=ipv6 + +# The below setting is optional, to also assign an address in the delegated prefix +# to the upstream interface\&. If not necessary, then comment out the line below and +# the [DHCPPrefixDelegation] section\&. +DHCPPrefixDelegation=yes + +# If the upstream network provides Router Advertisement with Managed bit set, +# then comment out the line below and WithoutRA= setting in the [DHCPv6] section\&. +IPv6AcceptRA=no + +[DHCPv6] +WithoutRA=solicit + +[DHCPPrefixDelegation] +UplinkInterface=:self +SubnetId=0 +Announce=no +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/55\-dhcpv6\-pd\-downstream\&.network +[Match] +Name=enp2s0 + +[Network] +DHCPPrefixDelegation=yes +IPv6SendRA=yes + +# It is expected that the host is acting as a router\&. So, usually it is not +# necessary to receive Router Advertisement from other hosts in the downstream network\&. +IPv6AcceptRA=no + +[DHCPPrefixDelegation] +UplinkInterface=enp1s0 +SubnetId=1 +Announce=yes +.fi +.if n \{\ +.RE +.\} +.PP +This will enable DHCPv6\-PD on the interface enp1s0 as an upstream interface where the DHCPv6 client is running and enp2s0 as a downstream interface where the prefix is delegated to\&. The delegated prefixes are distributed by IPv6 Router Advertisement on the downstream network\&. +.PP +\fBExample\ \&4.\ \&IPv6 Prefix Delegation (DHCPv4 6RD)\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/55\-dhcpv4\-6rd\-upstream\&.network +[Match] +Name=enp1s0 + +[Network] +DHCP=ipv4 + +# When DHCPv4\-6RD is used, the upstream network does not support IPv6\&. +# Hence, it is not necessary to wait for Router Advertisement, which is enabled by default\&. +IPv6AcceptRA=no + +[DHCPv4] +Use6RD=yes +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/55\-dhcpv4\-6rd\-downstream\&.network +[Match] +Name=enp2s0 + +[Network] +DHCPPrefixDelegation=yes +IPv6SendRA=yes + +# It is expected that the host is acting as a router\&. So, usually it is not +# necessary to receive Router Advertisement from other hosts in the downstream network\&. +IPv6AcceptRA=no + +[DHCPPrefixDelegation] +UplinkInterface=enp1s0 +SubnetId=1 +Announce=yes +.fi +.if n \{\ +.RE +.\} +.PP +This will enable DHCPv4\-6RD on the interface enp1s0 as an upstream interface where the DHCPv4 client is running and enp2s0 as a downstream interface where the prefix is delegated to\&. The delegated prefixes are distributed by IPv6 Router Advertisement on the downstream network\&. +.PP +\fBExample\ \&5.\ \&A bridge with two enslaved links\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/25\-bridge\-static\&.netdev +[NetDev] +Name=bridge0 +Kind=bridge +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/25\-bridge\-static\&.network +[Match] +Name=bridge0 + +[Network] +Address=192\&.168\&.0\&.15/24 +Gateway=192\&.168\&.0\&.1 +DNS=192\&.168\&.0\&.1 +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/25\-bridge\-slave\-interface\-1\&.network +[Match] +Name=enp2s0 + +[Network] +Bridge=bridge0 +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/25\-bridge\-slave\-interface\-2\&.network +[Match] +Name=wlp3s0 + +[Network] +Bridge=bridge0 +.fi +.if n \{\ +.RE +.\} +.PP +This creates a bridge and attaches devices +"enp2s0" +and +"wlp3s0" +to it\&. The bridge will have the specified static address and network assigned, and a default route via the specified gateway will be added\&. The specified DNS server will be added to the global list of DNS resolvers\&. +.PP +\fBExample\ \&6.\ \&Bridge port with VLAN forwarding\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/25\-bridge\-slave\-interface\-1\&.network +[Match] +Name=enp2s0 + +[Network] +Bridge=bridge0 + +[BridgeVLAN] +VLAN=1\-32 +PVID=42 +EgressUntagged=42 + +[BridgeVLAN] +VLAN=100\-200 + +[BridgeVLAN] +EgressUntagged=300\-400 +.fi +.if n \{\ +.RE +.\} +.PP +This overrides the configuration specified in the previous example for the interface +"enp2s0", and enables VLAN on that bridge port\&. VLAN IDs 1\-32, 42, 100\-400 will be allowed\&. Packets tagged with VLAN IDs 42, 300\-400 will be untagged when they leave on this interface\&. Untagged packets which arrive on this interface will be assigned VLAN ID 42\&. +.PP +\fBExample\ \&7.\ \&Various tunnels\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/systemd/network/25\-tunnels\&.network +[Match] +Name=ens1 + +[Network] +Tunnel=ipip\-tun +Tunnel=sit\-tun +Tunnel=gre\-tun +Tunnel=vti\-tun + +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/systemd/network/25\-tunnel\-ipip\&.netdev +[NetDev] +Name=ipip\-tun +Kind=ipip + +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/systemd/network/25\-tunnel\-sit\&.netdev +[NetDev] +Name=sit\-tun +Kind=sit + +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/systemd/network/25\-tunnel\-gre\&.netdev +[NetDev] +Name=gre\-tun +Kind=gre + +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/systemd/network/25\-tunnel\-vti\&.netdev +[NetDev] +Name=vti\-tun +Kind=vti + +.fi +.if n \{\ +.RE +.\} +.PP +This will bring interface +"ens1" +up and create an IPIP tunnel, a SIT tunnel, a GRE tunnel, and a VTI tunnel using it\&. +.PP +\fBExample\ \&8.\ \&A bond device\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/30\-bond1\&.network +[Match] +Name=bond1 + +[Network] +DHCP=ipv6 +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/30\-bond1\&.netdev +[NetDev] +Name=bond1 +Kind=bond +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/30\-bond1\-dev1\&.network +[Match] +MACAddress=52:54:00:e9:64:41 + +[Network] +Bond=bond1 +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/30\-bond1\-dev2\&.network +[Match] +MACAddress=52:54:00:e9:64:42 + +[Network] +Bond=bond1 +.fi +.if n \{\ +.RE +.\} +.PP +This will create a bond device +"bond1" +and enslave the two devices with MAC addresses 52:54:00:e9:64:41 and 52:54:00:e9:64:42 to it\&. IPv6 DHCP will be used to acquire an address\&. +.PP +\fBExample\ \&9.\ \&Virtual Routing and Forwarding (VRF)\fR +.PP +Add the +"bond1" +interface to the VRF master interface +"vrf1"\&. This will redirect routes generated on this interface to be within the routing table defined during VRF creation\&. For kernels before 4\&.8 traffic won\*(Aqt be redirected towards the VRFs routing table unless specific ip\-rules are added\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/25\-vrf\&.network +[Match] +Name=bond1 + +[Network] +VRF=vrf1 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&10.\ \&MacVTap\fR +.PP +This brings up a network interface +"macvtap\-test" +and attaches it to +"enp0s25"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/systemd/network/25\-macvtap\&.network +[Match] +Name=enp0s25 + +[Network] +MACVTAP=macvtap\-test +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&11.\ \&A Xfrm interface with physical underlying device\&.\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/27\-xfrm\&.netdev +[NetDev] +Name=xfrm0 +Kind=xfrm + +[Xfrm] +InterfaceId=7 +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/network/27\-eth0\&.network +[Match] +Name=eth0 + +[Network] +Xfrm=xfrm0 +.fi +.if n \{\ +.RE +.\} +.PP +This creates a +"xfrm0" +interface and binds it to the +"eth0" +device\&. This allows hardware based ipsec offloading to the +"eth0" +nic\&. If offloading is not needed, xfrm interfaces can be assigned to the +"lo" +device\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-networkd.service\fR(8), +\fBsystemd.link\fR(5), +\fBsystemd.netdev\fR(5), +\fBsystemd-network-generator.service\fR(8), +\fBsystemd-resolved.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +System and Service Credentials +.RS 4 +\%https://systemd.io/CREDENTIALS +.RE +.IP " 2." 4 +Link-Local Multicast Name Resolution +.RS 4 +\%https://tools.ietf.org/html/rfc4795 +.RE +.IP " 3." 4 +Multicast DNS +.RS 4 +\%https://tools.ietf.org/html/rfc6762 +.RE +.IP " 4." 4 +DNS-over-TLS +.RS 4 +\%https://tools.ietf.org/html/rfc7858 +.RE +.IP " 5." 4 +DNSSEC +.RS 4 +\%https://tools.ietf.org/html/rfc4033 +.RE +.IP " 6." 4 +IEEE 802.1AB-2016 +.RS 4 +\%https://standards.ieee.org/findstds/standard/802.1AB-2016.html +.RE +.IP " 7." 4 +IP Sysctl +.RS 4 +\%https://docs.kernel.org/networking/ip-sysctl.html +.RE +.IP " 8." 4 +RFC 4941 +.RS 4 +\%https://tools.ietf.org/html/rfc4941 +.RE +.IP " 9." 4 +RFC 3704 +.RS 4 +\%https://tools.ietf.org/html/rfc1027 +.RE +.IP "10." 4 +RFC 6275 +.RS 4 +\%https://tools.ietf.org/html/rfc6275 +.RE +.IP "11." 4 +RFC 5227 +.RS 4 +\%https://tools.ietf.org/html/rfc5227 +.RE +.IP "12." 4 +RFC 4862 +.RS 4 +\%https://tools.ietf.org/html/rfc4862 +.RE +.IP "13." 4 +RFC 3041 +.RS 4 +\%https://tools.ietf.org/html/rfc3041 +.RE +.IP "14." 4 +NetLabel +.RS 4 +\%https://docs.kernel.org/netlabel/index.html +.RE +.IP "15." 4 +Linux Security Modules (LSMs) +.RS 4 +\%https://en.wikipedia.org/wiki/Linux_Security_Modules +.RE +.IP "16." 4 +NetLabel Fallback Peer Labeling +.RS 4 +\%https://github.com/SELinuxProject/selinux-notebook/blob/main/src/network_support.md +.RE +.IP "17." 4 +NFT +.RS 4 +\%https://netfilter.org/projects/nftables/index.html +.RE +.IP "18." 4 +RFC 3484 +.RS 4 +\%https://tools.ietf.org/html/rfc3484 +.RE +.IP "19." 4 +Type of Service +.RS 4 +\%https://en.wikipedia.org/wiki/Type_of_service +.RE +.IP "20." 4 +Differentiated services +.RS 4 +\%https://en.wikipedia.org/wiki/Differentiated_services +.RE +.IP "21." 4 +RFC 4191 +.RS 4 +\%https://tools.ietf.org/html/rfc4191 +.RE +.IP "22." 4 +RFC 8520 +.RS 4 +\%https://tools.ietf.org/html/rfc8520 +.RE +.IP "23." 4 +RFC 4039 +.RS 4 +\%https://tools.ietf.org/html/rfc4039 +.RE +.IP "24." 4 +RFC 7844 +.RS 4 +\%https://tools.ietf.org/html/rfc7844 +.RE +.IP "25." 4 +C-style escapes +.RS 4 +\%https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences +.RE +.IP "26." 4 +RFC 3442 +.RS 4 +\%https://datatracker.ietf.org/doc/html/rfc3442 +.RE +.IP "27." 4 +RFC 5969 +.RS 4 +\%https://tools.ietf.org/html/rfc5969 +.RE +.IP "28." 4 +RFC 8925 +.RS 4 +\%https://tools.ietf.org/html/rfc8925 +.RE +.IP "29." 4 +RFC 3315 +.RS 4 +\%https://tools.ietf.org/html/rfc3315#section-17.2.1 +.RE +.IP "30." 4 +RFC 8415 +.RS 4 +\%https://www.rfc-editor.org/rfc/rfc8415.html#section-6.3 +.RE +.IP "31." 4 +RFC 4291 +.RS 4 +\%https://tools.ietf.org/html/rfc4291#section-2.5.4 +.RE +.IP "32." 4 +RFC 7217 +.RS 4 +\%https://tools.ietf.org/html/rfc7217 +.RE +.IP "33." 4 +RFC 8781 +.RS 4 +\%https://tools.ietf.org/html/rfc8781 +.RE +.IP "34." 4 +RFC 2131 +.RS 4 +\%https://www.rfc-editor.org/rfc/rfc2131.html +.RE +.IP "35." 4 +RFC 2132 +.RS 4 +\%https://www.rfc-editor.org/rfc/rfc2132.html +.RE +.IP "36." 4 +RFC 1542 +.RS 4 +\%https://tools.ietf.org/html/rfc1542 +.RE +.IP "37." 4 +RFC 4039 +.RS 4 +\%https://datatracker.ietf.org/doc/html/rfc4039 +.RE +.IP "38." 4 +RFC 4861 +.RS 4 +\%https://tools.ietf.org/html/rfc4861 +.RE diff --git a/upstream/fedora-40/man5/systemd.nspawn.5 b/upstream/fedora-40/man5/systemd.nspawn.5 new file mode 100644 index 00000000..0c441ba1 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.nspawn.5 @@ -0,0 +1,592 @@ +'\" t +.TH "SYSTEMD\&.NSPAWN" "5" "" "systemd 255" "systemd.nspawn" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.nspawn \- Container settings +.SH "SYNOPSIS" +.PP +/etc/systemd/nspawn/\fImachine\fR\&.nspawn +.PP +/run/systemd/nspawn/\fImachine\fR\&.nspawn +.PP +/var/lib/machines/\fImachine\fR\&.nspawn +.SH "DESCRIPTION" +.PP +An nspawn container settings file (suffix +\&.nspawn) contains runtime configuration for a local container, and is used by +\fBsystemd-nspawn\fR(1)\&. Files of this type are named after the containers they define settings for\&. They are optional, and only required for containers whose execution environment shall differ from the defaults\&. Files of this type mostly contain settings that may also be set on the +\fBsystemd\-nspawn\fR +command line, and make it easier to persistently attach specific settings to specific containers\&. The syntax of these files is inspired by +\&.desktop +files, similarly to other configuration files supported by the systemd project\&. See +\fBsystemd.syntax\fR(7) +for an overview\&. +.SH "\&.NSPAWN FILE DISCOVERY" +.PP +Files are searched for by appending the +\&.nspawn +suffix to the machine name of the container, as specified with the +\fB\-\-machine=\fR +switch of +\fBsystemd\-nspawn\fR, or derived from the directory or image file name\&. This file is first searched for in +/etc/systemd/nspawn/ +and +/run/systemd/nspawn/\&. If found there, the settings are read and all of them take full effect (but may still be overridden by corresponding command line arguments)\&. Otherwise, the file will then be searched for next to the image file or in the immediate parent of the root directory of the container\&. If the file is found there, only a subset of the settings will take effect however\&. All settings that possibly elevate privileges or grant additional access to resources of the host (such as files or directories) are ignored\&. To which options this applies is documented below\&. +.PP +Persistent settings files created and maintained by the administrator (and thus trusted) should be placed in +/etc/systemd/nspawn/, while automatically downloaded (and thus potentially untrusted) settings files are placed in +/var/lib/machines/ +instead (next to the container images), where their security impact is limited\&. In order to add privileged settings to +\&.nspawn +files acquired from the image vendor, it is recommended to copy the settings files into +/etc/systemd/nspawn/ +and edit them there, so that the privileged options become available\&. The precise algorithm for how the files are searched and interpreted may be configured with +\fBsystemd\-nspawn\fR\*(Aqs +\fB\-\-settings=\fR +switch, see +\fBsystemd-nspawn\fR(1) +for details\&. +.SH "[EXEC] SECTION OPTIONS" +.PP +Settings files may include an [Exec] section, which carries various execution parameters: +.PP +\fIBoot=\fR +.RS 4 +Takes a boolean argument, which defaults to off\&. If enabled, +\fBsystemd\-nspawn\fR +will automatically search for an +init +executable and invoke it\&. In this case, the specified parameters using +\fIParameters=\fR +are passed as additional arguments to the +init +process\&. This setting corresponds to the +\fB\-\-boot\fR +switch on the +\fBsystemd\-nspawn\fR +command line\&. This option may not be combined with +\fIProcessTwo=yes\fR\&. This option is specified by default in the +systemd\-nspawn@\&.service +template unit\&. +.sp +Added in version 226\&. +.RE +.PP +\fIEphemeral=\fR +.RS 4 +Takes a boolean argument, which defaults to off, If enabled, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates\&. This is equivalent to the +\fB\-\-ephemeral\fR +command line switch\&. See +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. +.sp +Added in version 240\&. +.RE +.PP +\fIProcessTwo=\fR +.RS 4 +Takes a boolean argument, which defaults to off\&. If enabled, the specified program is run as PID 2\&. A stub init process is run as PID 1\&. This setting corresponds to the +\fB\-\-as\-pid2\fR +switch on the +\fBsystemd\-nspawn\fR +command line\&. This option may not be combined with +\fIBoot=yes\fR\&. +.sp +Added in version 229\&. +.RE +.PP +\fIParameters=\fR +.RS 4 +Takes a whitespace\-separated list of arguments\&. Single ("\*(Aq") and double (""") quotes may be used around arguments with whitespace\&. This is either a command line, beginning with the binary name to execute, or \(en if +\fIBoot=\fR +is enabled \(en the list of arguments to pass to the init process\&. This setting corresponds to the command line parameters passed on the +\fBsystemd\-nspawn\fR +command line\&. +.sp +Note: +\fBBoot=no\fR, +\fBParameters=a b "c c"\fR +is the same as +\fBsystemd\-nspawn a b "c c"\fR, and +\fBBoot=yes\fR, +\fBParameters=b \*(Aqc c\*(Aq\fR +is the same as +\fBsystemd\-nspawn \-\-boot b \*(Aqc c\*(Aq\fR\&. +.sp +Added in version 226\&. +.RE +.PP +\fIEnvironment=\fR +.RS 4 +Takes an environment variable assignment consisting of key and value, separated by +"="\&. Sets an environment variable for the main process invoked in the container\&. This setting may be used multiple times to set multiple environment variables\&. It corresponds to the +\fB\-\-setenv=\fR +command line switch\&. +.sp +Added in version 226\&. +.RE +.PP +\fIUser=\fR +.RS 4 +Takes a UNIX user name\&. Specifies the user name to invoke the main process of the container as\&. This user must be known in the container\*(Aqs user database\&. This corresponds to the +\fB\-\-user=\fR +command line switch\&. +.sp +Added in version 226\&. +.RE +.PP +\fIWorkingDirectory=\fR +.RS 4 +Selects the working directory for the process invoked in the container\&. Expects an absolute path in the container\*(Aqs file system namespace\&. This corresponds to the +\fB\-\-chdir=\fR +command line switch\&. +.sp +Added in version 229\&. +.RE +.PP +\fIPivotRoot=\fR +.RS 4 +Selects a directory to pivot to +/ +inside the container when starting up\&. Takes a single path, or a pair of two paths separated by a colon\&. Both paths must be absolute, and are resolved in the container\*(Aqs file system namespace\&. This corresponds to the +\fB\-\-pivot\-root=\fR +command line switch\&. +.sp +Added in version 233\&. +.RE +.PP +\fICapability=\fR, \fIDropCapability=\fR +.RS 4 +Takes a space\-separated list of Linux process capabilities (see +\fBcapabilities\fR(7) +for details)\&. The +\fICapability=\fR +setting specifies additional capabilities to pass on top of the default set of capabilities\&. The +\fIDropCapability=\fR +setting specifies capabilities to drop from the default set\&. These settings correspond to the +\fB\-\-capability=\fR +and +\fB\-\-drop\-capability=\fR +command line switches\&. Note that +\fICapability=\fR +is a privileged setting, and only takes effect in +\&.nspawn +files in +/etc/systemd/nspawn/ +and +/run/system/nspawn/ +(see above)\&. On the other hand, +\fIDropCapability=\fR +takes effect in all cases\&. If the special value +"all" +is passed, all capabilities are retained (or dropped)\&. +.sp +These settings change the bounding set of capabilities which also limits the ambient capabilities as given with the +\fIAmbientCapability=\fR\&. +.sp +Added in version 226\&. +.RE +.PP +\fIAmbientCapability=\fR +.RS 4 +Takes a space\-separated list of Linux process capabilities (see +\fBcapabilities\fR(7) +for details)\&. The +\fIAmbientCapability=\fR +setting specifies capabilities which will be passed to the started program in the inheritable and ambient capability sets\&. This will grant these capabilities to this process\&. This setting correspond to the +\fB\-\-ambient\-capability=\fR +command line switch\&. +.sp +The value +"all" +is not supported for this setting\&. +.sp +The setting of +\fIAmbientCapability=\fR +must be covered by the bounding set settings which were established by +\fICapability=\fR +and +\fIDropCapability=\fR\&. +.sp +Note that +\fIAmbientCapability=\fR +is a privileged setting (see above)\&. +.sp +Added in version 248\&. +.RE +.PP +\fINoNewPrivileges=\fR +.RS 4 +Takes a boolean argument that controls the +\fBPR_SET_NO_NEW_PRIVS\fR +flag for the container payload\&. This is equivalent to the +\fB\-\-no\-new\-privileges=\fR +command line switch\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fIKillSignal=\fR +.RS 4 +Specify the process signal to send to the container\*(Aqs PID 1 when nspawn itself receives SIGTERM, in order to trigger an orderly shutdown of the container\&. Defaults to SIGRTMIN+3 if +\fBBoot=\fR +is used (on systemd\-compatible init systems SIGRTMIN+3 triggers an orderly shutdown)\&. For a list of valid signals, see +\fBsignal\fR(7)\&. +.sp +Added in version 230\&. +.RE +.PP +\fIPersonality=\fR +.RS 4 +Configures the kernel personality for the container\&. This is equivalent to the +\fB\-\-personality=\fR +switch\&. +.sp +Added in version 226\&. +.RE +.PP +\fIMachineID=\fR +.RS 4 +Configures the 128\-bit machine ID (UUID) to pass to the container\&. This is equivalent to the +\fB\-\-uuid=\fR +command line switch\&. This option is privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.PP +\fIPrivateUsers=\fR +.RS 4 +Configures support for usernamespacing\&. This is equivalent to the +\fB\-\-private\-users=\fR +command line switch, and takes the same options\&. This option is privileged (see above)\&. This option is the default if the +systemd\-nspawn@\&.service +template unit file is used\&. +.sp +Added in version 230\&. +.RE +.PP +\fINotifyReady=\fR +.RS 4 +Configures support for notifications from the container\*(Aqs init process\&. This is equivalent to the +\fB\-\-notify\-ready=\fR +command line switch, and takes the same parameters\&. See +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. +.sp +Added in version 231\&. +.RE +.PP +\fISystemCallFilter=\fR +.RS 4 +Configures the system call filter applied to containers\&. This is equivalent to the +\fB\-\-system\-call\-filter=\fR +command line switch, and takes the same list parameter\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 235\&. +.RE +.PP +\fILimitCPU=\fR, \fILimitFSIZE=\fR, \fILimitDATA=\fR, \fILimitSTACK=\fR, \fILimitCORE=\fR, \fILimitRSS=\fR, \fILimitNOFILE=\fR, \fILimitAS=\fR, \fILimitNPROC=\fR, \fILimitMEMLOCK=\fR, \fILimitLOCKS=\fR, \fILimitSIGPENDING=\fR, \fILimitMSGQUEUE=\fR, \fILimitNICE=\fR, \fILimitRTPRIO=\fR, \fILimitRTTIME=\fR +.RS 4 +Configures various types of resource limits applied to containers\&. This is equivalent to the +\fB\-\-rlimit=\fR +command line switch, and takes the same arguments\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fIOOMScoreAdjust=\fR +.RS 4 +Configures the OOM score adjustment value\&. This is equivalent to the +\fB\-\-oom\-score\-adjust=\fR +command line switch, and takes the same argument\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fICPUAffinity=\fR +.RS 4 +Configures the CPU affinity\&. This is equivalent to the +\fB\-\-cpu\-affinity=\fR +command line switch, and takes the same argument\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fIHostname=\fR +.RS 4 +Configures the kernel hostname set for the container\&. This is equivalent to the +\fB\-\-hostname=\fR +command line switch, and takes the same argument\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fIResolvConf=\fR +.RS 4 +Configures how +/etc/resolv\&.conf +in the container shall be handled\&. This is equivalent to the +\fB\-\-resolv\-conf=\fR +command line switch, and takes the same argument\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fITimezone=\fR +.RS 4 +Configures how +/etc/localtime +in the container shall be handled\&. This is equivalent to the +\fB\-\-timezone=\fR +command line switch, and takes the same argument\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fILinkJournal=\fR +.RS 4 +Configures how to link host and container journal setups\&. This is equivalent to the +\fB\-\-link\-journal=\fR +command line switch, and takes the same parameter\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 239\&. +.RE +.PP +\fISuppressSync=\fR +.RS 4 +Configures whether to suppress disk synchronization for the container payload\&. This is equivalent to the +\fB\-\-suppress\-sync=\fR +command line switch, and takes the same parameter\&. See +\fBsystemd-nspawn\fR(1) +for details\&. +.sp +Added in version 250\&. +.RE +.SH "[FILES] SECTION OPTIONS" +.PP +Settings files may include a [Files] section, which carries various parameters configuring the file system of the container: +.PP +\fIReadOnly=\fR +.RS 4 +Takes a boolean argument, which defaults to off\&. If specified, the container will be run with a read\-only file system\&. This setting corresponds to the +\fB\-\-read\-only\fR +command line switch\&. +.sp +Added in version 226\&. +.RE +.PP +\fIVolatile=\fR +.RS 4 +Takes a boolean argument, or the special value +"state"\&. This configures whether to run the container with volatile state and/or configuration\&. This option is equivalent to +\fB\-\-volatile=\fR, see +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. +.sp +Added in version 226\&. +.RE +.PP +\fIBind=\fR, \fIBindReadOnly=\fR +.RS 4 +Adds a bind mount from the host into the container\&. Takes a single path, a pair of two paths separated by a colon, or a triplet of two paths plus an option string separated by colons\&. This option may be used multiple times to configure multiple bind mounts\&. This option is equivalent to the command line switches +\fB\-\-bind=\fR +and +\fB\-\-bind\-ro=\fR, see +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. This setting is privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.PP +\fIBindUser=\fR +.RS 4 +Binds a user from the host into the container\&. This option is equivalent to the command line switch +\fB\-\-bind\-user=\fR, see +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. This setting is privileged (see above)\&. +.sp +Added in version 249\&. +.RE +.PP +\fITemporaryFileSystem=\fR +.RS 4 +Adds a +"tmpfs" +mount to the container\&. Takes a path or a pair of path and option string, separated by a colon\&. This option may be used multiple times to configure multiple +"tmpfs" +mounts\&. This option is equivalent to the command line switch +\fB\-\-tmpfs=\fR, see +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. This setting is privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.PP +\fIInaccessible=\fR +.RS 4 +Masks the specified file or directory in the container, by over\-mounting it with an empty file node of the same type with the most restrictive access mode\&. Takes a file system path as argument\&. This option may be used multiple times to mask multiple files or directories\&. This option is equivalent to the command line switch +\fB\-\-inaccessible=\fR, see +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. This setting is privileged (see above)\&. +.sp +Added in version 242\&. +.RE +.PP +\fIOverlay=\fR, \fIOverlayReadOnly=\fR +.RS 4 +Adds an overlay mount point\&. Takes a colon\-separated list of paths\&. This option may be used multiple times to configure multiple overlay mounts\&. This option is equivalent to the command line switches +\fB\-\-overlay=\fR +and +\fB\-\-overlay\-ro=\fR, see +\fBsystemd-nspawn\fR(1) +for details about the specific options supported\&. This setting is privileged (see above)\&. +.sp +Added in version 233\&. +.RE +.PP +\fIPrivateUsersOwnership=\fR +.RS 4 +Configures whether the ownership of the files and directories in the container tree shall be adjusted to the UID/GID range used, if necessary and user namespacing is enabled\&. This is equivalent to the +\fB\-\-private\-users\-ownership=\fR +command line switch\&. This option is privileged (see above)\&. +.sp +Added in version 249\&. +.RE +.SH "[NETWORK] SECTION OPTIONS" +.PP +Settings files may include a [Network] section, which carries various parameters configuring the network connectivity of the container: +.PP +\fIPrivate=\fR +.RS 4 +Takes a boolean argument, which defaults to off\&. If enabled, the container will run in its own network namespace and not share network interfaces and configuration with the host\&. This setting corresponds to the +\fB\-\-private\-network\fR +command line switch\&. +.sp +Added in version 226\&. +.RE +.PP +\fIVirtualEthernet=\fR +.RS 4 +Takes a boolean argument\&. Configures whether to create a virtual Ethernet connection ("veth") between host and the container\&. This setting implies +\fIPrivate=yes\fR\&. This setting corresponds to the +\fB\-\-network\-veth\fR +command line switch\&. This option is privileged (see above)\&. This option is the default if the +systemd\-nspawn@\&.service +template unit file is used\&. +.sp +Added in version 226\&. +.RE +.PP +\fIVirtualEthernetExtra=\fR +.RS 4 +Takes a colon\-separated pair of interface names\&. Configures an additional virtual Ethernet connection ("veth") between host and the container\&. The first specified name is the interface name on the host, the second the interface name in the container\&. The latter may be omitted in which case it is set to the same name as the host side interface\&. This setting implies +\fIPrivate=yes\fR\&. This setting corresponds to the +\fB\-\-network\-veth\-extra=\fR +command line switch, and may be used multiple times\&. It is independent of +\fIVirtualEthernet=\fR\&. Note that this option is unrelated to the +\fIBridge=\fR +setting below, and thus any connections created this way are not automatically added to any bridge device on the host side\&. This option is privileged (see above)\&. +.sp +Added in version 228\&. +.RE +.PP +\fIInterface=\fR +.RS 4 +Takes a space\-separated list of interfaces to add to the container\&. The interface object is defined either by a single interface name, referencing the name on the host, or a colon\-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container\&. This option corresponds to the +\fB\-\-network\-interface=\fR +command line switch and implies +\fIPrivate=yes\fR\&. This option is privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.PP +\fIMACVLAN=\fR, \fIIPVLAN=\fR +.RS 4 +Takes a space\-separated list of interfaces to add MACLVAN or IPVLAN interfaces to, which are then added to the container\&. The interface object is defined either by a single interface name, referencing the name on the host, or a colon\-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container\&. These options correspond to the +\fB\-\-network\-macvlan=\fR +and +\fB\-\-network\-ipvlan=\fR +command line switches and imply +\fIPrivate=yes\fR\&. These options are privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.PP +\fIBridge=\fR +.RS 4 +Takes an interface name\&. This setting implies +\fIVirtualEthernet=yes\fR +and +\fIPrivate=yes\fR +and has the effect that the host side of the created virtual Ethernet link is connected to the specified bridge interface\&. This option corresponds to the +\fB\-\-network\-bridge=\fR +command line switch\&. This option is privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.PP +\fIZone=\fR +.RS 4 +Takes a network zone name\&. This setting implies +\fIVirtualEthernet=yes\fR +and +\fIPrivate=yes\fR +and has the effect that the host side of the created virtual Ethernet link is connected to an automatically managed bridge interface named after the passed argument, prefixed with +"vz\-"\&. This option corresponds to the +\fB\-\-network\-zone=\fR +command line switch\&. This option is privileged (see above)\&. +.sp +Added in version 230\&. +.RE +.PP +\fIPort=\fR +.RS 4 +Exposes a TCP or UDP port of the container on the host\&. This option corresponds to the +\fB\-\-port=\fR +command line switch, see +\fBsystemd-nspawn\fR(1) +for the precise syntax of the argument this option takes\&. This option is privileged (see above)\&. +.sp +Added in version 226\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-nspawn\fR(1), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/systemd.path.5 b/upstream/fedora-40/man5/systemd.path.5 new file mode 100644 index 00000000..9fbc4d47 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.path.5 @@ -0,0 +1,211 @@ +'\" t +.TH "SYSTEMD\&.PATH" "5" "" "systemd 255" "systemd.path" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.path \- Path unit configuration +.SH "SYNOPSIS" +.PP +\fIpath\fR\&.path +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.path" +encodes information about a path monitored by systemd, for path\-based activation\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The path specific configuration options are configured in the [Path] section\&. +.PP +For each path file, a matching unit file must exist, describing the unit to activate when the path changes\&. By default, a service by the same name as the path (except for the suffix) is activated\&. Example: a path file +foo\&.path +activates a matching service +foo\&.service\&. The unit to activate may be controlled by +\fIUnit=\fR +(see below)\&. +.PP +Internally, path units use the +\fBinotify\fR(7) +API to monitor file systems\&. Due to that, it suffers by the same limitations as inotify, and for example cannot be used to monitor files or directories changed by other machines on remote NFS file systems\&. +.PP +When a service unit triggered by a path unit terminates (regardless whether it exited successfully or failed), monitored paths are checked immediately again, and the service accordingly restarted instantly\&. As protection against busy looping in this trigger/start cycle, a start rate limit is enforced on the service unit, see +\fIStartLimitIntervalSec=\fR +and +\fIStartLimitBurst=\fR +in +\fBsystemd.unit\fR(5)\&. Unlike other service failures, the error condition that the start rate limit is hit is propagated from the service unit to the path unit and causes the path unit to fail as well, thus ending the loop\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If a path unit is beneath another mount unit in the file system hierarchy, both a requirement and an ordering dependency between both units are created automatically\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An implicit +\fIBefore=\fR +dependency is added between a path unit and the unit it is supposed to activate\&. +.RE +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Path units will automatically have dependencies of type +\fIBefore=\fR +on +paths\&.target, dependencies of type +\fIAfter=\fR +and +\fIRequires=\fR +on +sysinit\&.target, and have dependencies of type +\fIConflicts=\fR +and +\fIBefore=\fR +on +shutdown\&.target\&. These ensure that path units are terminated cleanly prior to system shutdown\&. Only path units involved with early boot or late system shutdown should disable +\fIDefaultDependencies=\fR +option\&. +.RE +.PP +.SH "OPTIONS" +.PP +Path unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Path unit files must include a [Path] section, which carries information about the path or paths it monitors\&. The options specific to the [Path] section of path units are the following: +.PP +\fIPathExists=\fR, \fIPathExistsGlob=\fR, \fIPathChanged=\fR, \fIPathModified=\fR, \fIDirectoryNotEmpty=\fR +.RS 4 +Defines paths to monitor for certain changes: +\fIPathExists=\fR +may be used to watch the mere existence of a file or directory\&. If the file specified exists, the configured unit is activated\&. +\fIPathExistsGlob=\fR +works similarly, but checks for the existence of at least one file matching the globbing pattern specified\&. +\fIPathChanged=\fR +may be used to watch a file or directory and activate the configured unit whenever it changes\&. It is not activated on every write to the watched file but it is activated if the file which was open for writing gets closed\&. +\fIPathModified=\fR +is similar, but additionally it is activated also on simple writes to the watched file\&. +\fIDirectoryNotEmpty=\fR +may be used to watch a directory and activate the configured unit whenever it contains at least one file\&. +.sp +The arguments of these directives must be absolute file system paths\&. +.sp +Multiple directives may be combined, of the same and of different types, to watch multiple paths\&. If the empty string is assigned to any of these options, the list of paths to watch is reset, and any prior assignments of these options will not have any effect\&. +.sp +If a path already exists (in case of +\fIPathExists=\fR +and +\fIPathExistsGlob=\fR) or a directory already is not empty (in case of +\fIDirectoryNotEmpty=\fR) at the time the path unit is activated, then the configured unit is immediately activated as well\&. Something similar does not apply to +\fIPathChanged=\fR +and +\fIPathModified=\fR\&. +.sp +If the path itself or any of the containing directories are not accessible, +\fBsystemd\fR +will watch for permission changes and notice that conditions are satisfied when permissions allow that\&. +.RE +.PP +\fIUnit=\fR +.RS 4 +The unit to activate when any of the configured paths changes\&. The argument is a unit name, whose suffix is not +"\&.path"\&. If not specified, this value defaults to a service that has the same name as the path unit, except for the suffix\&. (See above\&.) It is recommended that the unit name that is activated and the unit name of the path unit are named identical, except for the suffix\&. +.RE +.PP +\fIMakeDirectory=\fR +.RS 4 +Takes a boolean argument\&. If true, the directories to watch are created before watching\&. This option is ignored for +\fIPathExists=\fR +settings\&. Defaults to +\fBfalse\fR\&. +.RE +.PP +\fIDirectoryMode=\fR +.RS 4 +If +\fIMakeDirectory=\fR +is enabled, use the mode specified here to create the directories in question\&. Takes an access mode in octal notation\&. Defaults to +\fB0755\fR\&. +.RE +.PP +\fITriggerLimitIntervalSec=\fR, \fITriggerLimitBurst=\fR +.RS 4 +Configures a limit on how often this path unit may be activated within a specific time interval\&. The +\fITriggerLimitIntervalSec=\fR +may be used to configure the length of the time interval in the usual time units +"us", +"ms", +"s", +"min", +"h", \&... and defaults to 2s\&. See +\fBsystemd.time\fR(7) +for details on the various time units understood\&. The +\fITriggerLimitBurst=\fR +setting takes a positive integer value and specifies the number of permitted activations per time interval, and defaults to 200\&. Set either to 0 to disable any form of trigger rate limiting\&. If the limit is hit, the unit is placed into a failure mode, and will not watch the paths anymore until restarted\&. Note that this limit is enforced before the service activation is enqueued\&. +.sp +Added in version 250\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +Environment variables with details on the trigger will be set for triggered units\&. See the section +"Environment Variables Set or Propagated by the Service Manager" +in +\fBsystemd.exec\fR(5) +for more details\&. +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.service\fR(5), +\fBinotify\fR(7), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/systemd.pcrlock.5 b/upstream/fedora-40/man5/systemd.pcrlock.5 new file mode 100644 index 00000000..cadc0742 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.pcrlock.5 @@ -0,0 +1,276 @@ +'\" t +.TH "SYSTEMD\&.PCRLOCK" "5" "" "systemd 255" "systemd.pcrlock" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.pcrlock, systemd.pcrlock.d \- PCR measurement prediction files +.SH "SYNOPSIS" +.PP +.nf +/etc/pcrlock\&.d/*\&.pcrlock +/etc/pcrlock\&.d/*\&.pcrlock\&.d/*\&.pcrlock +/run/pcrlock\&.d/*\&.pcrlock +/run/pcrlock\&.d/*\&.pcrlock\&.d/*\&.pcrlock +/var/lib/pcrlock\&.d/*\&.pcrlock +/var/lib/pcrlock\&.d/*\&.pcrlock\&.d/*\&.pcrlock +/usr/local/pcrlock\&.d/*\&.pcrlock +/usr/local/pcrlock\&.d/*\&.pcrlock\&.d/*\&.pcrlock +/usr/lib/pcrlock\&.d/*\&.pcrlock +/usr/lib/pcrlock\&.d/*\&.pcrlock\&.d/*\&.pcrlock +.fi +.SH "DESCRIPTION" +.PP +*\&.pcrlock +files define expected TPM2 PCR measurements of components involved in the boot process\&. +\fBsystemd-pcrlock\fR(1) +uses such pcrlock files to analyze and predict TPM2 PCR measurements\&. The pcrlock files are JSON arrays that follow a subset of the +\m[blue]\fBTCG Common Event Log Format (CEL\-JSON)\fR\m[]\&\s-2\u[1]\d\s+2 +specification\&. Specifically the +"recnum", +"content", and +"content_type" +record fields are not used and ignored if present\&. Each pcrlock file defines one set of expected, ordered PCR measurements of a specific component of the boot\&. +.PP +*\&.pcrlock files may be placed in various +\&.d/ +drop\-in directories (see above for a full list)\&. All matching files discovered in these directories are sorted alphabetically by their file name (without taking the actual directory they were found in into account): pcrlock files with alphabetically earlier names are expected to cover measurements done before those with alphabetically later names\&. In order to make positioning pcrlock files in the boot process convenient the files are expected (by convention, this is not enforced) to be named +"\fINNN\fR\-\fIcomponent\fR\&.pcrlock" +(where +\fINNN\fR +is a three\-digit decimal number), for example +750\-enter\-initrd\&.pcrlock\&. +.PP +For various components of the boot process more than one alternative pcrlock file shall be supported (i\&.e\&. "variants")\&. For example to cover multiple kernels installed in parallel in the access policy, or multiple versions of the boot loader\&. This can be done by placing +*\&.pcrlock\&.d/*\&.pcrlock +in the drop\-in dirs, i\&.e\&. a common directory for a specific component, that contains one or more pcrlock files each covering one +\fIvariant\fR +of the component\&. Example: +650\-kernel\&.pcrlock\&.d/6\&.5\&.5\-200\&.fc38\&.x86_64\&.pcrlock +and +650\-kernel\&.pcrlock\&.d/6\&.5\&.7\-100\&.fc38\&.x86_64\&.pcrlock +.PP +Use +\fBsystemd\-pcrlock list\-components\fR +to list all pcrlock files currently installed\&. +.PP +Use the various +\fBlock\-*\fR +commands of +\fBsystemd\-pcrlock\fR +to automatically generate suitable pcrlock files for various types of resources\&. +.SH "WELL\-KNOWN COMPONENTS" +.PP +Components of the boot process may be defined freely by the administrator or OS vendor\&. The following components are well\-known however, and are defined by systemd\&. The list below is useful for ordering local pcrlock files properly against these components of the boot\&. +.PP +240\-secureboot\-policy\&.pcrlock +.RS 4 +The SecureBoot policy, as recorded to PCR 7\&. May be generated via +\fBsystemd\-pcrlock lock\-secureboot\-policy\fR\&. +.sp +Added in version 255\&. +.RE +.PP +250\-firmware\-code\-early\&.pcrlock +.RS 4 +Firmware code measurements, as recorded to PCR 0 and 2, up to the separator measurement (see +400\-secureboot\-separator\&.pcrlock\&. +below)\&. May be generated via +\fBsystemd\-pcrlock lock\-firmware\-code\fR\&. +.sp +Added in version 255\&. +.RE +.PP +250\-firmware\-config\-early\&.pcrlock +.RS 4 +Firmware configuration measurements, as recorded to PCR 1 and 3, up to the separator measurement (see +400\-secureboot\-separator\&.pcrlock\&. +below)\&. May be generated via +\fBsystemd\-pcrlock lock\-firmware\-config\fR\&. +.sp +Added in version 255\&. +.RE +.PP +350\-action\-efi\-application\&.pcrlock +.RS 4 +The EFI "Application" measurement done once by the firmware\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +400\-secureboot\-separator\&.pcrlock +.RS 4 +The EFI "separator" measurement on PCR 7 done once by the firmware to indicate where firmware control transitions into boot loader/OS control\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +500\-separator\&.pcrlock +.RS 4 +The EFI "separator" measurements on PCRs 0\-6 done once by the firmware to indicate where firmware control transitions into boot loader/OS control\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +550\-firmware\-code\-late\&.pcrlock +.RS 4 +Firmware code measurements, as recorded to PCR 0 and 2, after the separator measurement (see +400\-secureboot\-separator\&.pcrlock\&. +above)\&. May be generated via +\fBsystemd\-pcrlock lock\-firmware\-code\fR\&. +.sp +Added in version 255\&. +.RE +.PP +550\-firmware\-config\-late\&.pcrlock +.RS 4 +Firmware configuration measurements, as recorded to PCR 1 and 3, after the separator measurement (see +400\-secureboot\-separator\&.pcrlock\&. +above)\&. May be generated via +\fBsystemd\-pcrlock lock\-firmware\-config\fR\&. +.sp +Added in version 255\&. +.RE +.PP +600\-gpt\&.pcrlock +.RS 4 +The GPT partition table of the booted medium, as recorded to PCR 5 by the firmware\&. May be generated via +\fBsystemd\-pcrlock lock\-gpt\fR\&. +.sp +Added in version 255\&. +.RE +.PP +620\-secureboot\-authority\&.pcrlock +.RS 4 +The SecureBoot authority, as recorded to PCR 7\&. May be generated via +\fBsystemd\-pcrlock lock\-secureboot\-authority\fR\&. +.sp +Added in version 255\&. +.RE +.PP +700\-action\-efi\-exit\-boot\-services\&.pcrlock +.RS 4 +The EFI action generated when +\fBExitBootServices()\fR +is generated, i\&.e\&. the UEFI environment is left and the OS takes over\&. Covers the PCR 5 measurement\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +710\-kernel\-cmdline\&.pcrlock +.RS 4 +The kernel command line, as measured by the Linux kernel to PCR 9\&. May be generated via +\fBsystemd\-pcrlock lock\-kernel\-cmdline\fR\&. +.sp +Added in version 255\&. +.RE +.PP +720\-kernel\-initrd\&.pcrlock +.RS 4 +The kernel initrd, as measured by the Linux kernel to PCR 9\&. May be generated via +\fBsystemd\-pcrlock lock\-kernel\-initrd\fR\&. +.sp +Added in version 255\&. +.RE +.PP +750\-enter\-initrd\&.pcrlock +.RS 4 +The measurement to PCR 11 +\fBsystemd-pcrphase-initrd.service\fR(8) +makes when the initrd initializes\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +800\-leave\-initrd\&.pcrlock +.RS 4 +The measurement to PCR 11 +\fBsystemd-pcrphase-initrd.service\fR(8) +makes when the initrd finishes\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +820\-machine\-id\&.pcrlock +.RS 4 +The measurement to PCR 15 +\fBsystemd-pcrmachine.service\fR(8) +makes at boot, covering +/etc/machine\-id +contents\&. May be generated via +\fBsystemd\-pcrlock lock\-machine\-id\fR\&. +.sp +Added in version 255\&. +.RE +.PP +830\-root\-file\-system\&.pcrlock +.RS 4 +The measurement to PCR 15 +\fBsystemd-pcrfs-root.service\fR(8) +makes at boot, covering the root file system identity\&. May be generated via +\fBsystemd\-pcrlock lock\-file\-system\fR\&. +.sp +Added in version 255\&. +.RE +.PP +850\-sysinit\&.pcrlock +.RS 4 +The measurement to PCR 11 +\fBsystemd-pcrphase-sysinit.service\fR(8) +makes when the main userspace did basic initialization and will now proceed to start regular system services\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +900\-ready\&.pcrlock +.RS 4 +The measurement to PCR 11 +\fBsystemd-pcrphase.service\fR(8) +makes when the system fully booted up\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +950\-shutdown\&.pcrlock +.RS 4 +The measurement to PCR 11 +\fBsystemd-pcrphase.service\fR(8) +makes when the system begins shutdown\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.PP +990\-final\&.pcrlock +.RS 4 +The measurement to PCR 11 +\fBsystemd-pcrphase-sysinit.service\fR(8) +makes when the system is close to finishing shutdown\&. Statically defined\&. +.sp +Added in version 255\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-pcrlock\fR(1) +.SH "NOTES" +.IP " 1." 4 +TCG Common Event Log Format (CEL-JSON) +.RS 4 +\%https://trustedcomputinggroup.org/resource/canonical-event-log-format/ +.RE diff --git a/upstream/fedora-40/man5/systemd.preset.5 b/upstream/fedora-40/man5/systemd.preset.5 new file mode 100644 index 00000000..945e0d62 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.preset.5 @@ -0,0 +1,220 @@ +'\" t +.TH "SYSTEMD\&.PRESET" "5" "" "systemd 255" "systemd.preset" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.preset \- Service enablement presets +.SH "SYNOPSIS" +.PP +/etc/systemd/system\-preset/*\&.preset +.PP +/run/systemd/system\-preset/*\&.preset +.PP +/usr/lib/systemd/system\-preset/*\&.preset +.PP +/etc/systemd/user\-preset/*\&.preset +.PP +/run/systemd/user\-preset/*\&.preset +.PP +/usr/lib/systemd/user\-preset/*\&.preset +.SH "DESCRIPTION" +.PP +Preset files may be used to encode policy which units shall be enabled by default and which ones shall be disabled\&. They are read by +\fBsystemctl preset\fR +which uses this information to enable or disable a unit\&. Depending on that policy, +\fBsystemctl preset\fR +is identical to +\fBsystemctl enable\fR +or +\fBsystemctl disable\fR\&. +\fBsystemctl preset\fR +is used by the post install scriptlets of rpm packages (or other OS package formats), to enable/disable specific units by default on package installation, enforcing distribution, spin or administrator preset policy\&. This allows choosing a certain set of units to be enabled/disabled even before installing the actual package\&. For more information, see +\fBsystemctl\fR(1)\&. +.PP +It is not recommended to ship preset files within the respective software packages implementing the units, but rather centralize them in a distribution or spin default policy, which can be amended by administrator policy, see below\&. +.PP +If no preset files exist, preset operations will enable all units that are installed by default\&. If this is not desired and all units shall rather be disabled, it is necessary to ship a preset file with a single, catchall "disable *" line\&. (See example 1, below\&.) +.PP +When the machine is booted for the first time, +\fBsystemd\fR(1) +will enable/disable all units according to preset policy, similarly to +\fBsystemctl preset\-all\fR\&. Also see "First Boot Semantics" in +\fBmachine-id\fR(5)\&. +.SH "PRESET FILE FORMAT" +.PP +The preset files contain a list of directives, one per line\&. Empty lines and lines whose first non\-whitespace character is +"#" +or +";" +are ignored\&. Each directive consists of one of the words +"enable", +"disable", or +"ignore", followed by whitespace and a unit name\&. The unit name may contain shell\-style wildcards\&. +.PP +For the enable directive for template units, one or more instance names may be specified as a space\-separated list after the unit name\&. In this case, those instances will be enabled instead of the instance specified via DefaultInstance= in the unit\&. +.PP +Presets must refer to the "real" unit file, and not to any aliases\&. See +\fBsystemd.unit\fR(5) +for a description of unit aliasing\&. +.PP +Three different directives are understood: +"enable" +may be used to enable units by default, +"disable" +to disable units by default, and +"ignore" +to ignore units and leave existing configuration intact\&. +.PP +If multiple lines apply to a unit name, the first matching one takes precedence over all others\&. +.PP +Each preset file shall be named in the style of +\-\&.preset\&. Files in +/etc/ +override files with the same name in +/usr/lib/ +and +/run/\&. Files in +/run/ +override files with the same name in +/usr/lib/\&. Packages should install their preset files in +/usr/lib/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the preset files installed by vendor packages\&. All preset files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same unit name, the entry in the file with the lexicographically earliest name will be applied\&. It is recommended to prefix all filenames with a two\-digit number and a dash, to simplify the ordering of the files\&. +.PP +If the administrator wants to disable a preset file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in +/etc/systemd/system\-preset/ +bearing the same filename\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Default to off\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/systemd/system\-preset/99\-default\&.preset + +disable * +.fi +.if n \{\ +.RE +.\} +.PP +This disables all units\&. Due to the filename prefix +"99\-", it will be read last and hence can easily be overridden by spin or administrator preset policy\&. +.PP +\fBExample\ \&2.\ \&Enable multiple template instances\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/systemd/system\-preset/80\-dirsrv\&.preset + +enable dirsrv@\&.service foo bar baz +.fi +.if n \{\ +.RE +.\} +.PP +This enables all three of +dirsrv@foo\&.service, +dirsrv@bar\&.service +and +dirsrv@baz\&.service\&. +.PP +\fBExample\ \&3.\ \&A GNOME spin\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/systemd/system\-preset/50\-gnome\&.preset + +enable gdm\&.service +enable colord\&.service +enable accounts\-daemon\&.service +enable avahi\-daemon\&.* +.fi +.if n \{\ +.RE +.\} +.PP +This enables the three mentioned units, plus all +avahi\-daemon +regardless of which unit type\&. A file like this could be useful for inclusion in a GNOME spin of a distribution\&. It will ensure that the units necessary for GNOME are properly enabled as they are installed\&. It leaves all other units untouched, and subject to other (later) preset files, for example like the one from the first example above\&. +.PP +\fBExample\ \&4.\ \&Administrator policy\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /etc/systemd/system\-preset/00\-lennart\&.preset + +enable httpd\&.service +enable sshd\&.service +enable postfix\&.service +disable * +.fi +.if n \{\ +.RE +.\} +.PP +This enables three specific services and disables all others\&. This is useful for administrators to specifically select the units to enable, and disable all others\&. Due to the filename prefix +"00\-" +it will be read early and override all other preset policy files\&. +.SH "MOTIVATION FOR THE PRESET LOGIC" +.PP +Different distributions have different policies on which services shall be enabled by default when the package they are shipped in is installed\&. On Fedora all services stay off by default, so that installing a package will not cause a service to be enabled (with some exceptions)\&. On Debian all services are immediately enabled by default, so that installing a package will cause its services to be enabled right\-away\&. +.PP +Even within a single distribution, different spins (flavours, remixes, whatever you might want to call them) of a distribution also have different policies on what services to enable, and what services to leave off\&. For example, Fedora Workstation will enable +\fBgdm\fR +as display manager by default, while the Fedora KDE spin will enable +\fBsddm\fR +instead\&. +.PP +Different sites might also have different policies what to turn on by default and what to turn off\&. For example, one administrator would prefer to enforce the policy of "\fBsshd\fR +should be always on, but everything else off", while another one might say "\fBsnmpd\fR +always on, and for everything else use the distribution policy defaults"\&. +.PP +Traditionally, policy about which services shall be enabled were implemented in each package individually\&. This made it cumbersome to implement different policies per spin or per site, or to create software packages that do the right thing on more than one distribution\&. The enablement mechanism was also encoding the enablement policy\&. +.PP +The preset mechanism allows clean separation of the enablement mechanism (inside the package scriptlets, by invoking +\fBsystemctl preset\fR) and enablement policy (centralized in the preset files), and lifts the configuration out of individual packages\&. Preset files may be written for specific distributions, for specific spins or for specific sites, in order to enforce different policies as needed\&. It is recommended to apply the policy encoded in preset files in package installation scriptlets\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-delta\fR(1) +.PP +\fBdaemon\fR(7) +has a discussion of packaging scriptlets\&. +.PP +Fedora page introducing the use of presets: +\m[blue]\fBFeatures/PackagePresets\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "NOTES" +.IP " 1." 4 +Features/PackagePresets +.RS 4 +\%https://fedoraproject.org/wiki/Features/PackagePresets +.RE diff --git a/upstream/fedora-40/man5/systemd.resource-control.5 b/upstream/fedora-40/man5/systemd.resource-control.5 new file mode 100644 index 00000000..3e1a9ae0 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.resource-control.5 @@ -0,0 +1,1826 @@ +'\" t +.TH "SYSTEMD\&.RESOURCE\-CONTROL" "5" "" "systemd 255" "systemd.resource-control" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.resource-control \- Resource control unit settings +.SH "SYNOPSIS" +.PP +\fIslice\fR\&.slice, +\fIscope\fR\&.scope, +\fIservice\fR\&.service, +\fIsocket\fR\&.socket, +\fImount\fR\&.mount, +\fIswap\fR\&.swap +.SH "DESCRIPTION" +.PP +Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset of configuration options for resource control of spawned processes\&. Internally, this relies on the Linux Control Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of resource management\&. +.PP +This man page lists the configuration options shared by those six unit types\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files, and +\fBsystemd.slice\fR(5), +\fBsystemd.scope\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.mount\fR(5), and +\fBsystemd.swap\fR(5) +for more information on the specific unit configuration files\&. The resource control configuration options are configured in the [Slice], [Scope], [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type\&. +.PP +In addition, options which control resources available to programs +\fIexecuted\fR +by systemd are listed in +\fBsystemd.exec\fR(5)\&. Those options complement options listed here\&. +.SS "Enabling and disabling controllers" +.PP +Controllers in the cgroup hierarchy are hierarchical, and resource control is realized by distributing resource assignments between siblings in branches of the cgroup hierarchy\&. There is no need to explicitly +\fIenable\fR +a cgroup controller for a unit\&. +\fBsystemd\fR +will instruct the kernel to enable a controller for a given unit when this unit has configuration for a given controller\&. For example, when +\fICPUWeight=\fR +is set, the +\fBcpu\fR +controller will be enabled, and when +\fITasksMax=\fR +are set, the +\fBpids\fR +controller will be enabled\&. In addition, various controllers may be also be enabled explicitly via the +\fIMemoryAccounting=\fR/\fITasksAccounting=\fR/\fIIOAccounting=\fR +settings\&. Because of how the cgroup hierarchy works, controllers will be automatically enabled for all parent units and for any sibling units starting with the lowest level at which a controller is enabled\&. Units for which a controller is enabled may be subject to resource control even if they don\*(Aqt have any explicit configuration\&. +.PP +Setting +\fIDelegate=\fR +enables any delegated controllers for that unit (see below)\&. The delegatee may then enable controllers for its children as appropriate\&. In particular, if the delegatee is +\fBsystemd\fR +(in the +user@\&.service +unit), it will repeat the same logic as the system instance and enable controllers for user units which have resource limits configured, and their siblings and parents and parents\*(Aq siblings\&. +.PP +Controllers may be +\fIdisabled\fR +for parts of the cgroup hierarchy with +\fIDisableControllers=\fR +(see below)\&. +.PP +\fBExample\ \&1.\ \&Enabling and disabling controllers\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf + \-\&.slice + / \e + /\-\-\-\-\-/ \e\-\-\-\-\-\-\-\-\-\-\-\-\-\-\e + / \e + system\&.slice user\&.slice + / \e / \e + / \e / \e + / \e user@42\&.service user@1000\&.service + / \e Delegate= Delegate=yes +a\&.service b\&.slice / \e +CPUWeight=20 DisableControllers=cpu / \e + / \e app\&.slice session\&.slice + / \e CPUWeight=100 CPUWeight=100 + / \e + b1\&.service b2\&.service + CPUWeight=1000 + +.fi +.if n \{\ +.RE +.\} +.PP +In this hierarchy, the +\fBcpu\fR +controller is enabled for all units shown except +b1\&.service +and +b2\&.service\&. Because there is no explicit configuration for +system\&.slice +and +user\&.slice, CPU resources will be split equally between them\&. Similarly, resources are allocated equally between children of +user\&.slice +and between the child slices beneath +user@1000\&.service\&. Assuming that there is no further configuration of resources or delegation below slices +app\&.slice +or +session\&.slice, the +\fBcpu\fR +controller would not be enabled for units in those slices and CPU resources would be further allocated using other mechanisms, e\&.g\&. based on nice levels\&. The manager for user 42 has delegation enabled without any controllers, i\&.e\&. it can manipulate its subtree of the cgroup hierarchy, but without resource control\&. +.PP +In the slice +system\&.slice, CPU resources are split 1:6 for service +a\&.service, and 5:6 for slice +b\&.slice, because slice +b\&.slice +gets the default value of 100 for +cpu\&.weight +when +\fICPUWeight=\fR +is not set\&. +.PP +\fICPUWeight=\fR +setting in service +b2\&.service +is neutralized by +\fIDisableControllers=\fR +in slice +b\&.slice, so the +\fBcpu\fR +controller would not be enabled for services +b1\&.service +and +b2\&.service, and CPU resources would be further allocated using other mechanisms, e\&.g\&. based on nice levels\&. +.SS "Setting resource controls for a group of related units" +.PP +As described in +\fBsystemd.unit\fR(5), the settings listed here may be set through the main file of a unit and drop\-in snippets in +*\&.d/ +directories\&. The list of directories searched for drop\-ins includes names formed by repeatedly truncating the unit name after all dashes\&. This is particularly convenient to set resource limits for a group of units with similar names\&. +.PP +For example, every user gets their own slice +user\-\fInnn\fR\&.slice\&. Drop\-ins with local configuration that affect user 1000 may be placed in +/etc/systemd/system/user\-1000\&.slice, +/etc/systemd/system/user\-1000\&.slice\&.d/*\&.conf, but also +/etc/systemd/system/user\-\&.slice\&.d/*\&.conf\&. This last directory applies to all user slices\&. +.PP +See the +\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2 +for an introduction on how to make use of resource control APIs from programs\&. +.SH "IMPLICIT DEPENDENCIES" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Units with the +\fISlice=\fR +setting set automatically acquire +\fIRequires=\fR +and +\fIAfter=\fR +dependencies on the specified slice unit\&. +.RE +.SH "OPTIONS" +.PP +Units of the types listed above can have settings for resource control configuration: +.SS "CPU Accounting and Control" +.PP +\fICPUAccounting=\fR +.RS 4 +Turn on CPU usage accounting for this unit\&. Takes a boolean argument\&. Note that turning on CPU accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein\&. The system default for this setting may be controlled with +\fIDefaultCPUAccounting=\fR +in +\fBsystemd-system.conf\fR(5)\&. +.sp +Under the unified cgroup hierarchy, CPU accounting is available for all units and this setting has no effect\&. +.sp +Added in version 208\&. +.RE +.PP +\fICPUWeight=\fR\fI\fIweight\fR\fR, \fIStartupCPUWeight=\fR\fI\fIweight\fR\fR +.RS 4 +These settings control the +\fBcpu\fR +controller in the unified hierarchy\&. +.sp +These options accept an integer value or a the special string "idle": +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to an integer value, assign the specified CPU time weight to the processes executed, if the unified control group hierarchy is used on the system\&. These options control the +"cpu\&.weight" +control group attribute\&. The allowed range is 1 to 10000\&. Defaults to unset, but the kernel default is 100\&. For details about this control group attribute, see +\m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[2]\d\s+2 +and +\m[blue]\fBCFS Scheduler\fR\m[]\&\s-2\u[3]\d\s+2\&. The available CPU time is split up among all units within one slice relative to their CPU time weight\&. A higher weight means more CPU time, a lower weight means less\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to the special string "idle", mark the cgroup for "idle scheduling", which means that it will get CPU resources only when there are no processes not marked in this way to execute in this cgroup or its siblings\&. This setting corresponds to the +"cpu\&.idle" +cgroup attribute\&. +.sp +Note that this value only has an effect on cgroup\-v2, for cgroup\-v1 it is equivalent to the minimum weight\&. +.RE +.sp +While +\fIStartupCPUWeight=\fR +applies to the startup and shutdown phases of the system, +\fICPUWeight=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupCPUWeight=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +In addition to the resource allocation performed by the +\fBcpu\fR +controller, the kernel may automatically divide resources based on session\-id grouping, see "The autogroup feature" in +\fBsched\fR(7)\&. The effect of this feature is similar to the +\fBcpu\fR +controller with no explicit configuration, so users should be careful to not mistake one for the other\&. +.sp +Added in version 232\&. +.RE +.PP +\fICPUQuota=\fR +.RS 4 +This setting controls the +\fBcpu\fR +controller in the unified hierarchy\&. +.sp +Assign the specified CPU time quota to the processes executed\&. Takes a percentage value, suffixed with "%"\&. The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time available on one CPU\&. Use values > 100% for allotting CPU time on more than one CPU\&. This controls the +"cpu\&.max" +attribute on the unified control group hierarchy and +"cpu\&.cfs_quota_us" +on legacy\&. For details about these control group attributes, see +\m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[2]\d\s+2 +and +\m[blue]\fBCFS Bandwidth Control\fR\m[]\&\s-2\u[4]\d\s+2\&. Setting +\fICPUQuota=\fR +to an empty value unsets the quota\&. +.sp +Example: +\fICPUQuota=20%\fR +ensures that the executed processes will never get more than 20% CPU time on one CPU\&. +.sp +Added in version 213\&. +.RE +.PP +\fICPUQuotaPeriodSec=\fR +.RS 4 +This setting controls the +\fBcpu\fR +controller in the unified hierarchy\&. +.sp +Assign the duration over which the CPU time quota specified by +\fICPUQuota=\fR +is measured\&. Takes a time duration value in seconds, with an optional suffix such as "ms" for milliseconds (or "s" for seconds\&.) The default setting is 100ms\&. The period is clamped to the range supported by the kernel, which is [1ms, 1000ms]\&. Additionally, the period is adjusted up so that the quota interval is also at least 1ms\&. Setting +\fICPUQuotaPeriodSec=\fR +to an empty value resets it to the default\&. +.sp +This controls the second field of +"cpu\&.max" +attribute on the unified control group hierarchy and +"cpu\&.cfs_period_us" +on legacy\&. For details about these control group attributes, see +\m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[2]\d\s+2 +and +\m[blue]\fBCFS Scheduler\fR\m[]\&\s-2\u[3]\d\s+2\&. +.sp +Example: +\fICPUQuotaPeriodSec=10ms\fR +to request that the CPU quota is measured in periods of 10ms\&. +.sp +Added in version 242\&. +.RE +.PP +\fIAllowedCPUs=\fR, \fIStartupAllowedCPUs=\fR +.RS 4 +This setting controls the +\fBcpuset\fR +controller in the unified hierarchy\&. +.sp +Restrict processes to be executed on specific CPUs\&. Takes a list of CPU indices or ranges separated by either whitespace or commas\&. CPU ranges are specified by the lower and upper CPU indices separated by a dash\&. +.sp +Setting +\fIAllowedCPUs=\fR +or +\fIStartupAllowedCPUs=\fR +doesn\*(Aqt guarantee that all of the CPUs will be used by the processes as it may be limited by parent units\&. The effective configuration is reported as +\fIEffectiveCPUs=\fR\&. +.sp +While +\fIStartupAllowedCPUs=\fR +applies to the startup and shutdown phases of the system, +\fIAllowedCPUs=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupAllowedCPUs=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +This setting is supported only with the unified control group hierarchy\&. +.sp +Added in version 244\&. +.RE +.SS "Memory Accounting and Control" +.PP +\fIMemoryAccounting=\fR +.RS 4 +This setting controls the +\fBmemory\fR +controller in the unified hierarchy\&. +.sp +Turn on process and kernel memory accounting for this unit\&. Takes a boolean argument\&. Note that turning on memory accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein\&. The system default for this setting may be controlled with +\fIDefaultMemoryAccounting=\fR +in +\fBsystemd-system.conf\fR(5)\&. +.sp +Added in version 208\&. +.RE +.PP +\fIMemoryMin=\fR\fI\fIbytes\fR\fR, \fIMemoryLow=\fR\fI\fIbytes\fR\fR, \fIStartupMemoryLow=\fR\fI\fIbytes\fR\fR, \fIDefaultStartupMemoryLow=\fR\fI\fIbytes\fR\fR +.RS 4 +These settings control the +\fBmemory\fR +controller in the unified hierarchy\&. +.sp +Specify the memory usage protection of the executed processes in this unit\&. When reclaiming memory, the unit is treated as if it was using less memory resulting in memory to be preferentially reclaimed from unprotected units\&. Using +\fIMemoryLow=\fR +results in a weaker protection where memory may still be reclaimed to avoid invoking the OOM killer in case there is no other reclaimable memory\&. +.sp +For a protection to be effective, it is generally required to set a corresponding allocation on all ancestors, which is then distributed between children (with the exception of the root slice)\&. Any +\fIMemoryMin=\fR +or +\fIMemoryLow=\fR +allocation that is not explicitly distributed to specific children is used to create a shared protection for all children\&. As this is a shared protection, the children will freely compete for the memory\&. +.sp +Takes a memory size in bytes\&. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively\&. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system\&. If assigned the special value +"infinity", all available memory is protected, which may be useful in order to always inherit all of the protection afforded by ancestors\&. This controls the +"memory\&.min" +or +"memory\&.low" +control group attribute\&. For details about this control group attribute, see +\m[blue]\fBMemory Interface Files\fR\m[]\&\s-2\u[5]\d\s+2\&. +.sp +Units may have their children use a default +"memory\&.min" +or +"memory\&.low" +value by specifying +\fIDefaultMemoryMin=\fR +or +\fIDefaultMemoryLow=\fR, which has the same semantics as +\fIMemoryMin=\fR +and +\fIMemoryLow=\fR, or +\fIDefaultStartupMemoryLow=\fR +which has the same semantics as +\fIStartupMemoryLow=\fR\&. This setting does not affect +"memory\&.min" +or +"memory\&.low" +in the unit itself\&. Using it to set a default child allocation is only useful on kernels older than 5\&.7, which do not support the +"memory_recursiveprot" +cgroup2 mount option\&. +.sp +While +\fIStartupMemoryLow=\fR +applies to the startup and shutdown phases of the system, +\fIMemoryMin=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupMemoryLow=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +Added in version 240\&. +.RE +.PP +\fIMemoryHigh=\fR\fI\fIbytes\fR\fR, \fIStartupMemoryHigh=\fR\fI\fIbytes\fR\fR +.RS 4 +These settings control the +\fBmemory\fR +controller in the unified hierarchy\&. +.sp +Specify the throttling limit on memory usage of the executed processes in this unit\&. Memory usage may go above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away aggressively in such cases\&. This is the main mechanism to control memory usage of a unit\&. +.sp +Takes a memory size in bytes\&. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively\&. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system\&. If assigned the special value +"infinity", no memory throttling is applied\&. This controls the +"memory\&.high" +control group attribute\&. For details about this control group attribute, see +\m[blue]\fBMemory Interface Files\fR\m[]\&\s-2\u[5]\d\s+2\&. +.sp +While +\fIStartupMemoryHigh=\fR +applies to the startup and shutdown phases of the system, +\fIMemoryHigh=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupMemoryHigh=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +Added in version 231\&. +.RE +.PP +\fIMemoryMax=\fR\fI\fIbytes\fR\fR, \fIStartupMemoryMax=\fR\fI\fIbytes\fR\fR +.RS 4 +These settings control the +\fBmemory\fR +controller in the unified hierarchy\&. +.sp +Specify the absolute limit on memory usage of the executed processes in this unit\&. If memory usage cannot be contained under the limit, out\-of\-memory killer is invoked inside the unit\&. It is recommended to use +\fIMemoryHigh=\fR +as the main control mechanism and use +\fIMemoryMax=\fR +as the last line of defense\&. +.sp +Takes a memory size in bytes\&. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively\&. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system\&. If assigned the special value +"infinity", no memory limit is applied\&. This controls the +"memory\&.max" +control group attribute\&. For details about this control group attribute, see +\m[blue]\fBMemory Interface Files\fR\m[]\&\s-2\u[5]\d\s+2\&. +.sp +While +\fIStartupMemoryMax=\fR +applies to the startup and shutdown phases of the system, +\fIMemoryMax=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupMemoryMax=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +Added in version 231\&. +.RE +.PP +\fIMemorySwapMax=\fR\fI\fIbytes\fR\fR, \fIStartupMemorySwapMax=\fR\fI\fIbytes\fR\fR +.RS 4 +These settings control the +\fBmemory\fR +controller in the unified hierarchy\&. +.sp +Specify the absolute limit on swap usage of the executed processes in this unit\&. +.sp +Takes a swap size in bytes\&. If the value is suffixed with K, M, G or T, the specified swap size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively\&. If assigned the special value +"infinity", no swap limit is applied\&. These settings control the +"memory\&.swap\&.max" +control group attribute\&. For details about this control group attribute, see +\m[blue]\fBMemory Interface Files\fR\m[]\&\s-2\u[5]\d\s+2\&. +.sp +While +\fIStartupMemorySwapMax=\fR +applies to the startup and shutdown phases of the system, +\fIMemorySwapMax=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupMemorySwapMax=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +Added in version 232\&. +.RE +.PP +\fIMemoryZSwapMax=\fR\fI\fIbytes\fR\fR, \fIStartupMemoryZSwapMax=\fR\fI\fIbytes\fR\fR +.RS 4 +These settings control the +\fBmemory\fR +controller in the unified hierarchy\&. +.sp +Specify the absolute limit on zswap usage of the processes in this unit\&. Zswap is a lightweight compressed cache for swap pages\&. It takes pages that are in the process of being swapped out and attempts to compress them into a dynamically allocated RAM\-based memory pool\&. If the limit specified is hit, no entries from this unit will be stored in the pool until existing entries are faulted back or written out to disk\&. See the kernel\*(Aqs +\m[blue]\fBZswap\fR\m[]\&\s-2\u[6]\d\s+2 +documentation for more details\&. +.sp +Takes a size in bytes\&. If the value is suffixed with K, M, G or T, the specified size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively\&. If assigned the special value +"infinity", no limit is applied\&. These settings control the +"memory\&.zswap\&.max" +control group attribute\&. For details about this control group attribute, see +\m[blue]\fBMemory Interface Files\fR\m[]\&\s-2\u[5]\d\s+2\&. +.sp +While +\fIStartupMemoryZSwapMax=\fR +applies to the startup and shutdown phases of the system, +\fIMemoryZSwapMax=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupMemoryZSwapMax=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +Added in version 253\&. +.RE +.PP +\fIAllowedMemoryNodes=\fR, \fIStartupAllowedMemoryNodes=\fR +.RS 4 +These settings control the +\fBcpuset\fR +controller in the unified hierarchy\&. +.sp +Restrict processes to be executed on specific memory NUMA nodes\&. Takes a list of memory NUMA nodes indices or ranges separated by either whitespace or commas\&. Memory NUMA nodes ranges are specified by the lower and upper NUMA nodes indices separated by a dash\&. +.sp +Setting +\fIAllowedMemoryNodes=\fR +or +\fIStartupAllowedMemoryNodes=\fR +doesn\*(Aqt guarantee that all of the memory NUMA nodes will be used by the processes as it may be limited by parent units\&. The effective configuration is reported as +\fIEffectiveMemoryNodes=\fR\&. +.sp +While +\fIStartupAllowedMemoryNodes=\fR +applies to the startup and shutdown phases of the system, +\fIAllowedMemoryNodes=\fR +applies to normal runtime of the system, and if the former is not set also to the startup and shutdown phases\&. Using +\fIStartupAllowedMemoryNodes=\fR +allows prioritizing specific services at boot\-up and shutdown differently than during normal runtime\&. +.sp +This setting is supported only with the unified control group hierarchy\&. +.sp +Added in version 244\&. +.RE +.SS "Process Accounting and Control" +.PP +\fITasksAccounting=\fR +.RS 4 +This setting controls the +\fBpids\fR +controller in the unified hierarchy\&. +.sp +Turn on task accounting for this unit\&. Takes a boolean argument\&. If enabled, the kernel will keep track of the total number of tasks in the unit and its children\&. This number includes both kernel threads and userspace processes, with each thread counted individually\&. Note that turning on tasks accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein\&. The system default for this setting may be controlled with +\fIDefaultTasksAccounting=\fR +in +\fBsystemd-system.conf\fR(5)\&. +.sp +Added in version 227\&. +.RE +.PP +\fITasksMax=\fR\fI\fIN\fR\fR +.RS 4 +This setting controls the +\fBpids\fR +controller in the unified hierarchy\&. +.sp +Specify the maximum number of tasks that may be created in the unit\&. This ensures that the number of tasks accounted for the unit (see above) stays below a specific limit\&. This either takes an absolute number of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the system\&. If assigned the special value +"infinity", no tasks limit is applied\&. This controls the +"pids\&.max" +control group attribute\&. For details about this control group attribute, the +\m[blue]\fBpids controller\fR\m[]\&\s-2\u[7]\d\s+2\&. +.sp +The system default for this setting may be controlled with +\fIDefaultTasksMax=\fR +in +\fBsystemd-system.conf\fR(5)\&. +.sp +Added in version 227\&. +.RE +.SS "IO Accounting and Control" +.PP +\fIIOAccounting=\fR +.RS 4 +This setting controls the +\fBio\fR +controller in the unified hierarchy\&. +.sp +Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the system\&. Takes a boolean argument\&. Note that turning on block I/O accounting for one unit will also implicitly turn it on for all units contained in the same slice and all for its parent slices and the units contained therein\&. The system default for this setting may be controlled with +\fIDefaultIOAccounting=\fR +in +\fBsystemd-system.conf\fR(5)\&. +.sp +Added in version 230\&. +.RE +.PP +\fIIOWeight=\fR\fI\fIweight\fR\fR, \fIStartupIOWeight=\fR\fI\fIweight\fR\fR +.RS 4 +These settings control the +\fBio\fR +controller in the unified hierarchy\&. +.sp +Set the default overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system\&. Takes a single weight value (between 1 and 10000) to set the default block I/O weight\&. This controls the +"io\&.weight" +control group attribute, which defaults to 100\&. For details about this control group attribute, see +\m[blue]\fBIO Interface Files\fR\m[]\&\s-2\u[8]\d\s+2\&. The available I/O bandwidth is split up among all units within one slice relative to their block I/O weight\&. A higher weight means more I/O bandwidth, a lower weight means less\&. +.sp +While +\fIStartupIOWeight=\fR +applies to the startup and shutdown phases of the system, +\fIIOWeight=\fR +applies to the later runtime of the system, and if the former is not set also to the startup and shutdown phases\&. This allows prioritizing specific services at boot\-up and shutdown differently than during runtime\&. +.sp +Added in version 230\&. +.RE +.PP +\fIIODeviceWeight=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIweight\fR\fR +.RS 4 +This setting controls the +\fBio\fR +controller in the unified hierarchy\&. +.sp +Set the per\-device overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system\&. Takes a space\-separated pair of a file path and a weight value to specify the device specific weight value, between 1 and 10000\&. (Example: +"/dev/sda 1000")\&. The file path may be specified as path to a block device node or as any other file, in which case the backing block device of the file system of the file is determined\&. This controls the +"io\&.weight" +control group attribute, which defaults to 100\&. Use this option multiple times to set weights for multiple devices\&. For details about this control group attribute, see +\m[blue]\fBIO Interface Files\fR\m[]\&\s-2\u[8]\d\s+2\&. +.sp +The specified device node should reference a block device that has an I/O scheduler associated, i\&.e\&. should not refer to partition or loopback block devices, but to the originating, physical device\&. When a path to a regular file or directory is specified it is attempted to discover the correct originating device backing the file system of the specified path\&. This works correctly only for simpler cases, where the file system is directly placed on a partition or physical block device, or where simple 1:1 encryption using dm\-crypt/LUKS is used\&. This discovery does not cover complex storage and in particular RAID and volume management storage devices\&. +.sp +Added in version 230\&. +.RE +.PP +\fIIOReadBandwidthMax=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIbytes\fR\fR, \fIIOWriteBandwidthMax=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIbytes\fR\fR +.RS 4 +These settings control the +\fBio\fR +controller in the unified hierarchy\&. +.sp +Set the per\-device overall block I/O bandwidth maximum limit for the executed processes, if the unified control group hierarchy is used on the system\&. This limit is not work\-conserving and the executed processes are not allowed to use more even if the device has idle capacity\&. Takes a space\-separated pair of a file path and a bandwidth value (in bytes per second) to specify the device specific bandwidth\&. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used\&. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000\&. (Example: "/dev/disk/by\-path/pci\-0000:00:1f\&.2\-scsi\-0:0:0:0 5M")\&. This controls the +"io\&.max" +control group attributes\&. Use this option multiple times to set bandwidth limits for multiple devices\&. For details about this control group attribute, see +\m[blue]\fBIO Interface Files\fR\m[]\&\s-2\u[8]\d\s+2\&. +.sp +Similar restrictions on block device discovery as for +\fIIODeviceWeight=\fR +apply, see above\&. +.sp +Added in version 230\&. +.RE +.PP +\fIIOReadIOPSMax=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIIOPS\fR\fR, \fIIOWriteIOPSMax=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIIOPS\fR\fR +.RS 4 +These settings control the +\fBio\fR +controller in the unified hierarchy\&. +.sp +Set the per\-device overall block I/O IOs\-Per\-Second maximum limit for the executed processes, if the unified control group hierarchy is used on the system\&. This limit is not work\-conserving and the executed processes are not allowed to use more even if the device has idle capacity\&. Takes a space\-separated pair of a file path and an IOPS value to specify the device specific IOPS\&. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used\&. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, GigaIOPS, or TeraIOPS, respectively, to the base of 1000\&. (Example: "/dev/disk/by\-path/pci\-0000:00:1f\&.2\-scsi\-0:0:0:0 1K")\&. This controls the +"io\&.max" +control group attributes\&. Use this option multiple times to set IOPS limits for multiple devices\&. For details about this control group attribute, see +\m[blue]\fBIO Interface Files\fR\m[]\&\s-2\u[8]\d\s+2\&. +.sp +Similar restrictions on block device discovery as for +\fIIODeviceWeight=\fR +apply, see above\&. +.sp +Added in version 230\&. +.RE +.PP +\fIIODeviceLatencyTargetSec=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fItarget\fR\fR +.RS 4 +This setting controls the +\fBio\fR +controller in the unified hierarchy\&. +.sp +Set the per\-device average target I/O latency for the executed processes, if the unified control group hierarchy is used on the system\&. Takes a file path and a timespan separated by a space to specify the device specific latency target\&. (Example: "/dev/sda 25ms")\&. The file path may be specified as path to a block device node or as any other file, in which case the backing block device of the file system of the file is determined\&. This controls the +"io\&.latency" +control group attribute\&. Use this option multiple times to set latency target for multiple devices\&. For details about this control group attribute, see +\m[blue]\fBIO Interface Files\fR\m[]\&\s-2\u[8]\d\s+2\&. +.sp +Implies +"IOAccounting=yes"\&. +.sp +These settings are supported only if the unified control group hierarchy is used\&. +.sp +Similar restrictions on block device discovery as for +\fIIODeviceWeight=\fR +apply, see above\&. +.sp +Added in version 240\&. +.RE +.SS "Network Accounting and Control" +.PP +\fIIPAccounting=\fR +.RS 4 +Takes a boolean argument\&. If true, turns on IPv4 and IPv6 network traffic accounting for packets sent or received by the unit\&. When this option is turned on, all IPv4 and IPv6 sockets created by any process of the unit are accounted for\&. +.sp +When this option is used in socket units, it applies to all IPv4 and IPv6 sockets associated with it (including both listening and connection sockets where this applies)\&. Note that for socket\-activated services, this configuration setting and the accounting data of the service unit and the socket unit are kept separate, and displayed separately\&. No propagation of the setting and the collected statistics is done, in either direction\&. Moreover, any traffic sent or received on any of the socket unit\*(Aqs sockets is accounted to the socket unit \(em and never to the service unit it might have activated, even if the socket is used by it\&. +.sp +The system default for this setting may be controlled with +\fIDefaultIPAccounting=\fR +in +\fBsystemd-system.conf\fR(5)\&. +.sp +Added in version 235\&. +.RE +.PP +\fIIPAddressAllow=\fR\fI\fIADDRESS[/PREFIXLENGTH]\&...\fR\fR, \fIIPAddressDeny=\fR\fI\fIADDRESS[/PREFIXLENGTH]\&...\fR\fR +.RS 4 +Turn on network traffic filtering for IP packets sent and received over +\fBAF_INET\fR +and +\fBAF_INET6\fR +sockets\&. Both directives take a space separated list of IPv4 or IPv6 addresses, each optionally suffixed with an address prefix length in bits after a +"/" +character\&. If the suffix is omitted, the address is considered a host address, i\&.e\&. the filter covers the whole address (32 bits for IPv4, 128 bits for IPv6)\&. +.sp +The access lists configured with this option are applied to all sockets created by processes of this unit (or in the case of socket units, associated with it)\&. The lists are implicitly combined with any lists configured for any of the parent slice units this unit might be a member of\&. By default both access lists are empty\&. Both ingress and egress traffic is filtered by these settings\&. In case of ingress traffic the source IP address is checked against these access lists, in case of egress traffic the destination IP address is checked\&. The following rules are applied in turn: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Access is granted when the checked IP address matches an entry in the +\fIIPAddressAllow=\fR +list\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, access is denied when the checked IP address matches an entry in the +\fIIPAddressDeny=\fR +list\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, access is granted\&. +.RE +.sp +In order to implement an allow\-listing IP firewall, it is recommended to use a +\fIIPAddressDeny=\fR\fBany\fR +setting on an upper\-level slice unit (such as the root slice +\-\&.slice +or the slice containing all system services +system\&.slice +\(en see +\fBsystemd.special\fR(7) +for details on these slice units), plus individual per\-service +\fIIPAddressAllow=\fR +lines permitting network access to relevant services, and only them\&. +.sp +Note that for socket\-activated services, the IP access list configured on the socket unit applies to all sockets associated with it directly, but not to any sockets created by the ultimately activated services for it\&. Conversely, the IP access list configured for the service is not applied to any sockets passed into the service via socket activation\&. Thus, it is usually a good idea to replicate the IP access lists on both the socket and the service unit\&. Nevertheless, it may make sense to maintain one list more open and the other one more restricted, depending on the use case\&. +.sp +If these settings are used multiple times in the same unit the specified lists are combined\&. If an empty string is assigned to these settings the specific access list is reset and all previous settings undone\&. +.sp +In place of explicit IPv4 or IPv6 address and prefix length specifications a small set of symbolic names may be used\&. The following names are defined: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Special address/network names +.TS +allbox tab(:); +lB lB lB. +T{ +Symbolic Name +T}:T{ +Definition +T}:T{ +Meaning +T} +.T& +l l l +l l l +l l l +l l l. +T{ +\fBany\fR +T}:T{ +0\&.0\&.0\&.0/0 ::/0 +T}:T{ +Any host +T} +T{ +\fBlocalhost\fR +T}:T{ +127\&.0\&.0\&.0/8 ::1/128 +T}:T{ +All addresses on the local loopback +T} +T{ +\fBlink\-local\fR +T}:T{ +169\&.254\&.0\&.0/16 fe80::/64 +T}:T{ +All link\-local IP addresses +T} +T{ +\fBmulticast\fR +T}:T{ +224\&.0\&.0\&.0/4 ff00::/8 +T}:T{ +All IP multicasting addresses +T} +.TE +.sp 1 +Note that these settings might not be supported on some systems (for example if eBPF control group support is not enabled in the underlying kernel or container manager)\&. These settings will have no effect in that case\&. If compatibility with such systems is desired it is hence recommended to not exclusively rely on them for IP security\&. +.sp +This option cannot be bypassed by prefixing +"+" +to the executable path in the service unit, as it applies to the whole control group\&. +.sp +Added in version 235\&. +.RE +.PP +\fISocketBindAllow=\fR\fI\fIbind\-rule\fR\fR, \fISocketBindDeny=\fR\fI\fIbind\-rule\fR\fR +.RS 4 +Allow or deny binding a socket address to a socket by matching it with the +\fIbind\-rule\fR +and applying a corresponding action if there is a match\&. +.sp +\fIbind\-rule\fR +describes socket properties such as +\fIaddress\-family\fR, +\fItransport\-protocol\fR +and +\fIip\-ports\fR\&. +.sp +\fIbind\-rule\fR +:= { [\fIaddress\-family\fR\fB:\fR][\fItransport\-protocol\fR\fB:\fR][\fIip\-ports\fR] | +\fBany\fR +} +.sp +\fIaddress\-family\fR +:= { +\fBipv4\fR +| +\fBipv6\fR +} +.sp +\fItransport\-protocol\fR +:= { +\fBtcp\fR +| +\fBudp\fR +} +.sp +\fIip\-ports\fR +:= { +\fIip\-port\fR +| +\fIip\-port\-range\fR +} +.sp +An optional +\fIaddress\-family\fR +expects +\fBipv4\fR +or +\fBipv6\fR +values\&. If not specified, a rule will be matched for both IPv4 and IPv6 addresses and applied depending on other socket fields, e\&.g\&. +\fItransport\-protocol\fR, +\fIip\-port\fR\&. +.sp +An optional +\fItransport\-protocol\fR +expects +\fBtcp\fR +or +\fBudp\fR +transport protocol names\&. If not specified, a rule will be matched for any transport protocol\&. +.sp +An optional +\fIip\-port\fR +value must lie within 1\&...65535 interval inclusively, i\&.e\&. dynamic port +\fB0\fR +is not allowed\&. A range of sequential ports is described by +\fIip\-port\-range\fR +:= +\fIip\-port\-low\fR\fB\-\fR\fIip\-port\-high\fR, where +\fIip\-port\-low\fR +is smaller than or equal to +\fIip\-port\-high\fR +and both are within 1\&...65535 inclusively\&. +.sp +A special value +\fBany\fR +can be used to apply a rule to any address family, transport protocol and any port with a positive value\&. +.sp +To allow multiple rules assign +\fISocketBindAllow=\fR +or +\fISocketBindDeny=\fR +multiple times\&. To clear the existing assignments pass an empty +\fISocketBindAllow=\fR +or +\fISocketBindDeny=\fR +assignment\&. +.sp +For each of +\fISocketBindAllow=\fR +and +\fISocketBindDeny=\fR, maximum allowed number of assignments is +\fB128\fR\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Binding to a socket is allowed when a socket address matches an entry in the +\fISocketBindAllow=\fR +list\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, binding is denied when the socket address matches an entry in the +\fISocketBindDeny=\fR +list\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Otherwise, binding is allowed\&. +.RE +.sp +The feature is implemented with +\fBcgroup/bind4\fR +and +\fBcgroup/bind6\fR +cgroup\-bpf hooks\&. +.sp +Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\&... +# Allow binding IPv6 socket addresses with a port greater than or equal to 10000\&. +[Service] +SocketBindAllow=ipv6:10000\-65535 +SocketBindDeny=any +\&... +# Allow binding IPv4 and IPv6 socket addresses with 1234 and 4321 ports\&. +[Service] +SocketBindAllow=1234 +SocketBindAllow=4321 +SocketBindDeny=any +\&... +# Deny binding IPv6 socket addresses\&. +[Service] +SocketBindDeny=ipv6 +\&... +# Deny binding IPv4 and IPv6 socket addresses\&. +[Service] +SocketBindDeny=any +\&... +# Allow binding only over TCP +[Service] +SocketBindAllow=tcp +SocketBindDeny=any +\&... +# Allow binding only over IPv6/TCP +[Service] +SocketBindAllow=ipv6:tcp +SocketBindDeny=any +\&... +# Allow binding ports within 10000\-65535 range over IPv4/UDP\&. +[Service] +SocketBindAllow=ipv4:udp:10000\-65535 +SocketBindDeny=any +\&... +.fi +.if n \{\ +.RE +.\} +.sp +This option cannot be bypassed by prefixing +"+" +to the executable path in the service unit, as it applies to the whole control group\&. +.sp +Added in version 249\&. +.RE +.PP +\fIRestrictNetworkInterfaces=\fR +.RS 4 +Takes a list of space\-separated network interface names\&. This option restricts the network interfaces that processes of this unit can use\&. By default processes can only use the network interfaces listed (allow\-list)\&. If the first character of the rule is +"~", the effect is inverted: the processes can only use network interfaces not listed (deny\-list)\&. +.sp +This option can appear multiple times, in which case the network interface names are merged\&. If the empty string is assigned the set is reset, all prior assignments will have not effect\&. +.sp +If you specify both types of this option (i\&.e\&. allow\-listing and deny\-listing), the first encountered will take precedence and will dictate the default action (allow vs deny)\&. Then the next occurrences of this option will add or delete the listed network interface names from the set, depending of its type and the default action\&. +.sp +The loopback interface ("lo") is not treated in any special way, you have to configure it explicitly in the unit file\&. +.sp +Example 1: allow\-list +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictNetworkInterfaces=eth1 +RestrictNetworkInterfaces=eth2 +.fi +.if n \{\ +.RE +.\} +.sp +Programs in the unit will be only able to use the eth1 and eth2 network interfaces\&. +.sp +Example 2: deny\-list +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictNetworkInterfaces=~eth1 eth2 +.fi +.if n \{\ +.RE +.\} +.sp +Programs in the unit will be able to use any network interface but eth1 and eth2\&. +.sp +Example 3: mixed +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestrictNetworkInterfaces=eth1 eth2 +RestrictNetworkInterfaces=~eth1 +.fi +.if n \{\ +.RE +.\} +.sp +Programs in the unit will be only able to use the eth2 network interface\&. +.sp +This option cannot be bypassed by prefixing +"+" +to the executable path in the service unit, as it applies to the whole control group\&. +.sp +Added in version 250\&. +.RE +.PP +\fINFTSet=\fR\fIfamily\fR:\fItable\fR:\fIset\fR +.RS 4 +This setting provides a method for integrating dynamic cgroup, user and group IDs into firewall rules with +\m[blue]\fBNFT\fR\m[]\&\s-2\u[9]\d\s+2 +sets\&. The benefit of using this setting is to be able to use the IDs as selectors in firewall rules easily and this in turn allows more fine grained filtering\&. NFT rules for cgroup matching use numeric cgroup IDs, which change every time a service is restarted, making them hard to use in systemd environment otherwise\&. Dynamic and random IDs used by +\fIDynamicUser=\fR +can be also integrated with this setting\&. +.sp +This option expects a whitespace separated list of NFT set definitions\&. Each definition consists of a colon\-separated tuple of source type (one of +"cgroup", +"user" +or +"group"), NFT address family (one of +"arp", +"bridge", +"inet", +"ip", +"ip6", or +"netdev"), table name and set name\&. The names of tables and sets must conform to lexical restrictions of NFT table names\&. The type of the element used in the NFT filter must match the type implied by the directive ("cgroup", +"user" +or +"group") as shown in the table below\&. When a control group or a unit is realized, the corresponding ID will be appended to the NFT sets and it will be be removed when the control group or unit is removed\&. +\fBsystemd\fR +only inserts elements to (or removes from) the sets, so the related NFT rules, tables and sets must be prepared elsewhere in advance\&. Failures to manage the sets will be ignored\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Defined \fIsource type\fR values +.TS +allbox tab(:); +lB lB lB. +T{ +Source type +T}:T{ +Description +T}:T{ +Corresponding NFT type name +T} +.T& +l l l +l l l +l l l. +T{ +"cgroup" +T}:T{ +control group ID +T}:T{ +"cgroupsv2" +T} +T{ +"user" +T}:T{ +user ID +T}:T{ +"meta skuid" +T} +T{ +"group" +T}:T{ +group ID +T}:T{ +"meta skgid" +T} +.TE +.sp 1 +If the firewall rules are reinstalled so that the contents of NFT sets are destroyed, command +\fBsystemctl daemon\-reload\fR +can be used to refill the sets\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +NFTSet=cgroup:inet:filter:my_service user:inet:filter:serviceuser +.fi +.if n \{\ +.RE +.\} +.sp +Corresponding NFT rules: +.sp +.if n \{\ +.RS 4 +.\} +.nf +table inet filter { + set my_service { + type cgroupsv2 + } + set serviceuser { + typeof meta skuid + } + chain x { + socket cgroupv2 level 2 @my_service accept + drop + } + chain y { + meta skuid @serviceuser accept + drop + } +} +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 255\&. +.RE +.SS "BPF Programs" +.PP +\fIIPIngressFilterPath=\fR\fI\fIBPF_FS_PROGRAM_PATH\fR\fR, \fIIPEgressFilterPath=\fR\fI\fIBPF_FS_PROGRAM_PATH\fR\fR +.RS 4 +Add custom network traffic filters implemented as BPF programs, applying to all IP packets sent and received over +\fBAF_INET\fR +and +\fBAF_INET6\fR +sockets\&. Takes an absolute path to a pinned BPF program in the BPF virtual filesystem (/sys/fs/bpf/)\&. +.sp +The filters configured with this option are applied to all sockets created by processes of this unit (or in the case of socket units, associated with it)\&. The filters are loaded in addition to filters any of the parent slice units this unit might be a member of as well as any +\fIIPAddressAllow=\fR +and +\fIIPAddressDeny=\fR +filters in any of these units\&. By default there are no filters specified\&. +.sp +If these settings are used multiple times in the same unit all the specified programs are attached\&. If an empty string is assigned to these settings the program list is reset and all previous specified programs ignored\&. +.sp +If the path +\fIBPF_FS_PROGRAM_PATH\fR +in +\fIIPIngressFilterPath=\fR +assignment is already being handled by +\fIBPFProgram=\fR +ingress hook, e\&.g\&. +\fIBPFProgram=\fR\fBingress\fR:\fIBPF_FS_PROGRAM_PATH\fR, the assignment will be still considered valid and the program will be attached to a cgroup\&. Same for +\fIIPEgressFilterPath=\fR +path and +\fBegress\fR +hook\&. +.sp +Note that for socket\-activated services, the IP filter programs configured on the socket unit apply to all sockets associated with it directly, but not to any sockets created by the ultimately activated services for it\&. Conversely, the IP filter programs configured for the service are not applied to any sockets passed into the service via socket activation\&. Thus, it is usually a good idea, to replicate the IP filter programs on both the socket and the service unit, however it often makes sense to maintain one configuration more open and the other one more restricted, depending on the use case\&. +.sp +Note that these settings might not be supported on some systems (for example if eBPF control group support is not enabled in the underlying kernel or container manager)\&. These settings will fail the service in that case\&. If compatibility with such systems is desired it is hence recommended to attach your filter manually (requires +\fIDelegate=\fR\fByes\fR) instead of using this setting\&. +.sp +Added in version 243\&. +.RE +.PP +\fIBPFProgram=\fR\fI\fItype\fR\fR\fI:\fR\fI\fIprogram\-path\fR\fR +.RS 4 +\fIBPFProgram=\fR +allows attaching custom BPF programs to the cgroup of a unit\&. (This generalizes the functionality exposed via +\fIIPEgressFilterPath=\fR +and +\fIIPIngressFilterPath=\fR +for other hooks\&.) Cgroup\-bpf hooks in the form of BPF programs loaded to the BPF filesystem are attached with cgroup\-bpf attach flags determined by the unit\&. For details about attachment types and flags see +\m[blue]\fBbpf\&.h\fR\m[]\&\s-2\u[10]\d\s+2\&. Also refer to the general +\m[blue]\fBBPF documentation\fR\m[]\&\s-2\u[11]\d\s+2\&. +.sp +The specification of BPF program consists of a pair of BPF program type and program path in the file system, with +":" +as the separator: +\fItype\fR:\fIprogram\-path\fR\&. +.sp +The BPF program type is equivalent to the BPF attach type used in +\fBbpftool\fR(8) +It may be one of +\fBegress\fR, +\fBingress\fR, +\fBsock_create\fR, +\fBsock_ops\fR, +\fBdevice\fR, +\fBbind4\fR, +\fBbind6\fR, +\fBconnect4\fR, +\fBconnect6\fR, +\fBpost_bind4\fR, +\fBpost_bind6\fR, +\fBsendmsg4\fR, +\fBsendmsg6\fR, +\fBsysctl\fR, +\fBrecvmsg4\fR, +\fBrecvmsg6\fR, +\fBgetsockopt\fR, or +\fBsetsockopt\fR\&. +.sp +The specified program path must be an absolute path referencing a BPF program inode in the bpffs file system (which generally means it must begin with +/sys/fs/bpf/)\&. If a specified program does not exist (i\&.e\&. has not been uploaded to the BPF subsystem of the kernel yet), it will not be installed but unit activation will continue (a warning will be printed to the logs)\&. +.sp +Setting +\fIBPFProgram=\fR +to an empty value makes previous assignments ineffective\&. +.sp +Multiple assignments of the same program type/path pair have the same effect as a single assignment: the program will be attached just once\&. +.sp +If BPF +\fBegress\fR +pinned to +\fIprogram\-path\fR +path is already being handled by +\fIIPEgressFilterPath=\fR, +\fIBPFProgram=\fR +assignment will be considered valid and +\fIBPFProgram=\fR +will be attached to a cgroup\&. Similarly for +\fBingress\fR +hook and +\fIIPIngressFilterPath=\fR +assignment\&. +.sp +BPF programs passed with +\fIBPFProgram=\fR +are attached to the cgroup of a unit with BPF attach flag +\fBmulti\fR, that allows further attachments of the same +\fItype\fR +within cgroup hierarchy topped by the unit cgroup\&. +.sp +Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BPFProgram=egress:/sys/fs/bpf/egress\-hook +BPFProgram=bind6:/sys/fs/bpf/sock\-addr\-hook +.fi +.if n \{\ +.RE +.\} +.sp +Added in version 249\&. +.RE +.SS "Device Access" +.PP +\fIDeviceAllow=\fR +.RS 4 +Control access to specific device nodes by the executed processes\&. Takes two space\-separated strings: a device node specifier followed by a combination of +\fBr\fR, +\fBw\fR, +\fBm\fR +to control +\fIr\fReading, +\fIw\fRriting, or creation of the specific device nodes by the unit (\fIm\fRknod), respectively\&. This functionality is implemented using eBPF filtering\&. +.sp +When access to +\fIall\fR +physical devices should be disallowed, +\fIPrivateDevices=\fR +may be used instead\&. See +\fBsystemd.exec\fR(5)\&. +.sp +The device node specifier is either a path to a device node in the file system, starting with +/dev/, or a string starting with either +"char\-" +or +"block\-" +followed by a device group name, as listed in +/proc/devices\&. The latter is useful to allow\-list all current and future devices belonging to a specific device group at once\&. The device group is matched according to filename globbing rules, you may hence use the +"*" +and +"?" +wildcards\&. (Note that such globbing wildcards are not available for device node path specifications!) In order to match device nodes by numeric major/minor, use device node paths in the +/dev/char/ +and +/dev/block/ +directories\&. However, matching devices by major/minor is generally not recommended as assignments are neither stable nor portable between systems or different kernel versions\&. +.sp +Examples: +/dev/sda5 +is a path to a device node, referring to an ATA or SCSI block device\&. +"char\-pts" +and +"char\-alsa" +are specifiers for all pseudo TTYs and all ALSA sound devices, respectively\&. +"char\-cpu/*" +is a specifier matching all CPU related device groups\&. +.sp +Note that allow lists defined this way should only reference device groups which are resolvable at the time the unit is started\&. Any device groups not resolvable then are not added to the device allow list\&. In order to work around this limitation, consider extending service units with a pair of +\fBAfter=modprobe@xyz\&.service\fR +and +\fBWants=modprobe@xyz\&.service\fR +lines that load the necessary kernel module implementing the device group if missing\&. Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\&... +[Unit] +Wants=modprobe@loop\&.service +After=modprobe@loop\&.service + +[Service] +DeviceAllow=block\-loop +DeviceAllow=/dev/loop\-control +\&... +.fi +.if n \{\ +.RE +.\} +.sp +This option cannot be bypassed by prefixing +"+" +to the executable path in the service unit, as it applies to the whole control group\&. +.sp +Added in version 208\&. +.RE +.PP +\fIDevicePolicy=auto|closed|strict\fR +.RS 4 +Control the policy for allowing device access: +.PP +\fBstrict\fR +.RS 4 +means to only allow types of access that are explicitly specified\&. +.sp +Added in version 208\&. +.RE +.PP +\fBclosed\fR +.RS 4 +in addition, allows access to standard pseudo devices including +/dev/null, +/dev/zero, +/dev/full, +/dev/random, and +/dev/urandom\&. +.sp +Added in version 208\&. +.RE +.PP +\fBauto\fR +.RS 4 +in addition, allows access to all devices if no explicit +\fIDeviceAllow=\fR +is present\&. This is the default\&. +.sp +Added in version 208\&. +.RE +.sp +This option cannot be bypassed by prefixing +"+" +to the executable path in the service unit, as it applies to the whole control group\&. +.sp +Added in version 208\&. +.RE +.SS "Control Group Management" +.PP +\fISlice=\fR +.RS 4 +The name of the slice unit to place the unit in\&. Defaults to +system\&.slice +for all non\-instantiated units of all unit types (except for slice units themselves see below)\&. Instance units are by default placed in a subslice of +system\&.slice +that is named after the template name\&. +.sp +This option may be used to arrange systemd units in a hierarchy of slices each of which might have resource settings applied\&. +.sp +For units of type slice, the only accepted value for this setting is the parent slice\&. Since the name of a slice unit implies the parent slice, it is hence redundant to ever set this parameter directly for slice units\&. +.sp +Special care should be taken when relying on the default slice assignment in templated service units that have +\fIDefaultDependencies=no\fR +set, see +\fBsystemd.service\fR(5), section "Default Dependencies" for details\&. +.sp +Added in version 208\&. +.RE +.PP +\fIDelegate=\fR +.RS 4 +Turns on delegation of further resource control partitioning to processes of the unit\&. Units where this is enabled may create and manage their own private subhierarchy of control groups below the control group of the unit itself\&. For unprivileged services (i\&.e\&. those using the +\fIUser=\fR +setting) the unit\*(Aqs control group will be made accessible to the relevant user\&. +.sp +When enabled the service manager will refrain from manipulating control groups or moving processes below the unit\*(Aqs control group, so that a clear concept of ownership is established: the control group tree at the level of the unit\*(Aqs control group and above (i\&.e\&. towards the root control group) is owned and managed by the service manager of the host, while the control group tree below the unit\*(Aqs control group is owned and managed by the unit itself\&. +.sp +Takes either a boolean argument or a (possibly empty) list of control group controller names\&. If true, delegation is turned on, and all supported controllers are enabled for the unit, making them available to the unit\*(Aqs processes for management\&. If false, delegation is turned off entirely (and no additional controllers are enabled)\&. If set to a list of controllers, delegation is turned on, and the specified controllers are enabled for the unit\&. Assigning the empty string will enable delegation, but reset the list of controllers, and all assignments prior to this will have no effect\&. Note that additional controllers other than the ones specified might be made available as well, depending on configuration of the containing slice unit or other units contained in it\&. Defaults to false\&. +.sp +Note that controller delegation to less privileged code is only safe on the unified control group hierarchy\&. Accordingly, access to the specified controllers will not be granted to unprivileged services on the legacy hierarchy, even when requested\&. +.sp +The following controller names may be specified: +\fBcpu\fR, +\fBcpuacct\fR, +\fBcpuset\fR, +\fBio\fR, +\fBblkio\fR, +\fBmemory\fR, +\fBdevices\fR, +\fBpids\fR, +\fBbpf\-firewall\fR, and +\fBbpf\-devices\fR\&. +.sp +Not all of these controllers are available on all kernels however, and some are specific to the unified hierarchy while others are specific to the legacy hierarchy\&. Also note that the kernel might support further controllers, which aren\*(Aqt covered here yet as delegation is either not supported at all for them or not defined cleanly\&. +.sp +Note that because of the hierarchical nature of cgroup hierarchy, any controllers that are delegated will be enabled for the parent and sibling units of the unit with delegation\&. +.sp +For further details on the delegation model consult +\m[blue]\fBControl Group APIs and Delegation\fR\m[]\&\s-2\u[12]\d\s+2\&. +.sp +Added in version 218\&. +.RE +.PP +\fIDelegateSubgroup=\fR +.RS 4 +Place unit processes in the specified subgroup of the unit\*(Aqs control group\&. Takes a valid control group name (not a path!) as parameter, or an empty string to turn this feature off\&. Defaults to off\&. The control group name must be usable as filename and avoid conflicts with the kernel\*(Aqs control group attribute files (i\&.e\&. +cgroup\&.procs +is not an acceptable name, since the kernel exposes a native control group attribute file by that name)\&. This option has no effect unless control group delegation is turned on via +\fIDelegate=\fR, see above\&. Note that this setting only applies to "main" processes of a unit, i\&.e\&. for services to +\fIExecStart=\fR, but not for +\fIExecReload=\fR +and similar\&. If delegation is enabled, the latter are always placed inside a subgroup named +\&.control\&. The specified subgroup is automatically created (and potentially ownership is passed to the unit\*(Aqs configured user/group) when a process is started in it\&. +.sp +This option is useful to avoid manually moving the invoked process into a subgroup after it has been started\&. Since no processes should live in inner nodes of the control group tree it\*(Aqs almost always necessary to run the main ("supervising") process of a unit that has delegation turned on in a subgroup\&. +.sp +Added in version 254\&. +.RE +.PP +\fIDisableControllers=\fR +.RS 4 +Disables controllers from being enabled for a unit\*(Aqs children\&. If a controller listed is already in use in its subtree, the controller will be removed from the subtree\&. This can be used to avoid configuration in child units from being able to implicitly or explicitly enable a controller\&. Defaults to empty\&. +.sp +Multiple controllers may be specified, separated by spaces\&. You may also pass +\fIDisableControllers=\fR +multiple times, in which case each new instance adds another controller to disable\&. Passing +\fIDisableControllers=\fR +by itself with no controller name present resets the disabled controller list\&. +.sp +It may not be possible to disable a controller after units have been started, if the unit or any child of the unit in question delegates controllers to its children, as any delegated subtree of the cgroup hierarchy is unmanaged by systemd\&. +.sp +The following controller names may be specified: +\fBcpu\fR, +\fBcpuacct\fR, +\fBcpuset\fR, +\fBio\fR, +\fBblkio\fR, +\fBmemory\fR, +\fBdevices\fR, +\fBpids\fR, +\fBbpf\-firewall\fR, and +\fBbpf\-devices\fR\&. +.sp +Added in version 240\&. +.RE +.SS "Memory Pressure Control" +.PP +\fIManagedOOMSwap=auto|kill\fR, \fIManagedOOMMemoryPressure=auto|kill\fR +.RS 4 +Specifies how +\fBsystemd-oomd.service\fR(8) +will act on this unit\*(Aqs cgroups\&. Defaults to +\fBauto\fR\&. +.sp +When set to +\fBkill\fR, the unit becomes a candidate for monitoring by +\fBsystemd\-oomd\fR\&. If the cgroup passes the limits set by +\fBoomd.conf\fR(5) +or the unit configuration, +\fBsystemd\-oomd\fR +will select a descendant cgroup and send +\fBSIGKILL\fR +to all of the processes under it\&. You can find more details on candidates and kill behavior at +\fBsystemd-oomd.service\fR(8) +and +\fBoomd.conf\fR(5)\&. +.sp +Setting either of these properties to +\fBkill\fR +will also result in +\fIAfter=\fR +and +\fIWants=\fR +dependencies on +systemd\-oomd\&.service +unless +\fIDefaultDependencies=no\fR\&. +.sp +When set to +\fBauto\fR, +\fBsystemd\-oomd\fR +will not actively use this cgroup\*(Aqs data for monitoring and detection\&. However, if an ancestor cgroup has one of these properties set to +\fBkill\fR, a unit with +\fBauto\fR +can still be a candidate for +\fBsystemd\-oomd\fR +to terminate\&. +.sp +Added in version 247\&. +.RE +.PP +\fIManagedOOMMemoryPressureLimit=\fR +.RS 4 +Overrides the default memory pressure limit set by +\fBoomd.conf\fR(5) +for this unit (cgroup)\&. Takes a percentage value between 0% and 100%, inclusive\&. This property is ignored unless +\fIManagedOOMMemoryPressure=\fR\fBkill\fR\&. Defaults to 0%, which means to use the default set by +\fBoomd.conf\fR(5)\&. +.sp +Added in version 247\&. +.RE +.PP +\fIManagedOOMPreference=none|avoid|omit\fR +.RS 4 +Allows deprioritizing or omitting this unit\*(Aqs cgroup as a candidate when +\fBsystemd\-oomd\fR +needs to act\&. Requires support for extended attributes (see +\fBxattr\fR(7)) in order to use +\fBavoid\fR +or +\fBomit\fR\&. +.sp +When calculating candidates to relieve swap usage, +\fBsystemd\-oomd\fR +will only respect these extended attributes if the unit\*(Aqs cgroup is owned by root\&. +.sp +When calculating candidates to relieve memory pressure, +\fBsystemd\-oomd\fR +will only respect these extended attributes if the unit\*(Aqs cgroup is owned by root, or if the unit\*(Aqs cgroup owner, and the owner of the monitored ancestor cgroup are the same\&. For example, if +\fBsystemd\-oomd\fR +is calculating candidates for +\-\&.slice, then extended attributes set on descendants of +/user\&.slice/user\-1000\&.slice/user@1000\&.service/ +will be ignored because the descendants are owned by UID 1000, and +\-\&.slice +is owned by UID 0\&. But, if calculating candidates for +/user\&.slice/user\-1000\&.slice/user@1000\&.service/, then extended attributes set on the descendants would be respected\&. +.sp +If this property is set to +\fBavoid\fR, the service manager will convey this to +\fBsystemd\-oomd\fR, which will only select this cgroup if there are no other viable candidates\&. +.sp +If this property is set to +\fBomit\fR, the service manager will convey this to +\fBsystemd\-oomd\fR, which will ignore this cgroup as a candidate and will not perform any actions on it\&. +.sp +It is recommended to use +\fBavoid\fR +and +\fBomit\fR +sparingly, as it can adversely affect +\fBsystemd\-oomd\fR\*(Aqs kill behavior\&. Also note that these extended attributes are not applied recursively to cgroups under this unit\*(Aqs cgroup\&. +.sp +Defaults to +\fBnone\fR +which means +\fBsystemd\-oomd\fR +will rank this unit\*(Aqs cgroup as defined in +\fBsystemd-oomd.service\fR(8) +and +\fBoomd.conf\fR(5)\&. +.sp +Added in version 248\&. +.RE +.PP +\fIMemoryPressureWatch=\fR +.RS 4 +Controls memory pressure monitoring for invoked processes\&. Takes one of +"off", +"on", +"auto" +or +"skip"\&. If +"off" +tells the service not to watch for memory pressure events, by setting the +\fI$MEMORY_PRESSURE_WATCH\fR +environment variable to the literal string +/dev/null\&. If +"on" +tells the service to watch for memory pressure events\&. This enables memory accounting for the service, and ensures the +memory\&.pressure +cgroup attribute file is accessible for reading and writing by the service\*(Aqs user\&. It then sets the +\fI$MEMORY_PRESSURE_WATCH\fR +environment variable for processes invoked by the unit to the file system path to this file\&. The threshold information configured with +\fIMemoryPressureThresholdSec=\fR +is encoded in the +\fI$MEMORY_PRESSURE_WRITE\fR +environment variable\&. If the +"auto" +value is set the protocol is enabled if memory accounting is anyway enabled for the unit, and disabled otherwise\&. If set to +"skip" +the logic is neither enabled, nor disabled and the two environment variables are not set\&. +.sp +Note that services are free to use the two environment variables, but it\*(Aqs unproblematic if they ignore them\&. Memory pressure handling must be implemented individually in each service, and usually means different things for different software\&. For further details on memory pressure handling see +\m[blue]\fBMemory Pressure Handling in systemd\fR\m[]\&\s-2\u[13]\d\s+2\&. +.sp +Services implemented using +\fBsd-event\fR(3) +may use +\fBsd_event_add_memory_pressure\fR(3) +to watch for and handle memory pressure events\&. +.sp +If not explicit set, defaults to the +\fIDefaultMemoryPressureWatch=\fR +setting in +\fBsystemd-system.conf\fR(5)\&. +.sp +Added in version 254\&. +.RE +.PP +\fIMemoryPressureThresholdSec=\fR +.RS 4 +Sets the memory pressure threshold time for memory pressure monitor as configured via +\fIMemoryPressureWatch=\fR\&. Specifies the maximum allocation latency before a memory pressure event is signalled to the service, per 2s window\&. If not specified defaults to the +\fIDefaultMemoryPressureThresholdSec=\fR +setting in +\fBsystemd-system.conf\fR(5) +(which in turn defaults to 200ms)\&. The specified value expects a time unit such as +"ms" +or +"μs", see +\fBsystemd.time\fR(7) +for details on the permitted syntax\&. +.sp +Added in version 254\&. +.RE +.SS "Coredump Control" +.PP +\fICoredumpReceive=\fR +.RS 4 +Takes a boolean argument\&. This setting is used to enable coredump forwarding for containers that belong to this unit\*(Aqs cgroup\&. Units with +\fICoredumpReceive=yes\fR +must also be configured with +\fIDelegate=yes\fR\&. Defaults to false\&. +.sp +When +\fBsystemd\-coredump\fR +is handling a coredump for a process from a container, if the container\*(Aqs leader process is a descendant of a cgroup with +\fICoredumpReceive=yes\fR +and +\fIDelegate=yes\fR, then +\fBsystemd\-coredump\fR +will attempt to forward the coredump to +\fBsystemd\-coredump\fR +within the container\&. +.sp +Added in version 255\&. +.RE +.SH "HISTORY" +.PP +systemd 252 +.RS 4 +Options for controlling the Legacy Control Group Hierarchy (\m[blue]\fBControl Groups version 1\fR\m[]\&\s-2\u[14]\d\s+2) are now fully deprecated: +\fICPUShares=\fR\fI\fIweight\fR\fR, +\fIStartupCPUShares=\fR\fI\fIweight\fR\fR, +\fIMemoryLimit=\fR\fI\fIbytes\fR\fR, +\fIBlockIOAccounting=\fR, +\fIBlockIOWeight=\fR\fI\fIweight\fR\fR, +\fIStartupBlockIOWeight=\fR\fI\fIweight\fR\fR, +\fIBlockIODeviceWeight=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIweight\fR\fR, +\fIBlockIOReadBandwidth=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIbytes\fR\fR, +\fIBlockIOWriteBandwidth=\fR\fI\fIdevice\fR\fR\fI \fR\fI\fIbytes\fR\fR\&. Please switch to the unified cgroup hierarchy\&. +.sp +Added in version 252\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.unit\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.slice\fR(5), +\fBsystemd.scope\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.mount\fR(5), +\fBsystemd.swap\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.directives\fR(7), +\fBsystemd.special\fR(7), +\fBsystemd-oomd.service\fR(8), The documentation for control groups and specific controllers in the Linux kernel: +\m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "NOTES" +.IP " 1." 4 +New Control Group Interfaces +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface +.RE +.IP " 2." 4 +Control Groups v2 +.RS 4 +\%https://docs.kernel.org/admin-guide/cgroup-v2.html +.RE +.IP " 3." 4 +CFS Scheduler +.RS 4 +\%https://docs.kernel.org/scheduler/sched-design-CFS.html +.RE +.IP " 4." 4 +CFS Bandwidth Control +.RS 4 +\%https://docs.kernel.org/scheduler/sched-bwc.html +.RE +.IP " 5." 4 +Memory Interface Files +.RS 4 +\%https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files +.RE +.IP " 6." 4 +Zswap +.RS 4 +\%https://www.kernel.org/doc/html/latest/admin-guide/mm/zswap.html +.RE +.IP " 7." 4 +pids controller +.RS 4 +\%https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#pid +.RE +.IP " 8." 4 +IO Interface Files +.RS 4 +\%https://docs.kernel.org/admin-guide/cgroup-v2.html#io-interface-files +.RE +.IP " 9." 4 +NFT +.RS 4 +\%https://netfilter.org/projects/nftables/index.html +.RE +.IP "10." 4 +bpf.h +.RS 4 +\%https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/linux/bpf.h +.RE +.IP "11." 4 +BPF documentation +.RS 4 +\%https://docs.kernel.org/bpf/ +.RE +.IP "12." 4 +Control Group APIs and Delegation +.RS 4 +\%https://systemd.io/CGROUP_DELEGATION +.RE +.IP "13." 4 +Memory Pressure Handling in systemd +.RS 4 +\%https://systemd.io/MEMORY_PRESSURE +.RE +.IP "14." 4 +Control Groups version 1 +.RS 4 +\%https://docs.kernel.org/admin-guide/cgroup-v1/index.html +.RE diff --git a/upstream/fedora-40/man5/systemd.scope.5 b/upstream/fedora-40/man5/systemd.scope.5 new file mode 100644 index 00000000..64cb28d7 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.scope.5 @@ -0,0 +1,170 @@ +'\" t +.TH "SYSTEMD\&.SCOPE" "5" "" "systemd 255" "systemd.scope" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.scope \- Scope unit configuration +.SH "SYNOPSIS" +.PP +\fIscope\fR\&.scope +.SH "DESCRIPTION" +.PP +Scope units are not configured via unit configuration files, but are only created programmatically using the bus interfaces of systemd\&. They are named similar to filenames\&. A unit whose name ends in +"\&.scope" +refers to a scope unit\&. Scopes units manage a set of system processes\&. Unlike service units, scope units manage externally created processes, and do not fork off processes on its own\&. +.PP +The main purpose of scope units is grouping worker processes of a system service for organization and for managing resources\&. +.PP +\fBsystemd\-run \fR\fB\fB\-\-scope\fR\fR +may be used to easily launch a command in a new scope unit from the command line\&. +.PP +See the +\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2 +for an introduction on how to make use of scope units from programs\&. +.PP +Note that, unlike service units, scope units have no "main" process: all processes in the scope are equivalent\&. The lifecycle of the scope unit is thus not bound to the lifetime of one specific process, but to the existence of at least one process in the scope\&. This also means that the exit statuses of these processes are not relevant for the scope unit failure state\&. Scope units may still enter a failure state, for example due to resource exhaustion or stop timeouts being reached, but not due to programs inside of them terminating uncleanly\&. Since processes managed as scope units generally remain children of the original process that forked them off, it is also the job of that process to collect their exit statuses and act on them as needed\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +Implicit dependencies may be added as result of resource control parameters as documented in +\fBsystemd.resource-control\fR(5)\&. +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Scope units will automatically have dependencies of type +\fIConflicts=\fR +and +\fIBefore=\fR +on +shutdown\&.target\&. These ensure that scope units are removed prior to system shutdown\&. Only scope units involved with early boot or late system shutdown should disable +\fIDefaultDependencies=\fR +option\&. +.RE +.SH "OPTIONS" +.PP +Scope files may include a [Unit] section, which is described in +\fBsystemd.unit\fR(5)\&. +.PP +Scope files may include a [Scope] section, which carries information about the scope and the units it contains\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in +\fBsystemd.kill\fR(5) +and +\fBsystemd.resource-control\fR(5)\&. The options specific to the [Scope] section of scope units are the following: +.PP +\fIOOMPolicy=\fR +.RS 4 +Configure the out\-of\-memory (OOM) killing policy for the kernel and the userspace OOM killer +\fBsystemd-oomd.service\fR(8)\&. On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory for itself, it might decide to kill a running process in order to free up memory and reduce memory pressure\&. Note that +systemd\-oomd\&.service +is a more flexible solution that aims to prevent out\-of\-memory situations for the userspace too, not just the kernel, by attempting to terminate services earlier, before the kernel would have to act\&. +.sp +This setting takes one of +\fBcontinue\fR, +\fBstop\fR +or +\fBkill\fR\&. If set to +\fBcontinue\fR +and a process in the unit is killed by the OOM killer, this is logged but the unit continues running\&. If set to +\fBstop\fR +the event is logged but the unit is terminated cleanly by the service manager\&. If set to +\fBkill\fR +and one of the unit\*(Aqs processes is killed by the OOM killer the kernel is instructed to kill all remaining processes of the unit too, by setting the +memory\&.oom\&.group +attribute to +\fB1\fR; also see kernel page +\m[blue]\fBControl Group v2\fR\m[]\&\s-2\u[2]\d\s+2\&. +.sp +Defaults to the setting +\fIDefaultOOMPolicy=\fR +in +\fBsystemd-system.conf\fR(5) +is set to, except for units where +\fIDelegate=\fR +is turned on, where it defaults to +\fBcontinue\fR\&. +.sp +Use the +\fIOOMScoreAdjust=\fR +setting to configure whether processes of the unit shall be considered preferred or less preferred candidates for process termination by the Linux OOM killer logic\&. See +\fBsystemd.exec\fR(5) +for details\&. +.sp +This setting also applies to +\fBsystemd-oomd.service\fR(8)\&. Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the unit after +\fBsystemd\-oomd\fR +kills a cgroup associated with it\&. +.sp +Added in version 243\&. +.RE +.PP +\fIRuntimeMaxSec=\fR +.RS 4 +Configures a maximum time for the scope to run\&. If this is used and the scope has been active for longer than the specified time it is terminated and put into a failure state\&. Pass +"infinity" +(the default) to configure no runtime limit\&. +.sp +Added in version 244\&. +.RE +.PP +\fIRuntimeRandomizedExtraSec=\fR +.RS 4 +This option modifies +\fIRuntimeMaxSec=\fR +by increasing the maximum runtime by an evenly distributed duration between 0 and the specified value (in seconds)\&. If +\fIRuntimeMaxSec=\fR +is unspecified, then this feature will be disabled\&. +.sp +Added in version 250\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-run\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.directives\fR(7)\&. +.SH "NOTES" +.IP " 1." 4 +New Control Group Interfaces +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface +.RE +.IP " 2." 4 +Control Group v2 +.RS 4 +\%https://docs.kernel.org/admin-guide/cgroup-v2.html +.RE diff --git a/upstream/fedora-40/man5/systemd.service.5 b/upstream/fedora-40/man5/systemd.service.5 new file mode 100644 index 00000000..098eba50 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.service.5 @@ -0,0 +1,2205 @@ +'\" t +.TH "SYSTEMD\&.SERVICE" "5" "" "systemd 255" "systemd.service" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.service \- Service unit configuration +.SH "SYNOPSIS" +.PP +\fIservice\fR\&.service +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.service" +encodes information about a process controlled and supervised by systemd\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The service specific configuration options are configured in the [Service] section\&. +.PP +Additional options are listed in +\fBsystemd.exec\fR(5), which define the execution environment the commands are executed in, and in +\fBsystemd.kill\fR(5), which define the way the processes of the service are terminated, and in +\fBsystemd.resource-control\fR(5), which configure resource control settings for the processes of the service\&. +.PP +If SysV init compat is enabled, systemd automatically creates service units that wrap SysV init scripts (the service name is the same as the name of the script, with a +"\&.service" +suffix added); see +\fBsystemd-sysv-generator\fR(8)\&. +.PP +The +\fBsystemd-run\fR(1) +command allows creating +\&.service +and +\&.scope +units dynamically and transiently from the command line\&. +.SH "SERVICE TEMPLATES" +.PP +It is possible for +\fBsystemd\fR +services to take a single argument via the +"\fIservice\fR@\fIargument\fR\&.service" +syntax\&. Such services are called "instantiated" services, while the unit definition without the +\fIargument\fR +parameter is called a "template"\&. An example could be a +dhcpcd@\&.service +service template which takes a network interface as a parameter to form an instantiated service\&. Within the service file, this parameter or "instance name" can be accessed with %\-specifiers\&. See +\fBsystemd.unit\fR(5) +for details\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Services with +\fIType=dbus\fR +set automatically acquire dependencies of type +\fIRequires=\fR +and +\fIAfter=\fR +on +dbus\&.socket\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Socket activated services are automatically ordered after their activating +\&.socket +units via an automatic +\fIAfter=\fR +dependency\&. Services also pull in all +\&.socket +units listed in +\fISockets=\fR +via automatic +\fIWants=\fR +and +\fIAfter=\fR +dependencies\&. +.RE +.PP +Additional implicit dependencies may be added as result of execution and resource control parameters as documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.resource-control\fR(5)\&. +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Service units will have dependencies of type +\fIRequires=\fR +and +\fIAfter=\fR +on +sysinit\&.target, a dependency of type +\fIAfter=\fR +on +basic\&.target +as well as dependencies of type +\fIConflicts=\fR +and +\fIBefore=\fR +on +shutdown\&.target\&. These ensure that normal service units pull in basic system initialization, and are terminated cleanly prior to system shutdown\&. Only services involved with early boot or late system shutdown should disable this option\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Instanced service units (i\&.e\&. service units with an +"@" +in their name) are assigned by default a per\-template slice unit (see +\fBsystemd.slice\fR(5)), named after the template unit, containing all instances of the specific template\&. This slice is normally stopped at shutdown, together with all template instances\&. If that is not desired, set +\fIDefaultDependencies=no\fR +in the template unit, and either define your own per\-template slice unit file that also sets +\fIDefaultDependencies=no\fR, or set +\fISlice=system\&.slice\fR +(or another suitable slice) in the template unit\&. Also see +\fBsystemd.resource-control\fR(5)\&. +.RE +.SH "OPTIONS" +.PP +Service unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Service unit files must include a [Service] section, which carries information about the service and the process it supervises\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in +\fBsystemd.exec\fR(5), +\fBsystemd.kill\fR(5) +and +\fBsystemd.resource-control\fR(5)\&. The options specific to the [Service] section of service units are the following: +.PP +\fIType=\fR +.RS 4 +Configures the mechanism via which the service notifies the manager that the service start\-up has finished\&. One of +\fBsimple\fR, +\fBexec\fR, +\fBforking\fR, +\fBoneshot\fR, +\fBdbus\fR, +\fBnotify\fR, +\fBnotify\-reload\fR, or +\fBidle\fR: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBsimple\fR +(the default if +\fIExecStart=\fR +is specified but neither +\fIType=\fR +nor +\fIBusName=\fR +are), the service manager will consider the unit started immediately after the main service process has been forked off (i\&.e\&. immediately after +\fBfork()\fR, and before various process attributes have been configured and in particular before the new process has called +\fBexecve()\fR +to invoke the actual service binary)\&. Typically, +\fIType=\fR\fBexec\fR +is the better choice, see below\&. +.sp +It is expected that the process configured with +\fIExecStart=\fR +is the main process of the service\&. In this mode, if the process offers functionality to other processes on the system, its communication channels should be installed before the service is started up (e\&.g\&. sockets set up by systemd, via socket activation), as the service manager will immediately proceed starting follow\-up units, right after creating the main service process, and before executing the service\*(Aqs binary\&. Note that this means +\fBsystemctl start\fR +command lines for +\fBsimple\fR +services will report success even if the service\*(Aqs binary cannot be invoked successfully (for example because the selected +\fIUser=\fR +doesn\*(Aqt exist, or the service binary is missing)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +\fBexec\fR +type is similar to +\fBsimple\fR, but the service manager will consider the unit started immediately after the main service binary has been executed\&. The service manager will delay starting of follow\-up units until that point\&. (Or in other words: +\fBsimple\fR +proceeds with further jobs right after +\fBfork()\fR +returns, while +\fBexec\fR +will not proceed before both +\fBfork()\fR +and +\fBexecve()\fR +in the service process succeeded\&.) Note that this means +\fBsystemctl start\fR +command lines for +\fBexec\fR +services will report failure when the service\*(Aqs binary cannot be invoked successfully (for example because the selected +\fIUser=\fR +doesn\*(Aqt exist, or the service binary is missing)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBforking\fR, the manager will consider the unit started immediately after the binary that forked off by the manager exits\&. +\fIThe use of this type is discouraged, use \fR\fI\fBnotify\fR\fR\fI, \fR\fI\fBnotify\-reload\fR\fR\fI, or \fR\fI\fBdbus\fR\fR\fI instead\&.\fR +.sp +It is expected that the process configured with +\fIExecStart=\fR +will call +\fBfork()\fR +as part of its start\-up\&. The parent process is expected to exit when start\-up is complete and all communication channels are set up\&. The child continues to run as the main service process, and the service manager will consider the unit started when the parent process exits\&. This is the behavior of traditional UNIX services\&. If this setting is used, it is recommended to also use the +\fIPIDFile=\fR +option, so that systemd can reliably identify the main process of the service\&. The manager will proceed with starting follow\-up units after the parent process exits\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Behavior of +\fBoneshot\fR +is similar to +\fBsimple\fR; however, the service manager will consider the unit up after the main process exits\&. It will then start follow\-up units\&. +\fIRemainAfterExit=\fR +is particularly useful for this type of service\&. +\fIType=\fR\fBoneshot\fR +is the implied default if neither +\fIType=\fR +nor +\fIExecStart=\fR +are specified\&. Note that if this option is used without +\fIRemainAfterExit=\fR +the service will never enter +"active" +unit state, but will directly transition from +"activating" +to +"deactivating" +or +"dead", since no process is configured that shall run continuously\&. In particular this means that after a service of this type ran (and which has +\fIRemainAfterExit=\fR +not set) it will not show up as started afterwards, but as dead\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Behavior of +\fBdbus\fR +is similar to +\fBsimple\fR; however, units of this type must have the +\fIBusName=\fR +specified and the service manager will consider the unit up when the specified bus name has been acquired\&. This type is the default if +\fIBusName=\fR +is specified\&. +.sp +Service units with this option configured implicitly gain dependencies on the +dbus\&.socket +unit\&. A service unit of this type is considered to be in the activating state until the specified bus name is acquired\&. It is considered activated while the bus name is taken\&. Once the bus name is released the service is considered being no longer functional which has the effect that the service manager attempts to terminate any remaining processes belonging to the service\&. Services that drop their bus name as part of their shutdown logic thus should be prepared to receive a +\fBSIGTERM\fR +(or whichever signal is configured in +\fIKillSignal=\fR) as result\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Behavior of +\fBnotify\fR +is similar to +\fBexec\fR; however, it is expected that the service sends a +"READY=1" +notification message via +\fBsd_notify\fR(3) +or an equivalent call when it has finished starting up\&. systemd will proceed with starting follow\-up units after this notification message has been sent\&. If this option is used, +\fINotifyAccess=\fR +(see below) should be set to open access to the notification socket provided by systemd\&. If +\fINotifyAccess=\fR +is missing or set to +\fBnone\fR, it will be forcibly set to +\fBmain\fR\&. +.sp +If the service supports reloading, and uses a signal to start the reload, using +\fBnotify\-reload\fR +instead is recommended\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Behavior of +\fBnotify\-reload\fR +is similar to +\fBnotify\fR, with one difference: the +\fBSIGHUP\fR +UNIX process signal is sent to the service\*(Aqs main process when the service is asked to reload and the manager will wait for a notification about the reload being finished\&. +.sp +When initiating the reload process the service is expected to reply with a notification message via +\fBsd_notify\fR(3) +that contains the +"RELOADING=1" +field in combination with +"MONOTONIC_USEC=" +set to the current monotonic time (i\&.e\&. +\fBCLOCK_MONOTONIC\fR +in +\fBclock_gettime\fR(2)) in μs, formatted as decimal string\&. Once reloading is complete another notification message must be sent, containing +"READY=1"\&. Using this service type and implementing this reload protocol is an efficient alternative to providing an +\fIExecReload=\fR +command for reloading of the service\*(Aqs configuration\&. +.sp +The signal to send can be tweaked via +\fIReloadSignal=\fR, see below\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Behavior of +\fBidle\fR +is very similar to +\fBsimple\fR; however, actual execution of the service program is delayed until all active jobs are dispatched\&. This may be used to avoid interleaving of output of shell services with the status output on the console\&. Note that this type is useful only to improve console output, it is not useful as a general unit ordering tool, and the effect of this service type is subject to a 5s timeout, after which the service program is invoked anyway\&. +.RE +.sp +It is recommended to use +\fIType=\fR\fBexec\fR +for long\-running services, as it ensures that process setup errors (e\&.g\&. errors such as a missing service executable, or missing user) are properly tracked\&. However, as this service type won\*(Aqt propagate the failures in the service\*(Aqs own startup code (as opposed to failures in the preparatory steps the service manager executes before +\fBexecve()\fR) and doesn\*(Aqt allow ordering of other units against completion of initialization of the service code itself (which for example is useful if clients need to connect to the service through some form of IPC, and the IPC channel is only established by the service itself \(em in contrast to doing this ahead of time through socket or bus activation or similar), it might not be sufficient for many cases\&. If so, +\fBnotify\fR, +\fBnotify\-reload\fR, or +\fBdbus\fR +(the latter only in case the service provides a D\-Bus interface) are the preferred options as they allow service program code to precisely schedule when to consider the service started up successfully and when to proceed with follow\-up units\&. The +\fBnotify\fR/\fBnotify\-reload\fR +service types require explicit support in the service codebase (as +\fBsd_notify()\fR +or an equivalent API needs to be invoked by the service at the appropriate time) \(em if it\*(Aqs not supported, then +\fBforking\fR +is an alternative: it supports the traditional heavy\-weight UNIX service start\-up protocol\&. Note that using any type other than +\fBsimple\fR +possibly delays the boot process, as the service manager needs to wait for at least some service initialization to complete\&. (Also note it is generally not recommended to use +\fBidle\fR +or +\fBoneshot\fR +for long\-running services\&.) +.sp +Note that various service settings (e\&.g\&. +\fIUser=\fR, +\fIGroup=\fR +through libc NSS) might result in "hidden" blocking IPC calls to other services when used\&. Sometimes it might be advisable to use the +\fBsimple\fR +service type to ensure that the service manager\*(Aqs transaction logic is not affected by such potentially slow operations and hidden dependencies, as this is the only service type where the service manager will not wait for such service execution setup operations to complete before proceeding\&. +.RE +.PP +\fIExitType=\fR +.RS 4 +Specifies when the manager should consider the service to be finished\&. One of +\fBmain\fR +or +\fBcgroup\fR: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBmain\fR +(the default), the service manager will consider the unit stopped when the main process, which is determined according to the +\fIType=\fR, exits\&. Consequently, it cannot be used with +\fIType=\fR\fBoneshot\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBcgroup\fR, the service will be considered running as long as at least one process in the cgroup has not exited\&. +.RE +.sp +It is generally recommended to use +\fIExitType=\fR\fBmain\fR +when a service has a known forking model and a main process can reliably be determined\&. +\fIExitType=\fR +\fBcgroup\fR +is meant for applications whose forking model is not known ahead of time and which might not have a specific main process\&. It is well suited for transient or automatically generated services, such as graphical applications inside of a desktop environment\&. +.sp +Added in version 250\&. +.RE +.PP +\fIRemainAfterExit=\fR +.RS 4 +Takes a boolean value that specifies whether the service shall be considered active even when all its processes exited\&. Defaults to +\fBno\fR\&. +.RE +.PP +\fIGuessMainPID=\fR +.RS 4 +Takes a boolean value that specifies whether systemd should try to guess the main PID of a service if it cannot be determined reliably\&. This option is ignored unless +\fBType=forking\fR +is set and +\fBPIDFile=\fR +is unset because for the other types or with an explicitly configured PID file, the main PID is always known\&. The guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process\&. If the main PID cannot be determined, failure detection and automatic restarting of a service will not work reliably\&. Defaults to +\fByes\fR\&. +.RE +.PP +\fIPIDFile=\fR +.RS 4 +Takes a path referring to the PID file of the service\&. Usage of this option is recommended for services where +\fIType=\fR +is set to +\fBforking\fR\&. The path specified typically points to a file below +/run/\&. If a relative path is specified it is hence prefixed with +/run/\&. The service manager will read the PID of the main process of the service from this file after start\-up of the service\&. The service manager will not write to the file configured here, although it will remove the file after the service has shut down if it still exists\&. The PID file does not need to be owned by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced: the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging to the service\&. +.sp +Note that PID files should be avoided in modern projects\&. Use +\fBType=notify\fR, +\fBType=notify\-reload\fR +or +\fBType=simple\fR +where possible, which does not require use of PID files to determine the main process of a service and avoids needless forking\&. +.RE +.PP +\fIBusName=\fR +.RS 4 +Takes a D\-Bus destination name that this service shall use\&. This option is mandatory for services where +\fIType=\fR +is set to +\fBdbus\fR\&. It is recommended to always set this property if known to make it easy to map the service name to the D\-Bus destination\&. In particular, +\fBsystemctl service\-log\-level/service\-log\-target\fR +verbs make use of this\&. +.RE +.PP +\fIExecStart=\fR +.RS 4 +Commands that are executed when this service is started\&. The value is split into zero or more command lines according to the rules described in the section "Command Lines" below\&. +.sp +Unless +\fIType=\fR +is +\fBoneshot\fR, exactly one command must be given\&. When +\fIType=oneshot\fR +is used, zero or more commands may be specified\&. Commands may be specified by providing multiple command lines in the same directive, or alternatively, this directive may be specified more than once with the same effect\&. If the empty string is assigned to this option, the list of commands to start is reset, prior assignments of this option will have no effect\&. If no +\fIExecStart=\fR +is specified, then the service must have +\fIRemainAfterExit=yes\fR +and at least one +\fIExecStop=\fR +line set\&. (Services lacking both +\fIExecStart=\fR +and +\fIExecStop=\fR +are not valid\&.) +.sp +If more than one command is specified, the commands are invoked sequentially in the order they appear in the unit file\&. If one of the commands fails (and is not prefixed with +"\-"), other lines are not executed, and the unit is considered failed\&. +.sp +Unless +\fIType=forking\fR +is set, the process started via this command line will be considered the main process of the daemon\&. +.RE +.PP +\fIExecStartPre=\fR, \fIExecStartPost=\fR +.RS 4 +Additional commands that are executed before or after the command in +\fIExecStart=\fR, respectively\&. Syntax is the same as for +\fIExecStart=\fR, except that multiple command lines are allowed and the commands are executed one after the other, serially\&. +.sp +If any of those commands (not prefixed with +"\-") fail, the rest are not executed and the unit is considered failed\&. +.sp +\fIExecStart=\fR +commands are only run after all +\fIExecStartPre=\fR +commands that were not prefixed with a +"\-" +exit successfully\&. +.sp +\fIExecStartPost=\fR +commands are only run after the commands specified in +\fIExecStart=\fR +have been invoked successfully, as determined by +\fIType=\fR +(i\&.e\&. the process has been started for +\fIType=simple\fR +or +\fIType=idle\fR, the last +\fIExecStart=\fR +process exited successfully for +\fIType=oneshot\fR, the initial process exited successfully for +\fIType=forking\fR, +"READY=1" +is sent for +\fIType=notify\fR/\fIType=notify\-reload\fR, or the +\fIBusName=\fR +has been taken for +\fIType=dbus\fR)\&. +.sp +Note that +\fIExecStartPre=\fR +may not be used to start long\-running processes\&. All processes forked off by processes invoked via +\fIExecStartPre=\fR +will be killed before the next service process is run\&. +.sp +Note that if any of the commands specified in +\fIExecStartPre=\fR, +\fIExecStart=\fR, or +\fIExecStartPost=\fR +fail (and are not prefixed with +"\-", see above) or time out before the service is fully up, execution continues with commands specified in +\fIExecStopPost=\fR, the commands in +\fIExecStop=\fR +are skipped\&. +.sp +Note that the execution of +\fIExecStartPost=\fR +is taken into account for the purpose of +\fIBefore=\fR/\fIAfter=\fR +ordering constraints\&. +.RE +.PP +\fIExecCondition=\fR +.RS 4 +Optional commands that are executed before the commands in +\fIExecStartPre=\fR\&. Syntax is the same as for +\fIExecStart=\fR, except that multiple command lines are allowed and the commands are executed one after the other, serially\&. +.sp +The behavior is like an +\fIExecStartPre=\fR +and condition check hybrid: when an +\fIExecCondition=\fR +command exits with exit code 1 through 254 (inclusive), the remaining commands are skipped and the unit is +\fInot\fR +marked as failed\&. However, if an +\fIExecCondition=\fR +command exits with 255 or abnormally (e\&.g\&. timeout, killed by a signal, etc\&.), the unit will be considered failed (and remaining commands will be skipped)\&. Exit code of 0 or those matching +\fISuccessExitStatus=\fR +will continue execution to the next commands\&. +.sp +The same recommendations about not running long\-running processes in +\fIExecStartPre=\fR +also applies to +\fIExecCondition=\fR\&. +\fIExecCondition=\fR +will also run the commands in +\fIExecStopPost=\fR, as part of stopping the service, in the case of any non\-zero or abnormal exits, like the ones described above\&. +.sp +Added in version 243\&. +.RE +.PP +\fIExecReload=\fR +.RS 4 +Commands to execute to trigger a configuration reload in the service\&. This argument takes multiple command lines, following the same scheme as described for +\fIExecStart=\fR +above\&. Use of this setting is optional\&. Specifier and environment variable substitution is supported here following the same scheme as for +\fIExecStart=\fR\&. +.sp +One additional, special environment variable is set: if known, +\fI$MAINPID\fR +is set to the main process of the daemon, and may be used for command lines like the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ExecReload=kill \-HUP $MAINPID +.fi +.if n \{\ +.RE +.\} +.sp +Note however that reloading a daemon by enqueuing a signal (as with the example line above) is usually not a good choice, because this is an asynchronous operation and hence not suitable when ordering reloads of multiple services against each other\&. It is thus strongly recommended to either use +\fIType=\fR\fBnotify\-reload\fR +in place of +\fIExecReload=\fR, or to set +\fIExecReload=\fR +to a command that not only triggers a configuration reload of the daemon, but also synchronously waits for it to complete\&. For example, +\fBdbus-broker\fR(1) +uses the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ExecReload=busctl call org\&.freedesktop\&.DBus \e + /org/freedesktop/DBus org\&.freedesktop\&.DBus \e + ReloadConfig +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\fIExecStop=\fR +.RS 4 +Commands to execute to stop the service started via +\fIExecStart=\fR\&. This argument takes multiple command lines, following the same scheme as described for +\fIExecStart=\fR +above\&. Use of this setting is optional\&. After the commands configured in this option are run, it is implied that the service is stopped, and any processes remaining for it are terminated according to the +\fIKillMode=\fR +setting (see +\fBsystemd.kill\fR(5))\&. If this option is not specified, the process is terminated by sending the signal specified in +\fIKillSignal=\fR +or +\fIRestartKillSignal=\fR +when service stop is requested\&. Specifier and environment variable substitution is supported (including +\fI$MAINPID\fR, see above)\&. +.sp +Note that it is usually not sufficient to specify a command for this setting that only asks the service to terminate (for example, by sending some form of termination signal to it), but does not wait for it to do so\&. Since the remaining processes of the services are killed according to +\fIKillMode=\fR +and +\fIKillSignal=\fR +or +\fIRestartKillSignal=\fR +as described above immediately after the command exited, this may not result in a clean stop\&. The specified command should hence be a synchronous operation, not an asynchronous one\&. +.sp +Note that the commands specified in +\fIExecStop=\fR +are only executed when the service started successfully first\&. They are not invoked if the service was never started at all, or in case its start\-up failed, for example because any of the commands specified in +\fIExecStart=\fR, +\fIExecStartPre=\fR +or +\fIExecStartPost=\fR +failed (and weren\*(Aqt prefixed with +"\-", see above) or timed out\&. Use +\fIExecStopPost=\fR +to invoke commands when a service failed to start up correctly and is shut down again\&. Also note that the stop operation is always performed if the service started successfully, even if the processes in the service terminated on their own or were killed\&. The stop commands must be prepared to deal with that case\&. +\fI$MAINPID\fR +will be unset if systemd knows that the main process exited by the time the stop commands are called\&. +.sp +Service restart requests are implemented as stop operations followed by start operations\&. This means that +\fIExecStop=\fR +and +\fIExecStopPost=\fR +are executed during a service restart operation\&. +.sp +It is recommended to use this setting for commands that communicate with the service requesting clean termination\&. For post\-mortem clean\-up steps use +\fIExecStopPost=\fR +instead\&. +.RE +.PP +\fIExecStopPost=\fR +.RS 4 +Additional commands that are executed after the service is stopped\&. This includes cases where the commands configured in +\fIExecStop=\fR +were used, where the service does not have any +\fIExecStop=\fR +defined, or where the service exited unexpectedly\&. This argument takes multiple command lines, following the same scheme as described for +\fIExecStart=\fR\&. Use of these settings is optional\&. Specifier and environment variable substitution is supported\&. Note that \(en unlike +\fIExecStop=\fR +\(en commands specified with this setting are invoked when a service failed to start up correctly and is shut down again\&. +.sp +It is recommended to use this setting for clean\-up operations that shall be executed even when the service failed to start up correctly\&. Commands configured with this setting need to be able to operate even if the service failed starting up half\-way and left incompletely initialized data around\&. As the service\*(Aqs processes have been terminated already when the commands specified with this setting are executed they should not attempt to communicate with them\&. +.sp +Note that all commands that are configured with this setting are invoked with the result code of the service, as well as the main process\*(Aq exit code and status, set in the +\fI$SERVICE_RESULT\fR, +\fI$EXIT_CODE\fR +and +\fI$EXIT_STATUS\fR +environment variables, see +\fBsystemd.exec\fR(5) +for details\&. +.sp +Note that the execution of +\fIExecStopPost=\fR +is taken into account for the purpose of +\fIBefore=\fR/\fIAfter=\fR +ordering constraints\&. +.RE +.PP +\fIRestartSec=\fR +.RS 4 +Configures the time to sleep before restarting a service (as configured with +\fIRestart=\fR)\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Defaults to 100ms\&. +.RE +.PP +\fIRestartSteps=\fR +.RS 4 +Configures the number of steps to take to increase the interval of auto\-restarts from +\fIRestartSec=\fR +to +\fIRestartMaxDelaySec=\fR\&. Takes a positive integer or 0 to disable it\&. Defaults to 0\&. +.sp +This setting is effective only if +\fIRestartMaxDelaySec=\fR +is also set\&. +.sp +Added in version 254\&. +.RE +.PP +\fIRestartMaxDelaySec=\fR +.RS 4 +Configures the longest time to sleep before restarting a service as the interval goes up with +\fIRestartSteps=\fR\&. Takes a value in the same format as +\fIRestartSec=\fR, or +"infinity" +to disable the setting\&. Defaults to +"infinity"\&. +.sp +This setting is effective only if +\fIRestartSteps=\fR +is also set\&. +.sp +Added in version 254\&. +.RE +.PP +\fITimeoutStartSec=\fR +.RS 4 +Configures the time to wait for start\-up\&. If a daemon service does not signal start\-up completion within the configured time, the service will be considered failed and will be shut down again\&. The precise action depends on the +\fITimeoutStartFailureMode=\fR +option\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass +"infinity" +to disable the timeout logic\&. Defaults to +\fIDefaultTimeoutStartSec=\fR +set in the manager, except when +\fIType=oneshot\fR +is used, in which case the timeout is disabled by default (see +\fBsystemd-system.conf\fR(5))\&. +.sp +If a service of +\fIType=notify\fR/\fIType=notify\-reload\fR +sends +"EXTEND_TIMEOUT_USEC=\&...", this may cause the start time to be extended beyond +\fITimeoutStartSec=\fR\&. The first receipt of this message must occur before +\fITimeoutStartSec=\fR +is exceeded, and once the start time has extended beyond +\fITimeoutStartSec=\fR, the service manager will allow the service to continue to start, provided the service repeats +"EXTEND_TIMEOUT_USEC=\&..." +within the interval specified until the service startup status is finished by +"READY=1"\&. (see +\fBsd_notify\fR(3))\&. +.sp +Added in version 188\&. +.RE +.PP +\fITimeoutStopSec=\fR +.RS 4 +This option serves two purposes\&. First, it configures the time to wait for each +\fIExecStop=\fR +command\&. If any of them times out, subsequent +\fIExecStop=\fR +commands are skipped and the service will be terminated by +\fBSIGTERM\fR\&. If no +\fIExecStop=\fR +commands are specified, the service gets the +\fBSIGTERM\fR +immediately\&. This default behavior can be changed by the +\fITimeoutStopFailureMode=\fR +option\&. Second, it configures the time to wait for the service itself to stop\&. If it doesn\*(Aqt terminate in the specified time, it will be forcibly terminated by +\fBSIGKILL\fR +(see +\fIKillMode=\fR +in +\fBsystemd.kill\fR(5))\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass +"infinity" +to disable the timeout logic\&. Defaults to +\fIDefaultTimeoutStopSec=\fR +from the manager configuration file (see +\fBsystemd-system.conf\fR(5))\&. +.sp +If a service of +\fIType=notify\fR/\fIType=notify\-reload\fR +sends +"EXTEND_TIMEOUT_USEC=\&...", this may cause the stop time to be extended beyond +\fITimeoutStopSec=\fR\&. The first receipt of this message must occur before +\fITimeoutStopSec=\fR +is exceeded, and once the stop time has extended beyond +\fITimeoutStopSec=\fR, the service manager will allow the service to continue to stop, provided the service repeats +"EXTEND_TIMEOUT_USEC=\&..." +within the interval specified, or terminates itself (see +\fBsd_notify\fR(3))\&. +.sp +Added in version 188\&. +.RE +.PP +\fITimeoutAbortSec=\fR +.RS 4 +This option configures the time to wait for the service to terminate when it was aborted due to a watchdog timeout (see +\fIWatchdogSec=\fR)\&. If the service has a short +\fITimeoutStopSec=\fR +this option can be used to give the system more time to write a core dump of the service\&. Upon expiration the service will be forcibly terminated by +\fBSIGKILL\fR +(see +\fIKillMode=\fR +in +\fBsystemd.kill\fR(5))\&. The core file will be truncated in this case\&. Use +\fITimeoutAbortSec=\fR +to set a sensible timeout for the core dumping per service that is large enough to write all expected data while also being short enough to handle the service failure in due time\&. +.sp +Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass an empty value to skip the dedicated watchdog abort timeout handling and fall back +\fITimeoutStopSec=\fR\&. Pass +"infinity" +to disable the timeout logic\&. Defaults to +\fIDefaultTimeoutAbortSec=\fR +from the manager configuration file (see +\fBsystemd-system.conf\fR(5))\&. +.sp +If a service of +\fIType=notify\fR/\fIType=notify\-reload\fR +handles +\fBSIGABRT\fR +itself (instead of relying on the kernel to write a core dump) it can send +"EXTEND_TIMEOUT_USEC=\&..." +to extended the abort time beyond +\fITimeoutAbortSec=\fR\&. The first receipt of this message must occur before +\fITimeoutAbortSec=\fR +is exceeded, and once the abort time has extended beyond +\fITimeoutAbortSec=\fR, the service manager will allow the service to continue to abort, provided the service repeats +"EXTEND_TIMEOUT_USEC=\&..." +within the interval specified, or terminates itself (see +\fBsd_notify\fR(3))\&. +.sp +Added in version 243\&. +.RE +.PP +\fITimeoutSec=\fR +.RS 4 +A shorthand for configuring both +\fITimeoutStartSec=\fR +and +\fITimeoutStopSec=\fR +to the specified value\&. +.RE +.PP +\fITimeoutStartFailureMode=\fR, \fITimeoutStopFailureMode=\fR +.RS 4 +These options configure the action that is taken in case a daemon service does not signal start\-up within its configured +\fITimeoutStartSec=\fR, respectively if it does not stop within +\fITimeoutStopSec=\fR\&. Takes one of +\fBterminate\fR, +\fBabort\fR +and +\fBkill\fR\&. Both options default to +\fBterminate\fR\&. +.sp +If +\fBterminate\fR +is set the service will be gracefully terminated by sending the signal specified in +\fIKillSignal=\fR +(defaults to +\fBSIGTERM\fR, see +\fBsystemd.kill\fR(5))\&. If the service does not terminate the +\fIFinalKillSignal=\fR +is sent after +\fITimeoutStopSec=\fR\&. If +\fBabort\fR +is set, +\fIWatchdogSignal=\fR +is sent instead and +\fITimeoutAbortSec=\fR +applies before sending +\fIFinalKillSignal=\fR\&. This setting may be used to analyze services that fail to start\-up or shut\-down intermittently\&. By using +\fBkill\fR +the service is immediately terminated by sending +\fIFinalKillSignal=\fR +without any further timeout\&. This setting can be used to expedite the shutdown of failing services\&. +.sp +Added in version 246\&. +.RE +.PP +\fIRuntimeMaxSec=\fR +.RS 4 +Configures a maximum time for the service to run\&. If this is used and the service has been active for longer than the specified time it is terminated and put into a failure state\&. Note that this setting does not have any effect on +\fIType=oneshot\fR +services, as they terminate immediately after activation completed\&. Pass +"infinity" +(the default) to configure no runtime limit\&. +.sp +If a service of +\fIType=notify\fR/\fIType=notify\-reload\fR +sends +"EXTEND_TIMEOUT_USEC=\&...", this may cause the runtime to be extended beyond +\fIRuntimeMaxSec=\fR\&. The first receipt of this message must occur before +\fIRuntimeMaxSec=\fR +is exceeded, and once the runtime has extended beyond +\fIRuntimeMaxSec=\fR, the service manager will allow the service to continue to run, provided the service repeats +"EXTEND_TIMEOUT_USEC=\&..." +within the interval specified until the service shutdown is achieved by +"STOPPING=1" +(or termination)\&. (see +\fBsd_notify\fR(3))\&. +.sp +Added in version 229\&. +.RE +.PP +\fIRuntimeRandomizedExtraSec=\fR +.RS 4 +This option modifies +\fIRuntimeMaxSec=\fR +by increasing the maximum runtime by an evenly distributed duration between 0 and the specified value (in seconds)\&. If +\fIRuntimeMaxSec=\fR +is unspecified, then this feature will be disabled\&. +.sp +Added in version 250\&. +.RE +.PP +\fIWatchdogSec=\fR +.RS 4 +Configures the watchdog timeout for a service\&. The watchdog is activated when the start\-up is completed\&. The service must call +\fBsd_notify\fR(3) +regularly with +"WATCHDOG=1" +(i\&.e\&. the "keep\-alive ping")\&. If the time between two such calls is larger than the configured time, then the service is placed in a failed state and it will be terminated with +\fBSIGABRT\fR +(or the signal specified by +\fIWatchdogSignal=\fR)\&. By setting +\fIRestart=\fR +to +\fBon\-failure\fR, +\fBon\-watchdog\fR, +\fBon\-abnormal\fR +or +\fBalways\fR, the service will be automatically restarted\&. The time configured here will be passed to the executed service process in the +\fIWATCHDOG_USEC=\fR +environment variable\&. This allows daemons to automatically enable the keep\-alive pinging logic if watchdog support is enabled for the service\&. If this option is used, +\fINotifyAccess=\fR +(see below) should be set to open access to the notification socket provided by systemd\&. If +\fINotifyAccess=\fR +is not set, it will be implicitly set to +\fBmain\fR\&. Defaults to 0, which disables this feature\&. The service can check whether the service manager expects watchdog keep\-alive notifications\&. See +\fBsd_watchdog_enabled\fR(3) +for details\&. +\fBsd_event_set_watchdog\fR(3) +may be used to enable automatic watchdog notification support\&. +.RE +.PP +\fIRestart=\fR +.RS 4 +Configures whether the service shall be restarted when the service process exits, is killed, or a timeout is reached\&. The service process may be the main service process, but it may also be one of the processes specified with +\fIExecStartPre=\fR, +\fIExecStartPost=\fR, +\fIExecStop=\fR, +\fIExecStopPost=\fR, or +\fIExecReload=\fR\&. When the death of the process is a result of systemd operation (e\&.g\&. service stop or restart), the service will not be restarted\&. Timeouts include missing the watchdog "keep\-alive ping" deadline and a service start, reload, and stop operation timeouts\&. +.sp +Takes one of +\fBno\fR, +\fBon\-success\fR, +\fBon\-failure\fR, +\fBon\-abnormal\fR, +\fBon\-watchdog\fR, +\fBon\-abort\fR, or +\fBalways\fR\&. If set to +\fBno\fR +(the default), the service will not be restarted\&. If set to +\fBon\-success\fR, it will be restarted only when the service process exits cleanly\&. In this context, a clean exit means any of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +exit code of 0; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +for types other than +\fIType=oneshot\fR, one of the signals +\fBSIGHUP\fR, +\fBSIGINT\fR, +\fBSIGTERM\fR, or +\fBSIGPIPE\fR; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +exit statuses and signals specified in +\fISuccessExitStatus=\fR\&. +.RE +.sp +If set to +\fBon\-failure\fR, the service will be restarted when the process exits with a non\-zero exit code, is terminated by a signal (including on core dump, but excluding the aforementioned four signals), when an operation (such as service reload) times out, and when the configured watchdog timeout is triggered\&. If set to +\fBon\-abnormal\fR, the service will be restarted when the process is terminated by a signal (including on core dump, excluding the aforementioned four signals), when an operation times out, or when the watchdog timeout is triggered\&. If set to +\fBon\-abort\fR, the service will be restarted only if the service process exits due to an uncaught signal not specified as a clean exit status\&. If set to +\fBon\-watchdog\fR, the service will be restarted only if the watchdog timeout for the service expires\&. If set to +\fBalways\fR, the service will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by a signal, or hit a timeout\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Exit causes and the effect of the \fIRestart=\fR settings +.TS +allbox tab(:); +lB lB lB lB lB lB lB lB. +T{ +Restart settings/Exit causes +T}:T{ +\fBno\fR +T}:T{ +\fBalways\fR +T}:T{ +\fBon\-success\fR +T}:T{ +\fBon\-failure\fR +T}:T{ +\fBon\-abnormal\fR +T}:T{ +\fBon\-abort\fR +T}:T{ +\fBon\-watchdog\fR +T} +.T& +l l l l l l l l +l l l l l l l l +l l l l l l l l +l l l l l l l l +l l l l l l l l. +T{ +Clean exit code or signal +T}:T{ +\ \& +T}:T{ +X +T}:T{ +X +T}:T{ +\ \& +T}:T{ +\ \& +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +Unclean exit code +T}:T{ +\ \& +T}:T{ +X +T}:T{ +\ \& +T}:T{ +X +T}:T{ +\ \& +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +Unclean signal +T}:T{ +\ \& +T}:T{ +X +T}:T{ +\ \& +T}:T{ +X +T}:T{ +X +T}:T{ +X +T}:T{ +\ \& +T} +T{ +Timeout +T}:T{ +\ \& +T}:T{ +X +T}:T{ +\ \& +T}:T{ +X +T}:T{ +X +T}:T{ +\ \& +T}:T{ +\ \& +T} +T{ +Watchdog +T}:T{ +\ \& +T}:T{ +X +T}:T{ +\ \& +T}:T{ +X +T}:T{ +X +T}:T{ +\ \& +T}:T{ +X +T} +.TE +.sp 1 +As exceptions to the setting above, the service will not be restarted if the exit code or signal is specified in +\fIRestartPreventExitStatus=\fR +(see below) or the service is stopped with +\fBsystemctl stop\fR +or an equivalent operation\&. Also, the services will always be restarted if the exit code or signal is specified in +\fIRestartForceExitStatus=\fR +(see below)\&. +.sp +Note that service restart is subject to unit start rate limiting configured with +\fIStartLimitIntervalSec=\fR +and +\fIStartLimitBurst=\fR, see +\fBsystemd.unit\fR(5) +for details\&. +.sp +Setting this to +\fBon\-failure\fR +is the recommended choice for long\-running services, in order to increase reliability by attempting automatic recovery from errors\&. For services that shall be able to terminate on their own choice (and avoid immediate restarting), +\fBon\-abnormal\fR +is an alternative choice\&. +.RE +.PP +\fIRestartMode=\fR +.RS 4 +Takes a string value that specifies how a service should restart: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBnormal\fR +(the default), the service restarts by going through a failed/inactive state\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If set to +\fBdirect\fR, the service transitions to the activating state directly during auto\-restart, skipping failed/inactive state\&. +\fIExecStopPost=\fR +is invoked\&. +\fIOnSuccess=\fR +and +\fIOnFailure=\fR +are skipped\&. +.RE +.sp +This option is useful in cases where a dependency can fail temporarily but we don\*(Aqt want these temporary failures to make the dependent units fail\&. When this option is set to +\fBdirect\fR, dependent units are not notified of these temporary failures\&. +.sp +Added in version 254\&. +.RE +.PP +\fISuccessExitStatus=\fR +.RS 4 +Takes a list of exit status definitions that, when returned by the main service process, will be considered successful termination, in addition to the normal successful exit status 0 and, except for +\fIType=oneshot\fR, the signals +\fBSIGHUP\fR, +\fBSIGINT\fR, +\fBSIGTERM\fR, and +\fBSIGPIPE\fR\&. Exit status definitions can be numeric termination statuses, termination status names, or termination signal names, separated by spaces\&. See the Process Exit Codes section in +\fBsystemd.exec\fR(5) +for a list of termination status names (for this setting only the part without the +"EXIT_" +or +"EX_" +prefix should be used)\&. See +\fBsignal\fR(7) +for a list of signal names\&. +.sp +Note that this setting does not change the mapping between numeric exit statuses and their names, i\&.e\&. regardless how this setting is used 0 will still be mapped to +"SUCCESS" +(and thus typically shown as +"0/SUCCESS" +in tool outputs) and 1 to +"FAILURE" +(and thus typically shown as +"1/FAILURE"), and so on\&. It only controls what happens as effect of these exit statuses, and how it propagates to the state of the service as a whole\&. +.sp +This option may appear more than once, in which case the list of successful exit statuses is merged\&. If the empty string is assigned to this option, the list is reset, all prior assignments of this option will have no effect\&. +.PP +\fBExample\ \&1.\ \&A service with the \fISuccessExitStatus=\fR setting\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +SuccessExitStatus=TEMPFAIL 250 SIGKILL +.fi +.if n \{\ +.RE +.\} +.sp +Exit status 75 (\fBTEMPFAIL\fR), 250, and the termination signal +\fBSIGKILL\fR +are considered clean service terminations\&. + +Note: +\fBsystemd\-analyze exit\-status\fR +may be used to list exit statuses and translate between numerical status values and names\&. +.sp +Added in version 189\&. +.RE +.PP +\fIRestartPreventExitStatus=\fR +.RS 4 +Takes a list of exit status definitions that, when returned by the main service process, will prevent automatic service restarts, regardless of the restart setting configured with +\fIRestart=\fR\&. Exit status definitions can either be numeric exit codes or termination signal names, and are separated by spaces\&. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +RestartPreventExitStatus=1 6 SIGABRT +.fi +.if n \{\ +.RE +.\} +.sp +ensures that exit codes 1 and 6 and the termination signal +\fBSIGABRT\fR +will not result in automatic service restarting\&. This option may appear more than once, in which case the list of restart\-preventing statuses is merged\&. If the empty string is assigned to this option, the list is reset and all prior assignments of this option will have no effect\&. +.sp +Note that this setting has no effect on processes configured via +\fIExecStartPre=\fR, +\fIExecStartPost=\fR, +\fIExecStop=\fR, +\fIExecStopPost=\fR +or +\fIExecReload=\fR, but only on the main service process, i\&.e\&. either the one invoked by +\fIExecStart=\fR +or (depending on +\fIType=\fR, +\fIPIDFile=\fR, \&...) the otherwise configured main process\&. +.sp +Added in version 189\&. +.RE +.PP +\fIRestartForceExitStatus=\fR +.RS 4 +Takes a list of exit status definitions that, when returned by the main service process, will force automatic service restarts, regardless of the restart setting configured with +\fIRestart=\fR\&. The argument format is similar to +\fIRestartPreventExitStatus=\fR\&. +.sp +Added in version 215\&. +.RE +.PP +\fIRootDirectoryStartOnly=\fR +.RS 4 +Takes a boolean argument\&. If true, the root directory, as configured with the +\fIRootDirectory=\fR +option (see +\fBsystemd.exec\fR(5) +for more information), is only applied to the process started with +\fIExecStart=\fR, and not to the various other +\fIExecStartPre=\fR, +\fIExecStartPost=\fR, +\fIExecReload=\fR, +\fIExecStop=\fR, and +\fIExecStopPost=\fR +commands\&. If false, the setting is applied to all configured commands the same way\&. Defaults to false\&. +.RE +.PP +\fINonBlocking=\fR +.RS 4 +Set the +\fBO_NONBLOCK\fR +flag for all file descriptors passed via socket\-based activation\&. If true, all file descriptors >= 3 (i\&.e\&. all except stdin, stdout, stderr), excluding those passed in via the file descriptor storage logic (see +\fIFileDescriptorStoreMax=\fR +for details), will have the +\fBO_NONBLOCK\fR +flag set and hence are in non\-blocking mode\&. This option is only useful in conjunction with a socket unit, as described in +\fBsystemd.socket\fR(5) +and has no effect on file descriptors which were previously saved in the file\-descriptor store for example\&. Defaults to false\&. +.sp +Note that if the same socket unit is configured to be passed to multiple service units (via the +\fISockets=\fR +setting, see below), and these services have different +\fINonBlocking=\fR +configurations, the precise state of +\fBO_NONBLOCK\fR +depends on the order in which these services are invoked, and will possibly change after service code already took possession of the socket file descriptor, simply because the +\fBO_NONBLOCK\fR +state of a socket is shared by all file descriptors referencing it\&. Hence it is essential that all services sharing the same socket use the same +\fINonBlocking=\fR +configuration, and do not change the flag in service code either\&. +.RE +.PP +\fINotifyAccess=\fR +.RS 4 +Controls access to the service status notification socket, as accessible via the +\fBsd_notify\fR(3) +call\&. Takes one of +\fBnone\fR +(the default), +\fBmain\fR, +\fBexec\fR +or +\fBall\fR\&. If +\fBnone\fR, no daemon status updates are accepted from the service processes, all status update messages are ignored\&. If +\fBmain\fR, only service updates sent from the main process of the service are accepted\&. If +\fBexec\fR, only service updates sent from any of the main or control processes originating from one of the +\fIExec*=\fR +commands are accepted\&. If +\fBall\fR, all services updates from all members of the service\*(Aqs control group are accepted\&. This option should be set to open access to the notification socket when using +\fIType=notify\fR/\fIType=notify\-reload\fR +or +\fIWatchdogSec=\fR +(see above)\&. If those options are used but +\fINotifyAccess=\fR +is not configured, it will be implicitly set to +\fBmain\fR\&. +.sp +Note that +\fBsd_notify()\fR +notifications may be attributed to units correctly only if either the sending process is still around at the time PID 1 processes the message, or if the sending process is explicitly runtime\-tracked by the service manager\&. The latter is the case if the service manager originally forked off the process, i\&.e\&. on all processes that match +\fBmain\fR +or +\fBexec\fR\&. Conversely, if an auxiliary process of the unit sends an +\fBsd_notify()\fR +message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if +\fINotifyAccess=\fR\fBall\fR +is set for it\&. +.sp +Hence, to eliminate all race conditions involving lookup of the client\*(Aqs unit and attribution of notifications to units correctly, +\fBsd_notify_barrier()\fR +may be used\&. This call acts as a synchronization point and ensures all notifications sent before this call have been picked up by the service manager when it returns successfully\&. Use of +\fBsd_notify_barrier()\fR +is needed for clients which are not invoked by the service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the unit\&. +.RE +.PP +\fISockets=\fR +.RS 4 +Specifies the name of the socket units this service shall inherit socket file descriptors from when the service is started\&. Normally, it should not be necessary to use this setting, as all socket file descriptors whose unit shares the same name as the service (subject to the different unit name suffix of course) are passed to the spawned process\&. +.sp +Note that the same socket file descriptors may be passed to multiple processes simultaneously\&. Also note that a different service may be activated on incoming socket traffic than the one which is ultimately configured to inherit the socket file descriptors\&. Or, in other words: the +\fIService=\fR +setting of +\&.socket +units does not have to match the inverse of the +\fISockets=\fR +setting of the +\&.service +it refers to\&. +.sp +This option may appear more than once, in which case the list of socket units is merged\&. Note that once set, clearing the list of sockets again (for example, by assigning the empty string to this option) is not supported\&. +.RE +.PP +\fIFileDescriptorStoreMax=\fR +.RS 4 +Configure how many file descriptors may be stored in the service manager for the service using +\fBsd_pid_notify_with_fds\fR(3)\*(Aqs +"FDSTORE=1" +messages\&. This is useful for implementing services that can restart after an explicit request or a crash without losing state\&. Any open sockets and other file descriptors which should not be closed during the restart may be stored this way\&. Application state can either be serialized to a file in +\fIRuntimeDirectory=\fR, or stored in a +\fBmemfd_create\fR(2) +memory file descriptor\&. Defaults to 0, i\&.e\&. no file descriptors may be stored in the service manager\&. All file descriptors passed to the service manager from a specific service are passed back to the service\*(Aqs main process on the next service restart (see +\fBsd_listen_fds\fR(3) +for details about the precise protocol used and the order in which the file descriptors are passed)\&. Any file descriptors passed to the service manager are automatically closed when +\fBPOLLHUP\fR +or +\fBPOLLERR\fR +is seen on them, or when the service is fully stopped and no job is queued or being executed for it (the latter can be tweaked with +\fIFileDescriptorStorePreserve=\fR, see below)\&. If this option is used, +\fINotifyAccess=\fR +(see above) should be set to open access to the notification socket provided by systemd\&. If +\fINotifyAccess=\fR +is not set, it will be implicitly set to +\fBmain\fR\&. +.sp +The +\fBfdstore\fR +command of +\fBsystemd-analyze\fR(1) +may be used to list the current contents of a service\*(Aqs file descriptor store\&. +.sp +Note that the service manager will only pass file descriptors contained in the file descriptor store to the service\*(Aqs own processes, never to other clients via IPC or similar\&. However, it does allow unprivileged clients to query the list of currently open file descriptors of a service\&. Sensitive data may hence be safely placed inside the referenced files, but should not be attached to the metadata (e\&.g\&. included in filenames) of the stored file descriptors\&. +.sp +If this option is set to a non\-zero value the +\fI$FDSTORE\fR +environment variable will be set for processes invoked for this service\&. See +\fBsystemd.exec\fR(5) +for details\&. +.sp +For further information on the file descriptor store see the +\m[blue]\fBFile Descriptor Store\fR\m[]\&\s-2\u[1]\d\s+2 +overview\&. +.sp +Added in version 219\&. +.RE +.PP +\fIFileDescriptorStorePreserve=\fR +.RS 4 +Takes one of +\fBno\fR, +\fByes\fR, +\fBrestart\fR +and controls when to release the service\*(Aqs file descriptor store (i\&.e\&. when to close the contained file descriptors, if any)\&. If set to +\fBno\fR +the file descriptor store is automatically released when the service is stopped; if +\fBrestart\fR +(the default) it is kept around as long as the unit is neither inactive nor failed, or a job is queued for the service, or the service is expected to be restarted\&. If +\fByes\fR +the file descriptor store is kept around until the unit is removed from memory (i\&.e\&. is not referenced anymore and inactive)\&. The latter is useful to keep entries in the file descriptor store pinned until the service manager exits\&. +.sp +Use +\fBsystemctl clean \-\-what=fdstore \&...\fR +to release the file descriptor store explicitly\&. +.sp +Added in version 254\&. +.RE +.PP +\fIUSBFunctionDescriptors=\fR +.RS 4 +Configure the location of a file containing +\m[blue]\fBUSB FunctionFS\fR\m[]\&\s-2\u[2]\d\s+2 +descriptors, for implementation of USB gadget functions\&. This is used only in conjunction with a socket unit with +\fIListenUSBFunction=\fR +configured\&. The contents of this file are written to the +ep0 +file after it is opened\&. +.sp +Added in version 227\&. +.RE +.PP +\fIUSBFunctionStrings=\fR +.RS 4 +Configure the location of a file containing USB FunctionFS strings\&. Behavior is similar to +\fIUSBFunctionDescriptors=\fR +above\&. +.sp +Added in version 227\&. +.RE +.PP +\fIOOMPolicy=\fR +.RS 4 +Configure the out\-of\-memory (OOM) killing policy for the kernel and the userspace OOM killer +\fBsystemd-oomd.service\fR(8)\&. On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory for itself, it might decide to kill a running process in order to free up memory and reduce memory pressure\&. Note that +systemd\-oomd\&.service +is a more flexible solution that aims to prevent out\-of\-memory situations for the userspace too, not just the kernel, by attempting to terminate services earlier, before the kernel would have to act\&. +.sp +This setting takes one of +\fBcontinue\fR, +\fBstop\fR +or +\fBkill\fR\&. If set to +\fBcontinue\fR +and a process in the unit is killed by the OOM killer, this is logged but the unit continues running\&. If set to +\fBstop\fR +the event is logged but the unit is terminated cleanly by the service manager\&. If set to +\fBkill\fR +and one of the unit\*(Aqs processes is killed by the OOM killer the kernel is instructed to kill all remaining processes of the unit too, by setting the +memory\&.oom\&.group +attribute to +\fB1\fR; also see kernel page +\m[blue]\fBControl Group v2\fR\m[]\&\s-2\u[3]\d\s+2\&. +.sp +Defaults to the setting +\fIDefaultOOMPolicy=\fR +in +\fBsystemd-system.conf\fR(5) +is set to, except for units where +\fIDelegate=\fR +is turned on, where it defaults to +\fBcontinue\fR\&. +.sp +Use the +\fIOOMScoreAdjust=\fR +setting to configure whether processes of the unit shall be considered preferred or less preferred candidates for process termination by the Linux OOM killer logic\&. See +\fBsystemd.exec\fR(5) +for details\&. +.sp +This setting also applies to +\fBsystemd-oomd.service\fR(8)\&. Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the unit after +\fBsystemd\-oomd\fR +kills a cgroup associated with it\&. +.sp +Added in version 243\&. +.RE +.PP +\fIOpenFile=\fR +.RS 4 +Takes an argument of the form +"path[\fI:fd\-name:options\fR]", where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"path" +is a path to a file or an +\fBAF_UNIX\fR +socket in the file system; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"fd\-name" +is a name that will be associated with the file descriptor; the name may contain any ASCII character, but must exclude control characters and ":", and must be at most 255 characters in length; it is optional and, if not provided, defaults to the file name; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"options" +is a comma\-separated list of access options; possible values are +"read\-only", +"append", +"truncate", +"graceful"; if not specified, files will be opened in +\fBrw\fR +mode; if +"graceful" +is specified, errors during file/socket opening are ignored\&. Specifying the same option several times is treated as an error\&. +.RE +.sp +The file or socket is opened by the service manager and the file descriptor is passed to the service\&. If the path is a socket, we call +\fBconnect()\fR +on it\&. See +\fBsd_listen_fds\fR(3) +for more details on how to retrieve these file descriptors\&. +.sp +This setting is useful to allow services to access files/sockets that they can\*(Aqt access themselves (due to running in a separate mount namespace, not having privileges, \&.\&.\&.)\&. +.sp +This setting can be specified multiple times, in which case all the specified paths are opened and the file descriptors passed to the service\&. If the empty string is assigned, the entire list of open files defined prior to this is reset\&. +.sp +Added in version 253\&. +.RE +.PP +\fIReloadSignal=\fR +.RS 4 +Configures the UNIX process signal to send to the service\*(Aqs main process when asked to reload the service\*(Aqs configuration\&. Defaults to +\fBSIGHUP\fR\&. This option has no effect unless +\fIType=\fR\fBnotify\-reload\fR +is used, see above\&. +.sp +Added in version 253\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "COMMAND LINES" +.PP +This section describes command line parsing and variable and specifier substitutions for +\fIExecStart=\fR, +\fIExecStartPre=\fR, +\fIExecStartPost=\fR, +\fIExecReload=\fR, +\fIExecStop=\fR, and +\fIExecStopPost=\fR +options\&. +.PP +Multiple command lines may be concatenated in a single directive by separating them with semicolons (these semicolons must be passed as separate words)\&. Lone semicolons may be escaped as +"\e;"\&. +.PP +Each command line is unquoted using the rules described in "Quoting" section in +\fBsystemd.syntax\fR(7)\&. The first item becomes the command to execute, and the subsequent items the arguments\&. +.PP +This syntax is inspired by shell syntax, but only the meta\-characters and expansions described in the following paragraphs are understood, and the expansion of variables is different\&. Specifically, redirection using +"<", +"<<", +">", and +">>", pipes using +"|", running programs in the background using +"&", and +\fIother elements of shell syntax are not supported\fR\&. +.PP +The command to execute may contain spaces, but control characters are not allowed\&. +.PP +Each command may be prefixed with a number of special characters: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Special executable prefixes +.TS +allbox tab(:); +lB lB. +T{ +Prefix +T}:T{ +Effect +T} +.T& +l l +l l +l l +l l +l l +l l. +T{ +"@" +T}:T{ +If the executable path is prefixed with "@", the second specified token will be passed as \fBargv[0]\fR to the executed process (instead of the actual filename), followed by the further arguments specified\&. +T} +T{ +"\-" +T}:T{ +If the executable path is prefixed with "\-", an exit code of the command normally considered a failure (i\&.e\&. non\-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success\&. +T} +T{ +":" +T}:T{ +If the executable path is prefixed with ":", environment variable substitution (as described by the "Command Lines" section below) is not applied\&. +T} +T{ +"+" +T}:T{ +If the executable path is prefixed with "+" then the process is executed with full privileges\&. In this mode privilege restrictions configured with \fIUser=\fR, \fIGroup=\fR, \fICapabilityBoundingSet=\fR or the various file system namespacing options (such as \fIPrivateDevices=\fR, \fIPrivateTmp=\fR) are not applied to the invoked command line (but still affect any other \fIExecStart=\fR, \fIExecStop=\fR, \&... lines)\&. However, note that this will not bypass options that apply to the whole control group, such as \fIDevicePolicy=\fR, see \fBsystemd.resource-control\fR(5) for the full list\&. +T} +T{ +"!" +T}:T{ +Similar to the "+" character discussed above this permits invoking command lines with elevated privileges\&. However, unlike "+" the "!" character exclusively alters the effect of \fIUser=\fR, \fIGroup=\fR and \fISupplementaryGroups=\fR, i\&.e\&. only the stanzas that affect user and group credentials\&. Note that this setting may be combined with \fIDynamicUser=\fR, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself\&. +T} +T{ +"!!" +T}:T{ +This prefix is very similar to "!", however it only has an effect on systems lacking support for ambient process capabilities, i\&.e\&. without support for \fIAmbientCapabilities=\fR\&. It\*(Aqs intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support\&. Note that when "!!" is used, and a system lacking ambient capability support is detected any configured \fISystemCallFilter=\fR and \fICapabilityBoundingSet=\fR stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed\&. Moreover, if this prefix is used and a system lacking ambient capability support is detected \fIAmbientCapabilities=\fR will be skipped and not be applied\&. On systems supporting ambient capabilities, "!!" has no effect and is redundant\&. +T} +.TE +.sp 1 +.PP +"@", +"\-", +":", and one of +"+"/"!"/"!!" +may be used together and they can appear in any order\&. However, only one of +"+", +"!", +"!!" +may be used at a time\&. +.PP +For each command, the first argument must be either an absolute path to an executable or a simple file name without any slashes\&. If the command is not a full (absolute) path, it will be resolved to a full path using a fixed search path determined at compilation time\&. Searched directories include +/usr/local/bin/, +/usr/bin/, +/bin/ +on systems using split +/usr/bin/ +and +/bin/ +directories, and their +sbin/ +counterparts on systems using split +bin/ +and +sbin/\&. It is thus safe to use just the executable name in case of executables located in any of the "standard" directories, and an absolute path must be used in other cases\&. Hint: this search path may be queried using +\fBsystemd\-path search\-binaries\-default\fR\&. +.PP +The command line accepts +"%" +specifiers as described in +\fBsystemd.unit\fR(5)\&. +.PP +Basic environment variable substitution is supported\&. Use +"${FOO}" +as part of a word, or as a word of its own, on the command line, in which case it will be erased and replaced by the exact value of the environment variable (if any) including all whitespace it contains, always resulting in exactly a single argument\&. Use +"$FOO" +as a separate word on the command line, in which case it will be replaced by the value of the environment variable split at whitespace, resulting in zero or more arguments\&. For this type of expansion, quotes are respected when splitting into words, and afterwards removed\&. +.PP +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Environment="ONE=one" \*(AqTWO=two two\*(Aq +ExecStart=echo $ONE $TWO ${TWO} +.fi +.if n \{\ +.RE +.\} +.PP +This will execute +\fB/bin/echo\fR +with four arguments: +"one", +"two", +"two", and +"two two"\&. +.PP +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Environment=ONE=\*(Aqone\*(Aq "TWO=\*(Aqtwo\ \&two\*(Aq\ \&too" THREE= +ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} +ExecStart=/bin/echo $ONE $TWO $THREE +.fi +.if n \{\ +.RE +.\} +.PP +This results in +/bin/echo +being called twice, the first time with arguments +"\*(Aqone\*(Aq", +"\*(Aqtwo\ \&two\*(Aq\ \&too", +"", and the second time with arguments +"one", +"two\ \&two", +"too"\&. +.PP +To pass a literal dollar sign, use +"$$"\&. Variables whose value is not known at expansion time are treated as empty strings\&. Note that the first argument (i\&.e\&. the program to execute) may not be a variable\&. +.PP +Variables to be used in this fashion may be defined through +\fIEnvironment=\fR +and +\fIEnvironmentFile=\fR\&. In addition, variables listed in the section "Environment variables in spawned processes" in +\fBsystemd.exec\fR(5), which are considered "static configuration", may be used (this includes e\&.g\&. +\fI$USER\fR, but not +\fI$TERM\fR)\&. +.PP +Note that shell command lines are not directly supported\&. If shell command lines are to be used, they need to be passed explicitly to a shell implementation of some kind\&. Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ExecStart=sh \-c \*(Aqdmesg | tac\*(Aq +.fi +.if n \{\ +.RE +.\} +.PP +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ExecStart=echo one ; echo "two two" +.fi +.if n \{\ +.RE +.\} +.PP +This will execute +\fBecho\fR +two times, each time with one argument: +"one" +and +"two two", respectively\&. Because two commands are specified, +\fIType=oneshot\fR +must be used\&. +.PP +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Type=oneshot +ExecStart=:echo $USER ; \-false ; +:@true $TEST +.fi +.if n \{\ +.RE +.\} +.PP +This will execute +\fB/usr/bin/echo\fR +with the literal argument +"$USER" +(":" +suppresses variable expansion), and then +\fB/usr/bin/false\fR +(the return value will be ignored because +"\-" +suppresses checking of the return value), and +\fB/usr/bin/true\fR +(with elevated privileges, with +"$TEST" +as +\fBargv[0]\fR)\&. +.PP +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ExecStart=echo / >/dev/null & \e; \e +ls +.fi +.if n \{\ +.RE +.\} +.PP +This will execute +\fBecho\fR +with five arguments: +"/", +">/dev/null", +"&", +";", and +"ls"\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&2.\ \&Simple service\fR +.PP +The following unit file creates a service that will execute +/usr/sbin/foo\-daemon\&. Since no +\fIType=\fR +is specified, the default +\fIType=\fR\fBsimple\fR +will be assumed\&. systemd will assume the unit to be started immediately after the program has begun executing\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo\-daemon + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Note that systemd assumes here that the process started by systemd will continue running until the service terminates\&. If the program daemonizes itself (i\&.e\&. forks), please use +\fIType=\fR\fBforking\fR +instead\&. +.PP +Since no +\fIExecStop=\fR +was specified, systemd will send SIGTERM to all processes started from this service, and after a timeout also SIGKILL\&. This behavior can be modified, see +\fBsystemd.kill\fR(5) +for details\&. +.PP +Note that this unit type does not include any type of notification when a service has completed initialization\&. For this, you should use other unit types, such as +\fIType=\fR\fBnotify\fR/\fIType=\fR\fBnotify\-reload\fR +if the service understands systemd\*(Aqs notification protocol, +\fIType=\fR\fBforking\fR +if the service can background itself or +\fIType=\fR\fBdbus\fR +if the unit acquires a DBus name once initialization is complete\&. See below\&. +.PP +\fBExample\ \&3.\ \&Oneshot service\fR +.PP +Sometimes, units should just execute an action without keeping active processes, such as a filesystem check or a cleanup action on boot\&. For this, +\fIType=\fR\fBoneshot\fR +exists\&. Units of this type will wait until the process specified terminates and then fall back to being inactive\&. The following unit will perform a cleanup action: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Cleanup old Foo data + +[Service] +Type=oneshot +ExecStart=/usr/sbin/foo\-cleanup + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Note that systemd will consider the unit to be in the state "starting" until the program has terminated, so ordered dependencies will wait for the program to finish before starting themselves\&. The unit will revert to the "inactive" state after the execution is done, never reaching the "active" state\&. That means another request to start the unit will perform the action again\&. +.PP +\fIType=\fR\fBoneshot\fR +are the only service units that may have more than one +\fIExecStart=\fR +specified\&. For units with multiple commands (\fIType=oneshot\fR), all commands will be run again\&. +.PP +For +\fIType=oneshot\fR, +\fIRestart=\fR\fBalways\fR +and +\fIRestart=\fR\fBon\-success\fR +are +\fInot\fR +allowed\&. +.PP +\fBExample\ \&4.\ \&Stoppable oneshot service\fR +.PP +Similarly to the oneshot services, there are sometimes units that need to execute a program to set up something and then execute another to shut it down, but no process remains active while they are considered "started"\&. Network configuration can sometimes fall into this category\&. Another use case is if a oneshot service shall not be executed each time when they are pulled in as a dependency, but only the first time\&. +.PP +For this, systemd knows the setting +\fIRemainAfterExit=\fR\fByes\fR, which causes systemd to consider the unit to be active if the start action exited successfully\&. This directive can be used with all types, but is most useful with +\fIType=\fR\fBoneshot\fR +and +\fIType=\fR\fBsimple\fR\&. With +\fIType=\fR\fBoneshot\fR, systemd waits until the start action has completed before it considers the unit to be active, so dependencies start only after the start action has succeeded\&. With +\fIType=\fR\fBsimple\fR, dependencies will start immediately after the start action has been dispatched\&. The following unit provides an example for a simple static firewall\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Simple firewall + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/local/sbin/simple\-firewall\-start +ExecStop=/usr/local/sbin/simple\-firewall\-stop + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Since the unit is considered to be running after the start action has exited, invoking +\fBsystemctl start\fR +on that unit again will cause no action to be taken\&. +.PP +\fBExample\ \&5.\ \&Traditional forking services\fR +.PP +Many traditional daemons/services background (i\&.e\&. fork, daemonize) themselves when starting\&. Set +\fIType=\fR\fBforking\fR +in the service\*(Aqs unit file to support this mode of operation\&. systemd will consider the service to be in the process of initialization while the original program is still running\&. Once it exits successfully and at least a process remains (and +\fIRemainAfterExit=\fR\fBno\fR), the service is considered started\&. +.PP +Often, a traditional daemon only consists of one process\&. Therefore, if only one process is left after the original process terminates, systemd will consider that process the main process of the service\&. In that case, the +\fI$MAINPID\fR +variable will be available in +\fIExecReload=\fR, +\fIExecStop=\fR, etc\&. +.PP +In case more than one process remains, systemd will be unable to determine the main process, so it will not assume there is one\&. In that case, +\fI$MAINPID\fR +will not expand to anything\&. However, if the process decides to write a traditional PID file, systemd will be able to read the main PID from there\&. Please set +\fIPIDFile=\fR +accordingly\&. Note that the daemon should write that file before finishing with its initialization\&. Otherwise, systemd might try to read the file before it exists\&. +.PP +The following example shows a simple daemon that forks and just starts one process in the background: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Some simple daemon + +[Service] +Type=forking +ExecStart=/usr/sbin/my\-simple\-daemon \-d + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Please see +\fBsystemd.kill\fR(5) +for details on how you can influence the way systemd terminates the service\&. +.PP +\fBExample\ \&6.\ \&DBus services\fR +.PP +For services that acquire a name on the DBus system bus, use +\fIType=\fR\fBdbus\fR +and set +\fIBusName=\fR +accordingly\&. The service should not fork (daemonize)\&. systemd will consider the service to be initialized once the name has been acquired on the system bus\&. The following example shows a typical DBus service: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Simple DBus service + +[Service] +Type=dbus +BusName=org\&.example\&.simple\-dbus\-service +ExecStart=/usr/sbin/simple\-dbus\-service + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +For +\fIbus\-activatable\fR +services, do not include a [Install] section in the systemd service file, but use the +\fISystemdService=\fR +option in the corresponding DBus service file, for example (/usr/share/dbus\-1/system\-services/org\&.example\&.simple\-dbus\-service\&.service): +.sp +.if n \{\ +.RS 4 +.\} +.nf +[D\-BUS Service] +Name=org\&.example\&.simple\-dbus\-service +Exec=/usr/sbin/simple\-dbus\-service +User=root +SystemdService=simple\-dbus\-service\&.service +.fi +.if n \{\ +.RE +.\} +.PP +Please see +\fBsystemd.kill\fR(5) +for details on how you can influence the way systemd terminates the service\&. +.PP +\fBExample\ \&7.\ \&Services that notify systemd about their initialization\fR +.PP +\fIType=\fR\fBsimple\fR +services are really easy to write, but have the major disadvantage of systemd not being able to tell when initialization of the given service is complete\&. For this reason, systemd supports a simple notification protocol that allows daemons to make systemd aware that they are done initializing\&. Use +\fIType=\fR\fBnotify\fR +or +\fIType=\fR\fBnotify\-reload\fR +for this\&. A typical service file for such a daemon would look like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Simple notifying service + +[Service] +Type=notify +ExecStart=/usr/sbin/simple\-notifying\-service + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Note that the daemon has to support systemd\*(Aqs notification protocol, else systemd will think the service has not started yet and kill it after a timeout\&. For an example of how to update daemons to support this protocol transparently, take a look at +\fBsd_notify\fR(3)\&. systemd will consider the unit to be in the \*(Aqstarting\*(Aq state until a readiness notification has arrived\&. +.PP +Please see +\fBsystemd.kill\fR(5) +for details on how you can influence the way systemd terminates the service\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.kill\fR(5), +\fBsystemd.directives\fR(7), +\fBsystemd-run\fR(1) +.SH "NOTES" +.IP " 1." 4 +File Descriptor Store +.RS 4 +\%https://systemd.io/FILE_DESCRIPTOR_STORE +.RE +.IP " 2." 4 +USB FunctionFS +.RS 4 +\%https://docs.kernel.org/usb/functionfs.html +.RE +.IP " 3." 4 +Control Group v2 +.RS 4 +\%https://docs.kernel.org/admin-guide/cgroup-v2.html +.RE diff --git a/upstream/fedora-40/man5/systemd.slice.5 b/upstream/fedora-40/man5/systemd.slice.5 new file mode 100644 index 00000000..e4e179cc --- /dev/null +++ b/upstream/fedora-40/man5/systemd.slice.5 @@ -0,0 +1,120 @@ +'\" t +.TH "SYSTEMD\&.SLICE" "5" "" "systemd 255" "systemd.slice" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.slice \- Slice unit configuration +.SH "SYNOPSIS" +.PP +\fIslice\fR\&.slice +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.slice" +encodes information about a slice unit\&. A slice unit is a concept for hierarchically managing resources of a group of processes\&. This management is performed by creating a node in the Linux Control Group (cgroup) tree\&. Units that manage processes (primarily scope and service units) may be assigned to a specific slice\&. For each slice, certain resource limits may be set that apply to all processes of all units contained in that slice\&. Slices are organized hierarchically in a tree\&. The name of the slice encodes the location in the tree\&. The name consists of a dash\-separated series of names, which describes the path to the slice from the root slice\&. The root slice is named +\-\&.slice\&. Example: +foo\-bar\&.slice +is a slice that is located within +foo\&.slice, which in turn is located in the root slice +\-\&.slice\&. +.PP +Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating additional symlinks to its unit file\&. +.PP +By default, service and scope units are placed in +system\&.slice, virtual machines and containers registered with +\fBsystemd-machined\fR(8) +are found in +machine\&.slice, and user sessions handled by +\fBsystemd-logind\fR(8) +in +user\&.slice\&. See +\fBsystemd.special\fR(7) +for more information\&. +.PP +See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The slice specific configuration options are configured in the [Slice] section\&. Currently, only generic resource control settings as described in +\fBsystemd.resource-control\fR(5) +are allowed\&. +.PP +See the +\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2 +for an introduction on how to make use of slice units from programs\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Slice units automatically gain dependencies of type +\fIAfter=\fR +and +\fIRequires=\fR +on their immediate parent slice unit\&. +.RE +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Slice units will automatically have dependencies of type +\fIConflicts=\fR +and +\fIBefore=\fR +on +shutdown\&.target\&. These ensure that slice units are removed prior to system shutdown\&. Only slice units involved with late system shutdown should disable +\fIDefaultDependencies=\fR +option\&. +.RE +.SH "OPTIONS" +.PP +Slice unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. No options specific to this file type are supported\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.scope\fR(5), +\fBsystemd.special\fR(7), +\fBsystemd.directives\fR(7) +.SH "NOTES" +.IP " 1." 4 +New Control Group Interfaces +.RS 4 +\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface +.RE diff --git a/upstream/fedora-40/man5/systemd.socket.5 b/upstream/fedora-40/man5/systemd.socket.5 new file mode 100644 index 00000000..1cd05d5c --- /dev/null +++ b/upstream/fedora-40/man5/systemd.socket.5 @@ -0,0 +1,915 @@ +'\" t +.TH "SYSTEMD\&.SOCKET" "5" "" "systemd 255" "systemd.socket" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.socket \- Socket unit configuration +.SH "SYNOPSIS" +.PP +\fIsocket\fR\&.socket +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.socket" +encodes information about an IPC or network socket or a file system FIFO controlled and supervised by systemd, for socket\-based activation\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The socket specific configuration options are configured in the [Socket] section\&. +.PP +Additional options are listed in +\fBsystemd.exec\fR(5), which define the execution environment the +\fBExecStartPre=\fR, +\fBExecStartPost=\fR, +\fBExecStopPre=\fR +and +\fBExecStopPost=\fR +commands are executed in, and in +\fBsystemd.kill\fR(5), which define the way the processes are terminated, and in +\fBsystemd.resource-control\fR(5), which configure resource control settings for the processes of the socket\&. +.PP +For each socket unit, a matching service unit must exist, describing the service to start on incoming traffic on the socket (see +\fBsystemd.service\fR(5) +for more information about \&.service units)\&. The name of the \&.service unit is by default the same as the name of the \&.socket unit, but can be altered with the +\fBService=\fR +option described below\&. Depending on the setting of the +\fBAccept=\fR +option described below, this \&.service unit must either be named like the \&.socket unit, but with the suffix replaced, unless overridden with +\fBService=\fR; or it must be a template unit named the same way\&. Example: a socket file +foo\&.socket +needs a matching service +foo\&.service +if +\fBAccept=no\fR +is set\&. If +\fBAccept=yes\fR +is set, a service template +foo@\&.service +must exist from which services are instantiated for each incoming connection\&. +.PP +No implicit +\fIWantedBy=\fR +or +\fIRequiredBy=\fR +dependency from the socket to the service is added\&. This means that the service may be started without the socket, in which case it must be able to open sockets by itself\&. To prevent this, an explicit +\fIRequires=\fR +dependency may be added\&. +.PP +Socket units may be used to implement on\-demand starting of services, as well as parallelized starting of services\&. See the blog stories linked at the end for an introduction\&. +.PP +Note that the daemon software configured for socket activation with socket units needs to be able to accept sockets from systemd, either via systemd\*(Aqs native socket passing interface (see +\fBsd_listen_fds\fR(3) +for details about the precise protocol used and the order in which the file descriptors are passed) or via traditional +\fBinetd\fR(8)\-style socket passing (i\&.e\&. sockets passed in via standard input and output, using +\fIStandardInput=socket\fR +in the service file)\&. +.PP +All network sockets allocated through +\&.socket +units are allocated in the host\*(Aqs network namespace (see +\fBnetwork_namespaces\fR(7))\&. This does not mean however that the service activated by a configured socket unit has to be part of the host\*(Aqs network namespace as well\&. It is supported and even good practice to run services in their own network namespace (for example through +\fIPrivateNetwork=\fR, see +\fBsystemd.exec\fR(5)), receiving only the sockets configured through socket\-activation from the host\*(Aqs namespace\&. In such a set\-up communication within the host\*(Aqs network namespace is only permitted through the activation sockets passed in while all sockets allocated from the service code itself will be associated with the service\*(Aqs own namespace, and thus possibly subject to a restrictive configuration\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Socket units automatically gain a +\fIBefore=\fR +dependency on the service units they activate\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Socket units referring to file system paths (such as +\fBAF_UNIX\fR +sockets or FIFOs) implicitly gain +\fIRequires=\fR +and +\fIAfter=\fR +dependencies on all mount units necessary to access those paths\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Socket units using the +\fIBindToDevice=\fR +setting automatically gain a +\fIBindsTo=\fR +and +\fIAfter=\fR +dependency on the device unit encapsulating the specified network interface\&. +.RE +.PP +Additional implicit dependencies may be added as result of execution and resource control parameters as documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.resource-control\fR(5)\&. +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Socket units automatically gain a +\fIBefore=\fR +dependency on +sockets\&.target\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Socket units automatically gain a pair of +\fIAfter=\fR +and +\fIRequires=\fR +dependency on +sysinit\&.target, and a pair of +\fIBefore=\fR +and +\fIConflicts=\fR +dependencies on +shutdown\&.target\&. These dependencies ensure that the socket unit is started before normal services at boot, and is stopped on shutdown\&. Only sockets involved with early boot or late system shutdown should disable +\fIDefaultDependencies=\fR +option\&. +.RE +.SH "OPTIONS" +.PP +Socket unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Socket unit files must include a [Socket] section, which carries information about the socket or FIFO it supervises\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.kill\fR(5)\&. The options specific to the [Socket] section of socket units are the following: +.PP +\fIListenStream=\fR, \fIListenDatagram=\fR, \fIListenSequentialPacket=\fR +.RS 4 +Specifies an address to listen on for a stream (\fBSOCK_STREAM\fR), datagram (\fBSOCK_DGRAM\fR), or sequential packet (\fBSOCK_SEQPACKET\fR) socket, respectively\&. The address can be written in various formats: +.sp +If the address starts with a slash ("/"), it is read as file system socket in the +\fBAF_UNIX\fR +socket family\&. +.sp +If the address starts with an at symbol ("@"), it is read as abstract namespace socket in the +\fBAF_UNIX\fR +family\&. The +"@" +is replaced with a +\fBNUL\fR +character before binding\&. For details, see +\fBunix\fR(7)\&. +.sp +If the address string is a single number, it is read as port number to listen on via IPv6\&. Depending on the value of +\fIBindIPv6Only=\fR +(see below) this might result in the service being available via both IPv6 and IPv4 (default) or just via IPv6\&. +.sp +If the address string is a string in the format +"\fIv\&.w\&.x\&.y\fR:\fIz\fR", it is interpreted as IPv4 address +\fIv\&.w\&.x\&.y\fR +and port +\fIz\fR\&. +.sp +If the address string is a string in the format +"[\fIx\fR]:\fIy\fR", it is interpreted as IPv6 address +\fIx\fR +and port +\fIy\fR\&. An optional interface scope (interface name or number) may be specified after a +"%" +symbol: +"[\fIx\fR]:\fIy\fR%\fIdev\fR"\&. Interface scopes are only useful with link\-local addresses, because the kernel ignores them in other cases\&. Note that if an address is specified as IPv6, it might still make the service available via IPv4 too, depending on the +\fIBindIPv6Only=\fR +setting (see below)\&. +.sp +If the address string is a string in the format +"vsock:\fIx\fR:\fIy\fR", it is read as CID +\fIx\fR +on a port +\fIy\fR +address in the +\fBAF_VSOCK\fR +family\&. The CID is a unique 32\-bit integer identifier in +\fBAF_VSOCK\fR +analogous to an IP address\&. Specifying the CID is optional, and may be set to the empty string\&. +.sp +Note that +\fBSOCK_SEQPACKET\fR +(i\&.e\&. +\fIListenSequentialPacket=\fR) is only available for +\fBAF_UNIX\fR +sockets\&. +\fBSOCK_STREAM\fR +(i\&.e\&. +\fIListenStream=\fR) when used for IP sockets refers to TCP sockets, +\fBSOCK_DGRAM\fR +(i\&.e\&. +\fIListenDatagram=\fR) to UDP\&. +.sp +These options may be specified more than once, in which case incoming traffic on any of the sockets will trigger service activation, and all listed sockets will be passed to the service, regardless of whether there is incoming traffic on them or not\&. If the empty string is assigned to any of these options, the list of addresses to listen on is reset, all prior uses of any of these options will have no effect\&. +.sp +It is also possible to have more than one socket unit for the same service when using +\fIService=\fR, and the service will receive all the sockets configured in all the socket units\&. Sockets configured in one unit are passed in the order of configuration, but no ordering between socket units is specified\&. +.sp +If an IP address is used here, it is often desirable to listen on it before the interface it is configured on is up and running, and even regardless of whether it will be up and running at any point\&. To deal with this, it is recommended to set the +\fIFreeBind=\fR +option described below\&. +.RE +.PP +\fIListenFIFO=\fR +.RS 4 +Specifies a file system FIFO (see +\fBfifo\fR(7) +for details) to listen on\&. This expects an absolute file system path as argument\&. Behavior otherwise is very similar to the +\fIListenDatagram=\fR +directive above\&. +.RE +.PP +\fIListenSpecial=\fR +.RS 4 +Specifies a special file in the file system to listen on\&. This expects an absolute file system path as argument\&. Behavior otherwise is very similar to the +\fIListenFIFO=\fR +directive above\&. Use this to open character device nodes as well as special files in +/proc/ +and +/sys/\&. +.RE +.PP +\fIListenNetlink=\fR +.RS 4 +Specifies a Netlink family to create a socket for to listen on\&. This expects a short string referring to the +\fBAF_NETLINK\fR +family name (such as +\fIaudit\fR +or +\fIkobject\-uevent\fR) as argument, optionally suffixed by a whitespace followed by a multicast group integer\&. Behavior otherwise is very similar to the +\fIListenDatagram=\fR +directive above\&. +.RE +.PP +\fIListenMessageQueue=\fR +.RS 4 +Specifies a POSIX message queue name to listen on (see +\fBmq_overview\fR(7) +for details)\&. This expects a valid message queue name (i\&.e\&. beginning with +"/")\&. Behavior otherwise is very similar to the +\fIListenFIFO=\fR +directive above\&. On Linux message queue descriptors are actually file descriptors and can be inherited between processes\&. +.RE +.PP +\fIListenUSBFunction=\fR +.RS 4 +Specifies a +\m[blue]\fBUSB FunctionFS\fR\m[]\&\s-2\u[1]\d\s+2 +endpoints location to listen on, for implementation of USB gadget functions\&. This expects an absolute file system path of a FunctionFS mount point as the argument\&. Behavior otherwise is very similar to the +\fIListenFIFO=\fR +directive above\&. Use this to open the FunctionFS endpoint +ep0\&. When using this option, the activated service has to have the +\fIUSBFunctionDescriptors=\fR +and +\fIUSBFunctionStrings=\fR +options set\&. +.sp +Added in version 227\&. +.RE +.PP +\fISocketProtocol=\fR +.RS 4 +Takes one of +\fBudplite\fR +or +\fBsctp\fR\&. The socket will use the UDP\-Lite (\fBIPPROTO_UDPLITE\fR) or SCTP (\fBIPPROTO_SCTP\fR) protocol, respectively\&. +.sp +Added in version 229\&. +.RE +.PP +\fIBindIPv6Only=\fR +.RS 4 +Takes one of +\fBdefault\fR, +\fBboth\fR +or +\fBipv6\-only\fR\&. Controls the IPV6_V6ONLY socket option (see +\fBipv6\fR(7) +for details)\&. If +\fBboth\fR, IPv6 sockets bound will be accessible via both IPv4 and IPv6\&. If +\fBipv6\-only\fR, they will be accessible via IPv6 only\&. If +\fBdefault\fR +(which is the default, surprise!), the system wide default setting is used, as controlled by +/proc/sys/net/ipv6/bindv6only, which in turn defaults to the equivalent of +\fBboth\fR\&. +.RE +.PP +\fIBacklog=\fR +.RS 4 +Takes an unsigned 32\-bit integer argument\&. Specifies the number of connections to queue that have not been accepted yet\&. This setting matters only for stream and sequential packet sockets\&. See +\fBlisten\fR(2) +for details\&. Defaults to 4294967295\&. Note that this value is silently capped by the +"net\&.core\&.somaxconn" +sysctl, which typically defaults to 4096, so typically the sysctl is the setting that actually matters\&. +.RE +.PP +\fIBindToDevice=\fR +.RS 4 +Specifies a network interface name to bind this socket to\&. If set, traffic will only be accepted from the specified network interfaces\&. This controls the +\fBSO_BINDTODEVICE\fR +socket option (see +\fBsocket\fR(7) +for details)\&. If this option is used, an implicit dependency from this socket unit on the network interface device unit is created (see +\fBsystemd.device\fR(5))\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&. +.RE +.PP +\fISocketUser=\fR, \fISocketGroup=\fR +.RS 4 +Takes a UNIX user/group name\&. When specified, all +\fBAF_UNIX\fR +sockets and FIFO nodes in the file system are owned by the specified user and group\&. If unset (the default), the nodes are owned by the root user/group (if run in system context) or the invoking user/group (if run in user context)\&. If only a user is specified but no group, then the group is derived from the user\*(Aqs default group\&. +.sp +Added in version 214\&. +.RE +.PP +\fISocketMode=\fR +.RS 4 +If listening on a file system socket or FIFO, this option specifies the file system access mode used when creating the file node\&. Takes an access mode in octal notation\&. Defaults to 0666\&. +.RE +.PP +\fIDirectoryMode=\fR +.RS 4 +If listening on a file system socket or FIFO, the parent directories are automatically created if needed\&. This option specifies the file system access mode used when creating these directories\&. Takes an access mode in octal notation\&. Defaults to 0755\&. +.RE +.PP +\fIAccept=\fR +.RS 4 +Takes a boolean argument\&. If yes, a service instance is spawned for each incoming connection and only the connection socket is passed to it\&. If no, all listening sockets themselves are passed to the started service unit, and only one service unit is spawned for all connections (also see above)\&. This value is ignored for datagram sockets and FIFOs where a single service unit unconditionally handles all incoming traffic\&. Defaults to +\fBno\fR\&. For performance reasons, it is recommended to write new daemons only in a way that is suitable for +\fBAccept=no\fR\&. A daemon listening on an +\fBAF_UNIX\fR +socket may, but does not need to, call +\fBclose\fR(2) +on the received socket before exiting\&. However, it must not unlink the socket from a file system\&. It should not invoke +\fBshutdown\fR(2) +on sockets it got with +\fIAccept=no\fR, but it may do so for sockets it got with +\fIAccept=yes\fR +set\&. Setting +\fIAccept=yes\fR +is mostly useful to allow daemons designed for usage with +\fBinetd\fR(8) +to work unmodified with systemd socket activation\&. +.sp +Note that depending on this setting the services activated by units of this type are either regular services (in case of +\fIAccept=\fR\fBno\fR) or instances of templated services (in case of +\fIAccept=\fR\fByes\fR)\&. See the Description section above for a more detailed discussion of the naming rules of triggered services\&. +.sp +For IPv4 and IPv6 connections, the +\fIREMOTE_ADDR\fR +environment variable will contain the remote IP address, and +\fIREMOTE_PORT\fR +will contain the remote port\&. This is the same as the format used by CGI\&. For +\fBSOCK_RAW\fR, the port is the IP protocol\&. +.sp +It is recommended to set +\fICollectMode=inactive\-or\-failed\fR +for service instances activated via +\fIAccept=yes\fR, to ensure that failed connection services are cleaned up and released from memory, and do not accumulate\&. +.RE +.PP +\fIWritable=\fR +.RS 4 +Takes a boolean argument\&. May only be used in conjunction with +\fIListenSpecial=\fR\&. If true, the specified special file is opened in read\-write mode, if false, in read\-only mode\&. Defaults to false\&. +.sp +Added in version 227\&. +.RE +.PP +\fIFlushPending=\fR +.RS 4 +Takes a boolean argument\&. May only be used when +\fBAccept=no\fR\&. If yes, the socket\*(Aqs buffers are cleared after the triggered service exited\&. This causes any pending data to be flushed and any pending incoming connections to be rejected\&. If no, the socket\*(Aqs buffers won\*(Aqt be cleared, permitting the service to handle any pending connections after restart, which is the usually expected behaviour\&. Defaults to +\fBno\fR\&. +.sp +Added in version 247\&. +.RE +.PP +\fIMaxConnections=\fR +.RS 4 +The maximum number of connections to simultaneously run services instances for, when +\fBAccept=yes\fR +is set\&. If more concurrent connections are coming in, they will be refused until at least one existing connection is terminated\&. This setting has no effect on sockets configured with +\fBAccept=no\fR +or datagram sockets\&. Defaults to 64\&. +.RE +.PP +\fIMaxConnectionsPerSource=\fR +.RS 4 +The maximum number of connections for a service per source IP address\&. This is very similar to the +\fIMaxConnections=\fR +directive above\&. Disabled by default\&. +.sp +Added in version 232\&. +.RE +.PP +\fIKeepAlive=\fR +.RS 4 +Takes a boolean argument\&. If true, the TCP/IP stack will send a keep alive message after 2h (depending on the configuration of +/proc/sys/net/ipv4/tcp_keepalive_time) for all TCP streams accepted on this socket\&. This controls the +\fBSO_KEEPALIVE\fR +socket option (see +\fBsocket\fR(7) +and the +\m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2 +for details\&.) Defaults to +\fBfalse\fR\&. +.RE +.PP +\fIKeepAliveTimeSec=\fR +.RS 4 +Takes time (in seconds) as argument\&. The connection needs to remain idle before TCP starts sending keepalive probes\&. This controls the TCP_KEEPIDLE socket option (see +\fBsocket\fR(7) +and the +\m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2 +for details\&.) Default value is 7200 seconds (2 hours)\&. +.sp +Added in version 216\&. +.RE +.PP +\fIKeepAliveIntervalSec=\fR +.RS 4 +Takes time (in seconds) as argument between individual keepalive probes, if the socket option +\fBSO_KEEPALIVE\fR +has been set on this socket\&. This controls the +\fBTCP_KEEPINTVL\fR +socket option (see +\fBsocket\fR(7) +and the +\m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2 +for details\&.) Default value is 75 seconds\&. +.sp +Added in version 216\&. +.RE +.PP +\fIKeepAliveProbes=\fR +.RS 4 +Takes an integer as argument\&. It is the number of unacknowledged probes to send before considering the connection dead and notifying the application layer\&. This controls the TCP_KEEPCNT socket option (see +\fBsocket\fR(7) +and the +\m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2 +for details\&.) Default value is 9\&. +.sp +Added in version 216\&. +.RE +.PP +\fINoDelay=\fR +.RS 4 +Takes a boolean argument\&. TCP Nagle\*(Aqs algorithm works by combining a number of small outgoing messages, and sending them all at once\&. This controls the TCP_NODELAY socket option (see +\fBtcp\fR(7))\&. Defaults to +\fBfalse\fR\&. +.sp +Added in version 216\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +Takes an integer argument controlling the priority for all traffic sent from this socket\&. This controls the +\fBSO_PRIORITY\fR +socket option (see +\fBsocket\fR(7) +for details\&.)\&. +.RE +.PP +\fIDeferAcceptSec=\fR +.RS 4 +Takes time (in seconds) as argument\&. If set, the listening process will be awakened only when data arrives on the socket, and not immediately when connection is established\&. When this option is set, the +\fBTCP_DEFER_ACCEPT\fR +socket option will be used (see +\fBtcp\fR(7)), and the kernel will ignore initial ACK packets without any data\&. The argument specifies the approximate amount of time the kernel should wait for incoming data before falling back to the normal behavior of honoring empty ACK packets\&. This option is beneficial for protocols where the client sends the data first (e\&.g\&. HTTP, in contrast to SMTP), because the server process will not be woken up unnecessarily before it can take any action\&. +.sp +If the client also uses the +\fBTCP_DEFER_ACCEPT\fR +option, the latency of the initial connection may be reduced, because the kernel will send data in the final packet establishing the connection (the third packet in the "three\-way handshake")\&. +.sp +Disabled by default\&. +.sp +Added in version 216\&. +.RE +.PP +\fIReceiveBuffer=\fR, \fISendBuffer=\fR +.RS 4 +Takes an integer argument controlling the receive or send buffer sizes of this socket, respectively\&. This controls the +\fBSO_RCVBUF\fR +and +\fBSO_SNDBUF\fR +socket options (see +\fBsocket\fR(7) +for details\&.)\&. The usual suffixes K, M, G are supported and are understood to the base of 1024\&. +.RE +.PP +\fIIPTOS=\fR +.RS 4 +Takes an integer argument controlling the IP Type\-Of\-Service field for packets generated from this socket\&. This controls the +\fBIP_TOS\fR +socket option (see +\fBip\fR(7) +for details\&.)\&. Either a numeric string or one of +\fBlow\-delay\fR, +\fBthroughput\fR, +\fBreliability\fR +or +\fBlow\-cost\fR +may be specified\&. +.RE +.PP +\fIIPTTL=\fR +.RS 4 +Takes an integer argument controlling the IPv4 Time\-To\-Live/IPv6 Hop\-Count field for packets generated from this socket\&. This sets the +\fBIP_TTL\fR/\fBIPV6_UNICAST_HOPS\fR +socket options (see +\fBip\fR(7) +and +\fBipv6\fR(7) +for details\&.) +.RE +.PP +\fIMark=\fR +.RS 4 +Takes an integer value\&. Controls the firewall mark of packets generated by this socket\&. This can be used in the firewall logic to filter packets from this socket\&. This sets the +\fBSO_MARK\fR +socket option\&. See +\fBiptables\fR(8) +for details\&. +.RE +.PP +\fIReusePort=\fR +.RS 4 +Takes a boolean value\&. If true, allows multiple +\fBbind\fR(2)s to this TCP or UDP port\&. This controls the +\fBSO_REUSEPORT\fR +socket option\&. See +\fBsocket\fR(7) +for details\&. +.sp +Added in version 206\&. +.RE +.PP +\fISmackLabel=\fR, \fISmackLabelIPIn=\fR, \fISmackLabelIPOut=\fR +.RS 4 +Takes a string value\&. Controls the extended attributes +"security\&.SMACK64", +"security\&.SMACK64IPIN" +and +"security\&.SMACK64IPOUT", respectively, i\&.e\&. the security label of the FIFO, or the security label for the incoming or outgoing connections of the socket, respectively\&. See +\m[blue]\fBSmack\fR\m[]\&\s-2\u[3]\d\s+2 +for details\&. +.sp +Added in version 196\&. +.RE +.PP +\fISELinuxContextFromNet=\fR +.RS 4 +Takes a boolean argument\&. When true, systemd will attempt to figure out the SELinux label used for the instantiated service from the information handed by the peer over the network\&. Note that only the security level is used from the information provided by the peer\&. Other parts of the resulting SELinux context originate from either the target binary that is effectively triggered by socket unit or from the value of the +\fISELinuxContext=\fR +option\&. This configuration option applies only when activated service is passed in single socket file descriptor, i\&.e\&. service instances that have standard input connected to a socket or services triggered by exactly one socket unit\&. Also note that this option is useful only when MLS/MCS SELinux policy is deployed\&. Defaults to +"false"\&. +.sp +Added in version 217\&. +.RE +.PP +\fIPipeSize=\fR +.RS 4 +Takes a size in bytes\&. Controls the pipe buffer size of FIFOs configured in this socket unit\&. See +\fBfcntl\fR(2) +for details\&. The usual suffixes K, M, G are supported and are understood to the base of 1024\&. +.RE +.PP +\fIMessageQueueMaxMessages=\fR, \fIMessageQueueMessageSize=\fR +.RS 4 +These two settings take integer values and control the mq_maxmsg field or the mq_msgsize field, respectively, when creating the message queue\&. Note that either none or both of these variables need to be set\&. See +\fBmq_setattr\fR(3) +for details\&. +.RE +.PP +\fIFreeBind=\fR +.RS 4 +Takes a boolean value\&. Controls whether the socket can be bound to non\-local IP addresses\&. This is useful to configure sockets listening on specific IP addresses before those IP addresses are successfully configured on a network interface\&. This sets the +\fBIP_FREEBIND\fR/\fBIPV6_FREEBIND\fR +socket option\&. For robustness reasons it is recommended to use this option whenever you bind a socket to a specific IP address\&. Defaults to +\fBfalse\fR\&. +.RE +.PP +\fITransparent=\fR +.RS 4 +Takes a boolean value\&. Controls the +\fBIP_TRANSPARENT\fR/\fBIPV6_TRANSPARENT\fR +socket option\&. Defaults to +\fBfalse\fR\&. +.RE +.PP +\fIBroadcast=\fR +.RS 4 +Takes a boolean value\&. This controls the +\fBSO_BROADCAST\fR +socket option, which allows broadcast datagrams to be sent from this socket\&. Defaults to +\fBfalse\fR\&. +.RE +.PP +\fIPassCredentials=\fR +.RS 4 +Takes a boolean value\&. This controls the +\fBSO_PASSCRED\fR +socket option, which allows +\fBAF_UNIX\fR +sockets to receive the credentials of the sending process in an ancillary message\&. Defaults to +\fBfalse\fR\&. +.RE +.PP +\fIPassSecurity=\fR +.RS 4 +Takes a boolean value\&. This controls the +\fBSO_PASSSEC\fR +socket option, which allows +\fBAF_UNIX\fR +sockets to receive the security context of the sending process in an ancillary message\&. Defaults to +\fBfalse\fR\&. +.RE +.PP +\fIPassPacketInfo=\fR +.RS 4 +Takes a boolean value\&. This controls the +\fBIP_PKTINFO\fR, +\fBIPV6_RECVPKTINFO\fR, +\fBNETLINK_PKTINFO\fR +or +\fBPACKET_AUXDATA\fR +socket options, which enable reception of additional per\-packet metadata as ancillary message, on +\fBAF_INET\fR, +\fBAF_INET6\fR, +\fBAF_UNIX\fR +and +\fBAF_PACKET\fR +sockets\&. Defaults to +\fBfalse\fR\&. +.sp +Added in version 246\&. +.RE +.PP +\fITimestamping=\fR +.RS 4 +Takes one of +"off", +"us" +(alias: +"usec", +"μs") or +"ns" +(alias: +"nsec")\&. This controls the +\fBSO_TIMESTAMP\fR +or +\fBSO_TIMESTAMPNS\fR +socket options, and enables whether ingress network traffic shall carry timestamping metadata\&. Defaults to +\fBoff\fR\&. +.sp +Added in version 247\&. +.RE +.PP +\fITCPCongestion=\fR +.RS 4 +Takes a string value\&. Controls the TCP congestion algorithm used by this socket\&. Should be one of +"westwood", +"veno", +"cubic", +"lp" +or any other available algorithm supported by the IP stack\&. This setting applies only to stream sockets\&. +.RE +.PP +\fIExecStartPre=\fR, \fIExecStartPost=\fR +.RS 4 +Takes one or more command lines, which are executed before or after the listening sockets/FIFOs are created and bound, respectively\&. The first token of the command line must be an absolute filename, then followed by arguments for the process\&. Multiple command lines may be specified following the same scheme as used for +\fIExecStartPre=\fR +of service unit files\&. +.RE +.PP +\fIExecStopPre=\fR, \fIExecStopPost=\fR +.RS 4 +Additional commands that are executed before or after the listening sockets/FIFOs are closed and removed, respectively\&. Multiple command lines may be specified following the same scheme as used for +\fIExecStartPre=\fR +of service unit files\&. +.RE +.PP +\fITimeoutSec=\fR +.RS 4 +Configures the time to wait for the commands specified in +\fIExecStartPre=\fR, +\fIExecStartPost=\fR, +\fIExecStopPre=\fR +and +\fIExecStopPost=\fR +to finish\&. If a command does not exit within the configured time, the socket will be considered failed and be shut down again\&. All commands still running will be terminated forcibly via +\fBSIGTERM\fR, and after another delay of this time with +\fBSIGKILL\fR\&. (See +\fBKillMode=\fR +in +\fBsystemd.kill\fR(5)\&.) Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass +"0" +to disable the timeout logic\&. Defaults to +\fIDefaultTimeoutStartSec=\fR +from the manager configuration file (see +\fBsystemd-system.conf\fR(5))\&. +.RE +.PP +\fIService=\fR +.RS 4 +Specifies the service unit name to activate on incoming traffic\&. This setting is only allowed for sockets with +\fIAccept=no\fR\&. It defaults to the service that bears the same name as the socket (with the suffix replaced)\&. In most cases, it should not be necessary to use this option\&. Note that setting this parameter might result in additional dependencies to be added to the unit (see above)\&. +.RE +.PP +\fIRemoveOnStop=\fR +.RS 4 +Takes a boolean argument\&. If enabled, any file nodes created by this socket unit are removed when it is stopped\&. This applies to +\fBAF_UNIX\fR +sockets in the file system, POSIX message queues, FIFOs, as well as any symlinks to them configured with +\fISymlinks=\fR\&. Normally, it should not be necessary to use this option, and is not recommended as services might continue to run after the socket unit has been terminated and it should still be possible to communicate with them via their file system node\&. Defaults to off\&. +.sp +Added in version 214\&. +.RE +.PP +\fISymlinks=\fR +.RS 4 +Takes a list of file system paths\&. The specified paths will be created as symlinks to the +\fBAF_UNIX\fR +socket path or FIFO path of this socket unit\&. If this setting is used, only one +\fBAF_UNIX\fR +socket in the file system or one FIFO may be configured for the socket unit\&. Use this option to manage one or more symlinked alias names for a socket, binding their lifecycle together\&. Note that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may still start\&. If an empty string is assigned, the list of paths is reset\&. Defaults to an empty list\&. +.sp +Added in version 214\&. +.RE +.PP +\fIFileDescriptorName=\fR +.RS 4 +Assigns a name to all file descriptors this socket unit encapsulates\&. This is useful to help activated services identify specific file descriptors, if multiple fds are passed\&. Services may use the +\fBsd_listen_fds_with_names\fR(3) +call to acquire the names configured for the received file descriptors\&. Names may contain any ASCII character, but must exclude control characters and +":", and must be at most 255 characters in length\&. If this setting is not used, the file descriptor name defaults to the name of the socket unit, including its +\&.socket +suffix\&. +.sp +Added in version 227\&. +.RE +.PP +\fITriggerLimitIntervalSec=\fR, \fITriggerLimitBurst=\fR +.RS 4 +Configures a limit on how often this socket unit may be activated within a specific time interval\&. The +\fITriggerLimitIntervalSec=\fR +setting may be used to configure the length of the time interval in the usual time units +"us", +"ms", +"s", +"min", +"h", \&... and defaults to 2s (See +\fBsystemd.time\fR(7) +for details on the various time units understood)\&. The +\fITriggerLimitBurst=\fR +setting takes a positive integer value and specifies the number of permitted activations per time interval, and defaults to 200 for +\fIAccept=yes\fR +sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 activations per 2s)\&. Set either to 0 to disable any form of trigger rate limiting\&. +.sp +If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible anymore until restarted\&. Note that this limit is enforced before the service activation is enqueued\&. +.sp +Compare with +\fIPollLimitIntervalSec=\fR/\fIPollLimitBurst=\fR +described below, which implements a temporary slowdown if a socket unit is flooded with incoming traffic, as opposed to the permanent failure state +\fITriggerLimitIntervalSec=\fR/\fITriggerLimitBurst=\fR +results in\&. +.sp +Added in version 230\&. +.RE +.PP +\fIPollLimitIntervalSec=\fR, \fIPollLimitBurst=\fR +.RS 4 +Configures a limit on how often polling events on the file descriptors backing this socket unit will be considered\&. This pair of settings is similar to +\fITriggerLimitIntervalSec=\fR/\fITriggerLimitBurst=\fR +but instead of putting a (fatal) limit on the activation frequency puts a (transient) limit on the polling frequency\&. The expected parameter syntax and range are identical to that of the aforementioned options, and can be disabled the same way\&. +.sp +If the polling limit is hit polling is temporarily disabled on it until the specified time window passes\&. The polling limit hence slows down connection attempts if hit, but unlike the trigger limit won\*(Aqt cause permanent failures\&. It\*(Aqs the recommended mechanism to deal with DoS attempts through packet flooding\&. +.sp +The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit which is enforced for the entire socket unit\&. This distinction matters for socket units that listen on multiple file descriptors (i\&.e\&. have multiple +\fIListenXYZ=\fR +stanzas)\&. +.sp +These setting defaults to 150 (in case of +\fIAccept=yes\fR) and 15 (otherwise) polling events per 2s\&. This is considerably lower than the default values for the trigger limit (see above) and means that the polling limit should typically ensure the trigger limit is never hit, unless one of them is reconfigured or disabled\&. +.sp +Added in version 255\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.kill\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.directives\fR(7), +\fBsd_listen_fds\fR(3), +\fBsd_listen_fds_with_names\fR(3) +.PP +For more extensive descriptions see the "systemd for Developers" series: +\m[blue]\fBSocket Activation\fR\m[]\&\s-2\u[4]\d\s+2, +\m[blue]\fBSocket Activation, part II\fR\m[]\&\s-2\u[5]\d\s+2, +\m[blue]\fBConverting inetd Services\fR\m[]\&\s-2\u[6]\d\s+2, +\m[blue]\fBSocket Activated Internet Services and OS Containers\fR\m[]\&\s-2\u[7]\d\s+2\&. +.SH "NOTES" +.IP " 1." 4 +USB FunctionFS +.RS 4 +\%https://docs.kernel.org/usb/functionfs.html +.RE +.IP " 2." 4 +TCP Keepalive HOWTO +.RS 4 +\%http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/ +.RE +.IP " 3." 4 +Smack +.RS 4 +\%https://docs.kernel.org/admin-guide/LSM/Smack.html +.RE +.IP " 4." 4 +Socket Activation +.RS 4 +\%https://0pointer.de/blog/projects/socket-activation.html +.RE +.IP " 5." 4 +Socket Activation, part II +.RS 4 +\%https://0pointer.de/blog/projects/socket-activation2.html +.RE +.IP " 6." 4 +Converting inetd Services +.RS 4 +\%https://0pointer.de/blog/projects/inetd.html +.RE +.IP " 7." 4 +Socket Activated Internet Services and OS Containers +.RS 4 +\%https://0pointer.de/blog/projects/socket-activated-containers.html +.RE diff --git a/upstream/fedora-40/man5/systemd.swap.5 b/upstream/fedora-40/man5/systemd.swap.5 new file mode 100644 index 00000000..1cb7edb2 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.swap.5 @@ -0,0 +1,247 @@ +'\" t +.TH "SYSTEMD\&.SWAP" "5" "" "systemd 255" "systemd.swap" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.swap \- Swap unit configuration +.SH "SYNOPSIS" +.PP +\fIswap\fR\&.swap +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.swap" +encodes information about a swap device or file for memory paging controlled and supervised by systemd\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The swap specific configuration options are configured in the [Swap] section\&. +.PP +Additional options are listed in +\fBsystemd.exec\fR(5), which define the execution environment the +\fBswapon\fR(8) +program is executed in, in +\fBsystemd.kill\fR(5), which define the way these processes are terminated, and in +\fBsystemd.resource-control\fR(5), which configure resource control settings for these processes of the unit\&. +.PP +Swap units must be named after the devices or files they control\&. Example: the swap device +/dev/sda5 +must be configured in a unit file +dev\-sda5\&.swap\&. For details about the escaping logic used to convert a file system path to a unit name, see +\fBsystemd.unit\fR(5)\&. Note that swap units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to it\&. +.PP +Note that swap support on Linux is privileged, swap units are hence only available in the system service manager (and root\*(Aqs user service manager), but not in unprivileged user\*(Aqs service manager\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +All swap units automatically get the +\fIBindsTo=\fR +and +\fIAfter=\fR +dependencies on the device units or the mount units of the files they are activated from\&. +.RE +.PP +Additional implicit dependencies may be added as result of execution and resource control parameters as documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.resource-control\fR(5)\&. +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Swap units automatically acquire a +\fIConflicts=\fR +and a +\fIBefore=\fR +dependency on +umount\&.target +so that they are deactivated at shutdown as well as a +\fIBefore=swap\&.target\fR +dependency\&. +.RE +.SH "FSTAB" +.PP +Swap units may either be configured via unit files, or via +/etc/fstab +(see +\fBfstab\fR(5) +for details)\&. Swaps listed in +/etc/fstab +will be converted into native units dynamically at boot and when the configuration of the system manager is reloaded\&. See +\fBsystemd-fstab-generator\fR(8) +for details about the conversion\&. +.PP +If a swap device or file is configured in both +/etc/fstab +and a unit file, the configuration in the latter takes precedence\&. +.PP +When reading +/etc/fstab, a few special options are understood by systemd which influence how dependencies are created for swap units\&. +.PP +\fBnoauto\fR, \fBauto\fR +.RS 4 +With +\fBnoauto\fR, the swap unit will not be added as a dependency for +swap\&.target\&. This means that it will not be activated automatically during boot, unless it is pulled in by some other unit\&. The +\fBauto\fR +option has the opposite meaning and is the default\&. +.sp +Added in version 218\&. +.RE +.PP +\fBnofail\fR +.RS 4 +With +\fBnofail\fR, the swap unit will be only wanted, not required by +swap\&.target\&. This means that the boot will continue even if this swap device is not activated successfully\&. +.sp +Added in version 218\&. +.RE +.PP +\fBx\-systemd\&.device\-timeout=\fR +.RS 4 +Configure how long systemd should wait for a device to show up before giving up on an entry from +/etc/fstab\&. Specify a time in seconds or explicitly append a unit such as +"s", +"min", +"h", +"ms"\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. +.sp +Added in version 215\&. +.RE +.PP +\fBx\-systemd\&.makefs\fR +.RS 4 +The swap structure will be initialized on the device\&. If the device is not "empty", i\&.e\&. it contains any signature, the operation will be skipped\&. It is hence expected that this option remains set even after the device has been initialized\&. +.sp +Note that this option can only be used in +/etc/fstab, and will be ignored when part of the +\fIOptions=\fR +setting in a unit file\&. +.sp +See +\fBsystemd-mkswap@.service\fR(8) +and the discussion of +\fBwipefs\fR(8) +in +\fBsystemd.mount\fR(5)\&. +.sp +Added in version 240\&. +.RE +.SH "OPTIONS" +.PP +Swap unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Swap unit files must include a [Swap] section, which carries information about the swap device it supervises\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in +\fBsystemd.exec\fR(5) +and +\fBsystemd.kill\fR(5)\&. The options specific to the [Swap] section of swap units are the following: +.PP +\fIWhat=\fR +.RS 4 +Takes an absolute path of a device node or file to use for paging\&. See +\fBswapon\fR(8) +for details\&. If this refers to a device node, a dependency on the respective device unit is automatically created\&. (See +\fBsystemd.device\fR(5) +for more information\&.) If this refers to a file, a dependency on the respective mount unit is automatically created\&. (See +\fBsystemd.mount\fR(5) +for more information\&.) This option is mandatory\&. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as +"%%"\&. +.RE +.PP +\fIPriority=\fR +.RS 4 +Swap priority to use when activating the swap device or file\&. This takes an integer\&. This setting is optional and ignored when the priority is set by +\fBpri=\fR +in the +\fIOptions=\fR +key\&. +.RE +.PP +\fIOptions=\fR +.RS 4 +May contain an option string for the swap device\&. This may be used for controlling discard options among other functionality, if the swap backing device supports the discard or trim operation\&. (See +\fBswapon\fR(8) +for more information\&.) Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as +"%%"\&. +.sp +Added in version 217\&. +.RE +.PP +\fITimeoutSec=\fR +.RS 4 +Configures the time to wait for the swapon command to finish\&. If a command does not exit within the configured time, the swap will be considered failed and be shut down again\&. All commands still running will be terminated forcibly via +\fBSIGTERM\fR, and after another delay of this time with +\fBSIGKILL\fR\&. (See +\fBKillMode=\fR +in +\fBsystemd.kill\fR(5)\&.) Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass +"0" +to disable the timeout logic\&. Defaults to +\fIDefaultTimeoutStartSec=\fR +from the manager configuration file (see +\fBsystemd-system.conf\fR(5))\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.kill\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.device\fR(5), +\fBsystemd.mount\fR(5), +\fBswapon\fR(8), +\fBsystemd-fstab-generator\fR(8), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/systemd.target.5 b/upstream/fedora-40/man5/systemd.target.5 new file mode 100644 index 00000000..ba0aa547 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.target.5 @@ -0,0 +1,177 @@ +'\" t +.TH "SYSTEMD\&.TARGET" "5" "" "systemd 255" "systemd.target" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.target \- Target unit configuration +.SH "SYNOPSIS" +.PP +\fItarget\fR\&.target +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.target" +encodes information about a target unit of systemd\&. Target units are used to group units and to set synchronization points for ordering dependencies with other unit files\&. +.PP +This unit type has no specific options\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. A separate [Target] section does not exist, since no target\-specific options may be configured\&. +.PP +Target units do not offer any additional functionality on top of the generic functionality provided by units\&. They merely group units, allowing a single target name to be used in +\fIWants=\fR +and +\fIRequires=\fR +settings to establish a dependency on a set of units defined by the target, and in +\fIBefore=\fR +and +\fIAfter=\fR +settings to establish ordering\&. Targets establish standardized names for synchronization points during boot and shutdown\&. Importantly, see +\fBsystemd.special\fR(7) +for examples and descriptions of standard systemd targets\&. +.PP +Target units provide a more flexible replacement for SysV runlevels in the classic SysV init system\&. For compatibility reasons special target units such as +runlevel3\&.target +exist which are used by the SysV runlevel compatibility code in systemd, see +\fBsystemd.special\fR(7) +for details\&. +.PP +Note that a target unit file must not be empty, lest it be considered a masked unit\&. It is recommended to provide a [Unit] section which includes informative +\fIDescription=\fR +and +\fIDocumentation=\fR +options\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +There are no implicit dependencies for target units\&. +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Target units will automatically complement all configured dependencies of type +\fIWants=\fR +or +\fIRequires=\fR +with dependencies of type +\fIAfter=\fR +unless +\fIDefaultDependencies=no\fR +is set in the specified units\&. +.sp +Note that the reverse is not true\&. For example, defining +\fBWants=that\&.target\fR +in +some\&.service +will not automatically add the +\fBAfter=that\&.target\fR +ordering dependency for +some\&.service\&. Instead, +some\&.service +should use the primary synchronization function of target type units, by setting a specific +\fBAfter=that\&.target\fR +or +\fBBefore=that\&.target\fR +ordering dependency in its \&.service unit file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Target units automatically gain +\fIConflicts=\fR +and +\fIBefore=\fR +dependencies against +shutdown\&.target\&. +.RE +.SH "OPTIONS" +.PP +Target unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. No options specific to this file type are supported\&. +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&Simple standalone target\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# emergency\-net\&.target + +[Unit] +Description=Emergency Mode with Networking +Requires=emergency\&.target systemd\-networkd\&.service +After=emergency\&.target systemd\-networkd\&.service +AllowIsolate=yes +.fi +.if n \{\ +.RE +.\} +.PP +When adding dependencies to other units, it\*(Aqs important to check if they set +\fIDefaultDependencies=\fR\&. Service units, unless they set +\fIDefaultDependencies=no\fR, automatically get a dependency on +sysinit\&.target\&. In this case, both +emergency\&.target +and +systemd\-networkd\&.service +have +\fIDefaultDependencies=no\fR, so they are suitable for use in this target, and do not pull in +sysinit\&.target\&. +.PP +You can now switch into this emergency mode by running +\fIsystemctl isolate emergency\-net\&.target\fR +or by passing the option +\fIsystemd\&.unit=emergency\-net\&.target\fR +on the kernel command line\&. +.PP +Other units can have +\fIWantedBy=emergency\-net\&.target\fR +in the +\fI[Install]\fR +section\&. After they are enabled using +\fBsystemctl enable\fR, they will be started before +\fIemergency\-net\&.target\fR +is started\&. It is also possible to add arbitrary units as dependencies of +emergency\&.target +without modifying them by using +\fBsystemctl add\-wants\fR\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.special\fR(7), +\fBsystemd.directives\fR(7) diff --git a/upstream/fedora-40/man5/systemd.timer.5 b/upstream/fedora-40/man5/systemd.timer.5 new file mode 100644 index 00000000..de75ccde --- /dev/null +++ b/upstream/fedora-40/man5/systemd.timer.5 @@ -0,0 +1,388 @@ +'\" t +.TH "SYSTEMD\&.TIMER" "5" "" "systemd 255" "systemd.timer" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.timer \- Timer unit configuration +.SH "SYNOPSIS" +.PP +\fItimer\fR\&.timer +.SH "DESCRIPTION" +.PP +A unit configuration file whose name ends in +"\&.timer" +encodes information about a timer controlled and supervised by systemd, for timer\-based activation\&. +.PP +This man page lists the configuration options specific to this unit type\&. See +\fBsystemd.unit\fR(5) +for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. The timer specific configuration options are configured in the [Timer] section\&. +.PP +For each timer file, a matching unit file must exist, describing the unit to activate when the timer elapses\&. By default, a service by the same name as the timer (except for the suffix) is activated\&. Example: a timer file +foo\&.timer +activates a matching service +foo\&.service\&. The unit to activate may be controlled by +\fIUnit=\fR +(see below)\&. +.PP +Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, but simply left running\&. There is no concept of spawning new service instances in this case\&. Due to this, services with +\fIRemainAfterExit=yes\fR +set (which stay around continuously even after the service\*(Aqs main process exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and then stay around forever\&. Target units, which by default do not deactivate on their own, can be activated repeatedly by timers by setting +\fIStopWhenUnneeded=yes\fR +on them\&. This will cause a target unit to be stopped immediately after its activation, if it is not a dependency of another running unit\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +The following dependencies are implicitly added: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Timer units automatically gain a +\fIBefore=\fR +dependency on the service they are supposed to activate\&. +.RE +.SS "Default Dependencies" +.PP +The following dependencies are added unless +\fIDefaultDependencies=no\fR +is set: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Timer units will automatically have dependencies of type +\fIRequires=\fR +and +\fIAfter=\fR +on +sysinit\&.target, a dependency of type +\fIBefore=\fR +on +timers\&.target, as well as +\fIConflicts=\fR +and +\fIBefore=\fR +on +shutdown\&.target +to ensure that they are stopped cleanly prior to system shutdown\&. Only timer units involved with early boot or late system shutdown should disable the +\fIDefaultDependencies=\fR +option\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Timer units with at least one +\fIOnCalendar=\fR +directive acquire a pair of additional +\fIAfter=\fR +dependencies on +time\-set\&.target +and +time\-sync\&.target, in order to avoid being started before the system clock has been correctly set\&. See +\fBsystemd.special\fR(7) +for details on these two targets\&. +.RE +.SH "OPTIONS" +.PP +Timer unit files may include [Unit] and [Install] sections, which are described in +\fBsystemd.unit\fR(5)\&. +.PP +Timer unit files must include a [Timer] section, which carries information about the timer it defines\&. The options specific to the [Timer] section of timer units are the following: +.PP +\fIOnActiveSec=\fR, \fIOnBootSec=\fR, \fIOnStartupSec=\fR, \fIOnUnitActiveSec=\fR, \fIOnUnitInactiveSec=\fR +.RS 4 +Defines monotonic timers relative to different starting points: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Settings and their starting points +.TS +allbox tab(:); +lB lB. +T{ +Setting +T}:T{ +Meaning +T} +.T& +l l +l l +l l +l l +l l. +T{ +\fIOnActiveSec=\fR +T}:T{ +Defines a timer relative to the moment the timer unit itself is activated\&. +T} +T{ +\fIOnBootSec=\fR +T}:T{ +Defines a timer relative to when the machine was booted up\&. In containers, for the system manager instance, this is mapped to \fIOnStartupSec=\fR, making both equivalent\&. +T} +T{ +\fIOnStartupSec=\fR +T}:T{ +Defines a timer relative to when the service manager was first started\&. For system timer units this is very similar to \fIOnBootSec=\fR as the system service manager is generally started very early at boot\&. It\*(Aqs primarily useful when configured in units running in the per\-user service manager, as the user service manager is generally started on first login only, not already during boot\&. +T} +T{ +\fIOnUnitActiveSec=\fR +T}:T{ +Defines a timer relative to when the unit the timer unit is activating was last activated\&. +T} +T{ +\fIOnUnitInactiveSec=\fR +T}:T{ +Defines a timer relative to when the unit the timer unit is activating was last deactivated\&. +T} +.TE +.sp 1 +Multiple directives may be combined of the same and of different types, in which case the timer unit will trigger whenever any of the specified timer expressions elapse\&. For example, by combining +\fIOnBootSec=\fR +and +\fIOnUnitActiveSec=\fR, it is possible to define a timer that elapses in regular intervals and activates a specific service each time\&. Moreover, both monotonic time expressions and +\fIOnCalendar=\fR +calendar expressions may be combined in the same timer unit\&. +.sp +The arguments to the directives are time spans configured in seconds\&. Example: "OnBootSec=50" means 50s after boot\-up\&. The argument may also include time units\&. Example: "OnBootSec=5h 30min" means 5 hours and 30 minutes after boot\-up\&. For details about the syntax of time spans, see +\fBsystemd.time\fR(7)\&. +.sp +If a timer configured with +\fIOnBootSec=\fR +or +\fIOnStartupSec=\fR +is already in the past when the timer unit is activated, it will immediately elapse and the configured unit is started\&. This is not the case for timers defined in the other directives\&. +.sp +These are monotonic timers, independent of wall\-clock time and timezones\&. If the computer is temporarily suspended, the monotonic clock generally pauses, too\&. Note that if +\fIWakeSystem=\fR +is used, a different monotonic clock is selected that continues to advance while the system is suspended and thus can be used as the trigger to resume the system\&. +.sp +If the empty string is assigned to any of these options, the list of timers is reset (both monotonic timers and +\fIOnCalendar=\fR +timers, see below), and all prior assignments will have no effect\&. +.sp +Note that timers do not necessarily expire at the precise time configured with these settings, as they are subject to the +\fIAccuracySec=\fR +setting below\&. +.RE +.PP +\fIOnCalendar=\fR +.RS 4 +Defines realtime (i\&.e\&. wallclock) timers with calendar event expressions\&. See +\fBsystemd.time\fR(7) +for more information on the syntax of calendar event expressions\&. Otherwise, the semantics are similar to +\fIOnActiveSec=\fR +and related settings\&. +.sp +Note that timers do not necessarily expire at the precise time configured with this setting, as it is subject to the +\fIAccuracySec=\fR +setting below\&. +.sp +May be specified more than once, in which case the timer unit will trigger whenever any of the specified expressions elapse\&. Moreover calendar timers and monotonic timers (see above) may be combined within the same timer unit\&. +.sp +If the empty string is assigned to any of these options, the list of timers is reset (both +\fIOnCalendar=\fR +timers and monotonic timers, see above), and all prior assignments will have no effect\&. +.sp +Note that calendar timers might be triggered at unexpected times if the system\*(Aqs realtime clock is not set correctly\&. Specifically, on systems that lack a battery\-buffered Realtime Clock (RTC) it might be wise to enable +systemd\-time\-wait\-sync\&.service +to ensure the clock is adjusted to a network time source +\fIbefore\fR +the timer event is set up\&. Timer units with at least one +\fIOnCalendar=\fR +expression are automatically ordered after +time\-sync\&.target, which +systemd\-time\-wait\-sync\&.service +is ordered before\&. +.sp +When a system is temporarily put to sleep (i\&.e\&. system suspend or hibernation) the realtime clock does not pause\&. When a calendar timer elapses while the system is sleeping it will not be acted on immediately, but once the system is later resumed it will catch up and process all timers that triggered while the system was sleeping\&. Note that if a calendar timer elapsed more than once while the system was continuously sleeping the timer will only result in a single service activation\&. If +\fIWakeSystem=\fR +(see below) is enabled a calendar time event elapsing while the system is suspended will cause the system to wake up (under the condition the system\*(Aqs hardware supports time\-triggered wake\-up functionality)\&. +.sp +Added in version 197\&. +.RE +.PP +\fIAccuracySec=\fR +.RS 4 +Specify the accuracy the timer shall elapse with\&. Defaults to 1min\&. The timer is scheduled to elapse within a time window starting with the time specified in +\fIOnCalendar=\fR, +\fIOnActiveSec=\fR, +\fIOnBootSec=\fR, +\fIOnStartupSec=\fR, +\fIOnUnitActiveSec=\fR +or +\fIOnUnitInactiveSec=\fR +and ending the time configured with +\fIAccuracySec=\fR +later\&. Within this time window, the expiry time will be placed at a host\-specific, randomized, but stable position that is synchronized between all local timer units\&. This is done in order to optimize power consumption to suppress unnecessary CPU wake\-ups\&. To get best accuracy, set this option to 1us\&. Note that the timer is still subject to the timer slack configured via +\fBsystemd-system.conf\fR(5)\*(Aqs +\fITimerSlackNSec=\fR +setting\&. See +\fBprctl\fR(2) +for details\&. To optimize power consumption, make sure to set this value as high as possible and as low as necessary\&. +.sp +Note that this setting is primarily a power saving option that allows coalescing CPU wake\-ups\&. It should not be confused with +\fIRandomizedDelaySec=\fR +(see below) which adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to stretch elapsing of timer events over a longer period to reduce workload spikes\&. For further details and explanations and how both settings play together, see below\&. +.sp +Added in version 209\&. +.RE +.PP +\fIRandomizedDelaySec=\fR +.RS 4 +Delay the timer by a randomly selected, evenly distributed amount of time between 0 and the specified time value\&. Defaults to 0, indicating that no randomized delay shall be applied\&. Each timer unit will determine this delay randomly before each iteration, and the delay will simply be added on top of the next determined elapsing time, unless modified with +\fIFixedRandomDelay=\fR, see below\&. +.sp +This setting is useful to stretch dispatching of similarly configured timer events over a certain time interval, to prevent them from firing all at the same time, possibly resulting in resource congestion\&. +.sp +Note the relation to +\fIAccuracySec=\fR +above: the latter allows the service manager to coalesce timer events within a specified time range in order to minimize wakeups, while this setting does the opposite: it stretches timer events over an interval, to make it unlikely that they fire simultaneously\&. If +\fIRandomizedDelaySec=\fR +and +\fIAccuracySec=\fR +are used in conjunction, first the randomized delay is added, and then the result is possibly further shifted to coalesce it with other timer events happening on the system\&. As mentioned above +\fIAccuracySec=\fR +defaults to 1 minute and +\fIRandomizedDelaySec=\fR +to 0, thus encouraging coalescing of timer events\&. In order to optimally stretch timer events over a certain range of time, set +\fIAccuracySec=1us\fR +and +\fIRandomizedDelaySec=\fR +to some higher value\&. +.sp +Added in version 229\&. +.RE +.PP +\fIFixedRandomDelay=\fR +.RS 4 +Takes a boolean argument\&. When enabled, the randomized offset specified by +\fIRandomizedDelaySec=\fR +is reused for all firings of the same timer\&. For a given timer unit, the offset depends on the machine ID, user identifier and timer name, which means that it is stable between restarts of the manager\&. This effectively creates a fixed offset for an individual timer, reducing the jitter in firings of this timer, while still avoiding firing at the same time as other similarly configured timers\&. +.sp +This setting has no effect if +\fIRandomizedDelaySec=\fR +is set to 0\&. Defaults to +\fBfalse\fR\&. +.sp +Added in version 247\&. +.RE +.PP +\fIOnClockChange=\fR, \fIOnTimezoneChange=\fR +.RS 4 +These options take boolean arguments\&. When true, the service unit will be triggered when the system clock (\fBCLOCK_REALTIME\fR) jumps relative to the monotonic clock (\fBCLOCK_MONOTONIC\fR), or when the local system timezone is modified\&. These options can be used alone or in combination with other timer expressions (see above) within the same timer unit\&. These options default to +\fBfalse\fR\&. +.sp +Added in version 242\&. +.RE +.PP +\fIUnit=\fR +.RS 4 +The unit to activate when this timer elapses\&. The argument is a unit name, whose suffix is not +"\&.timer"\&. If not specified, this value defaults to a service that has the same name as the timer unit, except for the suffix\&. (See above\&.) It is recommended that the unit name that is activated and the unit name of the timer unit are named identically, except for the suffix\&. +.RE +.PP +\fIPersistent=\fR +.RS 4 +Takes a boolean argument\&. If true, the time when the service unit was last triggered is stored on disk\&. When the timer is activated, the service unit is triggered immediately if it would have been triggered at least once during the time when the timer was inactive\&. Such triggering is nonetheless subject to the delay imposed by +\fIRandomizedDelaySec=\fR\&. This is useful to catch up on missed runs of the service when the system was powered down\&. Note that this setting only has an effect on timers configured with +\fIOnCalendar=\fR\&. Defaults to +\fBfalse\fR\&. +.sp +Use +\fBsystemctl clean \-\-what=state \&...\fR +on the timer unit to remove the timestamp file maintained by this option from disk\&. In particular, use this command before uninstalling a timer unit\&. See +\fBsystemctl\fR(1) +for details\&. +.sp +Added in version 212\&. +.RE +.PP +\fIWakeSystem=\fR +.RS 4 +Takes a boolean argument\&. If true, an elapsing timer will cause the system to resume from suspend, should it be suspended and if the system supports this\&. Note that this option will only make sure the system resumes on the appropriate times, it will not take care of suspending it again after any work that is to be done is finished\&. Defaults to +\fBfalse\fR\&. +.sp +Note that this functionality requires privileges and is thus generally only available in the system service manager\&. +.sp +Note that behaviour of monotonic clock timers (as configured with +\fIOnActiveSec=\fR, +\fIOnBootSec=\fR, +\fIOnStartupSec=\fR, +\fIOnUnitActiveSec=\fR, +\fIOnUnitInactiveSec=\fR, see above) is altered depending on this option\&. If false, a monotonic clock is used that is paused during system suspend (\fBCLOCK_MONOTONIC\fR), if true a different monotonic clock is used that continues advancing during system suspend (\fBCLOCK_BOOTTIME\fR), see +\fBclock_getres\fR(2) +for details\&. +.sp +Added in version 212\&. +.RE +.PP +\fIRemainAfterElapse=\fR +.RS 4 +Takes a boolean argument\&. If true, a timer will stay loaded, and its state remains queryable even after it elapsed and the associated unit (as configured with +\fIUnit=\fR, see above) deactivated again\&. If false, an elapsed timer unit that cannot elapse anymore is unloaded once its associated unit deactivated again\&. Turning this off is particularly useful for transient timer units\&. Note that this setting has an effect when repeatedly starting a timer unit: if +\fIRemainAfterElapse=\fR +is on, starting the timer a second time has no effect\&. However, if +\fIRemainAfterElapse=\fR +is off and the timer unit was already unloaded, it can be started again, and thus the service can be triggered multiple times\&. Defaults to +\fBtrue\fR\&. +.sp +Added in version 229\&. +.RE +.PP +Check +\fBsystemd.unit\fR(5), +\fBsystemd.exec\fR(5), and +\fBsystemd.kill\fR(5) +for more settings\&. +.SH "SEE ALSO" +.PP +Environment variables with details on the trigger will be set for triggered units\&. See the +"Environment Variables Set or Propagated by the Service Manager" +section in +\fBsystemd.exec\fR(5) +for more details\&. +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.time\fR(7), +\fBsystemd.directives\fR(7), +\fBsystemd-system.conf\fR(5), +\fBprctl\fR(2) diff --git a/upstream/fedora-40/man5/systemd.unit.5 b/upstream/fedora-40/man5/systemd.unit.5 new file mode 100644 index 00000000..9c3e27c6 --- /dev/null +++ b/upstream/fedora-40/man5/systemd.unit.5 @@ -0,0 +1,3015 @@ +'\" t +.TH "SYSTEMD\&.UNIT" "5" "" "systemd 255" "systemd.unit" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.unit \- Unit configuration +.SH "SYNOPSIS" +.PP +\fIservice\fR\&.service, +\fIsocket\fR\&.socket, +\fIdevice\fR\&.device, +\fImount\fR\&.mount, +\fIautomount\fR\&.automount, +\fIswap\fR\&.swap, +\fItarget\fR\&.target, +\fIpath\fR\&.path, +\fItimer\fR\&.timer, +\fIslice\fR\&.slice, +\fIscope\fR\&.scope +.SS "System Unit Search Path" +.PP +.nf +/etc/systemd/system\&.control/* +/run/systemd/system\&.control/* +/run/systemd/transient/* +/run/systemd/generator\&.early/* +/etc/systemd/system/* +/etc/systemd/system\&.attached/* +/run/systemd/system/* +/run/systemd/system\&.attached/* +/run/systemd/generator/* +\&... +/usr/lib/systemd/system/* +/run/systemd/generator\&.late/* +.fi +.SS "User Unit Search Path" +.PP +.nf +~/\&.config/systemd/user\&.control/* +$XDG_RUNTIME_DIR/systemd/user\&.control/* +$XDG_RUNTIME_DIR/systemd/transient/* +$XDG_RUNTIME_DIR/systemd/generator\&.early/* +~/\&.config/systemd/user/* +$XDG_CONFIG_DIRS/systemd/user/* +/etc/systemd/user/* +$XDG_RUNTIME_DIR/systemd/user/* +/run/systemd/user/* +$XDG_RUNTIME_DIR/systemd/generator/* +$XDG_DATA_HOME/systemd/user/* +$XDG_DATA_DIRS/systemd/user/* +\&... +/usr/lib/systemd/user/* +$XDG_RUNTIME_DIR/systemd/generator\&.late/* +.fi +.SH "DESCRIPTION" +.PP +A unit file is a plain text ini\-style file that encodes information about a service, a socket, a device, a mount point, an automount point, a swap file or partition, a start\-up target, a watched file system path, a timer controlled and supervised by +\fBsystemd\fR(1), a resource management slice or a group of externally created processes\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.PP +This man page lists the common configuration options of all the unit types\&. These options need to be configured in the [Unit] or [Install] sections of the unit files\&. +.PP +In addition to the generic [Unit] and [Install] sections described here, each unit may have a type\-specific section, e\&.g\&. [Service] for a service unit\&. See the respective man pages for more information: +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.device\fR(5), +\fBsystemd.mount\fR(5), +\fBsystemd.automount\fR(5), +\fBsystemd.swap\fR(5), +\fBsystemd.target\fR(5), +\fBsystemd.path\fR(5), +\fBsystemd.timer\fR(5), +\fBsystemd.slice\fR(5), +\fBsystemd.scope\fR(5)\&. +.PP +Unit files are loaded from a set of paths determined during compilation, described in the next section\&. +.PP +Valid unit names consist of a "unit name prefix", and a suffix specifying the unit type which begins with a dot\&. The "unit name prefix" must consist of one or more valid characters (ASCII letters, digits, +":", +"\-", +"_", +"\&.", and +"\e")\&. The total length of the unit name including the suffix must not exceed 255 characters\&. The unit type suffix must be one of +"\&.service", +"\&.socket", +"\&.device", +"\&.mount", +"\&.automount", +"\&.swap", +"\&.target", +"\&.path", +"\&.timer", +"\&.slice", or +"\&.scope"\&. +.PP +Unit names can be parameterized by a single argument called the "instance name"\&. The unit is then constructed based on a "template file" which serves as the definition of multiple services or other units\&. A template unit must have a single +"@" +at the end of the unit name prefix (right before the type suffix)\&. The name of the full unit is formed by inserting the instance name between +"@" +and the unit type suffix\&. In the unit file itself, the instance parameter may be referred to using +"%i" +and other specifiers, see below\&. +.PP +Unit files may contain additional options on top of those listed here\&. If systemd encounters an unknown option, it will write a warning log message but continue loading the unit\&. If an option or section name is prefixed with +\fBX\-\fR, it is ignored completely by systemd\&. Options within an ignored section do not need the prefix\&. Applications may use this to include additional information in the unit files\&. To access those options, applications need to parse the unit files on their own\&. +.PP +Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name in one of the unit search paths\&. For example, +systemd\-networkd\&.service +has the alias +dbus\-org\&.freedesktop\&.network1\&.service, created during installation as a symlink, so when +\fBsystemd\fR +is asked through D\-Bus to load +dbus\-org\&.freedesktop\&.network1\&.service, it\*(Aqll load +systemd\-networkd\&.service\&. As another example, +default\&.target +\(em the default system target started at boot \(em is commonly aliased to either +multi\-user\&.target +or +graphical\&.target +to select what is started by default\&. Alias names may be used in commands like +\fBdisable\fR, +\fBstart\fR, +\fBstop\fR, +\fBstatus\fR, and similar, and in all unit dependency directives, including +\fIWants=\fR, +\fIRequires=\fR, +\fIBefore=\fR, +\fIAfter=\fR\&. Aliases cannot be used with the +\fBpreset\fR +command\&. +.PP +Aliases obey the following restrictions: a unit of a certain type ("\&.service", +"\&.socket", \&...) can only be aliased by a name with the same type suffix\&. A plain unit (not a template or an instance), may only be aliased by a plain name\&. A template instance may only be aliased by another template instance, and the instance part must be identical\&. A template may be aliased by another template (in which case the alias applies to all instances of the template)\&. As a special case, a template instance (e\&.g\&. +"alias@inst\&.service") may be a symlink to different template (e\&.g\&. +"template@inst\&.service")\&. In that case, just this specific instance is aliased, while other instances of the template (e\&.g\&. +"alias@foo\&.service", +"alias@bar\&.service") are not aliased\&. Those rules preserve the requirement that the instance (if any) is always uniquely defined for a given unit and all its aliases\&. The target of alias symlink must point to a valid unit file location, i\&.e\&. the symlink target name must match the symlink source name as described, and the destination path must be in one of the unit search paths, see UNIT FILE LOAD PATH section below for more details\&. Note that the target file may not exist, i\&.e\&. the symlink may be dangling\&. +.PP +Unit files may specify aliases through the +\fIAlias=\fR +directive in the [Install] section\&. When the unit is enabled, symlinks will be created for those names, and removed when the unit is disabled\&. For example, +reboot\&.target +specifies +\fIAlias=ctrl\-alt\-del\&.target\fR, so when enabled, the symlink +/etc/systemd/system/ctrl\-alt\-del\&.service +pointing to the +reboot\&.target +file will be created, and when +Ctrl+Alt+Del +is invoked, +\fBsystemd\fR +will look for the +ctrl\-alt\-del\&.service +and execute +reboot\&.service\&. +\fBsystemd\fR +does not look at the [Install] section at all during normal operation, so any directives in that section only have an effect through the symlinks created during enablement\&. +.PP +Along with a unit file +foo\&.service, the directory +foo\&.service\&.wants/ +may exist\&. All unit files symlinked from such a directory are implicitly added as dependencies of type +\fIWants=\fR +to the unit\&. Similar functionality exists for +\fIRequires=\fR +type dependencies as well, the directory suffix is +\&.requires/ +in this case\&. This functionality is useful to hook units into the start\-up of other units, without having to modify their unit files\&. For details about the semantics of +\fIWants=\fR +and +\fIRequires=\fR, see below\&. The preferred way to create symlinks in the +\&.wants/ +or +\&.requires/ +directories is by specifying the dependency in [Install] section of the target unit, and creating the symlink in the file system with the +\fBenable\fR +or +\fBpreset\fR +commands of +\fBsystemctl\fR(1)\&. The target can be a normal unit (either plain or a specific instance of a template unit)\&. In case when the source unit is a template, the target can also be a template, in which case the instance will be "propagated" to the target unit to form a valid unit instance\&. The target of symlinks in +\&.wants/ +or +\&.requires/ +must thus point to a valid unit file location, i\&.e\&. the symlink target name must satisfy the described requirements, and the destination path must be in one of the unit search paths, see UNIT FILE LOAD PATH section below for more details\&. Note that the target file may not exist, i\&.e\&. the symlink may be dangling\&. +.PP +Along with a unit file +foo\&.service, a "drop\-in" directory +foo\&.service\&.d/ +may exist\&. All files with the suffix +"\&.conf" +from this directory will be merged in the alphanumeric order and parsed after the main unit file itself has been parsed\&. This is useful to alter or add configuration settings for a unit, without having to modify unit files\&. Each drop\-in file must contain appropriate section headers\&. For instantiated units, this logic will first look for the instance +"\&.d/" +subdirectory (e\&.g\&. +"foo@bar\&.service\&.d/") and read its +"\&.conf" +files, followed by the template +"\&.d/" +subdirectory (e\&.g\&. +"foo@\&.service\&.d/") and the +"\&.conf" +files there\&. Moreover for unit names containing dashes ("\-"), the set of directories generated by repeatedly truncating the unit name after all dashes is searched too\&. Specifically, for a unit name +foo\-bar\-baz\&.service +not only the regular drop\-in directory +foo\-bar\-baz\&.service\&.d/ +is searched but also both +foo\-bar\-\&.service\&.d/ +and +foo\-\&.service\&.d/\&. This is useful for defining common drop\-ins for a set of related units, whose names begin with a common prefix\&. This scheme is particularly useful for mount, automount and slice units, whose systematic naming structure is built around dashes as component separators\&. Note that equally named drop\-in files further down the prefix hierarchy override those further up, i\&.e\&. +foo\-bar\-\&.service\&.d/10\-override\&.conf +overrides +foo\-\&.service\&.d/10\-override\&.conf\&. +.PP +In cases of unit aliases (described above), dropins for the aliased name and all aliases are loaded\&. In the example of +default\&.target +aliasing +graphical\&.target, +default\&.target\&.d/, +default\&.target\&.wants/, +default\&.target\&.requires/, +graphical\&.target\&.d/, +graphical\&.target\&.wants/, +graphical\&.target\&.requires/ +would all be read\&. For templates, dropins for the template, any template aliases, the template instance, and all alias instances are read\&. When just a specific template instance is aliased, then the dropins for the target template, the target template instance, and the alias template instance are read\&. +.PP +In addition to +/etc/systemd/system, the drop\-in +"\&.d/" +directories for system services can be placed in +/usr/lib/systemd/system +or +/run/systemd/system +directories\&. Drop\-in files in +/etc/ +take precedence over those in +/run/ +which in turn take precedence over those in +/usr/lib/\&. Drop\-in files under any of these directories take precedence over unit files wherever located\&. Multiple drop\-in files with different names are applied in lexicographic order, regardless of which of the directories they reside in\&. +.PP +Units also support a top\-level drop\-in with +\fItype\fR\&.d/, where +\fItype\fR +may be e\&.g\&. +"service" +or +"socket", that allows altering or adding to the settings of all corresponding unit files on the system\&. The formatting and precedence of applying drop\-in configurations follow what is defined above\&. Files in +\fItype\fR\&.d/ +have lower precedence compared to files in name\-specific override directories\&. The usual rules apply: multiple drop\-in files with different names are applied in lexicographic order, regardless of which of the directories they reside in, so a file in +\fItype\fR\&.d/ +applies to a unit only if there are no drop\-ins or masks with that name in directories with higher precedence\&. See Examples\&. +.PP +Note that while systemd offers a flexible dependency system between units it is recommended to use this functionality only sparingly and instead rely on techniques such as bus\-based or socket\-based activation which make dependencies implicit, resulting in a both simpler and more flexible system\&. +.PP +As mentioned above, a unit may be instantiated from a template file\&. This allows creation of multiple units from a single configuration file\&. If systemd looks for a unit configuration file, it will first search for the literal unit name in the file system\&. If that yields no success and the unit name contains an +"@" +character, systemd will look for a unit template that shares the same name but with the instance string (i\&.e\&. the part between the +"@" +character and the suffix) removed\&. Example: if a service +getty@tty3\&.service +is requested and no file by that name is found, systemd will look for +getty@\&.service +and instantiate a service from that configuration file if it is found\&. +.PP +To refer to the instance string from within the configuration file you may use the special +"%i" +specifier in many of the configuration options\&. See below for details\&. +.PP +If a unit file is empty (i\&.e\&. has the file size 0) or is symlinked to +/dev/null, its configuration will not be loaded and it appears with a load state of +"masked", and cannot be activated\&. Use this as an effective way to fully disable a unit, making it impossible to start it even manually\&. +.PP +The unit file format is covered by the +\m[blue]\fBInterface Portability and Stability Promise\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "STRING ESCAPING FOR INCLUSION IN UNIT NAMES" +.PP +Sometimes it is useful to convert arbitrary strings into unit names\&. To facilitate this, a method of string escaping is used, in order to map strings containing arbitrary byte values (except +\fBNUL\fR) into valid unit names and their restricted character set\&. A common special case are unit names that reflect paths to objects in the file system hierarchy\&. Example: a device unit +dev\-sda\&.device +refers to a device with the device node +/dev/sda +in the file system\&. +.PP +The escaping algorithm operates as follows: given a string, any +"/" +character is replaced by +"\-", and all other characters which are not ASCII alphanumerics, +":", +"_" +or +"\&." +are replaced by C\-style +"\ex2d" +escapes\&. In addition, +"\&." +is replaced with such a C\-style escape when it would appear as the first character in the escaped string\&. +.PP +When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the root directory +"/" +is encoded as single dash +"\-"\&. In addition, any leading, trailing or duplicate +"/" +characters are removed from the string before transformation\&. Example: +/foo//bar/baz/ +becomes +"foo\-bar\-baz"\&. +.PP +This escaping is fully reversible, as long as it is known whether the escaped string was a path (the unescaping results are different for paths and non\-path strings)\&. The +\fBsystemd-escape\fR(1) +command may be used to apply and reverse escaping on arbitrary strings\&. Use +\fBsystemd\-escape \-\-path\fR +to escape path strings, and +\fBsystemd\-escape\fR +without +\fB\-\-path\fR +otherwise\&. +.SH "AUTOMATIC DEPENDENCIES" +.SS "Implicit Dependencies" +.PP +A number of unit dependencies are implicitly established, depending on unit type and unit configuration\&. These implicit dependencies can make unit configuration file cleaner\&. For the implicit dependencies in each unit type, please refer to section "Implicit Dependencies" in respective man pages\&. +.PP +For example, service units with +\fIType=dbus\fR +automatically acquire dependencies of type +\fIRequires=\fR +and +\fIAfter=\fR +on +dbus\&.socket\&. See +\fBsystemd.service\fR(5) +for details\&. +.SS "Default Dependencies" +.PP +Default dependencies are similar to implicit dependencies, but can be turned on and off by setting +\fIDefaultDependencies=\fR +to +\fIyes\fR +(the default) and +\fIno\fR, while implicit dependencies are always in effect\&. See section "Default Dependencies" in respective man pages for the effect of enabling +\fIDefaultDependencies=\fR +in each unit types\&. +.PP +For example, target units will complement all configured dependencies of type +\fIWants=\fR +or +\fIRequires=\fR +with dependencies of type +\fIAfter=\fR\&. See +\fBsystemd.target\fR(5) +for details\&. Note that this behavior can be opted out by setting +\fIDefaultDependencies=no\fR +in the specified units, or it can be selectively overridden via an explicit +\fIBefore=\fR +dependency\&. +.SH "UNIT FILE LOAD PATH" +.PP +Unit files are loaded from a set of paths determined during compilation, described in the two tables below\&. Unit files found in directories listed earlier override files with the same name in directories lower in the list\&. +.PP +When the variable +\fI$SYSTEMD_UNIT_PATH\fR +is set, the contents of this variable overrides the unit load path\&. If +\fI$SYSTEMD_UNIT_PATH\fR +ends with an empty component (":"), the usual unit load path will be appended to the contents of the variable\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \& Load path when running in system mode (\-\-system)\&. +.TS +allbox tab(:); +lB lB. +T{ +Path +T}:T{ +Description +T} +.T& +l l +l ^ +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +/etc/systemd/system\&.control +T}:T{ +Persistent and transient configuration created using the dbus API +T} +T{ +/run/systemd/system\&.control +T}: +T{ +/run/systemd/transient +T}:T{ +Dynamic configuration for transient units +T} +T{ +/run/systemd/generator\&.early +T}:T{ +Generated units with high priority (see \fIearly\-dir\fR in \fBsystemd.generator\fR(7)) +T} +T{ +/etc/systemd/system +T}:T{ +System units created by the administrator +T} +T{ +/run/systemd/system +T}:T{ +Runtime units +T} +T{ +/run/systemd/generator +T}:T{ +Generated units with medium priority (see \fInormal\-dir\fR in \fBsystemd.generator\fR(7)) +T} +T{ +/usr/local/lib/systemd/system +T}:T{ +System units installed by the administrator +T} +T{ +/usr/lib/systemd/system +T}:T{ +System units installed by the distribution package manager +T} +T{ +/run/systemd/generator\&.late +T}:T{ +Generated units with low priority (see \fIlate\-dir\fR in \fBsystemd.generator\fR(7)) +T} +.TE +.sp 1 +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \& Load path when running in user mode (\-\-user)\&. +.TS +allbox tab(:); +lB lB. +T{ +Path +T}:T{ +Description +T} +.T& +l l +l ^ +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +$XDG_CONFIG_HOME/systemd/user\&.control or ~/\&.config/systemd/user\&.control +T}:T{ +Persistent and transient configuration created using the dbus API (\fI$XDG_CONFIG_HOME\fR is used if set, ~/\&.config otherwise) +T} +T{ +$XDG_RUNTIME_DIR/systemd/user\&.control +T}: +T{ +$XDG_RUNTIME_DIR/systemd/transient +T}:T{ +Dynamic configuration for transient units +T} +T{ +$XDG_RUNTIME_DIR/systemd/generator\&.early +T}:T{ +Generated units with high priority (see \fIearly\-dir\fR in \fBsystemd.generator\fR(7)) +T} +T{ +$XDG_CONFIG_HOME/systemd/user or $HOME/\&.config/systemd/user +T}:T{ +User configuration (\fI$XDG_CONFIG_HOME\fR is used if set, ~/\&.config otherwise) +T} +T{ +$XDG_CONFIG_DIRS/systemd/user or /etc/xdg/systemd/user +T}:T{ +Additional configuration directories as specified by the XDG base directory specification (\fI$XDG_CONFIG_DIRS\fR is used if set, /etc/xdg otherwise) +T} +T{ +/etc/systemd/user +T}:T{ +User units created by the administrator +T} +T{ +$XDG_RUNTIME_DIR/systemd/user +T}:T{ +Runtime units (only used when $XDG_RUNTIME_DIR is set) +T} +T{ +/run/systemd/user +T}:T{ +Runtime units +T} +T{ +$XDG_RUNTIME_DIR/systemd/generator +T}:T{ +Generated units with medium priority (see \fInormal\-dir\fR in \fBsystemd.generator\fR(7)) +T} +T{ +$XDG_DATA_HOME/systemd/user or $HOME/\&.local/share/systemd/user +T}:T{ +Units of packages that have been installed in the home directory (\fI$XDG_DATA_HOME\fR is used if set, ~/\&.local/share otherwise) +T} +T{ +$XDG_DATA_DIRS/systemd/user or /usr/local/share/systemd/user and /usr/share/systemd/user +T}:T{ +Additional data directories as specified by the XDG base directory specification (\fI$XDG_DATA_DIRS\fR is used if set, /usr/local/share and /usr/share otherwise) +T} +T{ +$dir/systemd/user for each \fI$dir\fR in \fI$XDG_DATA_DIRS\fR +T}:T{ +Additional locations for installed user units, one for each entry in \fI$XDG_DATA_DIRS\fR +T} +T{ +/usr/local/lib/systemd/user +T}:T{ +User units installed by the administrator +T} +T{ +/usr/lib/systemd/user +T}:T{ +User units installed by the distribution package manager +T} +T{ +$XDG_RUNTIME_DIR/systemd/generator\&.late +T}:T{ +Generated units with low priority (see \fIlate\-dir\fR in \fBsystemd.generator\fR(7)) +T} +.TE +.sp 1 +.PP +The set of load paths for the user manager instance may be augmented or changed using various environment variables\&. And environment variables may in turn be set using environment generators, see +\fBsystemd.environment-generator\fR(7)\&. In particular, +\fI$XDG_DATA_HOME\fR +and +\fI$XDG_DATA_DIRS\fR +may be easily set using +\fBsystemd-environment-d-generator\fR(8)\&. Thus, directories listed here are just the defaults\&. To see the actual list that would be used based on compilation options and current environment use +.sp +.if n \{\ +.RS 4 +.\} +.nf +systemd\-analyze \-\-user unit\-paths +.fi +.if n \{\ +.RE +.\} +.PP +Moreover, additional units might be loaded into systemd from directories not on the unit load path by creating a symlink pointing to a unit file in the directories\&. You can use +\fBsystemctl link\fR +for this; see +\fBsystemctl\fR(1)\&. The file system where the linked unit files are located must be accessible when systemd is started (e\&.g\&. anything underneath +/home/ +or +/var/ +is not allowed, unless those directories are located on the root file system)\&. +.PP +It is important to distinguish "linked unit files" from "unit file aliases": any symlink where the symlink +\fItarget\fR +is within the unit load path becomes an alias: the source name and the target file name must satisfy specific constraints listed above in the discussion of aliases, but the symlink target doesn\*(Aqt have to exist, and in fact the symlink target path is not used, except to check whether the target is within the unit load path\&. In contrast, a symlink which goes outside of the unit load path signifies a linked unit file\&. The symlink is followed when loading the file, but the destination name is otherwise unused (and may even not be a valid unit file name)\&. For example, symlinks +/etc/systemd/system/alias1\&.service +→ +service1\&.service, +/etc/systemd/system/alias2\&.service +→ +/usr/lib/systemd/service1\&.service, +/etc/systemd/system/alias3\&.service +→ +/etc/systemd/system/service1\&.service +are all valid aliases and +service1\&.service +will have four names, even if the unit file is located at +/run/systemd/system/service1\&.service\&. In contrast, a symlink +/etc/systemd/system/link1\&.service +→ +\&.\&./link1_service_file +means that +link1\&.service +is a "linked unit" and the contents of +/etc/systemd/link1_service_file +provide its configuration\&. +.SH "UNIT GARBAGE COLLECTION" +.PP +The system and service manager loads a unit\*(Aqs configuration automatically when a unit is referenced for the first time\&. It will automatically unload the unit configuration and state again when the unit is not needed anymore ("garbage collection")\&. A unit may be referenced through a number of different mechanisms: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Another loaded unit references it with a dependency such as +\fIAfter=\fR, +\fIWants=\fR, \&... +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +The unit is currently starting, running, reloading or stopping\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +The unit is currently in the +\fBfailed\fR +state\&. (But see below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +A job for the unit is pending\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +The unit is pinned by an active IPC client program\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +The unit is a special "perpetual" unit that is always active and loaded\&. Examples for perpetual units are the root mount unit +\-\&.mount +or the scope unit +init\&.scope +that the service manager itself lives in\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +The unit has running processes associated with it\&. +.RE +.PP +The garbage collection logic may be altered with the +\fICollectMode=\fR +option, which allows configuration whether automatic unloading of units that are in +\fBfailed\fR +state is permissible, see below\&. +.PP +Note that when a unit\*(Aqs configuration and state is unloaded, all execution results, such as exit codes, exit signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem\&. +.PP +Use +\fBsystemctl daemon\-reload\fR +or an equivalent command to reload unit configuration while the unit is already loaded\&. In this case all configuration settings are flushed out and replaced with the new configuration (which however might not be in effect immediately), however all runtime state is saved/restored\&. +.SH "[UNIT] SECTION OPTIONS" +.PP +The unit file may include a [Unit] section, which carries generic information about the unit that is not dependent on the type of unit: +.PP +\fIDescription=\fR +.RS 4 +A short human readable title of the unit\&. This may be used by +\fBsystemd\fR +(and other UIs) as a user\-visible label for the unit, so this string should identify the unit rather than describe it, despite the name\&. This string also shouldn\*(Aqt just repeat the unit name\&. +"Apache2 Web Server" +is a good example\&. Bad examples are +"high\-performance light\-weight HTTP server" +(too generic) or +"Apache2" +(meaningless for people who do not know Apache, duplicates the unit name)\&. +\fBsystemd\fR +may use this string as a noun in status messages ("Starting \fIdescription\fR\&.\&.\&.", +"Started \fIdescription\fR\&.", +"Reached target \fIdescription\fR\&.", +"Failed to start \fIdescription\fR\&."), so it should be capitalized, and should not be a full sentence, or a phrase with a continuous verb\&. Bad examples include +"exiting the container" +or +"updating the database once per day\&."\&. +.sp +Added in version 201\&. +.RE +.PP +\fIDocumentation=\fR +.RS 4 +A space\-separated list of URIs referencing documentation for this unit or its configuration\&. Accepted are only URIs of the types +"http://", +"https://", +"file:", +"info:", +"man:"\&. For more information about the syntax of these URIs, see +\fBuri\fR(7)\&. The URIs should be listed in order of relevance, starting with the most relevant\&. It is a good idea to first reference documentation that explains what the unit\*(Aqs purpose is, followed by how it is configured, followed by any other related documentation\&. This option may be specified more than once, in which case the specified list of URIs is merged\&. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect\&. +.sp +Added in version 201\&. +.RE +.PP +\fIWants=\fR +.RS 4 +Configures (weak) requirement dependencies on other units\&. This option may be specified more than once or multiple space\-separated units may be specified in one option in which case dependencies for all listed names will be created\&. Dependencies of this type may also be configured outside of the unit configuration file by adding a symlink to a +\&.wants/ +directory accompanying the unit file\&. For details, see above\&. +.sp +Units listed in this option will be started if the configuring unit is\&. However, if the listed units fail to start or cannot be added to the transaction, this has no impact on the validity of the transaction as a whole, and this unit will still be started\&. This is the recommended way to hook the start\-up of one unit to the start\-up of another unit\&. +.sp +Note that requirement dependencies do not influence the order in which services are started or stopped\&. This has to be configured independently with the +\fIAfter=\fR +or +\fIBefore=\fR +options\&. If unit +foo\&.service +pulls in unit +bar\&.service +as configured with +\fIWants=\fR +and no ordering is configured with +\fIAfter=\fR +or +\fIBefore=\fR, then both units will be started simultaneously and without any delay between them if +foo\&.service +is activated\&. +.sp +Added in version 201\&. +.RE +.PP +\fIRequires=\fR +.RS 4 +Similar to +\fIWants=\fR, but declares a stronger requirement dependency\&. Dependencies of this type may also be configured by adding a symlink to a +\&.requires/ +directory accompanying the unit file\&. +.sp +If this unit gets activated, the units listed will be activated as well\&. If one of the other units fails to activate, and an ordering dependency +\fIAfter=\fR +on the failing unit is set, this unit will not be started\&. Besides, with or without specifying +\fIAfter=\fR, this unit will be stopped (or restarted) if one of the other units is explicitly stopped (or restarted)\&. +.sp +Often, it is a better choice to use +\fIWants=\fR +instead of +\fIRequires=\fR +in order to achieve a system that is more robust when dealing with failing services\&. +.sp +Note that this dependency type does not imply that the other unit always has to be in active state when this unit is running\&. Specifically: failing condition checks (such as +\fIConditionPathExists=\fR, +\fIConditionPathIsSymbolicLink=\fR, \&... \(em see below) do not cause the start job of a unit with a +\fIRequires=\fR +dependency on it to fail\&. Also, some unit types may deactivate on their own (for example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not propagated to units having a +\fIRequires=\fR +dependency\&. Use the +\fIBindsTo=\fR +dependency type together with +\fIAfter=\fR +to ensure that a unit may never be in active state without a specific other unit also in active state (see below)\&. +.sp +Added in version 201\&. +.RE +.PP +\fIRequisite=\fR +.RS 4 +Similar to +\fIRequires=\fR\&. However, if the units listed here are not started already, they will not be started and the starting of this unit will fail immediately\&. +\fIRequisite=\fR +does not imply an ordering dependency, even if both units are started in the same transaction\&. Hence this setting should usually be combined with +\fIAfter=\fR, to ensure this unit is not started before the other unit\&. +.sp +When +\fIRequisite=b\&.service\fR +is used on +a\&.service, this dependency will show as +\fIRequisiteOf=a\&.service\fR +in property listing of +b\&.service\&. +\fIRequisiteOf=\fR +dependency cannot be specified directly\&. +.sp +Added in version 201\&. +.RE +.PP +\fIBindsTo=\fR +.RS 4 +Configures requirement dependencies, very similar in style to +\fIRequires=\fR\&. However, this dependency type is stronger: in addition to the effect of +\fIRequires=\fR +it declares that if the unit bound to is stopped, this unit will be stopped too\&. This means a unit bound to another unit that suddenly enters inactive state will be stopped too\&. Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of a mount unit might be unmounted without involvement of the system and service manager\&. +.sp +When used in conjunction with +\fIAfter=\fR +on the same unit the behaviour of +\fIBindsTo=\fR +is even stronger\&. In this case, the unit bound to strictly has to be in active state for this unit to also be in active state\&. This not only means a unit bound to another unit that suddenly enters inactive state, but also one that is bound to another unit that gets skipped due to an unmet condition check (such as +\fIConditionPathExists=\fR, +\fIConditionPathIsSymbolicLink=\fR, \&... \(em see below) will be stopped, should it be running\&. Hence, in many cases it is best to combine +\fIBindsTo=\fR +with +\fIAfter=\fR\&. +.sp +When +\fIBindsTo=b\&.service\fR +is used on +a\&.service, this dependency will show as +\fIBoundBy=a\&.service\fR +in property listing of +b\&.service\&. +\fIBoundBy=\fR +dependency cannot be specified directly\&. +.sp +Added in version 201\&. +.RE +.PP +\fIPartOf=\fR +.RS 4 +Configures dependencies similar to +\fIRequires=\fR, but limited to stopping and restarting of units\&. When systemd stops or restarts the units listed here, the action is propagated to this unit\&. Note that this is a one\-way dependency\ \&\(em changes to this unit do not affect the listed units\&. +.sp +When +\fIPartOf=b\&.service\fR +is used on +a\&.service, this dependency will show as +\fIConsistsOf=a\&.service\fR +in property listing of +b\&.service\&. +\fIConsistsOf=\fR +dependency cannot be specified directly\&. +.sp +Added in version 201\&. +.RE +.PP +\fIUpholds=\fR +.RS 4 +Configures dependencies similar to +\fIWants=\fR, but as long as this unit is up, all units listed in +\fIUpholds=\fR +are started whenever found to be inactive or failed, and no job is queued for them\&. While a +\fIWants=\fR +dependency on another unit has a one\-time effect when this units started, a +\fIUpholds=\fR +dependency on it has a continuous effect, constantly restarting the unit if necessary\&. This is an alternative to the +\fIRestart=\fR +setting of service units, to ensure they are kept running whatever happens\&. The restart happens without delay, and usual per\-unit rate\-limit applies\&. +.sp +When +\fIUpholds=b\&.service\fR +is used on +a\&.service, this dependency will show as +\fIUpheldBy=a\&.service\fR +in the property listing of +b\&.service\&. +.sp +Added in version 249\&. +.RE +.PP +\fIConflicts=\fR +.RS 4 +A space\-separated list of unit names\&. Configures negative requirement dependencies\&. If a unit has a +\fIConflicts=\fR +setting on another unit, starting the former will stop the latter and vice versa\&. +.sp +Note that this setting does not imply an ordering dependency, similarly to the +\fIWants=\fR +and +\fIRequires=\fR +dependencies described above\&. This means that to ensure that the conflicting unit is stopped before the other unit is started, an +\fIAfter=\fR +or +\fIBefore=\fR +dependency must be declared\&. It doesn\*(Aqt matter which of the two ordering dependencies is used, because stop jobs are always ordered before start jobs, see the discussion in +\fIBefore=\fR/\fIAfter=\fR +below\&. +.sp +If unit A that conflicts with unit B is scheduled to be started at the same time as B, the transaction will either fail (in case both are required parts of the transaction) or be modified to be fixed (in case one or both jobs are not a required part of the transaction)\&. In the latter case, the job that is not required will be removed, or in case both are not required, the unit that conflicts will be started and the unit that is conflicted is stopped\&. +.sp +Added in version 201\&. +.RE +.PP +\fIBefore=\fR, \fIAfter=\fR +.RS 4 +These two settings expect a space\-separated list of unit names\&. They may be specified more than once, in which case dependencies for all listed names are created\&. +.sp +Those two settings configure ordering dependencies between units\&. If unit +foo\&.service +contains the setting +\fBBefore=bar\&.service\fR +and both units are being started, +bar\&.service\*(Aqs start\-up is delayed until +foo\&.service +has finished starting up\&. +\fIAfter=\fR +is the inverse of +\fIBefore=\fR, i\&.e\&. while +\fIBefore=\fR +ensures that the configured unit is started before the listed unit begins starting up, +\fIAfter=\fR +ensures the opposite, that the listed unit is fully started up before the configured unit is started\&. +.sp +When two units with an ordering dependency between them are shut down, the inverse of the start\-up order is applied\&. I\&.e\&. if a unit is configured with +\fIAfter=\fR +on another unit, the former is stopped before the latter if both are shut down\&. Given two units with any ordering dependency between them, if one unit is shut down and the other is started up, the shutdown is ordered before the start\-up\&. It doesn\*(Aqt matter if the ordering dependency is +\fIAfter=\fR +or +\fIBefore=\fR, in this case\&. It also doesn\*(Aqt matter which of the two is shut down, as long as one is shut down and the other is started up; the shutdown is ordered before the start\-up in all cases\&. If two units have no ordering dependencies between them, they are shut down or started up simultaneously, and no ordering takes place\&. It depends on the unit type when precisely a unit has finished starting up\&. Most importantly, for service units start\-up is considered completed for the purpose of +\fIBefore=\fR/\fIAfter=\fR +when all its configured start\-up commands have been invoked and they either failed or reported start\-up success\&. Note that this does includes +\fIExecStartPost=\fR +(or +\fIExecStopPost=\fR +for the shutdown case)\&. +.sp +Note that those settings are independent of and orthogonal to the requirement dependencies as configured by +\fIRequires=\fR, +\fIWants=\fR, +\fIRequisite=\fR, or +\fIBindsTo=\fR\&. It is a common pattern to include a unit name in both the +\fIAfter=\fR +and +\fIWants=\fR +options, in which case the unit listed will be started before the unit that is configured with these options\&. +.sp +Note that +\fIBefore=\fR +dependencies on device units have no effect and are not supported\&. Devices generally become available as a result of an external hotplug event, and systemd creates the corresponding device unit without delay\&. +.sp +Added in version 201\&. +.RE +.PP +\fIOnFailure=\fR +.RS 4 +A space\-separated list of one or more units that are activated when this unit enters the +"failed" +state\&. +.sp +Added in version 201\&. +.RE +.PP +\fIOnSuccess=\fR +.RS 4 +A space\-separated list of one or more units that are activated when this unit enters the +"inactive" +state\&. +.sp +Added in version 249\&. +.RE +.PP +\fIPropagatesReloadTo=\fR, \fIReloadPropagatedFrom=\fR +.RS 4 +A space\-separated list of one or more units to which reload requests from this unit shall be propagated to, or units from which reload requests shall be propagated to this unit, respectively\&. Issuing a reload request on a unit will automatically also enqueue reload requests on all units that are linked to it using these two settings\&. +.sp +Added in version 201\&. +.RE +.PP +\fIPropagatesStopTo=\fR, \fIStopPropagatedFrom=\fR +.RS 4 +A space\-separated list of one or more units to which stop requests from this unit shall be propagated to, or units from which stop requests shall be propagated to this unit, respectively\&. Issuing a stop request on a unit will automatically also enqueue stop requests on all units that are linked to it using these two settings\&. +.sp +Added in version 249\&. +.RE +.PP +\fIJoinsNamespaceOf=\fR +.RS 4 +For units that start processes (such as service units), lists one or more other units whose network and/or temporary file namespace to join\&. If this is specified on a unit (say, +a\&.service +has +\fIJoinsNamespaceOf=b\&.service\fR), then the inverse dependency (\fIJoinsNamespaceOf=a\&.service\fR +for b\&.service) is implied\&. This only applies to unit types which support the +\fIPrivateNetwork=\fR, +\fINetworkNamespacePath=\fR, +\fIPrivateIPC=\fR, +\fIIPCNamespacePath=\fR, and +\fIPrivateTmp=\fR +directives (see +\fBsystemd.exec\fR(5) +for details)\&. If a unit that has this setting set is started, its processes will see the same +/tmp/, +/var/tmp/, IPC namespace and network namespace as one listed unit that is started\&. If multiple listed units are already started and these do not share their namespace, then it is not defined which namespace is joined\&. Note that this setting only has an effect if +\fIPrivateNetwork=\fR/\fINetworkNamespacePath=\fR, +\fIPrivateIPC=\fR/\fIIPCNamespacePath=\fR +and/or +\fIPrivateTmp=\fR +is enabled for both the unit that joins the namespace and the unit whose namespace is joined\&. +.sp +Added in version 209\&. +.RE +.PP +\fIRequiresMountsFor=\fR +.RS 4 +Takes a space\-separated list of absolute paths\&. Automatically adds dependencies of type +\fIRequires=\fR +and +\fIAfter=\fR +for all mount units required to access the specified path\&. +.sp +Mount points marked with +\fBnoauto\fR +are not mounted automatically through +local\-fs\&.target, but are still honored for the purposes of this option, i\&.e\&. they will be pulled in by this unit\&. +.sp +Added in version 201\&. +.RE +.PP +\fIOnSuccessJobMode=\fR, \fIOnFailureJobMode=\fR +.RS 4 +Takes a value of +"fail", +"replace", +"replace\-irreversibly", +"isolate", +"flush", +"ignore\-dependencies" +or +"ignore\-requirements"\&. Defaults to +"replace"\&. Specifies how the units listed in +\fIOnSuccess=\fR/\fIOnFailure=\fR +will be enqueued\&. See +\fBsystemctl\fR(1)\*(Aqs +\fB\-\-job\-mode=\fR +option for details on the possible values\&. If this is set to +"isolate", only a single unit may be listed in +\fIOnSuccess=\fR/\fIOnFailure=\fR\&. +.sp +Added in version 209\&. +.RE +.PP +\fIIgnoreOnIsolate=\fR +.RS 4 +Takes a boolean argument\&. If +\fBtrue\fR, this unit will not be stopped when isolating another unit\&. Defaults to +\fBfalse\fR +for service, target, socket, timer, and path units, and +\fBtrue\fR +for slice, scope, device, swap, mount, and automount units\&. +.sp +Added in version 201\&. +.RE +.PP +\fIStopWhenUnneeded=\fR +.RS 4 +Takes a boolean argument\&. If +\fBtrue\fR, this unit will be stopped when it is no longer used\&. Note that, in order to minimize the work to be executed, systemd will not stop units by default unless they are conflicting with other units, or the user explicitly requested their shut down\&. If this option is set, a unit will be automatically cleaned up if no other active unit requires it\&. Defaults to +\fBfalse\fR\&. +.sp +Added in version 201\&. +.RE +.PP +\fIRefuseManualStart=\fR, \fIRefuseManualStop=\fR +.RS 4 +Takes a boolean argument\&. If +\fBtrue\fR, this unit can only be activated or deactivated indirectly\&. In this case, explicit start\-up or termination requested by the user is denied, however if it is started or stopped as a dependency of another unit, start\-up or termination will succeed\&. This is mostly a safety feature to ensure that the user does not accidentally activate units that are not intended to be activated explicitly, and not accidentally deactivate units that are not intended to be deactivated\&. These options default to +\fBfalse\fR\&. +.sp +Added in version 201\&. +.RE +.PP +\fIAllowIsolate=\fR +.RS 4 +Takes a boolean argument\&. If +\fBtrue\fR, this unit may be used with the +\fBsystemctl isolate\fR +command\&. Otherwise, this will be refused\&. It probably is a good idea to leave this disabled except for target units that shall be used similar to runlevels in SysV init systems, just as a precaution to avoid unusable system states\&. This option defaults to +\fBfalse\fR\&. +.sp +Added in version 201\&. +.RE +.PP +\fIDefaultDependencies=\fR +.RS 4 +Takes a boolean argument\&. If +\fByes\fR, (the default), a few default dependencies will implicitly be created for the unit\&. The actual dependencies created depend on the unit type\&. For example, for service units, these dependencies ensure that the service is started only after basic system initialization is completed and is properly terminated on system shutdown\&. See the respective man pages for details\&. Generally, only services involved with early boot or late shutdown should set this option to +\fBno\fR\&. It is highly recommended to leave this option enabled for the majority of common units\&. If set to +\fBno\fR, this option does not disable all implicit dependencies, just non\-essential ones\&. +.sp +Added in version 201\&. +.RE +.PP +\fISurviveFinalKillSignal=\fR +.RS 4 +Takes a boolean argument\&. Defaults to +\fBno\fR\&. If +\fByes\fR, processes belonging to this unit will not be sent the final +"SIGTERM" +and +"SIGKILL" +signals during the final phase of the system shutdown process\&. This functionality replaces the older mechanism that allowed a program to set +"argv[0][0] = \*(Aq@\*(Aq" +as described at +\m[blue]\fBsystemd and Storage Daemons for the Root File System\fR\m[]\&\s-2\u[2]\d\s+2, which however continues to be supported\&. +.sp +Added in version 255\&. +.RE +.PP +\fICollectMode=\fR +.RS 4 +Tweaks the "garbage collection" algorithm for this unit\&. Takes one of +\fBinactive\fR +or +\fBinactive\-or\-failed\fR\&. If set to +\fBinactive\fR +the unit will be unloaded if it is in the +\fBinactive\fR +state and is not referenced by clients, jobs or other units \(em however it is not unloaded if it is in the +\fBfailed\fR +state\&. In +\fBfailed\fR +mode, failed units are not unloaded until the user invoked +\fBsystemctl reset\-failed\fR +on them to reset the +\fBfailed\fR +state, or an equivalent command\&. This behaviour is altered if this option is set to +\fBinactive\-or\-failed\fR: in this case the unit is unloaded even if the unit is in a +\fBfailed\fR +state, and thus an explicitly resetting of the +\fBfailed\fR +state is not necessary\&. Note that if this mode is used unit results (such as exit codes, exit signals, consumed resources, \&...) are flushed out immediately after the unit completed, except for what is stored in the logging subsystem\&. Defaults to +\fBinactive\fR\&. +.sp +Added in version 236\&. +.RE +.PP +\fIFailureAction=\fR, \fISuccessAction=\fR +.RS 4 +Configure the action to take when the unit stops and enters a failed state or inactive state\&. Takes one of +\fBnone\fR, +\fBreboot\fR, +\fBreboot\-force\fR, +\fBreboot\-immediate\fR, +\fBpoweroff\fR, +\fBpoweroff\-force\fR, +\fBpoweroff\-immediate\fR, +\fBexit\fR, +\fBexit\-force\fR, +\fBsoft\-reboot\fR, +\fBsoft\-reboot\-force\fR, +\fBkexec\fR, +\fBkexec\-force\fR, +\fBhalt\fR, +\fBhalt\-force\fR +and +\fBhalt\-immediate\fR\&. In system mode, all options are allowed\&. In user mode, only +\fBnone\fR, +\fBexit\fR, +\fBexit\-force\fR, +\fBsoft\-reboot\fR +and +\fBsoft\-reboot\-force\fR +are allowed\&. Both options default to +\fBnone\fR\&. +.sp +If +\fBnone\fR +is set, no action will be triggered\&. +\fBreboot\fR +causes a reboot following the normal shutdown procedure (i\&.e\&. equivalent to +\fBsystemctl reboot\fR)\&. +\fBreboot\-force\fR +causes a forced reboot which will terminate all processes forcibly but should cause no dirty file systems on reboot (i\&.e\&. equivalent to +\fBsystemctl reboot \-f\fR) and +\fBreboot\-immediate\fR +causes immediate execution of the +\fBreboot\fR(2) +system call, which might result in data loss (i\&.e\&. equivalent to +\fBsystemctl reboot \-ff\fR)\&. Similarly, +\fBpoweroff\fR, +\fBpoweroff\-force\fR, +\fBpoweroff\-immediate\fR, +\fBkexec\fR, +\fBkexec\-force\fR, +\fBhalt\fR, +\fBhalt\-force\fR +and +\fBhalt\-immediate\fR +have the effect of powering down the system, executing kexec, and halting the system respectively with similar semantics\&. +\fBexit\fR +causes the manager to exit following the normal shutdown procedure, and +\fBexit\-force\fR +causes it terminate without shutting down services\&. When +\fBexit\fR +or +\fBexit\-force\fR +is used by default the exit status of the main process of the unit (if this applies) is returned from the service manager\&. However, this may be overridden with +\fIFailureActionExitStatus=\fR/\fISuccessActionExitStatus=\fR, see below\&. +\fBsoft\-reboot\fR +will trigger a userspace reboot operation\&. +\fBsoft\-reboot\-force\fR +does that too, but does not go through the shutdown transaction beforehand\&. +.sp +Added in version 236\&. +.RE +.PP +\fIFailureActionExitStatus=\fR, \fISuccessActionExitStatus=\fR +.RS 4 +Controls the exit status to propagate back to an invoking container manager (in case of a system service) or service manager (in case of a user manager) when the +\fIFailureAction=\fR/\fISuccessAction=\fR +are set to +\fBexit\fR +or +\fBexit\-force\fR +and the action is triggered\&. By default the exit status of the main process of the triggering unit (if this applies) is propagated\&. Takes a value in the range 0\&...255 or the empty string to request default behaviour\&. +.sp +Added in version 240\&. +.RE +.PP +\fIJobTimeoutSec=\fR, \fIJobRunningTimeoutSec=\fR +.RS 4 +\fIJobTimeoutSec=\fR +specifies a timeout for the whole job that starts running when the job is queued\&. +\fIJobRunningTimeoutSec=\fR +specifies a timeout that starts running when the queued job is actually started\&. If either limit is reached, the job will be cancelled, the unit however will not change state or even enter the +"failed" +mode\&. +.sp +Both settings take a time span with the default unit of seconds, but other units may be specified, see +\fBsystemd.time\fR(5)\&. The default is +"infinity" +(job timeouts disabled), except for device units where +\fIJobRunningTimeoutSec=\fR +defaults to +\fIDefaultDeviceTimeoutSec=\fR\&. +.sp +Note: these timeouts are independent from any unit\-specific timeouts (for example, the timeout set with +\fITimeoutStartSec=\fR +in service units)\&. The job timeout has no effect on the unit itself\&. Or in other words: unit\-specific timeouts are useful to abort unit state changes, and revert them\&. The job timeout set with this option however is useful to abort only the job waiting for the unit state to change\&. +.sp +Added in version 201\&. +.RE +.PP +\fIJobTimeoutAction=\fR, \fIJobTimeoutRebootArgument=\fR +.RS 4 +\fIJobTimeoutAction=\fR +optionally configures an additional action to take when the timeout is hit, see description of +\fIJobTimeoutSec=\fR +and +\fIJobRunningTimeoutSec=\fR +above\&. It takes the same values as +\fIStartLimitAction=\fR\&. Defaults to +\fBnone\fR\&. +.sp +\fIJobTimeoutRebootArgument=\fR +configures an optional reboot string to pass to the +\fBreboot\fR(2) +system call\&. +.sp +Added in version 240\&. +.RE +.PP +\fIStartLimitIntervalSec=\fR\fI\fIinterval\fR\fR, \fIStartLimitBurst=\fR\fI\fIburst\fR\fR +.RS 4 +Configure unit start rate limiting\&. Units which are started more than +\fIburst\fR +times within an +\fIinterval\fR +time span are not permitted to start any more\&. Use +\fIStartLimitIntervalSec=\fR +to configure the checking interval and +\fIStartLimitBurst=\fR +to configure how many starts per interval are allowed\&. +.sp +\fIinterval\fR +is a time span with the default unit of seconds, but other units may be specified, see +\fBsystemd.time\fR(5)\&. The special value +"infinity" +can be used to limit the total number of start attempts, even if they happen at large time intervals\&. Defaults to +\fIDefaultStartLimitIntervalSec=\fR +in manager configuration file, and may be set to 0 to disable any kind of rate limiting\&. +\fIburst\fR +is a number and defaults to +\fIDefaultStartLimitBurst=\fR +in manager configuration file\&. +.sp +These configuration options are particularly useful in conjunction with the service setting +\fIRestart=\fR +(see +\fBsystemd.service\fR(5)); however, they apply to all kinds of starts (including manual), not just those triggered by the +\fIRestart=\fR +logic\&. +.sp +Note that units which are configured for +\fIRestart=\fR, and which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted manually or from a timer or socket at a later point, after the +\fIinterval\fR +has passed\&. From that point on, the restart logic is activated again\&. +\fBsystemctl reset\-failed\fR +will cause the restart rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit and the start limit interferes with that\&. Rate\-limiting is enforced after any unit condition checks are executed, and hence unit activations with failing conditions do not count towards the rate limit\&. +.sp +When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are flushed out too\&. This means that configuring start rate limiting for a unit that is not referenced continuously has no effect\&. +.sp +This setting does not apply to slice, target, device, and scope units, since they are unit types whose activation may either never fail, or may succeed only a single time\&. +.sp +Added in version 229\&. +.RE +.PP +\fIStartLimitAction=\fR +.RS 4 +Configure an additional action to take if the rate limit configured with +\fIStartLimitIntervalSec=\fR +and +\fIStartLimitBurst=\fR +is hit\&. Takes the same values as the +\fIFailureAction=\fR/\fISuccessAction=\fR +settings\&. If +\fBnone\fR +is set, hitting the rate limit will trigger no action except that the start will not be permitted\&. Defaults to +\fBnone\fR\&. +.sp +Added in version 229\&. +.RE +.PP +\fIRebootArgument=\fR +.RS 4 +Configure the optional argument for the +\fBreboot\fR(2) +system call if +\fIStartLimitAction=\fR +or +\fIFailureAction=\fR +is a reboot action\&. This works just like the optional argument to +\fBsystemctl reboot\fR +command\&. +.sp +Added in version 229\&. +.RE +.PP +\fISourcePath=\fR +.RS 4 +A path to a configuration file this unit has been generated from\&. This is primarily useful for implementation of generator tools that convert configuration from an external configuration file format into native unit files\&. This functionality should not be used in normal units\&. +.sp +Added in version 201\&. +.RE +.SS "Conditions and Asserts" +.PP +Unit files may also include a number of +\fICondition\&...=\fR +and +\fIAssert\&...=\fR +settings\&. Before the unit is started, systemd will verify that the specified conditions and asserts are true\&. If not, the starting of the unit will be (mostly silently) skipped (in case of conditions), or aborted with an error message (in case of asserts)\&. Failing conditions or asserts will not result in the unit being moved into the +"failed" +state\&. The conditions and asserts are checked at the time the queued start job is to be executed\&. The ordering dependencies are still respected, so other units are still pulled in and ordered as if this unit was successfully activated, and the conditions and asserts are executed the precise moment the unit would normally start and thus can validate system state after the units ordered before completed initialization\&. Use condition expressions for skipping units that do not apply to the local system, for example because the kernel or runtime environment doesn\*(Aqt require their functionality\&. +.PP +If multiple conditions are specified, the unit will be executed if all of them apply (i\&.e\&. a logical AND is applied)\&. Condition checks can use a pipe symbol ("|") after the equals sign ("Condition\&...=|\&..."), which causes the condition to become a +\fItriggering\fR +condition\&. If at least one triggering condition is defined for a unit, then the unit will be started if at least one of the triggering conditions of the unit applies and all of the regular (i\&.e\&. non\-triggering) conditions apply\&. If you prefix an argument with the pipe symbol and an exclamation mark, the pipe symbol must be passed first, the exclamation second\&. If any of these options is assigned the empty string, the list of conditions is reset completely, all previous condition settings (of any kind) will have no effect\&. +.PP +The +\fIAssertArchitecture=\fR, +\fIAssertVirtualization=\fR, \&... options are similar to conditions but cause the start job to fail (instead of being skipped)\&. The failed check is logged\&. Units with unmet conditions are considered to be in a clean state and will be garbage collected if they are not referenced\&. This means that when queried, the condition failure may or may not show up in the state of the unit\&. +.PP +Note that neither assertion nor condition expressions result in unit state changes\&. Also note that both are checked at the time the job is to be executed, i\&.e\&. long after depending jobs and it itself were queued\&. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit dependencies\&. +.PP +The +\fBcondition\fR +verb of +\fBsystemd-analyze\fR(1) +can be used to test condition and assert expressions\&. +.PP +Except for +\fIConditionPathIsSymbolicLink=\fR, all path checks follow symlinks\&. +.PP +\fIConditionArchitecture=\fR +.RS 4 +Check whether the system is running on a specific architecture\&. Takes one of +"x86", +"x86\-64", +"ppc", +"ppc\-le", +"ppc64", +"ppc64\-le", +"ia64", +"parisc", +"parisc64", +"s390", +"s390x", +"sparc", +"sparc64", +"mips", +"mips\-le", +"mips64", +"mips64\-le", +"alpha", +"arm", +"arm\-be", +"arm64", +"arm64\-be", +"sh", +"sh64", +"m68k", +"tilegx", +"cris", +"arc", +"arc\-be", or +"native"\&. +.sp +The architecture is determined from the information returned by +\fBuname\fR(2) +and is thus subject to +\fBpersonality\fR(2)\&. Note that a +\fIPersonality=\fR +setting in the same unit file has no effect on this condition\&. A special architecture name +"native" +is mapped to the architecture the system manager itself is compiled for\&. The test may be negated by prepending an exclamation mark\&. +.sp +Added in version 201\&. +.RE +.PP +\fIConditionFirmware=\fR +.RS 4 +Check whether the system\*(Aqs firmware is of a certain type\&. The following values are possible: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"uefi" +matches systems with EFI\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"device\-tree" +matches systems with a device tree\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"device\-tree\-compatible(\fIvalue\fR)" +matches systems with a device tree that are compatible with +"value"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +"smbios\-field(\fIfield\fR \fIoperator\fR \fIvalue\fR)" +matches systems with a SMBIOS field containing a certain value\&. +\fIfield\fR +is the name of the SMBIOS field exposed as +"sysfs" +attribute file below +/sys/class/dmi/id/\&. +\fIoperator\fR +is one of +"<", +"<=", +">=", +">", +"==", +"<>" +for version comparisons, +"=" +and +"!=" +for literal string comparisons, or +"$=", +"!$=" +for shell\-style glob comparisons\&. +\fIvalue\fR +is the expected value of the SMBIOS field value (possibly containing shell style globs in case +"$="/"!$=" +is used)\&. +.RE +.sp +Added in version 249\&. +.RE +.PP +\fIConditionVirtualization=\fR +.RS 4 +Check whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation\&. Takes either boolean value to check if being executed in any virtualized environment, or one of +"vm" +and +"container" +to test against a generic type of virtualization solution, or one of +"qemu", +"kvm", +"amazon", +"zvm", +"vmware", +"microsoft", +"oracle", +"powervm", +"xen", +"bochs", +"uml", +"bhyve", +"qnx", +"apple", +"sre", +"openvz", +"lxc", +"lxc\-libvirt", +"systemd\-nspawn", +"docker", +"podman", +"rkt", +"wsl", +"proot", +"pouch", +"acrn" +to test against a specific implementation, or +"private\-users" +to check whether we are running in a user namespace\&. See +\fBsystemd-detect-virt\fR(1) +for a full list of known virtualization technologies and their identifiers\&. If multiple virtualization technologies are nested, only the innermost is considered\&. The test may be negated by prepending an exclamation mark\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionHost=\fR +.RS 4 +\fIConditionHost=\fR +may be used to match against the hostname or machine ID of the host\&. This either takes a hostname string (optionally with shell style globs) which is tested against the locally set hostname as returned by +\fBgethostname\fR(2), or a machine ID formatted as string (see +\fBmachine-id\fR(5))\&. The test may be negated by prepending an exclamation mark\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionKernelCommandLine=\fR +.RS 4 +\fIConditionKernelCommandLine=\fR +may be used to check whether a specific kernel command line option is set (or if prefixed with the exclamation mark \(em unset)\&. The argument must either be a single word, or an assignment (i\&.e\&. two words, separated by +"=")\&. In the former case the kernel command line is searched for the word appearing as is, or as left hand side of an assignment\&. In the latter case, the exact assignment is looked for with right and left hand side matching\&. This operates on the kernel command line communicated to userspace via +/proc/cmdline, except when the service manager is invoked as payload of a container manager, in which case the command line of +PID 1 +is used instead (i\&.e\&. +/proc/1/cmdline)\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionKernelVersion=\fR +.RS 4 +\fIConditionKernelVersion=\fR +may be used to check whether the kernel version (as reported by +\fBuname \-r\fR) matches a certain expression, or if prefixed with the exclamation mark, does not match\&. The argument must be a list of (potentially quoted) expressions\&. Each expression starts with one of +"=" +or +"!=" +for string comparisons, +"<", +"<=", +"==", +"<>", +">=", +">" +for version comparisons, or +"$=", +"!$=" +for a shell\-style glob match\&. If no operator is specified, +"$=" +is implied\&. +.sp +Note that using the kernel version string is an unreliable way to determine which features are supported by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream kernels into older versions provided by distributions\&. Hence, this check is inherently unportable and should not be used for units which may be used on different distributions\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionCredential=\fR +.RS 4 +\fIConditionCredential=\fR +may be used to check whether a credential by the specified name was passed into the service manager\&. See +\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[3]\d\s+2 +for details about credentials\&. If used in services for the system service manager this may be used to conditionalize services based on system credentials passed in\&. If used in services for the per\-user service manager this may be used to conditionalize services based on credentials passed into the +unit@\&.service +service instance belonging to the user\&. The argument must be a valid credential name\&. +.sp +Added in version 252\&. +.RE +.PP +\fIConditionEnvironment=\fR +.RS 4 +\fIConditionEnvironment=\fR +may be used to check whether a specific environment variable is set (or if prefixed with the exclamation mark \(em unset) in the service manager\*(Aqs environment block\&. The argument may be a single word, to check if the variable with this name is defined in the environment block, or an assignment ("\fIname\fR=\fIvalue\fR"), to check if the variable with this exact value is defined\&. Note that the environment block of the service manager itself is checked, i\&.e\&. not any variables defined with +\fIEnvironment=\fR +or +\fIEnvironmentFile=\fR, as described above\&. This is particularly useful when the service manager runs inside a containerized environment or as per\-user service manager, in order to check for variables passed in by the enclosing container manager or PAM\&. +.sp +Added in version 246\&. +.RE +.PP +\fIConditionSecurity=\fR +.RS 4 +\fIConditionSecurity=\fR +may be used to check whether the given security technology is enabled on the system\&. Currently, the following values are recognized: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&3.\ \&Recognized security technologies +.TS +allbox tab(:); +lB lB. +T{ +Value +T}:T{ +Description +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +selinux +T}:T{ +SELinux MAC +T} +T{ +apparmor +T}:T{ +AppArmor MAC +T} +T{ +tomoyo +T}:T{ +Tomoyo MAC +T} +T{ +smack +T}:T{ +SMACK MAC +T} +T{ +ima +T}:T{ +Integrity Measurement Architecture (IMA) +T} +T{ +audit +T}:T{ +Linux Audit Framework +T} +T{ +uefi\-secureboot +T}:T{ +UEFI SecureBoot +T} +T{ +tpm2 +T}:T{ +Trusted Platform Module 2\&.0 (TPM2) +T} +T{ +cvm +T}:T{ +Confidential virtual machine (SEV/TDX) +T} +T{ +measured\-uki +T}:T{ +Unified Kernel Image with PCR 11 Measurements, as per \fBsystemd-stub\fR(7)\&. Added in version 255\&. +T} +.TE +.sp 1 +The test may be negated by prepending an exclamation mark\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionCapability=\fR +.RS 4 +Check whether the given capability exists in the capability bounding set of the service manager (i\&.e\&. this does not check whether capability is actually available in the permitted or effective sets, see +\fBcapabilities\fR(7) +for details)\&. Pass a capability name such as +"CAP_MKNOD", possibly prefixed with an exclamation mark to negate the check\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionACPower=\fR +.RS 4 +Check whether the system has AC power, or is exclusively battery powered at the time of activation of the unit\&. This takes a boolean argument\&. If set to +"true", the condition will hold only if at least one AC connector of the system is connected to a power source, or if no AC connectors are known\&. Conversely, if set to +"false", the condition will hold only if there is at least one AC connector known and all AC connectors are disconnected from a power source\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionNeedsUpdate=\fR +.RS 4 +Takes one of +/var/ +or +/etc/ +as argument, possibly prefixed with a +"!" +(to invert the condition)\&. This condition may be used to conditionalize units on whether the specified directory requires an update because +/usr/\*(Aqs modification time is newer than the stamp file +\&.updated +in the specified directory\&. This is useful to implement offline updates of the vendor operating system resources in +/usr/ +that require updating of +/etc/ +or +/var/ +on the next following boot\&. Units making use of this condition should order themselves before +\fBsystemd-update-done.service\fR(8), to make sure they run before the stamp file\*(Aqs modification time gets reset indicating a completed update\&. +.sp +If the +\fIsystemd\&.condition\-needs\-update=\fR +option is specified on the kernel command line (taking a boolean), it will override the result of this condition check, taking precedence over any file modification time checks\&. If the kernel command line option is used, +systemd\-update\-done\&.service +will not have immediate effect on any following +\fIConditionNeedsUpdate=\fR +checks, until the system is rebooted where the kernel command line option is not specified anymore\&. +.sp +Note that to make this scheme effective, the timestamp of +/usr/ +should be explicitly updated after its contents are modified\&. The kernel will automatically update modification timestamp on a directory only when immediate children of a directory are modified; an modification of nested files will not automatically result in mtime of +/usr/ +being updated\&. +.sp +Also note that if the update method includes a call to execute appropriate post\-update steps itself, it should not touch the timestamp of +/usr/\&. In a typical distribution packaging scheme, packages will do any required update steps as part of the installation or upgrade, to make package contents immediately usable\&. +\fIConditionNeedsUpdate=\fR +should be used with other update mechanisms where such an immediate update does not happen\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionFirstBoot=\fR +.RS 4 +Takes a boolean argument\&. This condition may be used to conditionalize units on whether the system is booting up for the first time\&. This roughly means that +/etc/ +was unpopulated when the system started booting (for details, see "First Boot Semantics" in +\fBmachine-id\fR(5))\&. First boot is considered finished (this condition will evaluate as false) after the manager has finished the startup phase\&. +.sp +This condition may be used to populate +/etc/ +on the first boot after factory reset, or when a new system instance boots up for the first time\&. +.sp +For robustness, units with +\fIConditionFirstBoot=yes\fR +should order themselves before +first\-boot\-complete\&.target +and pull in this passive target with +\fIWants=\fR\&. This ensures that in a case of an aborted first boot, these units will be re\-run during the next system startup\&. +.sp +If the +\fIsystemd\&.condition\-first\-boot=\fR +option is specified on the kernel command line (taking a boolean), it will override the result of this condition check, taking precedence over +/etc/machine\-id +existence checks\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathExists=\fR +.RS 4 +Check for the existence of a file\&. If the specified absolute path name does not exist, the condition will fail\&. If the absolute path name passed to +\fIConditionPathExists=\fR +is prefixed with an exclamation mark ("!"), the test is negated, and the unit is only started if the path does not exist\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathExistsGlob=\fR +.RS 4 +\fIConditionPathExistsGlob=\fR +is similar to +\fIConditionPathExists=\fR, but checks for the existence of at least one file or directory matching the specified globbing pattern\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathIsDirectory=\fR +.RS 4 +\fIConditionPathIsDirectory=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that a certain path exists and is a directory\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathIsSymbolicLink=\fR +.RS 4 +\fIConditionPathIsSymbolicLink=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that a certain path exists and is a symbolic link\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathIsMountPoint=\fR +.RS 4 +\fIConditionPathIsMountPoint=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that a certain path exists and is a mount point\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathIsReadWrite=\fR +.RS 4 +\fIConditionPathIsReadWrite=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that the underlying file system is readable and writable (i\&.e\&. not mounted read\-only)\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionPathIsEncrypted=\fR +.RS 4 +\fIConditionPathIsEncrypted=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that the underlying file system\*(Aqs backing block device is encrypted using dm\-crypt/LUKS\&. Note that this check does not cover ext4 per\-directory encryption, and only detects block level encryption\&. Moreover, if the specified path resides on a file system on top of a loopback block device, only encryption above the loopback device is detected\&. It is not detected whether the file system backing the loopback block device is encrypted\&. +.sp +Added in version 246\&. +.RE +.PP +\fIConditionDirectoryNotEmpty=\fR +.RS 4 +\fIConditionDirectoryNotEmpty=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that a certain path exists and is a non\-empty directory\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionFileNotEmpty=\fR +.RS 4 +\fIConditionFileNotEmpty=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that a certain path exists and refers to a regular file with a non\-zero size\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionFileIsExecutable=\fR +.RS 4 +\fIConditionFileIsExecutable=\fR +is similar to +\fIConditionPathExists=\fR +but verifies that a certain path exists, is a regular file, and marked executable\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionUser=\fR +.RS 4 +\fIConditionUser=\fR +takes a numeric +"UID", a UNIX user name, or the special value +"@system"\&. This condition may be used to check whether the service manager is running as the given user\&. The special value +"@system" +can be used to check if the user id is within the system user range\&. This option is not useful for system services, as the system manager exclusively runs as the root user, and thus the test result is constant\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionGroup=\fR +.RS 4 +\fIConditionGroup=\fR +is similar to +\fIConditionUser=\fR +but verifies that the service manager\*(Aqs real or effective group, or any of its auxiliary groups, match the specified group or GID\&. This setting does not support the special value +"@system"\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionControlGroupController=\fR +.RS 4 +Check whether given cgroup controllers (e\&.g\&. +"cpu") are available for use on the system or whether the legacy v1 cgroup or the modern v2 cgroup hierarchy is used\&. +.sp +Multiple controllers may be passed with a space separating them; in this case the condition will only pass if all listed controllers are available for use\&. Controllers unknown to systemd are ignored\&. Valid controllers are +"cpu", +"io", +"memory", and +"pids"\&. Even if available in the kernel, a particular controller may not be available if it was disabled on the kernel command line with +\fIcgroup_disable=controller\fR\&. +.sp +Alternatively, two special strings +"v1" +and +"v2" +may be specified (without any controller names)\&. +"v2" +will pass if the unified v2 cgroup hierarchy is used, and +"v1" +will pass if the legacy v1 hierarchy or the hybrid hierarchy are used\&. Note that legacy or hybrid hierarchies have been deprecated\&. See +\fBsystemd\fR(1) +for more information\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionMemory=\fR +.RS 4 +Verify that the specified amount of system memory is available to the current system\&. Takes a memory size in bytes as argument, optionally prefixed with a comparison operator +"<", +"<=", +"=" +(or +"=="), +"!=" +(or +"<>"), +">=", +">"\&. On bare\-metal systems compares the amount of physical memory in the system with the specified size, adhering to the specified comparison operator\&. In containers compares the amount of memory assigned to the container instead\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionCPUs=\fR +.RS 4 +Verify that the specified number of CPUs is available to the current system\&. Takes a number of CPUs as argument, optionally prefixed with a comparison operator +"<", +"<=", +"=" +(or +"=="), +"!=" +(or +"<>"), +">=", +">"\&. Compares the number of CPUs in the CPU affinity mask configured of the service manager itself with the specified number, adhering to the specified comparison operator\&. On physical systems the number of CPUs in the affinity mask of the service manager usually matches the number of physical CPUs, but in special and virtual environments might differ\&. In particular, in containers the affinity mask usually matches the number of CPUs assigned to the container and not the physically available ones\&. +.sp +Added in version 244\&. +.RE +.PP +\fIConditionCPUFeature=\fR +.RS 4 +Verify that a given CPU feature is available via the +"CPUID" +instruction\&. This condition only does something on i386 and x86\-64 processors\&. On other processors it is assumed that the CPU does not support the given feature\&. It checks the leaves +"1", +"7", +"0x80000001", and +"0x80000007"\&. Valid values are: +"fpu", +"vme", +"de", +"pse", +"tsc", +"msr", +"pae", +"mce", +"cx8", +"apic", +"sep", +"mtrr", +"pge", +"mca", +"cmov", +"pat", +"pse36", +"clflush", +"mmx", +"fxsr", +"sse", +"sse2", +"ht", +"pni", +"pclmul", +"monitor", +"ssse3", +"fma3", +"cx16", +"sse4_1", +"sse4_2", +"movbe", +"popcnt", +"aes", +"xsave", +"osxsave", +"avx", +"f16c", +"rdrand", +"bmi1", +"avx2", +"bmi2", +"rdseed", +"adx", +"sha_ni", +"syscall", +"rdtscp", +"lm", +"lahf_lm", +"abm", +"constant_tsc"\&. +.sp +Added in version 248\&. +.RE +.PP +\fIConditionOSRelease=\fR +.RS 4 +Verify that a specific +"key=value" +pair is set in the host\*(Aqs +\fBos-release\fR(5)\&. +.sp +Other than exact string matching (with +"=" +and +"!="), relative comparisons are supported for versioned parameters (e\&.g\&. +"VERSION_ID"; with +"<", +"<=", +"==", +"<>", +">=", +">"), and shell\-style wildcard comparisons ("*", +"?", +"[]") are supported with the +"$=" +(match) and +"!$=" +(non\-match)\&. +.sp +Added in version 249\&. +.RE +.PP +\fIConditionMemoryPressure=\fR, \fIConditionCPUPressure=\fR, \fIConditionIOPressure=\fR +.RS 4 +Verify that the overall system (memory, CPU or IO) pressure is below or equal to a threshold\&. This setting takes a threshold value as argument\&. It can be specified as a simple percentage value, suffixed with +"%", in which case the pressure will be measured as an average over the last five minutes before the attempt to start the unit is performed\&. Alternatively, the average timespan can also be specified using +"/" +as a separator, for example: +"10%/1min"\&. The supported timespans match what the kernel provides, and are limited to +"10sec", +"1min" +and +"5min"\&. The +"full" +PSI will be checked first, and if not found +"some" +will be checked\&. For more details, see the documentation on +\m[blue]\fBPSI (Pressure Stall Information)\fR\m[]\&\s-2\u[4]\d\s+2\&. +.sp +Optionally, the threshold value can be prefixed with the slice unit under which the pressure will be checked, followed by a +":"\&. If the slice unit is not specified, the overall system pressure will be measured, instead of a particular cgroup\*(Aqs\&. +.sp +Added in version 250\&. +.RE +.PP +\fIAssertArchitecture=\fR, \fIAssertVirtualization=\fR, \fIAssertHost=\fR, \fIAssertKernelCommandLine=\fR, \fIAssertKernelVersion=\fR, \fIAssertCredential=\fR, \fIAssertEnvironment=\fR, \fIAssertSecurity=\fR, \fIAssertCapability=\fR, \fIAssertACPower=\fR, \fIAssertNeedsUpdate=\fR, \fIAssertFirstBoot=\fR, \fIAssertPathExists=\fR, \fIAssertPathExistsGlob=\fR, \fIAssertPathIsDirectory=\fR, \fIAssertPathIsSymbolicLink=\fR, \fIAssertPathIsMountPoint=\fR, \fIAssertPathIsReadWrite=\fR, \fIAssertPathIsEncrypted=\fR, \fIAssertDirectoryNotEmpty=\fR, \fIAssertFileNotEmpty=\fR, \fIAssertFileIsExecutable=\fR, \fIAssertUser=\fR, \fIAssertGroup=\fR, \fIAssertControlGroupController=\fR, \fIAssertMemory=\fR, \fIAssertCPUs=\fR, \fIAssertCPUFeature=\fR, \fIAssertOSRelease=\fR, \fIAssertMemoryPressure=\fR, \fIAssertCPUPressure=\fR, \fIAssertIOPressure=\fR +.RS 4 +Similar to the +\fIConditionArchitecture=\fR, +\fIConditionVirtualization=\fR, \&..., condition settings described above, these settings add assertion checks to the start\-up of the unit\&. However, unlike the conditions settings, any assertion setting that is not met results in failure of the start job (which means this is logged loudly)\&. Note that hitting a configured assertion does not cause the unit to enter the +"failed" +state (or in fact result in any state change of the unit), it affects only the job queued for it\&. Use assertion expressions for units that cannot operate when specific requirements are not met, and when this is something the administrator or user should look into\&. +.sp +Added in version 218\&. +.RE +.SH "MAPPING OF UNIT PROPERTIES TO THEIR INVERSES" +.PP +Unit settings that create a relationship with a second unit usually show up in properties of both units, for example in +\fBsystemctl show\fR +output\&. In some cases the name of the property is the same as the name of the configuration setting, but not always\&. This table lists the properties that are shown on two units which are connected through some dependency, and shows which property on "source" unit corresponds to which property on the "target" unit\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&4.\ \& "Forward" and "reverse" unit properties +.TS +allbox tab(:); +lB lB lB s. +T{ +"Forward" property +T}:T{ +"Reverse" property +T}:T{ +Where used +T} +.T& +l l l s +l l ^ ^ +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l s +l l l s +l l ^ ^ +l l l s +l l ^ ^ +l l l l. +T{ +\fIBefore=\fR +T}:T{ +\fIAfter=\fR +T}:T{ +[Unit] section +T} +T{ +\fIAfter=\fR +T}:T{ +\fIBefore=\fR +T}:: +T{ +\fIRequires=\fR +T}:T{ +\fIRequiredBy=\fR +T}:T{ +[Unit] section +T}:T{ +[Install] section +T} +T{ +\fIWants=\fR +T}:T{ +\fIWantedBy=\fR +T}:T{ +[Unit] section +T}:T{ +[Install] section +T} +T{ +\fIUpholds=\fR +T}:T{ +\fIUpheldBy=\fR +T}:T{ +[Unit] section +T}:T{ +[Install] section +T} +T{ +\fIPartOf=\fR +T}:T{ +\fIConsistsOf=\fR +T}:T{ +[Unit] section +T}:T{ +an automatic property +T} +T{ +\fIBindsTo=\fR +T}:T{ +\fIBoundBy=\fR +T}:T{ +[Unit] section +T}:T{ +an automatic property +T} +T{ +\fIRequisite=\fR +T}:T{ +\fIRequisiteOf=\fR +T}:T{ +[Unit] section +T}:T{ +an automatic property +T} +T{ +\fIConflicts=\fR +T}:T{ +\fIConflictedBy=\fR +T}:T{ +[Unit] section +T}:T{ +an automatic property +T} +T{ +\fITriggers=\fR +T}:T{ +\fITriggeredBy=\fR +T}:T{ +Automatic properties, see notes below +T} +T{ +\fIPropagatesReloadTo=\fR +T}:T{ +\fIReloadPropagatedFrom=\fR +T}:T{ +[Unit] section +T} +T{ +\fIReloadPropagatedFrom=\fR +T}:T{ +\fIPropagatesReloadTo=\fR +T}:: +T{ +\fIPropagatesStopTo=\fR +T}:T{ +\fIStopPropagatedFrom=\fR +T}:T{ +[Unit] section +T} +T{ +\fIStopPropagatedFrom=\fR +T}:T{ +\fIPropagatesStopTo=\fR +T}:: +T{ +\fIFollowing=\fR +T}:T{ +n/a +T}:T{ +An automatic property +T}:T{ +\ \& +T} +.TE +.sp 1 +.PP +Note: +\fIWantedBy=\fR, +\fIRequiredBy=\fR, and +\fIUpheldBy=\fR +are used in the [Install] section to create symlinks in +\&.wants/, +\&.requires/, and +\&.upholds/ +directories\&. They cannot be used directly as a unit configuration setting\&. +.PP +Note: +\fIConsistsOf=\fR, +\fIBoundBy=\fR, +\fIRequisiteOf=\fR, +\fIConflictedBy=\fR +are created implicitly along with their reverses and cannot be specified directly\&. +.PP +Note: +\fITriggers=\fR +is created implicitly between a socket, path unit, or an automount unit, and the unit they activate\&. By default a unit with the same name is triggered, but this can be overridden using +\fISockets=\fR, +\fIService=\fR, and +\fIUnit=\fR +settings\&. See +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.path\fR(5), and +\fBsystemd.automount\fR(5) +for details\&. +\fITriggeredBy=\fR +is created implicitly on the triggered unit\&. +.PP +Note: +\fIFollowing=\fR +is used to group device aliases and points to the "primary" device unit that systemd is using to track device state, usually corresponding to a sysfs path\&. It does not show up in the "target" unit\&. +.SH "[INSTALL] SECTION OPTIONS" +.PP +Unit files may include an [Install] section, which carries installation information for the unit\&. This section is not interpreted by +\fBsystemd\fR(1) +during runtime; it is used by the +\fBenable\fR +and +\fBdisable\fR +commands of the +\fBsystemctl\fR(1) +tool during installation of a unit\&. +.PP +\fIAlias=\fR +.RS 4 +A space\-separated list of additional names this unit shall be installed under\&. The names listed here must have the same suffix (i\&.e\&. type) as the unit filename\&. This option may be specified more than once, in which case all listed names are used\&. At installation time, +\fBsystemctl enable\fR +will create symlinks from these names to the unit filename\&. Note that not all unit types support such alias names, and this setting is not supported for them\&. Specifically, mount, slice, swap, and automount units do not support aliasing\&. +.sp +Added in version 201\&. +.RE +.PP +\fIWantedBy=\fR, \fIRequiredBy=\fR, \fIUpheldBy=\fR +.RS 4 +This option may be used more than once, or a space\-separated list of unit names may be given\&. A symbolic link is created in the +\&.wants/, +\&.requires/, or +\&.upholds/ +directory of each of the listed units when this unit is installed by +\fBsystemctl enable\fR\&. This has the effect of a dependency of type +\fIWants=\fR, +\fIRequires=\fR, or +\fIUpholds=\fR +being added from the listed unit to the current unit\&. See the description of the mentioned dependency types in the [Unit] section for details\&. +.sp +In case of template units listing non template units, the listing unit must have +\fIDefaultInstance=\fR +set, or +\fBsystemctl enable\fR +must be called with an instance name\&. The instance (default or specified) will be added to the +\&.wants/, +\&.requires/, or +\&.upholds/ +list of the listed unit\&. For example, +\fBWantedBy=getty\&.target\fR +in a service +getty@\&.service +will result in +\fBsystemctl enable getty@tty2\&.service\fR +creating a +getty\&.target\&.wants/getty@tty2\&.service +link to +getty@\&.service\&. This also applies to listing specific instances of templated units: this specific instance will gain the dependency\&. A template unit may also list a template unit, in which case a generic dependency will be added where each instance of the listing unit will have a dependency on an instance of the listed template with the same instance value\&. For example, +\fBWantedBy=container@\&.target\fR +in a service +monitor@\&.service +will result in +\fBsystemctl enable monitor@\&.service\fR +creating a +container@\&.target\&.wants/monitor@\&.service +link to +monitor@\&.service, which applies to all instances of +container@\&.target\&. +.sp +Added in version 201\&. +.RE +.PP +\fIAlso=\fR +.RS 4 +Additional units to install/deinstall when this unit is installed/deinstalled\&. If the user requests installation/deinstallation of a unit with this option configured, +\fBsystemctl enable\fR +and +\fBsystemctl disable\fR +will automatically install/uninstall units listed in this option as well\&. +.sp +This option may be used more than once, or a space\-separated list of unit names may be given\&. +.sp +Added in version 201\&. +.RE +.PP +\fIDefaultInstance=\fR +.RS 4 +In template unit files, this specifies for which instance the unit shall be enabled if the template is enabled without any explicitly set instance\&. This option has no effect in non\-template unit files\&. The specified string must be usable as instance identifier\&. +.sp +Added in version 215\&. +.RE +.PP +The following specifiers are interpreted in the Install section: %a, %b, %B, %g, %G, %H, %i, %j, %l, %m, %n, %N, %o, %p, %u, %U, %v, %w, %W, %%\&. For their meaning see the next section\&. +.SH "SPECIFIERS" +.PP +Many settings resolve specifiers which may be used to write generic unit files referring to runtime or unit parameters that are replaced when the unit files are loaded\&. Specifiers must be known and resolvable for the setting to be valid\&. The following specifiers are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&5.\ \&Specifiers available in unit files +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR above for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%C" +T}:T{ +Cache directory root +T}:T{ +This is either /var/cache (for the system manager) or the path "$XDG_CACHE_HOME" resolves to (for user managers)\&. +T} +T{ +"%d" +T}:T{ +Credentials directory +T}:T{ +This is the value of the "$CREDENTIALS_DIRECTORY" environment variable if available\&. See section "Credentials" in \fBsystemd.exec\fR(5) for more information\&. +T} +T{ +"%E" +T}:T{ +Configuration directory root +T}:T{ +This is either /etc/ (for the system manager) or the path "$XDG_CONFIG_HOME" resolves to (for user managers)\&. +T} +T{ +"%f" +T}:T{ +Unescaped filename +T}:T{ +This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the unescaped prefix name prepended with /\&. This implements unescaping according to the rules for escaping absolute file system paths discussed above\&. +T} +T{ +"%g" +T}:T{ +User group +T}:T{ +This is the name of the group running the service manager instance\&. In case of the system manager this resolves to "root"\&. +T} +T{ +"%G" +T}:T{ +User GID +T}:T{ +This is the numeric GID of the user running the service manager instance\&. In case of the system manager this resolves to "0"\&. +T} +T{ +"%h" +T}:T{ +User home directory +T}:T{ +This is the home directory of the \fIuser running the service manager instance\fR\&. In case of the system manager this resolves to "/root"\&. + +Note that this setting is \fInot\fR influenced by the \fIUser=\fR setting configurable in the [Service] section of the service unit\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system at the point in time the unit configuration is loaded\&. +T} +T{ +"%i" +T}:T{ +Instance name +T}:T{ +For instantiated units this is the string between the first "@" character and the type suffix\&. Empty for non\-instantiated units\&. +T} +T{ +"%I" +T}:T{ +Unescaped instance name +T}:T{ +Same as "%i", but with escaping undone\&. +T} +T{ +"%j" +T}:T{ +Final component of the prefix +T}:T{ +This is the string between the last "\-" and the end of the prefix name\&. If there is no "\-", this is the same as "%p"\&. +T} +T{ +"%J" +T}:T{ +Unescaped final component of the prefix +T}:T{ +Same as "%j", but with escaping undone\&. +T} +T{ +"%l" +T}:T{ +Short host name +T}:T{ +The hostname of the running system at the point in time the unit configuration is loaded, truncated at the first dot to remove any domain component\&. +T} +T{ +"%L" +T}:T{ +Log directory root +T}:T{ +This is either /var/log (for the system manager) or the path \fI$XDG_STATE_HOME\fR resolves to with /log appended (for user managers)\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%n" +T}:T{ +Full unit name +T}:T{ +\ \& +T} +T{ +"%N" +T}:T{ +Full unit name +T}:T{ +Same as "%n", but with the type suffix removed\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%p" +T}:T{ +Prefix name +T}:T{ +For instantiated units, this refers to the string before the first "@" character of the unit name\&. For non\-instantiated units, same as "%N"\&. +T} +T{ +"%P" +T}:T{ +Unescaped prefix name +T}:T{ +Same as "%p", but with escaping undone\&. +T} +T{ +"%q" +T}:T{ +Pretty host name +T}:T{ +The pretty hostname of the running system at the point in time the unit configuration is loaded, as read from the \fIPRETTY_HOSTNAME=\fR field of /etc/machine\-info\&. If not set, resolves to the short hostname\&. See \fBmachine-info\fR(5) for more information\&. +T} +T{ +"%s" +T}:T{ +User shell +T}:T{ +This is the shell of the user running the service manager instance\&. +T} +T{ +"%S" +T}:T{ +State directory root +T}:T{ +This is either /var/lib (for the system manager) or the path \fI$XDG_STATE_HOME\fR resolves to (for user managers)\&. +T} +T{ +"%t" +T}:T{ +Runtime directory root +T}:T{ +This is either /run/ (for the system manager) or the path "$XDG_RUNTIME_DIR" resolves to (for user managers)\&. +T} +T{ +"%T" +T}:T{ +Directory for temporary files +T}:T{ +This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%u" +T}:T{ +User name +T}:T{ +This is the name of the \fIuser running the service manager instance\fR\&. In case of the system manager this resolves to "root"\&. + +Note that this setting is \fInot\fR influenced by the \fIUser=\fR setting configurable in the [Service] section of the service unit\&. +T} +T{ +"%U" +T}:T{ +User UID +T}:T{ +This is the numeric UID of the \fIuser running the service manager instance\fR\&. In case of the system manager this resolves to "0"\&. + +Note that this setting is \fInot\fR influenced by the \fIUser=\fR setting configurable in the [Service] section of the service unit\&. +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%V" +T}:T{ +Directory for larger and persistent temporary files +T}:T{ +This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%y" +T}:T{ +The path to the fragment +T}:T{ +This is the path where the main part of the unit file is located\&. For linked unit files, the real path outside of the unit search directories is used\&. For units that don\*(Aqt have a fragment file, this specifier will raise an error\&. +T} +T{ +"%Y" +T}:T{ +The directory of the fragment +T}:T{ +This is the directory part of "%y"\&. +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Allowing units to be enabled\fR +.PP +The following snippet (highlighted) allows a unit (e\&.g\&. +foo\&.service) to be enabled via +\fBsystemctl enable\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo\-daemon + +\fI[Install]\fR +\fIWantedBy=multi\-user\&.target\fR +.fi +.if n \{\ +.RE +.\} +.PP +After running +\fBsystemctl enable\fR, a symlink +/etc/systemd/system/multi\-user\&.target\&.wants/foo\&.service +linking to the actual unit will be created\&. It tells systemd to pull in the unit when starting +multi\-user\&.target\&. The inverse +\fBsystemctl disable\fR +will remove that symlink again\&. +.PP +\fBExample\ \&2.\ \&Overriding vendor settings\fR +.PP +There are two methods of overriding vendor settings in unit files: copying the unit file from +/usr/lib/systemd/system +to +/etc/systemd/system +and modifying the chosen settings\&. Alternatively, one can create a directory named +\fIunit\fR\&.d/ +within +/etc/systemd/system +and place a drop\-in file +\fIname\fR\&.conf +there that only changes the specific settings one is interested in\&. Note that multiple such drop\-in files are read if present, processed in lexicographic order of their filename\&. +.PP +The advantage of the first method is that one easily overrides the complete unit, the vendor unit is not parsed at all anymore\&. It has the disadvantage that improvements to the unit file by the vendor are not automatically incorporated on updates\&. +.PP +The advantage of the second method is that one only overrides the settings one specifically wants, where updates to the unit by the vendor automatically apply\&. This has the disadvantage that some future updates by the vendor might be incompatible with the local changes\&. +.PP +This also applies for user instances of systemd, but with different locations for the unit files\&. See the section on unit load paths for further details\&. +.PP +Suppose there is a vendor\-supplied unit +/usr/lib/systemd/system/httpd\&.service +with the following contents: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Some HTTP server +After=remote\-fs\&.target sqldb\&.service +Requires=sqldb\&.service +AssertPathExists=/srv/webserver + +[Service] +Type=notify +ExecStart=/usr/sbin/some\-fancy\-httpd\-server +Nice=5 + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Now one wants to change some settings as an administrator: firstly, in the local setup, +/srv/webserver +might not exist, because the HTTP server is configured to use +/srv/www +instead\&. Secondly, the local configuration makes the HTTP server also depend on a memory cache service, +memcached\&.service, that should be pulled in (\fIRequires=\fR) and also be ordered appropriately (\fIAfter=\fR)\&. Thirdly, in order to harden the service a bit more, the administrator would like to set the +\fIPrivateTmp=\fR +setting (see +\fBsystemd.exec\fR(5) +for details)\&. And lastly, the administrator would like to reset the niceness of the service to its default value of 0\&. +.PP +The first possibility is to copy the unit file to +/etc/systemd/system/httpd\&.service +and change the chosen settings: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=Some HTTP server +After=remote\-fs\&.target sqldb\&.service \fImemcached\&.service\fR +Requires=sqldb\&.service \fImemcached\&.service\fR +AssertPathExists=\fI/srv/www\fR + +[Service] +Type=notify +ExecStart=/usr/sbin/some\-fancy\-httpd\-server +\fINice=0\fR +\fIPrivateTmp=yes\fR + +[Install] +WantedBy=multi\-user\&.target +.fi +.if n \{\ +.RE +.\} +.PP +Alternatively, the administrator could create a drop\-in file +/etc/systemd/system/httpd\&.service\&.d/local\&.conf +with the following contents: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +After=memcached\&.service +Requires=memcached\&.service +# Reset all assertions and then re\-add the condition we want +AssertPathExists= +AssertPathExists=/srv/www + +[Service] +Nice=0 +PrivateTmp=yes +.fi +.if n \{\ +.RE +.\} +.PP +Note that for drop\-in files, if one wants to remove entries from a setting that is parsed as a list (and is not a dependency), such as +\fIAssertPathExists=\fR +(or e\&.g\&. +\fIExecStart=\fR +in service units), one needs to first clear the list before re\-adding all entries except the one that is to be removed\&. Dependencies (\fIAfter=\fR, etc\&.) cannot be reset to an empty list, so dependencies can only be added in drop\-ins\&. If you want to remove dependencies, you have to override the entire unit\&. +.PP +\fBExample\ \&3.\ \&Top level drop\-ins with template units\fR +.PP +Top level per\-type drop\-ins can be used to change some aspect of all units of a particular type\&. For example, by creating the +/etc/systemd/system/service\&.d/ +directory with a drop\-in file, the contents of the drop\-in file can be applied to all service units\&. We can take this further by having the top\-level drop\-in instantiate a secondary helper unit\&. Consider for example the following set of units and drop\-in files where we install an +\fIOnFailure=\fR +dependency for all service units\&. +.PP +/etc/systemd/system/failure\-handler@\&.service: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +Description=My failure handler for %i + +[Service] +Type=oneshot +# Perform some special action for when %i exits unexpectedly\&. +ExecStart=/usr/sbin/myfailurehandler %i + +.fi +.if n \{\ +.RE +.\} +.PP +We can then add an instance of +failure\-handler@\&.service +as an +\fIOnFailure=\fR +dependency for all service units\&. +.PP +/etc/systemd/system/service\&.d/10\-all\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +[Unit] +OnFailure=failure\-handler@%N\&.service + +.fi +.if n \{\ +.RE +.\} +.PP +Now, after running +\fBsystemctl daemon\-reload\fR +all services will have acquired an +\fIOnFailure=\fR +dependency on +failure\-handler@%N\&.service\&. The template instance units will also have gained the dependency which results in the creation of a recursive dependency chain\&. systemd will try to detect these recursive dependency chains where a template unit directly and recursively depends on itself and will remove such dependencies automatically if it finds them\&. If systemd doesn\*(Aqt detect the recursive dependency chain, we can break the chain ourselves by disabling the drop\-in for the template instance units via a symlink to +/dev/null: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBmkdir /etc/systemd/system/failure\-handler@\&.service\&.d/\fR +\fBln \-s /dev/null /etc/systemd/system/failure\-handler@\&.service\&.d/10\-all\&.conf\fR +\fBsystemctl daemon\-reload\fR + +.fi +.if n \{\ +.RE +.\} +.PP +This ensures that if a +failure\-handler@\&.service +instance fails it will not trigger an instance named +failure\-handler@failure\-handler\&.service\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-system.conf\fR(5), +\fBsystemd.special\fR(7), +\fBsystemd.service\fR(5), +\fBsystemd.socket\fR(5), +\fBsystemd.device\fR(5), +\fBsystemd.mount\fR(5), +\fBsystemd.automount\fR(5), +\fBsystemd.swap\fR(5), +\fBsystemd.target\fR(5), +\fBsystemd.path\fR(5), +\fBsystemd.timer\fR(5), +\fBsystemd.scope\fR(5), +\fBsystemd.slice\fR(5), +\fBsystemd.time\fR(7), +\fBsystemd-analyze\fR(1), +\fBcapabilities\fR(7), +\fBsystemd.directives\fR(7), +\fBuname\fR(1) +.SH "NOTES" +.IP " 1." 4 +Interface Portability and Stability Promise +.RS 4 +\%https://systemd.io/PORTABILITY_AND_STABILITY/ +.RE +.IP " 2." 4 +systemd and Storage Daemons for the Root File System +.RS 4 +\%https://systemd.io/ROOT_STORAGE_DAEMONS +.RE +.IP " 3." 4 +System and Service Credentials +.RS 4 +\%https://systemd.io/CREDENTIALS +.RE +.IP " 4." 4 +PSI (Pressure Stall Information) +.RS 4 +\%https://docs.kernel.org/accounting/psi.html +.RE diff --git a/upstream/fedora-40/man5/sysupdate.d.5 b/upstream/fedora-40/man5/sysupdate.d.5 new file mode 100644 index 00000000..456bdb01 --- /dev/null +++ b/upstream/fedora-40/man5/sysupdate.d.5 @@ -0,0 +1,1340 @@ +'\" t +.TH "SYSUPDATE\&.D" "5" "" "systemd 255" "sysupdate.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +sysupdate.d \- Transfer Definition Files for Automatic Updates +.SH "SYNOPSIS" +.PP +.nf +/etc/sysupdate\&.d/*\&.conf +/run/sysupdate\&.d/*\&.conf +/usr/lib/sysupdate\&.d/*\&.conf + +.fi +.SH "DESCRIPTION" +.PP +sysupdate\&.d/*\&.conf +files describe how specific resources on the local system shall be updated from a remote source\&. Each such file defines one such transfer: typically a remote HTTP/HTTPS resource as source; and a local file, directory or partition as target\&. This may be used as a simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system extension images \(em but in fact may be used to update any kind of file from a remote source\&. +.PP +The +\fBsystemd-sysupdate\fR(8) +command reads these files and uses them to determine which local resources should be updated, and then executes the update\&. +.PP +Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent versions, in order to implement flexible update schemes, e\&.g\&. A/B updating (or a superset thereof, e\&.g\&. A/B/C, A/B/C/D, \&...)\&. +.PP +Each +*\&.conf +file defines one transfer, i\&.e\&. describes one resource to update\&. Typically, multiple of these files (i\&.e\&. multiple of such transfers) are defined together, and are bound together by a common version identifier in order to update multiple resources at once on each update operation, for example to update a kernel, a root file system and a Verity partition in a single, combined, synchronized operation, so that only a combined update of all three together constitutes a complete update\&. +.PP +Each +*\&.conf +file contains three sections: [Transfer], [Source] and [Target]\&. +.SH "BASIC MODE OF OPERATION" +.PP +Disk\-image based OS updates typically consist of multiple different resources that need to be updated together, for example a secure OS update might consist of a root file system image to drop into a partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the combination of the two partitions\&. The first two resources are files that are downloaded and placed in a disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file system (e\&.g\&. EFI system partition)\&. Hence, during an update of a hypothetical operating system "foobarOS" to a hypothetical version 47 the following operations should take place: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +A file +"https://download\&.example\&.com/foobarOS_47\&.root\&.xz" +should be downloaded, decompressed and written to a previously unused partition with GPT partition type UUID 4f68bce3\-e8cd\-4db1\-96e7\-fbcaf984b709 for x86\-64, as per +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Similarly, a file +"https://download\&.example\&.com/foobarOS_47\&.verity\&.xz" +should be downloaded, decompressed and written to a previously empty partition with GPT partition type UUID of 2c7357ed\-ebd2\-46d9\-aec1\-23d437ec2bf5 (i\&.e\&. the partition type for Verity integrity information for x86\-64 root file systems)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Finally, a file +"https://download\&.example\&.com/foobarOS_47\&.efi\&.xz" +(a unified kernel, as per +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2 +Type #2) should be downloaded, decompressed and written to the $BOOT file system, i\&.e\&. to +EFI/Linux/foobarOS_47\&.efi +in the ESP or XBOOTLDR partition\&. +.RE +.PP +The version\-independent generalization of this would be (using the special marker +"@v" +as wildcard for the version identifier): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +A transfer of a file +"https://download\&.example\&.com/foobarOS_@v\&.root\&.xz" +→ a local, previously empty GPT partition of type 4f68bce3\-e8cd\-4db1\-96e7\-fbcaf984b709, with the label to be set to +"foobarOS_@v"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +A transfer of a file +"https://download\&.example\&.com/foobarOS_@v\&.verity\&.xz" +→ a local, previously empty GPT partition of type 2c7357ed\-ebd2\-46d9\-aec1\-23d437ec2bf5, with the label to be set to +"foobarOS_@v_verity"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +A transfer of a file +"https://download\&.example\&.com/foobarOS_@v\&.efi\&.xz" +→ a local file +$BOOT/EFI/Linux/foobarOS_@v\&.efi\&. +.RE +.PP +An update can only complete if the relevant URLs provide their resources for the same version, i\&.e\&. for the same value of +"@v"\&. +.PP +The above may be translated into three +*\&.conf +files in +sysupdate\&.d/, one for each resource to transfer\&. The +*\&.conf +files configure the type of download, and what place to write the download to (i\&.e\&. whether to a partition or a file in the file system)\&. Most importantly these files contain the URL, partition name and filename patterns shown above that describe how these resources are called on the source and how they shall be called on the target\&. +.PP +In order to enumerate available versions and figuring out candidates to update to, a mechanism is necessary to list suitable files: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For partitions: the surrounding GPT partition table contains a list of defined partitions, including a partition type UUID and a partition label (in this scheme the partition label plays a role for the partition similar to the filename for a regular file)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For regular files: the directory listing of the directory the files are contained in provides a list of existing files in a straightforward way\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For HTTP/HTTPS sources a simple scheme is used: a manifest file +SHA256SUMS, following the format defined by +\fBsha256sum\fR(1), lists file names and their SHA256 hashes\&. +.RE +.PP +Transfers are done in the alphabetical order of the +\&.conf +file names they are defined in\&. First, the resource data is downloaded directly into a target file/directory/partition\&. Once this is completed for all defined transfers, in a second step the files/directories/partitions are renamed to their final names as defined by the target +\fIMatchPattern=\fR, again in the order the +\&.conf +transfer file names dictate\&. This step is not atomic, however it is guaranteed to be executed strictly in order with suitable disk synchronization in place\&. Typically, when updating an OS one of the transfers defines the entry point when booting\&. Thus it is generally a good idea to order the resources via the transfer configuration file names so that the entry point is written last, ensuring that any abnormal termination does not leave an entry point around whose backing is not established yet\&. In the example above it would hence make sense to establish the EFI kernel image last and thus give its transfer configuration file the alphabetically last name\&. +.PP +See below for an extended, more specific example based on the above\&. +.SH "RESOURCE TYPES" +.PP +Each transfer file defines one source resource to transfer to one target resource\&. The following resource types are supported: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Resources of type +"url\-file" +encapsulate a file on a web server, referenced via a HTTP or HTTPS URL\&. When an update takes place, the file is downloaded and decompressed and then written to the target file or partition\&. This resource type is only available for sources, not for targets\&. The list of available versions of resources of this type is encoded in +SHA256SUMS +manifest files, accompanied by +SHA256SUMS\&.gpg +detached signatures\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +The +"url\-tar" +resource type is similar, but the file must be a +\&.tar +archive\&. When an update takes place, the file is decompressed and unpacked into a directory or btrfs subvolume\&. This resource type is only available for sources, not for targets\&. Just like +"url\-file", +"url\-tar" +version enumeration makes use of +SHA256SUMS +files, authenticated via +SHA256SUMS\&.gpg\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +The +"regular\-file" +resource type encapsulates a local regular file on disk\&. During updates the file is uncompressed and written to the target file or partition\&. This resource type is available both as source and as target\&. When updating no integrity or authentication verification is done for resources of this type\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +The +"partition" +resource type is similar to +"regular\-file", and encapsulates a GPT partition on disk\&. When updating, the partition must exist already, and have the correct GPT partition type\&. A partition whose GPT partition label is set to +"_empty" +is considered empty, and a candidate to place a newly downloaded resource in\&. The GPT partition label is used to store version information, once a partition is updated\&. This resource type is only available for target resources\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +The +"tar" +resource type encapsulates local +\&.tar +archive files\&. When an update takes place, the files are uncompressed and unpacked into a target directory or btrfs subvolume\&. Behaviour of +"tar" +and +"url\-tar" +is generally similar, but the latter downloads from remote sources, and does integrity and authentication checks while the former does not\&. The +"tar" +resource type is only available for source resources\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +The +"directory" +resource type encapsulates local directory trees\&. This type is available both for source and target resources\&. If an update takes place on a source resource of this type, a recursive copy of the directory is done\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +The +"subvolume" +resource type is identical to +"directory", except when used as the target, in which case the file tree is placed in a btrfs subvolume instead of a plain directory, if the backing file system supports it (i\&.e\&. is btrfs)\&. +.RE +.PP +As already indicated, only a subset of source and target resource type combinations are supported: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Resource Types +.TS +allbox tab(:); +lB lB lB lB lB lB lB lB. +T{ +Identifier +T}:T{ +Description +T}:T{ +Usable as Source +T}:T{ +When Used as Source: Compatible Targets +T}:T{ +When Used as Source: Integrity + Authentication +T}:T{ +When Used as Source: Decompression +T}:T{ +Usable as Target +T}:T{ +When Used as Target: Compatible Sources +T} +.T& +l l l l l l l l +l l l l l l l l +l l l l l l l l +l l l l l l l l +l l l l l l l l +l l l l l l l l +l l l l l l l l. +T{ +\fBurl\-file\fR +T}:T{ +HTTP/HTTPS files +T}:T{ +yes +T}:T{ +\fBregular\-file\fR, \fBpartition\fR +T}:T{ +yes +T}:T{ +yes +T}:T{ +no +T}:T{ +\- +T} +T{ +\fBurl\-tar\fR +T}:T{ +HTTP/HTTPS \&.tar archives +T}:T{ +yes +T}:T{ +\fBdirectory\fR, \fBsubvolume\fR +T}:T{ +yes +T}:T{ +yes +T}:T{ +no +T}:T{ +\- +T} +T{ +\fBregular\-file\fR +T}:T{ +Local files +T}:T{ +yes +T}:T{ +\fBregular\-file\fR, \fBpartition\fR +T}:T{ +no +T}:T{ +yes +T}:T{ +yes +T}:T{ +\fBurl\-file\fR, \fBregular\-file\fR +T} +T{ +\fBpartition\fR +T}:T{ +Local GPT partitions +T}:T{ +no +T}:T{ +\- +T}:T{ +\- +T}:T{ +\- +T}:T{ +yes +T}:T{ +\fBurl\-file\fR, \fBregular\-file\fR +T} +T{ +\fBtar\fR +T}:T{ +Local \&.tar archives +T}:T{ +yes +T}:T{ +\fBdirectory\fR, \fBsubvolume\fR +T}:T{ +no +T}:T{ +yes +T}:T{ +no +T}:T{ +\- +T} +T{ +\fBdirectory\fR +T}:T{ +Local directories +T}:T{ +yes +T}:T{ +\fBdirectory\fR, \fBsubvolume\fR +T}:T{ +no +T}:T{ +no +T}:T{ +yes +T}:T{ +\fBurl\-tar\fR, \fBtar\fR, \fBdirectory\fR, \fBsubvolume\fR +T} +T{ +\fBsubvolume\fR +T}:T{ +Local btrfs subvolumes +T}:T{ +yes +T}:T{ +\fBdirectory\fR, \fBsubvolume\fR +T}:T{ +no +T}:T{ +no +T}:T{ +yes +T}:T{ +\fBurl\-tar\fR, \fBtar\fR, \fBdirectory\fR, \fBsubvolume\fR +T} +.TE +.sp 1 +.SH "MATCH PATTERNS" +.PP +Both the source and target resources typically exist in multiple versions concurrently\&. An update operation is done whenever the newest of the source versions is newer than the newest of the target versions\&. To determine the newest version of the resources a directory listing, partition listing or manifest listing is used, a subset of qualifying entries selected from that, and the version identifier extracted from the file names or partition labels of these selected entries\&. Subset selection and extraction of the version identifier (plus potentially other metadata) is done via match patterns, configured in +\fIMatchPattern=\fR +in the [Source] and [Target] sections\&. These patterns are strings that describe how files or partitions are named, with named wildcards for specific fields such as the version identifier\&. The following wildcards are defined: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&2.\ \&Match Pattern Wildcards +.TS +allbox tab(:); +lB lB lB lB. +T{ +Wildcard +T}:T{ +Description +T}:T{ +Format +T}:T{ +Notes +T} +.T& +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l +l l l l. +T{ +"@v" +T}:T{ +Version identifier +T}:T{ +Valid version string +T}:T{ +Mandatory +T} +T{ +"@u" +T}:T{ +GPT partition UUID +T}:T{ +Valid 128\-Bit UUID string +T}:T{ +Only relevant if target resource type chosen as \fBpartition\fR +T} +T{ +"@f" +T}:T{ +GPT partition flags +T}:T{ +Formatted hexadecimal integer +T}:T{ +Only relevant if target resource type chosen as \fBpartition\fR +T} +T{ +"@a" +T}:T{ +GPT partition flag NoAuto +T}:T{ +Either "0" or "1" +T}:T{ +Controls NoAuto bit of the GPT partition flags, as per \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2; only relevant if target resource type chosen as \fBpartition\fR +T} +T{ +"@g" +T}:T{ +GPT partition flag GrowFileSystem +T}:T{ +Either "0" or "1" +T}:T{ +Controls GrowFileSystem bit of the GPT partition flags, as per \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2; only relevant if target resource type chosen as \fBpartition\fR +T} +T{ +"@r" +T}:T{ +Read\-only flag +T}:T{ +Either "0" or "1" +T}:T{ +Controls ReadOnly bit of the GPT partition flags, as per \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2 and other output read\-only flags, see \fIReadOnly=\fR below +T} +T{ +"@t" +T}:T{ +File modification time +T}:T{ +Formatted decimal integer, μs since UNIX epoch Jan 1st 1970 +T}:T{ +Only relevant if target resource type chosen as \fBregular\-file\fR +T} +T{ +"@m" +T}:T{ +File access mode +T}:T{ +Formatted octal integer, in UNIX fashion +T}:T{ +Only relevant if target resource type chosen as \fBregular\-file\fR +T} +T{ +"@s" +T}:T{ +File size after decompression +T}:T{ +Formatted decimal integer +T}:T{ +Useful for measuring progress and to improve partition allocation logic +T} +T{ +"@d" +T}:T{ +Tries done +T}:T{ +Formatted decimal integer +T}:T{ +Useful when operating with kernel image files, as per \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2 +T} +T{ +"@l" +T}:T{ +Tries left +T}:T{ +Formatted decimal integer +T}:T{ +Useful when operating with kernel image files, as per \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2 +T} +T{ +"@h" +T}:T{ +SHA256 hash of compressed file +T}:T{ +64 hexadecimal characters +T}:T{ +The SHA256 hash of the compressed file; not useful for \fBurl\-file\fR or \fBurl\-tar\fR where the SHA256 hash is already included in the manifest file anyway +T} +.TE +.sp 1 +.PP +Of these wildcards only +"@v" +must be present in a valid pattern, all other wildcards are optional\&. Each wildcard may be used at most once in each pattern\&. A typical wildcard matching a file system source image could be +"MatchPattern=foobar_@v\&.raw\&.xz", i\&.e\&. any file whose name begins with +"foobar_", followed by a version ID and suffixed by +"\&.raw\&.xz"\&. +.PP +Do not confuse the +"@" +pattern matching wildcard prefix with the +"%" +specifier expansion prefix\&. The former encapsulate a variable part of a match pattern string, the latter are simple shortcuts that are expanded while the drop\-in files are parsed\&. For details about specifiers, see below\&. +.SH "[TRANSFER] SECTION OPTIONS" +.PP +This section defines general properties of this transfer\&. +.PP +\fIMinVersion=\fR +.RS 4 +Specifies the minimum version to require for this transfer to take place\&. If the source or target patterns in this transfer definition match files older than this version they will be considered obsolete, and never be considered for the update operation\&. +.sp +Added in version 251\&. +.RE +.PP +\fIProtectVersion=\fR +.RS 4 +Takes one or more version strings to mark as "protected"\&. Protected versions are never removed while making room for new, updated versions\&. This is useful to ensure that the currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten during updates, in order to avoid runtime file system corruptions\&. +.sp +Like many of the settings in these configuration files this setting supports specifier expansion\&. It\*(Aqs particularly useful to set this setting to one of the +"%A", +"%B" +or +"%w" +specifiers to automatically refer to the current OS version of the running system\&. See below for details on supported specifiers\&. +.sp +Added in version 251\&. +.RE +.PP +\fIVerify=\fR +.RS 4 +Takes a boolean, defaults to yes\&. Controls whether to cryptographically verify downloaded resources (specifically: validate the GPG signatures for downloaded +SHA256SUMS +manifest files, via their detached signature files +SHA256SUMS\&.gpg +in combination with the system keyring +/usr/lib/systemd/import\-pubring\&.gpg +or +/etc/systemd/import\-pubring\&.gpg)\&. +.sp +This option is essential to provide integrity guarantees for downloaded resources and thus should be left enabled, outside of test environments\&. +.sp +Note that the downloaded payload files are unconditionally checked against the SHA256 hashes listed in the manifest\&. This option only controls whether the signatures of these manifests are verified\&. +.sp +This option only has an effect if the source resource type is selected as +\fBurl\-file\fR +or +\fBurl\-tar\fR, as integrity and authentication checking is only available for transfers from remote sources\&. +.sp +Added in version 251\&. +.RE +.SH "[SOURCE] SECTION OPTIONS" +.PP +This section defines properties of the transfer source\&. +.PP +\fIType=\fR +.RS 4 +Specifies the resource type of the source for the transfer\&. Takes one of +\fBurl\-file\fR, +\fBurl\-tar\fR, +\fBtar\fR, +\fBregular\-file\fR, +\fBdirectory\fR +or +\fBsubvolume\fR\&. For details about the resource types, see above\&. This option is mandatory\&. +.sp +Note that only certain combinations of source and target resource types are supported, see above\&. +.sp +Added in version 251\&. +.RE +.PP +\fIPath=\fR +.RS 4 +Specifies where to find source versions of this resource\&. +.sp +If the source type is selected as +\fBurl\-file\fR +or +\fBurl\-tar\fR +this must be a HTTP/HTTPS URL\&. The URL is suffixed with +/SHA256SUMS +to acquire the manifest file, with +/SHA256SUMS\&.gpg +to acquire the detached signature file for it, and with the file names listed in the manifest file in case an update is executed and a resource shall be downloaded\&. +.sp +For all other source resource types this must be a local path in the file system, referring to a local directory to find the versions of this resource in\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMatchPattern=\fR +.RS 4 +Specifies one or more file name match patterns that select the subset of files that are update candidates as source for this transfer\&. See above for details on match patterns\&. +.sp +This option is mandatory\&. Any pattern listed must contain at least the +"@v" +wildcard, so that a version identifier may be extracted from the filename\&. All other wildcards are optional\&. +.sp +If the source type is +\fBregular\-file\fR +or +\fBdirectory\fR, the pattern may contain slash characters\&. In this case it will match the file or directory in corresponding subdirectory\&. For example +"MatchPattern=foo_@v/bar\&.efi" +will match +"bar\&.efi" +in directory +"foo_1"\&. +.sp +Added in version 251\&. +.RE +.SH "[TARGET] SECTION OPTIONS" +.PP +This section defines properties of the transfer target\&. +.PP +\fIType=\fR +.RS 4 +Specifies the resource type of the target for the transfer\&. Takes one of +\fBpartition\fR, +\fBregular\-file\fR, +\fBdirectory\fR +or +\fBsubvolume\fR\&. For details about the resource types, see above\&. This option is mandatory\&. +.sp +Note that only certain combinations of source and target resource types are supported, see above\&. +.sp +Added in version 251\&. +.RE +.PP +\fIPath=\fR +.RS 4 +Specifies a file system path where to look for already installed versions or place newly downloaded versions of this configured resource\&. If +\fIType=\fR +is set to +\fBpartition\fR, expects a path to a (whole) block device node, or the special string +"auto" +in which case the block device which contains the root file system of the currently booted system is automatically determined and used\&. If +\fIType=\fR +is set to +\fBregular\-file\fR, +\fBdirectory\fR +or +\fBsubvolume\fR, must refer to a path in the local file system referencing the directory to find or place the version files or directories under\&. +.sp +Note that this mechanism cannot be used to create or remove partitions, in case +\fIType=\fR +is set to +\fBpartition\fR\&. Partitions must exist already, and a special partition label +"_empty" +is used to indicate empty partitions\&. To automatically generate suitable partitions on first boot, use a tool such as +\fBsystemd-repart\fR(8)\&. +.sp +Added in version 251\&. +.RE +.PP +\fIPathRelativeTo=\fR +.RS 4 +Specifies what partition +\fIPath=\fR +should be relative to\&. Takes one of +\fBroot\fR, +\fBesp\fR, +\fBxbootldr\fR, or +\fBboot\fR\&. If unspecified, defaults to +\fBroot\fR\&. +.sp +If set to +\fBboot\fR, the specified +\fIPath=\fR +will be resolved relative to the mount point of the $BOOT partition (i\&.e\&. the ESP or XBOOTLDR), as defined by the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. +.sp +The values +\fBesp\fR, +\fBxbootldr\fR, and +\fBboot\fR +are only supported when +\fIType=\fR +is set to +\fBregular\-file\fR +or +\fBdirectory\fR\&. +.sp +Added in version 254\&. +.RE +.PP +\fIMatchPattern=\fR +.RS 4 +Specifies one or more file name or partition label match patterns that select the subset of files or partitions that are update candidates as targets for this transfer\&. See above for details on match patterns\&. +.sp +This option is mandatory\&. Any pattern listed must contain at least the +"@v" +wildcard, so that a version identifier may be extracted from the filename\&. All other wildcards are optional\&. +.sp +This pattern is both used for matching existing installed versions and for determining the name of new versions to install\&. If multiple patterns are specified, the first specified is used for naming newly installed versions\&. +.sp +If the target type is +\fBregular\-file\fR +or +\fBdirectory\fR, the pattern may contain slash characters\&. In this case it will match the file or directory in corresponding subdirectory\&. For example +"MatchPattern=foo_@v/bar\&.efi" +will match +"bar\&.efi" +in directory +"foo_1"\&. Directories in the path will be created when file is installed\&. Empty directories will be removed when file is removed\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMatchPartitionType=\fR +.RS 4 +When the target +\fIType=\fR +is chosen as +\fBpartition\fR, specifies the GPT partition type to look for\&. Only partitions of this type are considered, all other partitions are ignored\&. If not specified, the GPT partition type +\fBlinux\-generic\fR +is used\&. Accepts either a literal type UUID or a symbolic type identifier\&. For a list of supported type identifiers, see the +\fIType=\fR +setting in +\fBrepart.d\fR(5)\&. +.sp +Added in version 251\&. +.RE +.PP +\fIPartitionUUID=\fR, \fIPartitionFlags=\fR, \fIPartitionNoAuto=\fR, \fIPartitionGrowFileSystem=\fR +.RS 4 +When the target +\fIType=\fR +is picked as +\fBpartition\fR, selects the GPT partition UUID and partition flags to use for the updated partition\&. Expects a valid UUID string, a hexadecimal integer, or booleans, respectively\&. If not set, but the source match pattern includes wildcards for these fields (i\&.e\&. +"@u", +"@f", +"@a", or +"@g"), the values from the patterns are used\&. If neither configured with wildcards or these explicit settings, the values are left untouched\&. If both the overall +\fIPartitionFlags=\fR +flags setting and the individual flag settings +\fIPartitionNoAuto=\fR +and +\fIPartitionGrowFileSystem=\fR +are used (or the wildcards for them), then the latter override the former, i\&.e\&. the individual flag bit overrides the overall flags value\&. See +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2 +for details about these flags\&. +.sp +Note that these settings are not used for matching, they only have effect on newly written partitions in case a transfer takes place\&. +.sp +Added in version 251\&. +.RE +.PP +\fIReadOnly=\fR +.RS 4 +Controls whether to mark the resulting file, subvolume or partition read\-only\&. If the target type is +\fBpartition\fR +this controls the ReadOnly partition flag, as per +\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2, similar to the +\fIPartitionNoAuto=\fR +and +\fIPartitionGrowFileSystem=\fR +flags described above\&. If the target type is +\fBregular\-file\fR, the writable bit is removed from the access mode\&. If the target type is +\fBsubvolume\fR, the subvolume will be marked read\-only as a whole\&. Finally, if the target +\fIType=\fR +is selected as +\fBdirectory\fR, the "immutable" file attribute is set, see +\fBchattr\fR(1) +for details\&. +.sp +Added in version 251\&. +.RE +.PP +\fIMode=\fR +.RS 4 +The UNIX file access mode to use for newly created files in case the target resource type is picked as +\fBregular\-file\fR\&. Expects an octal integer, in typical UNIX fashion\&. If not set, but the source match pattern includes a wildcard for this field (i\&.e\&. +"@t"), the value from the pattern is used\&. +.sp +Note that this setting is not used for matching, it only has an effect on newly written files when a transfer takes place\&. +.sp +Added in version 251\&. +.RE +.PP +\fITriesDone=\fR, \fITriesLeft=\fR +.RS 4 +These options take positive, decimal integers, and control the number of attempts done and left for this file\&. These settings are useful for managing kernel images, following the scheme defined in +\m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2, and only have an effect if the target pattern includes the +"@d" +or +"@l" +wildcards\&. +.sp +Added in version 251\&. +.RE +.PP +\fIInstancesMax=\fR +.RS 4 +Takes a decimal integer equal to or greater than 2\&. This configures how many concurrent versions of the resource to keep\&. Whenever a new update is initiated it is made sure that no more than the number of versions specified here minus one exist in the target\&. Any excess versions are deleted (in case the target +\fIType=\fR +of +\fBregular\-file\fR, +\fBdirectory\fR, +\fBsubvolume\fR +is used) or emptied (in case the target +\fIType=\fR +of +\fBpartition\fR +is used; emptying in this case simply means to set the partition label to the special string +"_empty"; note that no partitions are actually removed)\&. After an update is completed the number of concurrent versions of the target resources is equal to or below the number specified here\&. +.sp +Note that this setting may be set differently for each transfer\&. However, it generally is advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of files or partitions will be left installed\&. +.sp +If the target +\fIType=\fR +is selected as +\fBpartition\fR, the number of concurrent versions to keep is additionally restricted by the number of partition slots of the right type in the partition table\&. I\&.e\&. if there are only 2 partition slots for the selected partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent versions could be stored in the image anyway\&. +.sp +Added in version 251\&. +.RE +.PP +\fIRemoveTemporary=\fR +.RS 4 +Takes a boolean argument\&. If this option is enabled (which is the default) before initiating an update, all left\-over, incomplete updates from a previous attempt are removed from the target directory\&. This only has an effect if the target resource +\fIType=\fR +is selected as +\fBregular\-file\fR, +\fBdirectory\fR +or +\fBsubvolume\fR\&. +.sp +Added in version 251\&. +.RE +.PP +\fICurrentSymlink=\fR +.RS 4 +Takes a symlink name as argument\&. If this option is used, as the last step of the update a symlink under the specified name is created/updated pointing to the completed update\&. This is useful in to provide a stable name always pointing to the newest version of the resource\&. This is only supported if the target resource +\fIType=\fR +is selected as +\fBregular\-file\fR, +\fBdirectory\fR +or +\fBsubvolume\fR\&. +.sp +Added in version 251\&. +.RE +.SH "SPECIFIERS" +.PP +Specifiers may be used in the +\fIMinVersion=\fR, +\fIProtectVersion=\fR, +\fIPath=\fR, +\fIMatchPattern=\fR +and +\fICurrentSymlink=\fR +settings\&. The following expansions are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&3.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system\&. +T} +T{ +"%l" +T}:T{ +Short host name +T}:T{ +The hostname of the running system, truncated at the first dot to remove any domain component\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%T" +T}:T{ +Directory for temporary files +T}:T{ +This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%V" +T}:T{ +Directory for larger and persistent temporary files +T}:T{ +This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +.PP +Do not confuse the +"%" +specifier expansion prefix with the +"@" +pattern matching wildcard prefix\&. The former are simple shortcuts that are expanded while the drop\-in files are parsed, the latter encapsulate a variable part of a match pattern string\&. For details about pattern matching wildcards, see above\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Updates for a Verity Enabled Secure OS\fR +.PP +With the following three files we define a root file system partition, a matching Verity partition, and a unified kernel image to update as one\&. This example is an extension of the example discussed earlier in this man page\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/sysupdate\&.d/50\-verity\&.conf +[Transfer] +ProtectVersion=%A + +[Source] +Type=url\-file +Path=https://download\&.example\&.com/ +MatchPattern=foobarOS_@v_@u\&.verity\&.xz + +[Target] +Type=partition +Path=auto +MatchPattern=foobarOS_@v_verity +MatchPartitionType=root\-verity +PartitionFlags=0 +ReadOnly=1 +.fi +.if n \{\ +.RE +.\} +.PP +The above defines the update mechanism for the Verity partition of the root file system\&. Verity partition images are downloaded from +"https://download\&.example\&.com/foobarOS_@v_@u\&.verity\&.xz" +and written to a suitable local partition, which is marked read\-only\&. Under the assumption this update is run from the image itself the current image version (i\&.e\&. the +"%A" +specifier) is marked as protected, to ensure it is not corrupted while booted\&. Note that the partition UUID for the target partition is encoded in the source file name\&. Fixating the partition UUID can be useful to ensure that +"roothash=" +on the kernel command line is sufficient to pinpoint both the Verity and root file system partition, and also encode the Verity root level hash (under the assumption the UUID in the file names match their top\-level hash, the way +\fBsystemd-gpt-auto-generator\fR(8) +suggests)\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/sysupdate\&.d/60\-root\&.conf +[Transfer] +ProtectVersion=%A + +[Source] +Type=url\-file +Path=https://download\&.example\&.com/ +MatchPattern=foobarOS_@v_@u\&.root\&.xz + +[Target] +Type=partition +Path=auto +MatchPattern=foobarOS_@v +MatchPartitionType=root +PartitionFlags=0 +ReadOnly=1 +.fi +.if n \{\ +.RE +.\} +.PP +The above defines a matching transfer definition for the root file system\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/sysupdate\&.d/70\-kernel\&.conf +[Transfer] +ProtectVersion=%A + +[Source] +Type=url\-file +Path=https://download\&.example\&.com/ +MatchPattern=foobarOS_@v\&.efi\&.xz + +[Target] +Type=regular\-file +Path=/EFI/Linux +PathRelativeTo=boot +MatchPattern=foobarOS_@v+@l\-@d\&.efi \e + foobarOS_@v+@l\&.efi \e + foobarOS_@v\&.efi +Mode=0444 +TriesLeft=3 +TriesDone=0 +InstancesMax=2 +.fi +.if n \{\ +.RE +.\} +.PP +The above installs a unified kernel image into the $BOOT partition, as per +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2 +Type #2\&. This defines three possible patterns for the names of the kernel images, as per +\m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[3]\d\s+2, and ensures when installing new kernels, they are set up with 3 tries left\&. No more than two parallel kernels are kept\&. +.PP +With this setup the web server would serve the following files, for a hypothetical version 7 of the OS: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA256SUMS +\(en The manifest file, containing available files and their SHA256 hashes +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA256SUMS\&.gpg +\(en The detached cryptographic signature for the manifest file +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +foobarOS_7_8b8186b1\-2b4e\-4eb6\-ad39\-8d4d18d2a8fb\&.verity\&.xz +\(en The Verity image for version 7 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +foobarOS_7_f4d1234f\-3ebf\-47c4\-b31d\-4052982f9a2f\&.root\&.xz +\(en The root file system image for version 7 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +foobarOS_7_efi\&.xz +\(en The unified kernel image for version 7 +.RE +.PP +For each new OS release a new set of the latter three files would be added, each time with an updated version\&. The +SHA256SUMS +manifest should then be updated accordingly, listing all files for all versions that shall be offered for download\&. +.PP +\fBExample\ \&2.\ \&Updates for Plain Directory Container Image\fR +.PP +.if n \{\ +.RS 4 +.\} +.nf +[Source] +Type=url\-tar +Path=https://download\&.example\&.com/ +MatchPattern=myContainer_@v\&.tar\&.gz + +[Target] +Type=subvolume +Path=/var/lib/machines +MatchPattern=myContainer_@v +CurrentSymlink=myContainer +.fi +.if n \{\ +.RE +.\} +.PP +On updates this downloads +"https://download\&.example\&.com/myContainer_@v\&.tar\&.gz" +and decompresses/unpacks it to +/var/lib/machines/myContainer_@v\&. After each update a symlink +/var/lib/machines/myContainer +is created/updated always pointing to the most recent update\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-sysupdate\fR(8), +\fBsystemd-repart\fR(8) +.SH "NOTES" +.IP " 1." 4 +Discoverable Partitions Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification +.RE +.IP " 2." 4 +Boot Loader Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/boot_loader_specification +.RE +.IP " 3." 4 +Automatic Boot Assessment +.RS 4 +\%https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT +.RE diff --git a/upstream/fedora-40/man5/sysusers.d.5 b/upstream/fedora-40/man5/sysusers.d.5 new file mode 100644 index 00000000..a44d461f --- /dev/null +++ b/upstream/fedora-40/man5/sysusers.d.5 @@ -0,0 +1,377 @@ +'\" t +.TH "SYSUSERS\&.D" "5" "" "systemd 255" "sysusers.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +sysusers.d \- Declarative allocation of system users and groups +.SH "SYNOPSIS" +.PP +/etc/sysusers\&.d/*\&.conf +.PP +/run/sysusers\&.d/*\&.conf +.PP +/usr/lib/sysusers\&.d/*\&.conf +.sp +.nf +#Type Name ID GECOS Home directory Shell +u user_name uid "User Description" /home/dir /path/to/shell +u user_name uid:gid "User Description" /home/dir /path/to/shell +u user_name /file/owned/by/user "User Description" /home/dir /path/to/shell +g group_name gid +g group_name /file/owned/by/group +m user_name group_name +r \- lowest\-highest +.fi +.SH "DESCRIPTION" +.PP +\fBsystemd\-sysusers\fR +uses the files from +sysusers\&.d +directory to create system users and groups and to add users to groups, at package installation or boot time\&. This tool may be used to allocate system users and groups only, it is not useful for creating non\-system (i\&.e\&. regular, "human") users and groups, as it accesses +/etc/passwd +and +/etc/group +directly, bypassing any more complex user databases, for example any database involving NIS or LDAP\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +Each configuration file shall be named in the style of +\fIpackage\fR\&.conf +or +\fIpackage\fR\-\fIpart\fR\&.conf\&. The second variant should be used when it is desirable to make it easy to override just this part of configuration\&. +.PP +Files in +/etc/sysusers\&.d +override files with the same name in +/usr/lib/sysusers\&.d +and +/run/sysusers\&.d\&. Files in +/run/sysusers\&.d +override files with the same name in +/usr/lib/sysusers\&.d\&. Packages should install their configuration files in +/usr/lib/sysusers\&.d\&. Files in +/etc/sysusers\&.d +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same path, the entry in the file with the lexicographically earliest name will be applied\&. All later entries for the same user and group names will be logged as warnings\&. +.PP +If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in +/etc/sysusers\&.d/ +bearing the same filename\&. +.SH "CONFIGURATION FILE FORMAT" +.PP +The file format is one line per user or group containing name, ID, GECOS field description, home directory, and login shell: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#Type Name ID GECOS Home directory Shell +u httpd 404 "HTTP User" +u _authd /usr/bin/authd "Authorization user" +u postgres \- "Postgresql Database" /var/lib/pgsql /usr/libexec/postgresdb +g input \- \- +m _authd input +u root 0 "Superuser" /root /bin/zsh +r \- 500\-900 +.fi +.if n \{\ +.RE +.\} +.PP +Empty lines and lines beginning with the +"#" +character are ignored, and may be used for commenting\&. +.SS "Type" +.PP +The type consists of a single letter\&. The following line types are understood: +.PP +\fIu\fR +.RS 4 +Create a system user and group of the specified name should they not exist yet\&. The user\*(Aqs primary group will be set to the group bearing the same name unless the ID field specifies it\&. The account will be created disabled, so that logins are not allowed\&. +.sp +Added in version 215\&. +.RE +.PP +\fIg\fR +.RS 4 +Create a system group of the specified name should it not exist yet\&. Note that +\fIu\fR +implicitly creates a matching group\&. The group will be created with no password set\&. +.sp +Added in version 215\&. +.RE +.PP +\fIm\fR +.RS 4 +Add a user to a group\&. If the user or group do not exist yet, they will be implicitly created\&. +.sp +Added in version 215\&. +.RE +.PP +\fIr\fR +.RS 4 +Add a range of numeric UIDs/GIDs to the pool to allocate new UIDs and GIDs from\&. If no line of this type is specified, the range of UIDs/GIDs is set to some compiled\-in default\&. Note that both UIDs and GIDs are allocated from the same pool, in order to ensure that users and groups of the same name are likely to carry the same numeric UID and GID\&. +.sp +Added in version 216\&. +.RE +.SS "Name" +.PP +The name field specifies the user or group name\&. The specified name must consist only of the characters a\-z, A\-Z, 0\-9, +"_" +and +"\-", except for the first character which must be one of a\-z, A\-Z or +"_" +(i\&.e\&. numbers and +"\-" +are not permitted as first character)\&. The user/group name must have at least one character, and at most 31\&. +.PP +For further details about the syntax of user/group names, see +\m[blue]\fBUser/Group Name Syntax\fR\m[]\&\s-2\u[1]\d\s+2\&. +.PP +It is strongly recommended to pick user and group names that are unlikely to clash with normal users created by the administrator\&. A good scheme to guarantee this is by prefixing all system and group names with the underscore, and avoiding too generic names\&. +.PP +For +\fIm\fR +lines, this field should contain the user name to add to a group\&. +.PP +For lines of type +\fIr\fR, this field should be set to +"\-"\&. +.SS "ID" +.PP +For +\fIu\fR +and +\fIg\fR, the numeric 32\-bit UID or GID of the user/group\&. Do not use IDs 65535 or 4294967295, as they have special placeholder meanings\&. Specify +"\-" +for automatic UID/GID allocation for the user or group (this is strongly recommended unless it is strictly necessary to use a specific UID or GID)\&. Alternatively, specify an absolute path in the file system\&. In this case, the UID/GID is read from the path\*(Aqs owner/group\&. This is useful to create users whose UID/GID match the owners of pre\-existing files (such as SUID or SGID binaries)\&. The syntaxes +"\fIuid\fR:\fIgid\fR" +and +"\fIuid\fR:\fIgroupname\fR" +are supported to allow creating users with specific primary groups\&. The given group must be created explicitly, or it must already exist\&. Specifying +"\-" +for the UID in these syntaxes is also supported\&. +.PP +For +\fIm\fR +lines, this field should contain the group name to add to a user to\&. +.PP +For lines of type +\fIr\fR, this field should be set to a UID/GID range in the format +"FROM\-TO", where both values are formatted as decimal ASCII numbers\&. Alternatively, a single UID/GID may be specified formatted as decimal ASCII numbers\&. +.SS "GECOS" +.PP +A short, descriptive string for users to be created, enclosed in quotation marks\&. Note that this field may not contain colons\&. +.PP +Only applies to lines of type +\fIu\fR +and should otherwise be left unset (or +"\-")\&. +.SS "Home Directory" +.PP +The home directory for a new system user\&. If omitted, defaults to the root directory\&. +.PP +Only applies to lines of type +\fIu\fR +and should otherwise be left unset (or +"\-")\&. It is recommended to omit this, unless software strictly requires a home directory to be set\&. +.PP +\fBsystemd\-sysusers\fR +only sets the home directory record in the user database\&. To actually create the directory, consider adding a corresponding +\fBtmpfiles.d\fR(5) +fragment\&. +.SS "Shell" +.PP +The login shell of the user\&. If not specified, this will be set to +/usr/sbin/nologin, except if the UID of the user is 0, in which case +/bin/sh +will be used\&. +.PP +Only applies to lines of type +\fIu\fR +and should otherwise be left unset (or +"\-")\&. It is recommended to omit this, unless a shell different +/usr/sbin/nologin +must be used\&. +.SH "SPECIFIERS" +.PP +Specifiers can be used in the +"Name", +"ID", +"GECOS", +"Home directory", and +"Shell" +fields\&. An unknown or unresolvable specifier is treated as invalid configuration\&. The following expansions are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system\&. +T} +T{ +"%l" +T}:T{ +Short host name +T}:T{ +The hostname of the running system, truncated at the first dot to remove any domain component\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%T" +T}:T{ +Directory for temporary files +T}:T{ +This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%V" +T}:T{ +Directory for larger and persistent temporary files +T}:T{ +This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +.SH "IDEMPOTENCE" +.PP +Note that +\fBsystemd\-sysusers\fR +will do nothing if the specified users or groups already exist or the users are members of specified groups, so normally there is no reason to override +sysusers\&.d +vendor configuration, except to block certain users or groups from being created\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-sysusers\fR(8) +.SH "NOTES" +.IP " 1." 4 +User/Group Name Syntax +.RS 4 +\%https://systemd.io/USER_NAMES +.RE diff --git a/upstream/fedora-40/man5/term.5 b/upstream/fedora-40/man5/term.5 new file mode 100644 index 00000000..92ed3fe8 --- /dev/null +++ b/upstream/fedora-40/man5/term.5 @@ -0,0 +1,452 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: term.5,v 1.73 2024/01/13 22:05:39 tom Exp $ +.TH term 5 2024-01-13 "ncurses 6.4" "File formats" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.ds ^ \(ha +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ds ' ' +.ds ^ ^ +.\} +.ie n .ds CW R +.el \{ +.ie \n(.g .ds CW CR +.el .ds CW CW +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. +.ds d /usr/share/terminfo +.SH NAME +term \- +compiled \fIterminfo\fR terminal description +.SH SYNOPSIS +.B term +.SH DESCRIPTION +.SS "Storage Location" +Compiled terminfo descriptions are placed under the directory \fB\*d\fP. +Two configurations are supported +(when building the \fI\%ncurses\fP libraries): +.TP 5 +.B directory tree +A two-level scheme is used to avoid a linear search +of a huge Unix system directory: \fB\*d/c/name\fP where +.I name +is the name of the terminal, and +.I c +is the first character of +.IR name . +Thus, +.I act4 +can be found in the file \fB\*d/a/act4\fP. +Synonyms for the same terminal are implemented by multiple +links to the same compiled file. +.TP 5 +.B hashed database +Using Berkeley database, two types of records are stored: +the terminfo data in the same format as stored in a directory tree with +the terminfo's primary name as a key, +and records containing only aliases pointing to the primary name. +.IP +If built to write hashed databases, +\fI\%ncurses\fP can still read terminfo databases organized as a +directory tree, +but cannot write entries into the directory tree. +It can write (or rewrite) entries in the hashed database. +.IP +\fI\%ncurses\fP distinguishes the two cases in the \fI\%TERMINFO\fP and +\fI\%TERMINFO_DIRS\fP environment variable by assuming a directory tree +for entries that correspond to an existing directory, +and hashed database otherwise. +.SS "Legacy Storage Format" +The format has been chosen so that it will be the same on all hardware. +An 8 or more bit byte is assumed, but no assumptions about byte ordering +or sign extension are made. +.PP +The compiled file is created with the \fBtic\fP program, +and read by the routine \fBsetupterm\fP(3X). +The file is divided into six parts: +.RS 5 +.TP 3 +a) \fIheader\fP, +.TP 3 +b) \fIterminal names\fP, +.TP 3 +c) \fIBoolean flags\fP, +.TP 3 +d) \fInumbers\fP, +.TP 3 +e) \fIstrings\fP, and +.TP 3 +f) \fIstring table\fP. +.RE +.PP +The \fIheader\fP section begins the file. +This section contains six short integers in the format +described below. +These integers are +.RS 5 +.TP 5 +(1) the \fImagic number\fP (octal 0432); +.TP 5 +(2) the size, in bytes, of the \fIterminal names\fP section; +.TP 5 +(3) the number of bytes in the \fIBoolean flags\fP section; +.TP 5 +(4) the number of short integers in the \fInumbers\fP section; +.TP 5 +(5) the number of offsets (short integers) in the \fIstrings\fP section; +.TP 5 +(6) the size, in bytes, of the \fIstring table\fP. +.RE +.PP +The capabilities in the +\fIBoolean flags\fP, +\fInumbers\fP, and +\fIstrings\fP +sections are in the same order as the file . +.PP +Short integers are signed, in the range \-32768 to 32767. +They are stored as two 8-bit bytes. +The first byte contains the least significant 8 bits of the value, +and the second byte contains the most significant 8 bits. +(Thus, the value represented is 256*second+first.) +This format corresponds to the hardware of the \s-1VAX\s+1 +and \s-1PDP\s+1-11 (that is, little-endian machines). +Machines where this does not correspond to the hardware must read the +integers as two bytes and compute the little-endian value. +.PP +Numbers in a terminal description, +whether they are entries in the \fInumbers\fP or \fIstrings\fP table, +are positive integers. +Boolean flags are treated as positive one-byte integers. +In each case, those positive integers represent a terminal capability. +The terminal compiler tic uses negative integers to handle the cases where +a capability is not available: +.bP +If a capability is absent from this terminal, +tic stores a \-1 in the corresponding table. +.IP +The integer value \-1 is represented by two bytes 0377, 0377. +.br +Absent Boolean values are represented by the byte 0 (false). +.bP +If a capability has been canceled from this terminal, +tic stores a \-2 in the corresponding table. +.IP +The integer value \-2 is represented by two bytes 0377, 0376. +.br +The Boolean value \-2 is represented by the byte 0376. +.br +.bP +Other negative values are illegal. +.PP +The \fIterminal names\fP section comes after the \fIheader\fP. +It contains the first line of the terminfo description, +listing the various names for the terminal, +separated by the \*(``|\*('' character. +The \fIterminal names\fP section is terminated +with an \s-1ASCII NUL\s+1 character. +.PP +The \fIBoolean flags\fP section has one byte for each flag. +Boolean capabilities are either 1 or 0 (true or false) +according to whether the terminal supports the given capability or not. +.PP +Between the \fIBoolean flags\fP section and the \fInumber\fP section, +a null byte will be inserted, if necessary, +to ensure that the \fInumber\fP section begins on an even byte +This is a relic of the PDP\-11's word-addressed architecture, +originally designed to avoid traps induced +by addressing a word on an odd byte boundary. +All short integers are aligned on a short word boundary. +.PP +The \fInumbers\fP section is similar to the \fIBoolean flags\fP section. +Each capability takes up two bytes, +and is stored as a little-endian short integer. +.PP +The \fIstrings\fP section is also similar. +Each capability is stored as a short integer. +The capability value is an index into the \fIstring table\fP. +.PP +The \fIstring table\fP is the last section. +It contains all of the values of string capabilities referenced in +the \fIstrings\fP section. +Each string is null-terminated. +Special characters in \*^X or \ec notation are stored in their +interpreted form, not the printing representation. +Padding information $ and parameter information %x are +stored intact in uninterpreted form. +.SS "Extended Storage Format" +The previous section describes the conventional terminfo binary format. +With some minor variations of the offsets (see PORTABILITY), +the same binary format is used in all modern Unix systems. +Each system uses a predefined set of Boolean, number or string capabilities. +.PP +The \fI\%ncurses\fP libraries and applications support +extended terminfo binary format, +allowing users to define capabilities which are loaded at runtime. +This +extension is made possible by using the fact that the other implementations +stop reading the terminfo data when they have reached the end of the size given +in the header. +\fI\%ncurses\fP checks the size, +and if it exceeds that due to the predefined data, +continues to parse according to its own scheme. +.PP +First, it reads the extended header (5 short integers): +.RS 5 +.TP 5 +(1) +count of extended Boolean capabilities +.TP 5 +(2) +count of extended numeric capabilities +.TP 5 +(3) +count of extended string capabilities +.TP 5 +(4) +count of the items in extended string table +.TP 5 +(5) +size of the extended string table in bytes +.RE +.PP +The count- and size-values for the extended string table +include the extended capability \fInames\fP as well as +extended capability \fIvalues\fP. +.PP +Using the counts and sizes, +\fI\%ncurses\fP allocates arrays and reads data for the extended +capabilities in the same order as the header information. +.PP +The extended string table contains values for string capabilities. +After the end of these values, it contains the names for each of +the extended capabilities in order, e.g., Booleans, then numbers and +finally strings. +.PP +By storing terminal descriptions in this way, +\fI\%ncurses\fP is able to provide a database useful with legacy +applications, +as well as providing data for applications which need more than the +predefined capabilities. +See \fBuser_caps\fP(5) for an overview +of the way \fI\%ncurses\fP uses this extended information. +.PP +Applications which manipulate terminal data can use the definitions +described in \fBterm_variables\fP(3X) which associate the long capability +names with members of a \fBTERMTYPE\fP structure. +. +.SS "Extended Number Format" +On occasion, 16-bit signed integers are not large enough. +With \fI\%ncurses\fP 6.1, +a new format was introduced by making a few changes +to the legacy format: +.bP +a different magic number (octal 01036) +.bP +changing the type for the \fInumber\fP array from signed 16-bit integers +to signed 32-bit integers. +.PP +To maintain compatibility, the library presents the same data structures +to direct users of the \fBTERMTYPE\fP structure as in previous formats. +However, that cannot provide callers with the extended numbers. +The library uses a similar but hidden data structure \fBTERMTYPE2\fP +to provide data for the terminfo functions. +.SH FILES +.TP +.I \*d +compiled terminal description database +.SH PORTABILITY +.SS setupterm +Note that it is possible for +.B setupterm +to expect a different set of capabilities +than are actually present in the file. +Either the database may have been updated since +.B setupterm +was recompiled +(resulting in extra unrecognized entries in the file) +or the program may have been recompiled more recently +than the database was updated +(resulting in missing entries). +The routine +.B setupterm +must be prepared for both possibilities \- +this is why the numbers and sizes are included. +Also, new capabilities must always be added at the end of the lists +of Boolean, number, and string capabilities. +.SS "Binary Format" +X/Open Curses does not specify a format for the terminfo database. +System V curses used a directory-tree of binary files, +one per terminal description. +.PP +Despite the consistent use of little-endian for numbers and the otherwise +self-describing format, it is not wise to count on portability of binary +terminfo entries between commercial Unix versions. +The problem is that there +are at least three versions of terminfo (under HP\-UX, AIX, and OSF/1) which +diverged from System V terminfo after SVr1, and have added extension +capabilities to the string table that (in the binary format) collide with +System V and XSI Curses extensions. +See \fBterminfo\fP(5) for detailed +discussion of terminfo source compatibility issues. +.PP +This implementation is by default compatible with the binary +terminfo format used by Solaris curses, +except in a few less-used details +where it was found that the latter did not match X/Open Curses. +The format used by the other Unix versions +can be matched by building \fI\%ncurses\fP +with different configuration options. +.SS "Magic Codes" +The magic number in a binary terminfo file is the first 16-bits (two bytes). +Besides making it more reliable for the library to check that a file +is terminfo, +utilities such as \fBfile\fP(1) also use that to tell what the file-format is. +System V defined more than one magic number, +with 0433, 0435 as screen-dumps (see \fBscr_dump\fP(5)). +This implementation uses 01036 as a continuation of that sequence, +but with a different high-order byte to avoid confusion. +.SS "The \fITERMTYPE\fP Structure" +Direct access to the \fBTERMTYPE\fP structure is provided for legacy +applications. +Portable applications should use the \fBtigetflag\fP and related functions +described in \fBcurs_terminfo\fP(3X) for reading terminal capabilities. +.SS "Mixed-case Terminal Names" +A small number of terminal descriptions use uppercase characters in +their names. +If the underlying filesystem ignores the difference between +uppercase and lowercase, +\fI\%ncurses\fP represents the \*(``first character\*('' +of the terminal name used as +the intermediate level of a directory tree in (two-character) hexadecimal form. +.SS Limits +\fI\%ncurses\fP stores compiled terminal descriptions +in three related formats, +described in the sections +.bP +\fBLEGACY STORAGE FORMAT\fP, and +.bP +\fBEXTENDED STORAGE FORMAT\fP, and +.bP +\fBEXTENDED NUMBER FORMAT\fP. +.PP +The legacy storage format and the extended number format differ by +the types of numeric capability which they can store +(i.e., 16-bit versus 32-bit integers). +The extended storage format introduced by \fI\%ncurses\fP 5.0 adds data +to either of these formats. +.PP +Some limitations apply: +.bP +total compiled entries cannot exceed 4096 bytes in the legacy format. +.bP +total compiled entries cannot exceed 32768 bytes in the extended format. +.bP +the name field cannot exceed 128 bytes. +.PP +Compiled entries are limited to 32768 bytes because offsets into the +\fIstrings table\fP use two-byte integers. +The legacy format could have supported 32768-byte entries, +but was limited to a virtual memory page's 4096 bytes. +.SH EXAMPLES +As an example, here is a description for the Lear-Siegler +ADM\-3, a popular though rather stupid early terminal: +.PP +.EX +adm3a|lsi adm3a, + am, + cols#80, lines#24, + bel=\*^G, clear=\e032$<1>, cr=\*^M, cub1=\*^H, cud1=\*^J, + cuf1=\*^L, cup=\eE=%p1%{32}%+%c%p2%{32}%+%c, cuu1=\*^K, + home=\*^\*^, ind=\*^J, +.EE +.PP +and a hexadecimal dump of the compiled terminal description: +.PP +.if t .in +4n +.ft \*(CW +.TS +Lp-1. +0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3 +0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P. +0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........ +0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.\*'... +0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..\-..... +0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0080 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0090 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +00f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0100 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0110 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ +0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1 +0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c +0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c.... +0150 00 08 00 0c 00 0b 00 0a 00 ........ . +.TE +.ft +.in +.SH AUTHORS +Thomas E. Dickey +.br +extended terminfo format for \fI\%ncurses\fP 5.0 +.br +hashed database support for \fI\%ncurses\fP 5.6 +.br +extended number support for \fI\%ncurses\fP 6.1 +.sp +Eric S. Raymond +.br +documented legacy terminfo format, e.g., from \fIpcurses\fP. +.SH SEE ALSO +\fB\%curses\fP(3X), +\fB\%curs_terminfo\fP(3X), +\fB\%terminfo\fP(5), +\fB\%user_caps\fP(5) diff --git a/upstream/fedora-40/man5/termcap.5 b/upstream/fedora-40/man5/termcap.5 new file mode 100644 index 00000000..a2fc7839 --- /dev/null +++ b/upstream/fedora-40/man5/termcap.5 @@ -0,0 +1,466 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified formatting Sat Jul 24 17:13:38 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified (extensions and corrections) +.\" Sun May 1 14:21:25 MET DST 1994 Michael Haardt +.\" If mistakes in the capabilities are found, please send a bug report to: +.\" michael@moria.de +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH termcap 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +termcap \- terminal capability database +.SH DESCRIPTION +The termcap database is an obsolete facility for describing the +capabilities of character-cell terminals and printers. +It is retained only for compatibility with old programs; +new programs should use the +.BR terminfo (5) +database and associated libraries. +.P +.I /etc/termcap +is an ASCII file (the database master) that lists the capabilities of +many different types of terminals. +Programs can read termcap to find +the particular escape codes needed to control the visual attributes of +the terminal actually in use. +(Other aspects of the terminal are +handled by +.BR stty (1).) +The termcap database is indexed on the +.B TERM +environment variable. +.P +Termcap entries must be defined on a single logical line, with \[aq]\e\[aq] +used to suppress the newline. +Fields are separated by \[aq]:\[aq]. +The first field of each entry starts at the left-hand margin, +and contains a list of names for the terminal, separated by \[aq]|\[aq]. +.P +The first subfield may (in BSD termcap entries from 4.3BSD and +earlier) contain a short name consisting of two characters. +This short name may consist of capital or small letters. +In 4.4BSD, termcap entries this field is omitted. +.P +The second subfield (first, in the newer 4.4BSD format) contains the +name used by the environment variable +.BR TERM . +It should be spelled in lowercase letters. +Selectable hardware capabilities should be marked +by appending a hyphen and a suffix to this name. +See below for an example. +Usual suffixes are w (more than 80 characters wide), am +(automatic margins), nam (no automatic margins), and rv (reverse video +display). +The third subfield contains a long and descriptive name for +this termcap entry. +.P +Subsequent fields contain the terminal capabilities; any continued +capability lines must be indented one tab from the left margin. +.P +Although there is no defined order, it is suggested to write first +boolean, then numeric, and then string capabilities, each sorted +alphabetically without looking at lower or upper spelling. +Capabilities of similar functions can be written in one line. +.P +Example for: +.nf +.P +Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\e +Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\e +Boolean: :bs:\e +Numeric: :co#80:\e +String: :sr=\eE[H:\e +.fi +.SS Boolean capabilities +.nf +5i Printer will not echo on screen +am Automatic margins which means automatic line wrap +bs Control-H (8 dec.) performs a backspace +bw Backspace on left margin wraps to previous line and right margin +da Display retained above screen +db Display retained below screen +eo A space erases all characters at cursor position +es Escape sequences and special characters work in status line +gn Generic device +hc This is a hardcopy terminal +HC The cursor is hard to see when not on bottom line +hs Has a status line +hz Hazeltine bug, the terminal can not print tilde characters +in Terminal inserts null bytes, not spaces, to fill whitespace +km Terminal has a meta key +mi Cursor movement works in insert mode +ms Cursor movement works in standout/underline mode +NP No pad character +NR ti does not reverse te +nx No padding, must use XON/XOFF +os Terminal can overstrike +ul Terminal underlines although it can not overstrike +xb Beehive glitch, f1 sends ESCAPE, f2 sends \fB\[ha]C\fP +xn Newline/wraparound glitch +xo Terminal uses xon/xoff protocol +xs Text typed over standout text will be displayed in standout +xt Teleray glitch, destructive tabs and odd standout mode +.fi +.SS Numeric capabilities +.nf +co Number of columns +dB Delay in milliseconds for backspace on hardcopy terminals +dC Delay in milliseconds for carriage return on hardcopy terminals +dF Delay in milliseconds for form feed on hardcopy terminals +dN Delay in milliseconds for new line on hardcopy terminals +dT Delay in milliseconds for tabulator stop on hardcopy terminals +dV Delay in milliseconds for vertical tabulator stop on + hardcopy terminals +it Difference between tab positions +lh Height of soft labels +lm Lines of memory +lw Width of soft labels +li Number of lines +Nl Number of soft labels +pb Lowest baud rate which needs padding +sg Standout glitch +ug Underline glitch +vt virtual terminal number +ws Width of status line if different from screen width +.fi +.SS String capabilities +.nf +!1 shifted save key +!2 shifted suspend key +!3 shifted undo key +#1 shifted help key +#2 shifted home key +#3 shifted input key +#4 shifted cursor left key +%0 redo key +%1 help key +%2 mark key +%3 message key +%4 move key +%5 next-object key +%6 open key +%7 options key +%8 previous-object key +%9 print key +%a shifted message key +%b shifted move key +%c shifted next key +%d shifted options key +%e shifted previous key +%f shifted print key +%g shifted redo key +%h shifted replace key +%i shifted cursor right key +%j shifted resume key +&0 shifted cancel key +&1 reference key +&2 refresh key +&3 replace key +&4 restart key +&5 resume key +&6 save key +&7 suspend key +&8 undo key +&9 shifted begin key +*0 shifted find key +*1 shifted command key +*2 shifted copy key +*3 shifted create key +*4 shifted delete character +*5 shifted delete line +*6 select key +*7 shifted end key +*8 shifted clear line key +*9 shifted exit key +@0 find key +@1 begin key +@2 cancel key +@3 close key +@4 command key +@5 copy key +@6 create key +@7 end key +@8 enter/send key +@9 exit key +al Insert one line +AL Insert %1 lines +ac Pairs of block graphic characters to map alternate character set +ae End alternative character set +as Start alternative character set for block graphic characters +bc Backspace, if not \fB\[ha]H\fP +bl Audio bell +bt Move to previous tab stop +cb Clear from beginning of line to cursor +cc Dummy command character +cd Clear to end of screen +ce Clear to end of line +ch Move cursor horizontally only to column %1 +cl Clear screen and cursor home +cm Cursor move to row %1 and column %2 (on screen) +CM Move cursor to row %1 and column %2 (in memory) +cr Carriage return +cs Scroll region from line %1 to %2 +ct Clear tabs +cv Move cursor vertically only to line %1 +dc Delete one character +DC Delete %1 characters +dl Delete one line +DL Delete %1 lines +dm Begin delete mode +do Cursor down one line +DO Cursor down #1 lines +ds Disable status line +eA Enable alternate character set +ec Erase %1 characters starting at cursor +ed End delete mode +ei End insert mode +ff Formfeed character on hardcopy terminals +fs Return character to its position before going to status line +F1 The string sent by function key f11 +F2 The string sent by function key f12 +F3 The string sent by function key f13 +\&... \&... +F9 The string sent by function key f19 +FA The string sent by function key f20 +FB The string sent by function key f21 +\&... \&... +FZ The string sent by function key f45 +Fa The string sent by function key f46 +Fb The string sent by function key f47 +\&... \&... +Fr The string sent by function key f63 +hd Move cursor a half line down +ho Cursor home +hu Move cursor a half line up +i1 Initialization string 1 at login +i3 Initialization string 3 at login +is Initialization string 2 at login +ic Insert one character +IC Insert %1 characters +if Initialization file +im Begin insert mode +ip Insert pad time and needed special characters after insert +iP Initialization program +K1 upper left key on keypad +K2 center key on keypad +K3 upper right key on keypad +K4 bottom left key on keypad +K5 bottom right key on keypad +k0 Function key 0 +k1 Function key 1 +k2 Function key 2 +k3 Function key 3 +k4 Function key 4 +k5 Function key 5 +k6 Function key 6 +k7 Function key 7 +k8 Function key 8 +k9 Function key 9 +k; Function key 10 +ka Clear all tabs key +kA Insert line key +kb Backspace key +kB Back tab stop +kC Clear screen key +kd Cursor down key +kD Key for delete character under cursor +ke turn keypad off +kE Key for clear to end of line +kF Key for scrolling forward/down +kh Cursor home key +kH Cursor hown down key +kI Insert character/Insert mode key +kl Cursor left key +kL Key for delete line +kM Key for exit insert mode +kN Key for next page +kP Key for previous page +kr Cursor right key +kR Key for scrolling backward/up +ks Turn keypad on +kS Clear to end of screen key +kt Clear this tab key +kT Set tab here key +ku Cursor up key +l0 Label of zeroth function key, if not f0 +l1 Label of first function key, if not f1 +l2 Label of first function key, if not f2 +\&... \&... +la Label of tenth function key, if not f10 +le Cursor left one character +ll Move cursor to lower left corner +LE Cursor left %1 characters +LF Turn soft labels off +LO Turn soft labels on +mb Start blinking +MC Clear soft margins +md Start bold mode +me End all mode like so, us, mb, md, and mr +mh Start half bright mode +mk Dark mode (Characters invisible) +ML Set left soft margin +mm Put terminal in meta mode +mo Put terminal out of meta mode +mp Turn on protected attribute +mr Start reverse mode +MR Set right soft margin +nd Cursor right one character +nw Carriage return command +pc Padding character +pf Turn printer off +pk Program key %1 to send string %2 as if typed by user +pl Program key %1 to execute string %2 in local mode +pn Program soft label %1 to show string %2 +po Turn the printer on +pO Turn the printer on for %1 (<256) bytes +ps Print screen contents on printer +px Program key %1 to send string %2 to computer +r1 Reset string 1 to set terminal to sane modes +r2 Reset string 2 to set terminal to sane modes +r3 Reset string 3 to set terminal to sane modes +RA disable automatic margins +rc Restore saved cursor position +rf Reset string filename +RF Request for input from terminal +RI Cursor right %1 characters +rp Repeat character %1 for %2 times +rP Padding after character sent in replace mode +rs Reset string +RX Turn off XON/XOFF flow control +sa Set %1 %2 %3 %4 %5 %6 %7 %8 %9 attributes +SA enable automatic margins +sc Save cursor position +se End standout mode +sf Normal scroll one line +SF Normal scroll %1 lines +so Start standout mode +sr Reverse scroll +SR scroll back %1 lines +st Set tabulator stop in all rows at current column +SX Turn on XON/XOFF flow control +ta move to next hardware tab +tc Read in terminal description from another entry +te End program that uses cursor motion +ti Begin program that uses cursor motion +ts Move cursor to column %1 of status line +uc Underline character under cursor and move cursor right +ue End underlining +up Cursor up one line +UP Cursor up %1 lines +us Start underlining +vb Visible bell +ve Normal cursor visible +vi Cursor invisible +vs Standout cursor +wi Set window from line %1 to %2 and column %3 to %4 +XF XOFF character if not \fB\[ha]S\fP +.fi +.P +There are several ways of defining the control codes for string capabilities: +.P +Every normal character represents itself, +except \[aq]\[ha]\[aq], \[aq]\e\[aq], and \[aq]%\[aq]. +.P +A \fB\[ha]x\fP means Control-x. +Control-A equals 1 decimal. +.P +\ex means a special code. +x can be one of the following characters: +.RS +E Escape (27) +.br +n Linefeed (10) +.br +r Carriage return (13) +.br +t Tabulation (9) +.br +b Backspace (8) +.br +f Form feed (12) +.br +0 Null character. +A \exxx specifies the octal character xxx. +.RE +.TP +i +Increments parameters by one. +.TP +r +Single parameter capability +.TP ++ +Add value of next character to this parameter and do binary output +.TP +2 +Do ASCII output of this parameter with a field with of 2 +.TP +d +Do ASCII output of this parameter with a field with of 3 +.TP +% +Print a \[aq]%\[aq] +.P +If you use binary output, +then you should avoid the null character (\[aq]\e0\[aq]) +because it terminates the string. +You should reset tabulator expansion +if a tabulator can be the binary output of a parameter. +.TP +Warning: +The above metacharacters for parameters may be wrong: they document Minix +termcap which may not be compatible with Linux termcap. +.P +The block graphic characters can be specified by three string capabilities: +.TP +as +start the alternative charset +.TP +ae +end the alternative charset +.TP +ac +pairs of characters. +The first character is the name of the block graphic +symbol and the second characters is its definition. +.P +The following names are available: +.P +.nf ++ right arrow (>) +, left arrow (<) +\&. down arrow (v) +0 full square (#) +I lantern (#) +- upper arrow (\[ha]) +\&' rhombus (+) +a chess board (:) +f degree (') +g plus-minus (#) +h square (#) +j right bottom corner (+) +k right upper corner (+) +l left upper corner (+) +m left bottom corner (+) +n cross (+) +o upper horizontal line (-) +q middle horizontal line (-) +s bottom horizontal line (_) +t left tee (+) +u right tee (+) +v bottom tee (+) +w normal tee (+) +x vertical line (|) +\[ti] paragraph (???) +.fi +.P +The values in parentheses are suggested defaults which are used by the +.I curses +library, if the capabilities are missing. +.SH SEE ALSO +.BR ncurses (3), +.BR termcap (3), +.BR terminfo (5) diff --git a/upstream/fedora-40/man5/terminfo.5 b/upstream/fedora-40/man5/terminfo.5 new file mode 100644 index 00000000..e2b051b9 --- /dev/null +++ b/upstream/fedora-40/man5/terminfo.5 @@ -0,0 +1,4345 @@ +'\" t +.\" DO NOT EDIT THIS FILE BY HAND! +.\" It is generated from terminfo.head, ../../man/../include/Caps ../../man/../include/Caps-ncurses, and terminfo.tail. +.\" +.\" Note: this must be run through tbl before nroff. +.\" The magic cookie on the first line triggers this under some man programs. +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: terminfo.head,v 1.63 2024/01/13 23:07:27 tom Exp $ +.TH terminfo 5 2024-01-13 "ncurses 6.4" "File formats" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.ds ^ \(ha +.ds ~ \(ti +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ds ' ' +.ds ^ ^ +.ds ~ ~ +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. +.ds d /usr/share/terminfo +.SH NAME +\fB\%terminfo\fP \- +terminal capability database +.SH SYNOPSIS +\*d/*/* +.SH DESCRIPTION +.I Terminfo +is a database describing terminals, +used by screen-oriented programs such as +\fBnvi\fP(1), +\fBlynx\fP(1), +\fBmutt\fP(1), +and other curses applications, +using high-level calls to libraries such as \fBcurses\fP(3X). +It is also used via low-level calls by non-curses applications +which may be screen-oriented (such as \fBclear\fP(1)) +or non-screen (such as \fBtabs\fP(1)). +.PP +.I Terminfo +describes terminals by giving a set of capabilities which they +have, by specifying how to perform screen operations, and by +specifying padding requirements and initialization sequences. +.PP +This manual describes \fI\%ncurses\fP +version 6.4 (patch 20240127). +.SS "\fIterminfo\fP Entry Syntax" +Entries in +.I terminfo +consist of a sequence of fields: +.bP +Each field ends with a comma \*(``,\*('' +(embedded commas may be +escaped with a backslash or written as \*(``\e054\*(''). +.bP +White space between fields is ignored. +.bP +The first field in a \fIterminfo\fP entry begins in the first column. +.bP +Newlines and leading whitespace (spaces or tabs) +may be used for formatting entries for readability. +These are removed from parsed entries. +.IP +The \fBinfocmp\fP \fB\-f\fP and \fB\-W\fP options rely on this to +format if-then-else expressions, +or to enforce maximum line-width. +The resulting formatted terminal description can be read by \fBtic\fP. +.bP +The first field for each terminal gives the names which are known for the +terminal, separated by \*(``|\*('' characters. +.IP +The first name given is the most common abbreviation for the terminal +(its primary name), +the last name given should be a long name fully identifying the terminal +(see \fBlongname\fP(3X)), +and all others are treated as synonyms (aliases) for the primary terminal name. +.IP +X/Open Curses advises that all names but the last should be in lower case +and contain no blanks; +the last name may well contain upper case and blanks for readability. +.IP +This implementation is not so strict; +it allows mixed case in the primary name and aliases. +If the last name has no embedded blanks, +it allows that to be both an alias and a verbose name +(but will warn about this ambiguity). +.bP +Lines beginning with a \*(``#\*('' in the first column are treated as comments. +.IP +While comment lines are valid at any point, the output of \fBcaptoinfo\fP +and \fBinfotocap\fP (aliases for \fBtic\fP) +will move comments so they occur only between entries. +.PP +Terminal names (except for the last, verbose entry) should +be chosen using the following conventions. +The particular piece of hardware making up the terminal should +have a root name, thus \*(``hp2621\*(''. +This name should not contain hyphens. +Modes that the hardware can be in, or user preferences, should +be indicated by appending a hyphen and a mode suffix. +Thus, a vt100 in 132-column mode would be vt100\-w. +The following suffixes should be used where possible: +.PP +.TS +center; +Lb Lb Lb +L L Lx. +Suffix Example Meaning +_ +\-\fInn\fP aaa\-60 Number of lines on the screen +\-\fIn\fPp c100\-4p Number of pages of memory +\-am vt100\-am With automargins (usually the default) +\-m ansi\-m Mono mode; suppress color +\-mc wy30\-mc Magic cookie; spaces when highlighting +\-na c100\-na No arrow keys (leave them in local) +\-nam vt100\-nam Without automatic margins +\-nl hp2621\-nl No status line +\-ns hp2626\-ns No status line +\-rv c100\-rv Reverse video +\-s vt100\-s Enable status line +\-vb wy370\-vb Use visible bell instead of beep +\-w vt100\-w Wide mode (> 80 columns, usually 132) +.TE +.PP +For more on terminal naming conventions, see the \fBterm\fP(7) manual page. +.SS "\fIterminfo\fP Capabilities Syntax" +The terminfo entry consists of several \fIcapabilities\fP, +i.e., features that the terminal has, +or methods for exercising the terminal's features. +.PP +After the first field (giving the name(s) of the terminal entry), +there should be one or more \fIcapability\fP fields. +These are Boolean, numeric or string names with corresponding values: +.bP +Boolean capabilities are true when present, false when absent. +There is no explicit value for Boolean capabilities. +.bP +Numeric capabilities have a \*(``#\*('' following the name, +then an unsigned decimal integer value. +.bP +String capabilities have a \*(``=\*('' following the name, +then an string of characters making up the capability value. +.IP +String capabilities can be split into multiple lines, +just as the fields comprising a terminal entry can be +split into multiple lines. +While blanks between fields are ignored, +blanks embedded within a string value are retained, +except for leading blanks on a line. +.PP +Any capability can be \fIcanceled\fP, +i.e., suppressed from the terminal entry, +by following its name with \*(``@\*('' +rather than a capability value. +.SS "Similar Terminals" +If there are two very similar terminals, one (the variant) can be defined as +being just like the other (the base) with certain exceptions. +In the +definition of the variant, the string capability \fBuse\fP can be given with +the name of the base terminal: +.bP +The capabilities given before +.B use +override those in the base type named by +.BR use . +.bP +If there are multiple \fBuse\fP capabilities, they are merged in reverse order. +That is, the rightmost \fBuse\fP reference is processed first, then the one to +its left, and so forth. +.bP +Capabilities given explicitly in the entry override +those brought in by \fBuse\fP references. +.PP +A capability can be canceled by placing \fBxx@\fP to the left of the +use reference that imports it, where \fIxx\fP is the capability. +For example, the entry +.RS +.PP +2621\-nl, smkx@, rmkx@, use=2621, +.RE +.PP +defines a 2621\-nl that does not have the \fBsmkx\fP or \fBrmkx\fP capabilities, +and hence does not turn on the function key labels when in visual mode. +This is useful for different modes for a terminal, or for different +user preferences. +.PP +An entry included via \fBuse\fP can contain canceled capabilities, +which have the same effect as if those cancels were inline in the +using terminal entry. +.SS "Predefined Capabilities" +.\" Head of terminfo man page ends here +.ps -1 +The following is a complete table of the capabilities included in a +terminfo description block and available to terminfo-using code. +In each line of the table, +.bP +The \fBvariable\fR is the name by which the programmer (at the terminfo level) +accesses the capability. +.bP +The \fBcapname\fR (\fICap-name\fP) +is the short name used in the text of the database, +and is used by a person updating the database. +.IP +Whenever possible, capnames are chosen to be the same as or similar to +the ANSI X3.64-1979 standard (now superseded by ECMA-48, which uses +identical or very similar names). +Semantics are also intended to match those of the specification. +.IP +Capability names have no hard length limit, but an informal limit of 5 +characters has been adopted to keep them short and to allow the tabs in +the source file +.B Caps +to line up nicely. +.bP +The \fBtermcap\fP (\fITcap\fP) code is the old capability name +(some capabilities are new, and have names which termcap did not originate). +.bP +Finally, the \fBdescription\fP field attempts to convey the semantics of the +capability. +.PP +You may find some codes in the description field: +.TP +(P) +indicates that padding may be specified +.TP +#[1-9] +in the description field indicates that the string is passed +through \fBtparm\fP(3X) with parameters as given (#\fIi\fP). +.IP +If no parameters are listed in the description, +passing the string through \fBtparm\fP(3X) may give unexpected results, +e.g., if it contains percent (%%) signs. +.TP +(P*) +indicates that padding may vary in proportion to the number of +lines affected +.TP +(#\d\fIi\fP\u) +indicates the \fIi\fP\uth\d parameter. +. +.PP +.TS +center; +Lb Cb S Lb +Lb Lb Lb Lb +Lbw(25n)2 Lbw(8n)2 Lb2 Lx. +\& Code \& +Boolean Capability Name TI TC Description +_ +auto_left_margin bw bw T{ +.ad l +cub1 wraps from column 0 to last column +T} +auto_right_margin am am T{ +.ad l +terminal has automatic margins +T} +no_esc_ctlc xsb xb T{ +.ad l +beehive (f1=escape, f2=ctrl C) +T} +ceol_standout_glitch xhp xs T{ +.ad l +standout not erased by overwriting (hp) +T} +eat_newline_glitch xenl xn T{ +.ad l +newline ignored after 80 cols (concept) +T} +erase_overstrike eo eo T{ +.ad l +can erase overstrikes with a blank +T} +generic_type gn gn T{ +.ad l +generic line type +T} +hard_copy hc hc T{ +.ad l +hardcopy terminal +T} +has_meta_key km km T{ +.ad l +Has a meta key (i.e., sets 8th-bit) +T} +has_status_line hs hs T{ +.ad l +has extra status line +T} +insert_null_glitch in in T{ +.ad l +insert mode distinguishes nulls +T} +memory_above da da T{ +.ad l +display may be retained above the screen +T} +memory_below db db T{ +.ad l +display may be retained below the screen +T} +move_insert_mode mir mi T{ +.ad l +safe to move while in insert mode +T} +move_standout_mode msgr ms T{ +.ad l +safe to move while in standout mode +T} +over_strike os os T{ +.ad l +terminal can overstrike +T} +status_line_esc_ok eslok es T{ +.ad l +escape can be used on the status line +T} +dest_tabs_magic_smso xt xt T{ +.ad l +tabs destructive, magic so char (t1061) +T} +tilde_glitch hz hz T{ +.ad l +cannot print ~'s (Hazeltine) +T} +transparent_underline ul ul T{ +.ad l +underline character overstrikes +T} +xon_xoff xon xo T{ +.ad l +terminal uses xon/xoff handshaking +T} +needs_xon_xoff nxon nx T{ +.ad l +padding will not work, xon/xoff required +T} +prtr_silent mc5i 5i T{ +.ad l +printer will not echo on screen +T} +hard_cursor chts HC T{ +.ad l +cursor is hard to see +T} +non_rev_rmcup nrrmc NR T{ +.ad l +smcup does not reverse rmcup +T} +no_pad_char npc NP T{ +.ad l +pad character does not exist +T} +non_dest_scroll_region ndscr ND T{ +.ad l +scrolling region is non-destructive +T} +can_change ccc cc T{ +.ad l +terminal can re-define existing colors +T} +back_color_erase bce ut T{ +.ad l +screen erased with background color +T} +hue_lightness_saturation hls hl T{ +.ad l +terminal uses only HLS color notation (Tektronix) +T} +col_addr_glitch xhpa YA T{ +.ad l +only positive motion for hpa/mhpa caps +T} +cr_cancels_micro_mode crxm YB T{ +.ad l +using cr turns off micro mode +T} +has_print_wheel daisy YC T{ +.ad l +printer needs operator to change character set +T} +row_addr_glitch xvpa YD T{ +.ad l +only positive motion for vpa/mvpa caps +T} +semi_auto_right_margin sam YE T{ +.ad l +printing in last column causes cr +T} +cpi_changes_res cpix YF T{ +.ad l +changing character pitch changes resolution +T} +lpi_changes_res lpix YG T{ +.ad l +changing line pitch changes resolution +T} +.TE +.PP +. +.TS +center; +Lb Cb S Lb +Lb Lb Lb Lb +Lbw(25n)2 Lbw(8n)2 Lb2 Lx. +\& Code \& +Numeric Capability Name TI TC Description +_ +columns cols co T{ +.ad l +number of columns in a line +T} +init_tabs it it T{ +.ad l +tabs initially every # spaces +T} +lines lines li T{ +.ad l +number of lines on screen or page +T} +lines_of_memory lm lm T{ +.ad l +lines of memory if > line. 0 means varies +T} +magic_cookie_glitch xmc sg T{ +.ad l +number of blank characters left by smso or rmso +T} +padding_baud_rate pb pb T{ +.ad l +lowest baud rate where padding needed +T} +virtual_terminal vt vt T{ +.ad l +virtual terminal number (CB/unix) +T} +width_status_line wsl ws T{ +.ad l +number of columns in status line +T} +num_labels nlab Nl T{ +.ad l +number of labels on screen +T} +label_height lh lh T{ +.ad l +rows in each label +T} +label_width lw lw T{ +.ad l +columns in each label +T} +max_attributes ma ma T{ +.ad l +maximum combined attributes terminal can handle +T} +maximum_windows wnum MW T{ +.ad l +maximum number of definable windows +T} +max_colors colors Co T{ +.ad l +maximum number of colors on screen +T} +max_pairs pairs pa T{ +.ad l +maximum number of color-pairs on the screen +T} +no_color_video ncv NC T{ +.ad l +video attributes that cannot be used with colors +T} +.TE +.PP +. +The following numeric capabilities are present in the SVr4.0 term structure, +but are not yet documented in the man page. +They came in with SVr4's printer support. +. +.PP +.TS +center; +Lb Cb S Lb +Lb Lb Lb Lb +Lbw(25n)2 Lbw(8n)2 Lb2 Lx. +\& Code \& +Numeric Capability Name TI TC Description +_ +buffer_capacity bufsz Ya T{ +.ad l +numbers of bytes buffered before printing +T} +dot_vert_spacing spinv Yb T{ +.ad l +spacing of pins vertically in pins per inch +T} +dot_horz_spacing spinh Yc T{ +.ad l +spacing of dots horizontally in dots per inch +T} +max_micro_address maddr Yd T{ +.ad l +maximum value in micro_..._address +T} +max_micro_jump mjump Ye T{ +.ad l +maximum value in parm_..._micro +T} +micro_col_size mcs Yf T{ +.ad l +character step size when in micro mode +T} +micro_line_size mls Yg T{ +.ad l +line step size when in micro mode +T} +number_of_pins npins Yh T{ +.ad l +numbers of pins in print-head +T} +output_res_char orc Yi T{ +.ad l +horizontal resolution in units per line +T} +output_res_line orl Yj T{ +.ad l +vertical resolution in units per line +T} +output_res_horz_inch orhi Yk T{ +.ad l +horizontal resolution in units per inch +T} +output_res_vert_inch orvi Yl T{ +.ad l +vertical resolution in units per inch +T} +print_rate cps Ym T{ +.ad l +print rate in characters per second +T} +wide_char_size widcs Yn T{ +.ad l +character step size when in double wide mode +T} +buttons btns BT T{ +.ad l +number of buttons on mouse +T} +bit_image_entwining bitwin Yo T{ +.ad l +number of passes for each bit-image row +T} +bit_image_type bitype Yp T{ +.ad l +type of bit-image device +T} +.TE +.PP +. +.TS +center; +Lb Cb S Lb +Lb Lb Lb Lb +Lbw(25n)2 Lbw(8n)2 Lb2 Lx. +\& Code \& +String Capability Name TI TC Description +_ +back_tab cbt bt T{ +.ad l +back tab (P) +T} +bell bel bl T{ +.ad l +audible signal (bell) (P) +T} +carriage_return cr cr T{ +.ad l +carriage return (P*) (P*) +T} +change_scroll_region csr cs T{ +.ad l +change region to line #1 to line #2 (P) +T} +clear_all_tabs tbc ct T{ +.ad l +clear all tab stops (P) +T} +clear_screen clear cl T{ +.ad l +clear screen and home cursor (P*) +T} +clr_eol el ce T{ +.ad l +clear to end of line (P) +T} +clr_eos ed cd T{ +.ad l +clear to end of screen (P*) +T} +column_address hpa ch T{ +.ad l +horizontal position #1, absolute (P) +T} +command_character cmdch CC T{ +.ad l +terminal settable cmd character in prototype !? +T} +cursor_address cup cm T{ +.ad l +move to row #1 columns #2 +T} +cursor_down cud1 do T{ +.ad l +down one line +T} +cursor_home home ho T{ +.ad l +home cursor (if no cup) +T} +cursor_invisible civis vi T{ +.ad l +make cursor invisible +T} +cursor_left cub1 le T{ +.ad l +move left one space +T} +cursor_mem_address mrcup CM T{ +.ad l +memory relative cursor addressing, move to row #1 columns #2 +T} +cursor_normal cnorm ve T{ +.ad l +make cursor appear normal (undo civis/cvvis) +T} +cursor_right cuf1 nd T{ +.ad l +non-destructive space (move right one space) +T} +cursor_to_ll ll ll T{ +.ad l +last line, first column (if no cup) +T} +cursor_up cuu1 up T{ +.ad l +up one line +T} +cursor_visible cvvis vs T{ +.ad l +make cursor very visible +T} +delete_character dch1 dc T{ +.ad l +delete character (P*) +T} +delete_line dl1 dl T{ +.ad l +delete line (P*) +T} +dis_status_line dsl ds T{ +.ad l +disable status line +T} +down_half_line hd hd T{ +.ad l +half a line down +T} +enter_alt_charset_mode smacs as T{ +.ad l +start alternate character set (P) +T} +enter_blink_mode blink mb T{ +.ad l +turn on blinking +T} +enter_bold_mode bold md T{ +.ad l +turn on bold (extra bright) mode +T} +enter_ca_mode smcup ti T{ +.ad l +string to start programs using cup +T} +enter_delete_mode smdc dm T{ +.ad l +enter delete mode +T} +enter_dim_mode dim mh T{ +.ad l +turn on half-bright mode +T} +enter_insert_mode smir im T{ +.ad l +enter insert mode +T} +enter_secure_mode invis mk T{ +.ad l +turn on blank mode (characters invisible) +T} +enter_protected_mode prot mp T{ +.ad l +turn on protected mode +T} +enter_reverse_mode rev mr T{ +.ad l +turn on reverse video mode +T} +enter_standout_mode smso so T{ +.ad l +begin standout mode +T} +enter_underline_mode smul us T{ +.ad l +begin underline mode +T} +erase_chars ech ec T{ +.ad l +erase #1 characters (P) +T} +exit_alt_charset_mode rmacs ae T{ +.ad l +end alternate character set (P) +T} +exit_attribute_mode sgr0 me T{ +.ad l +turn off all attributes +T} +exit_ca_mode rmcup te T{ +.ad l +strings to end programs using cup +T} +exit_delete_mode rmdc ed T{ +.ad l +end delete mode +T} +exit_insert_mode rmir ei T{ +.ad l +exit insert mode +T} +exit_standout_mode rmso se T{ +.ad l +exit standout mode +T} +exit_underline_mode rmul ue T{ +.ad l +exit underline mode +T} +flash_screen flash vb T{ +.ad l +visible bell (may not move cursor) +T} +form_feed ff ff T{ +.ad l +hardcopy terminal page eject (P*) +T} +from_status_line fsl fs T{ +.ad l +return from status line +T} +init_1string is1 i1 T{ +.ad l +initialization string +T} +init_2string is2 is T{ +.ad l +initialization string +T} +init_3string is3 i3 T{ +.ad l +initialization string +T} +init_file if if T{ +.ad l +name of initialization file +T} +insert_character ich1 ic T{ +.ad l +insert character (P) +T} +insert_line il1 al T{ +.ad l +insert line (P*) +T} +insert_padding ip ip T{ +.ad l +insert padding after inserted character +T} +key_backspace kbs kb T{ +.ad l +backspace key +T} +key_catab ktbc ka T{ +.ad l +clear-all-tabs key +T} +key_clear kclr kC T{ +.ad l +clear-screen or erase key +T} +key_ctab kctab kt T{ +.ad l +clear-tab key +T} +key_dc kdch1 kD T{ +.ad l +delete-character key +T} +key_dl kdl1 kL T{ +.ad l +delete-line key +T} +key_down kcud1 kd T{ +.ad l +down-arrow key +T} +key_eic krmir kM T{ +.ad l +sent by rmir or smir in insert mode +T} +key_eol kel kE T{ +.ad l +clear-to-end-of-line key +T} +key_eos ked kS T{ +.ad l +clear-to-end-of-screen key +T} +key_f0 kf0 k0 T{ +.ad l +F0 function key +T} +key_f1 kf1 k1 T{ +.ad l +F1 function key +T} +key_f10 kf10 k; T{ +.ad l +F10 function key +T} +key_f2 kf2 k2 T{ +.ad l +F2 function key +T} +key_f3 kf3 k3 T{ +.ad l +F3 function key +T} +key_f4 kf4 k4 T{ +.ad l +F4 function key +T} +key_f5 kf5 k5 T{ +.ad l +F5 function key +T} +key_f6 kf6 k6 T{ +.ad l +F6 function key +T} +key_f7 kf7 k7 T{ +.ad l +F7 function key +T} +key_f8 kf8 k8 T{ +.ad l +F8 function key +T} +key_f9 kf9 k9 T{ +.ad l +F9 function key +T} +key_home khome kh T{ +.ad l +home key +T} +key_ic kich1 kI T{ +.ad l +insert-character key +T} +key_il kil1 kA T{ +.ad l +insert-line key +T} +key_left kcub1 kl T{ +.ad l +left-arrow key +T} +key_ll kll kH T{ +.ad l +lower-left key (home down) +T} +key_npage knp kN T{ +.ad l +next-page key +T} +key_ppage kpp kP T{ +.ad l +previous-page key +T} +key_right kcuf1 kr T{ +.ad l +right-arrow key +T} +key_sf kind kF T{ +.ad l +scroll-forward key +T} +key_sr kri kR T{ +.ad l +scroll-backward key +T} +key_stab khts kT T{ +.ad l +set-tab key +T} +key_up kcuu1 ku T{ +.ad l +up-arrow key +T} +keypad_local rmkx ke T{ +.ad l +leave keyboard transmit mode +T} +keypad_xmit smkx ks T{ +.ad l +enter keyboard transmit mode +T} +lab_f0 lf0 l0 T{ +.ad l +label on function key f0 if not f0 +T} +lab_f1 lf1 l1 T{ +.ad l +label on function key f1 if not f1 +T} +lab_f10 lf10 la T{ +.ad l +label on function key f10 if not f10 +T} +lab_f2 lf2 l2 T{ +.ad l +label on function key f2 if not f2 +T} +lab_f3 lf3 l3 T{ +.ad l +label on function key f3 if not f3 +T} +lab_f4 lf4 l4 T{ +.ad l +label on function key f4 if not f4 +T} +lab_f5 lf5 l5 T{ +.ad l +label on function key f5 if not f5 +T} +lab_f6 lf6 l6 T{ +.ad l +label on function key f6 if not f6 +T} +lab_f7 lf7 l7 T{ +.ad l +label on function key f7 if not f7 +T} +lab_f8 lf8 l8 T{ +.ad l +label on function key f8 if not f8 +T} +lab_f9 lf9 l9 T{ +.ad l +label on function key f9 if not f9 +T} +meta_off rmm mo T{ +.ad l +turn off meta mode +T} +meta_on smm mm T{ +.ad l +turn on meta mode (8th-bit on) +T} +newline nel nw T{ +.ad l +newline (behave like cr followed by lf) +T} +pad_char pad pc T{ +.ad l +padding char (instead of null) +T} +parm_dch dch DC T{ +.ad l +delete #1 characters (P*) +T} +parm_delete_line dl DL T{ +.ad l +delete #1 lines (P*) +T} +parm_down_cursor cud DO T{ +.ad l +down #1 lines (P*) +T} +parm_ich ich IC T{ +.ad l +insert #1 characters (P*) +T} +parm_index indn SF T{ +.ad l +scroll forward #1 lines (P) +T} +parm_insert_line il AL T{ +.ad l +insert #1 lines (P*) +T} +parm_left_cursor cub LE T{ +.ad l +move #1 characters to the left (P) +T} +parm_right_cursor cuf RI T{ +.ad l +move #1 characters to the right (P*) +T} +parm_rindex rin SR T{ +.ad l +scroll back #1 lines (P) +T} +parm_up_cursor cuu UP T{ +.ad l +up #1 lines (P*) +T} +pkey_key pfkey pk T{ +.ad l +program function key #1 to type string #2 +T} +pkey_local pfloc pl T{ +.ad l +program function key #1 to execute string #2 +T} +pkey_xmit pfx px T{ +.ad l +program function key #1 to transmit string #2 +T} +print_screen mc0 ps T{ +.ad l +print contents of screen +T} +prtr_off mc4 pf T{ +.ad l +turn off printer +T} +prtr_on mc5 po T{ +.ad l +turn on printer +T} +repeat_char rep rp T{ +.ad l +repeat char #1 #2 times (P*) +T} +reset_1string rs1 r1 T{ +.ad l +reset string +T} +reset_2string rs2 r2 T{ +.ad l +reset string +T} +reset_3string rs3 r3 T{ +.ad l +reset string +T} +reset_file rf rf T{ +.ad l +name of reset file +T} +restore_cursor rc rc T{ +.ad l +restore cursor to position of last save_cursor +T} +row_address vpa cv T{ +.ad l +vertical position #1 absolute (P) +T} +save_cursor sc sc T{ +.ad l +save current cursor position (P) +T} +scroll_forward ind sf T{ +.ad l +scroll text up (P) +T} +scroll_reverse ri sr T{ +.ad l +scroll text down (P) +T} +set_attributes sgr sa T{ +.ad l +define video attributes #1-#9 (PG9) +T} +set_tab hts st T{ +.ad l +set a tab in every row, current columns +T} +set_window wind wi T{ +.ad l +current window is lines #1-#2 cols #3-#4 +T} +tab ht ta T{ +.ad l +tab to next 8-space hardware tab stop +T} +to_status_line tsl ts T{ +.ad l +move to status line, column #1 +T} +underline_char uc uc T{ +.ad l +underline char and move past it +T} +up_half_line hu hu T{ +.ad l +half a line up +T} +init_prog iprog iP T{ +.ad l +path name of program for initialization +T} +key_a1 ka1 K1 T{ +.ad l +upper left of keypad +T} +key_a3 ka3 K3 T{ +.ad l +upper right of keypad +T} +key_b2 kb2 K2 T{ +.ad l +center of keypad +T} +key_c1 kc1 K4 T{ +.ad l +lower left of keypad +T} +key_c3 kc3 K5 T{ +.ad l +lower right of keypad +T} +prtr_non mc5p pO T{ +.ad l +turn on printer for #1 bytes +T} +char_padding rmp rP T{ +.ad l +like ip but when in insert mode +T} +acs_chars acsc ac T{ +.ad l +graphics charset pairs, based on vt100 +T} +plab_norm pln pn T{ +.ad l +program label #1 to show string #2 +T} +key_btab kcbt kB T{ +.ad l +back-tab key +T} +enter_xon_mode smxon SX T{ +.ad l +turn on xon/xoff handshaking +T} +exit_xon_mode rmxon RX T{ +.ad l +turn off xon/xoff handshaking +T} +enter_am_mode smam SA T{ +.ad l +turn on automatic margins +T} +exit_am_mode rmam RA T{ +.ad l +turn off automatic margins +T} +xon_character xonc XN T{ +.ad l +XON character +T} +xoff_character xoffc XF T{ +.ad l +XOFF character +T} +ena_acs enacs eA T{ +.ad l +enable alternate char set +T} +label_on smln LO T{ +.ad l +turn on soft labels +T} +label_off rmln LF T{ +.ad l +turn off soft labels +T} +key_beg kbeg @1 T{ +.ad l +begin key +T} +key_cancel kcan @2 T{ +.ad l +cancel key +T} +key_close kclo @3 T{ +.ad l +close key +T} +key_command kcmd @4 T{ +.ad l +command key +T} +key_copy kcpy @5 T{ +.ad l +copy key +T} +key_create kcrt @6 T{ +.ad l +create key +T} +key_end kend @7 T{ +.ad l +end key +T} +key_enter kent @8 T{ +.ad l +enter/send key +T} +key_exit kext @9 T{ +.ad l +exit key +T} +key_find kfnd @0 T{ +.ad l +find key +T} +key_help khlp %1 T{ +.ad l +help key +T} +key_mark kmrk %2 T{ +.ad l +mark key +T} +key_message kmsg %3 T{ +.ad l +message key +T} +key_move kmov %4 T{ +.ad l +move key +T} +key_next knxt %5 T{ +.ad l +next key +T} +key_open kopn %6 T{ +.ad l +open key +T} +key_options kopt %7 T{ +.ad l +options key +T} +key_previous kprv %8 T{ +.ad l +previous key +T} +key_print kprt %9 T{ +.ad l +print key +T} +key_redo krdo %0 T{ +.ad l +redo key +T} +key_reference kref &1 T{ +.ad l +reference key +T} +key_refresh krfr &2 T{ +.ad l +refresh key +T} +key_replace krpl &3 T{ +.ad l +replace key +T} +key_restart krst &4 T{ +.ad l +restart key +T} +key_resume kres &5 T{ +.ad l +resume key +T} +key_save ksav &6 T{ +.ad l +save key +T} +key_suspend kspd &7 T{ +.ad l +suspend key +T} +key_undo kund &8 T{ +.ad l +undo key +T} +key_sbeg kBEG &9 T{ +.ad l +shifted begin key +T} +key_scancel kCAN &0 T{ +.ad l +shifted cancel key +T} +key_scommand kCMD *1 T{ +.ad l +shifted command key +T} +key_scopy kCPY *2 T{ +.ad l +shifted copy key +T} +key_screate kCRT *3 T{ +.ad l +shifted create key +T} +key_sdc kDC *4 T{ +.ad l +shifted delete-character key +T} +key_sdl kDL *5 T{ +.ad l +shifted delete-line key +T} +key_select kslt *6 T{ +.ad l +select key +T} +key_send kEND *7 T{ +.ad l +shifted end key +T} +key_seol kEOL *8 T{ +.ad l +shifted clear-to-end-of-line key +T} +key_sexit kEXT *9 T{ +.ad l +shifted exit key +T} +key_sfind kFND *0 T{ +.ad l +shifted find key +T} +key_shelp kHLP #1 T{ +.ad l +shifted help key +T} +key_shome kHOM #2 T{ +.ad l +shifted home key +T} +key_sic kIC #3 T{ +.ad l +shifted insert-character key +T} +key_sleft kLFT #4 T{ +.ad l +shifted left-arrow key +T} +key_smessage kMSG %a T{ +.ad l +shifted message key +T} +key_smove kMOV %b T{ +.ad l +shifted move key +T} +key_snext kNXT %c T{ +.ad l +shifted next key +T} +key_soptions kOPT %d T{ +.ad l +shifted options key +T} +key_sprevious kPRV %e T{ +.ad l +shifted previous key +T} +key_sprint kPRT %f T{ +.ad l +shifted print key +T} +key_sredo kRDO %g T{ +.ad l +shifted redo key +T} +key_sreplace kRPL %h T{ +.ad l +shifted replace key +T} +key_sright kRIT %i T{ +.ad l +shifted right-arrow key +T} +key_srsume kRES %j T{ +.ad l +shifted resume key +T} +key_ssave kSAV !1 T{ +.ad l +shifted save key +T} +key_ssuspend kSPD !2 T{ +.ad l +shifted suspend key +T} +key_sundo kUND !3 T{ +.ad l +shifted undo key +T} +req_for_input rfi RF T{ +.ad l +send next input char (for ptys) +T} +key_f11 kf11 F1 T{ +.ad l +F11 function key +T} +key_f12 kf12 F2 T{ +.ad l +F12 function key +T} +key_f13 kf13 F3 T{ +.ad l +F13 function key +T} +key_f14 kf14 F4 T{ +.ad l +F14 function key +T} +key_f15 kf15 F5 T{ +.ad l +F15 function key +T} +key_f16 kf16 F6 T{ +.ad l +F16 function key +T} +key_f17 kf17 F7 T{ +.ad l +F17 function key +T} +key_f18 kf18 F8 T{ +.ad l +F18 function key +T} +key_f19 kf19 F9 T{ +.ad l +F19 function key +T} +key_f20 kf20 FA T{ +.ad l +F20 function key +T} +key_f21 kf21 FB T{ +.ad l +F21 function key +T} +key_f22 kf22 FC T{ +.ad l +F22 function key +T} +key_f23 kf23 FD T{ +.ad l +F23 function key +T} +key_f24 kf24 FE T{ +.ad l +F24 function key +T} +key_f25 kf25 FF T{ +.ad l +F25 function key +T} +key_f26 kf26 FG T{ +.ad l +F26 function key +T} +key_f27 kf27 FH T{ +.ad l +F27 function key +T} +key_f28 kf28 FI T{ +.ad l +F28 function key +T} +key_f29 kf29 FJ T{ +.ad l +F29 function key +T} +key_f30 kf30 FK T{ +.ad l +F30 function key +T} +key_f31 kf31 FL T{ +.ad l +F31 function key +T} +key_f32 kf32 FM T{ +.ad l +F32 function key +T} +key_f33 kf33 FN T{ +.ad l +F33 function key +T} +key_f34 kf34 FO T{ +.ad l +F34 function key +T} +key_f35 kf35 FP T{ +.ad l +F35 function key +T} +key_f36 kf36 FQ T{ +.ad l +F36 function key +T} +key_f37 kf37 FR T{ +.ad l +F37 function key +T} +key_f38 kf38 FS T{ +.ad l +F38 function key +T} +key_f39 kf39 FT T{ +.ad l +F39 function key +T} +key_f40 kf40 FU T{ +.ad l +F40 function key +T} +key_f41 kf41 FV T{ +.ad l +F41 function key +T} +key_f42 kf42 FW T{ +.ad l +F42 function key +T} +key_f43 kf43 FX T{ +.ad l +F43 function key +T} +key_f44 kf44 FY T{ +.ad l +F44 function key +T} +key_f45 kf45 FZ T{ +.ad l +F45 function key +T} +key_f46 kf46 Fa T{ +.ad l +F46 function key +T} +key_f47 kf47 Fb T{ +.ad l +F47 function key +T} +key_f48 kf48 Fc T{ +.ad l +F48 function key +T} +key_f49 kf49 Fd T{ +.ad l +F49 function key +T} +key_f50 kf50 Fe T{ +.ad l +F50 function key +T} +key_f51 kf51 Ff T{ +.ad l +F51 function key +T} +key_f52 kf52 Fg T{ +.ad l +F52 function key +T} +key_f53 kf53 Fh T{ +.ad l +F53 function key +T} +key_f54 kf54 Fi T{ +.ad l +F54 function key +T} +key_f55 kf55 Fj T{ +.ad l +F55 function key +T} +key_f56 kf56 Fk T{ +.ad l +F56 function key +T} +key_f57 kf57 Fl T{ +.ad l +F57 function key +T} +key_f58 kf58 Fm T{ +.ad l +F58 function key +T} +key_f59 kf59 Fn T{ +.ad l +F59 function key +T} +key_f60 kf60 Fo T{ +.ad l +F60 function key +T} +key_f61 kf61 Fp T{ +.ad l +F61 function key +T} +key_f62 kf62 Fq T{ +.ad l +F62 function key +T} +key_f63 kf63 Fr T{ +.ad l +F63 function key +T} +clr_bol el1 cb T{ +.ad l +Clear to beginning of line +T} +clear_margins mgc MC T{ +.ad l +clear right and left soft margins +T} +set_left_margin smgl ML T{ +.ad l +set left soft margin at current column. (ML is not in BSD termcap). +T} +set_right_margin smgr MR T{ +.ad l +set right soft margin at current column +T} +label_format fln Lf T{ +.ad l +label format +T} +set_clock sclk SC T{ +.ad l +set clock, #1 hrs #2 mins #3 secs +T} +display_clock dclk DK T{ +.ad l +display clock +T} +remove_clock rmclk RC T{ +.ad l +remove clock +T} +create_window cwin CW T{ +.ad l +define a window #1 from #2,#3 to #4,#5 +T} +goto_window wingo WG T{ +.ad l +go to window #1 +T} +hangup hup HU T{ +.ad l +hang-up phone +T} +dial_phone dial DI T{ +.ad l +dial number #1 +T} +quick_dial qdial QD T{ +.ad l +dial number #1 without checking +T} +tone tone TO T{ +.ad l +select touch tone dialing +T} +pulse pulse PU T{ +.ad l +select pulse dialing +T} +flash_hook hook fh T{ +.ad l +flash switch hook +T} +fixed_pause pause PA T{ +.ad l +pause for 2-3 seconds +T} +wait_tone wait WA T{ +.ad l +wait for dial-tone +T} +user0 u0 u0 T{ +.ad l +User string #0 +T} +user1 u1 u1 T{ +.ad l +User string #1 +T} +user2 u2 u2 T{ +.ad l +User string #2 +T} +user3 u3 u3 T{ +.ad l +User string #3 +T} +user4 u4 u4 T{ +.ad l +User string #4 +T} +user5 u5 u5 T{ +.ad l +User string #5 +T} +user6 u6 u6 T{ +.ad l +User string #6 +T} +user7 u7 u7 T{ +.ad l +User string #7 +T} +user8 u8 u8 T{ +.ad l +User string #8 +T} +user9 u9 u9 T{ +.ad l +User string #9 +T} +orig_pair op op T{ +.ad l +Set default pair to its original value +T} +orig_colors oc oc T{ +.ad l +Set all color pairs to the original ones +T} +initialize_color initc Ic T{ +.ad l +initialize color #1 to (#2,#3,#4) +T} +initialize_pair initp Ip T{ +.ad l +Initialize color pair #1 to fg=(#2,#3,#4), bg=(#5,#6,#7) +T} +set_color_pair scp sp T{ +.ad l +Set current color pair to #1 +T} +set_foreground setf Sf T{ +.ad l +Set foreground color #1 +T} +set_background setb Sb T{ +.ad l +Set background color #1 +T} +change_char_pitch cpi ZA T{ +.ad l +Change number of characters per inch to #1 +T} +change_line_pitch lpi ZB T{ +.ad l +Change number of lines per inch to #1 +T} +change_res_horz chr ZC T{ +.ad l +Change horizontal resolution to #1 +T} +change_res_vert cvr ZD T{ +.ad l +Change vertical resolution to #1 +T} +define_char defc ZE T{ +.ad l +Define a character #1, #2 dots wide, descender #3 +T} +enter_doublewide_mode swidm ZF T{ +.ad l +Enter double-wide mode +T} +enter_draft_quality sdrfq ZG T{ +.ad l +Enter draft-quality mode +T} +enter_italics_mode sitm ZH T{ +.ad l +Enter italic mode +T} +enter_leftward_mode slm ZI T{ +.ad l +Start leftward carriage motion +T} +enter_micro_mode smicm ZJ T{ +.ad l +Start micro-motion mode +T} +enter_near_letter_quality snlq ZK T{ +.ad l +Enter NLQ mode +T} +enter_normal_quality snrmq ZL T{ +.ad l +Enter normal-quality mode +T} +enter_shadow_mode sshm ZM T{ +.ad l +Enter shadow-print mode +T} +enter_subscript_mode ssubm ZN T{ +.ad l +Enter subscript mode +T} +enter_superscript_mode ssupm ZO T{ +.ad l +Enter superscript mode +T} +enter_upward_mode sum ZP T{ +.ad l +Start upward carriage motion +T} +exit_doublewide_mode rwidm ZQ T{ +.ad l +End double-wide mode +T} +exit_italics_mode ritm ZR T{ +.ad l +End italic mode +T} +exit_leftward_mode rlm ZS T{ +.ad l +End left-motion mode +T} +exit_micro_mode rmicm ZT T{ +.ad l +End micro-motion mode +T} +exit_shadow_mode rshm ZU T{ +.ad l +End shadow-print mode +T} +exit_subscript_mode rsubm ZV T{ +.ad l +End subscript mode +T} +exit_superscript_mode rsupm ZW T{ +.ad l +End superscript mode +T} +exit_upward_mode rum ZX T{ +.ad l +End reverse character motion +T} +micro_column_address mhpa ZY T{ +.ad l +Like column_address in micro mode +T} +micro_down mcud1 ZZ T{ +.ad l +Like cursor_down in micro mode +T} +micro_left mcub1 Za T{ +.ad l +Like cursor_left in micro mode +T} +micro_right mcuf1 Zb T{ +.ad l +Like cursor_right in micro mode +T} +micro_row_address mvpa Zc T{ +.ad l +Like row_address #1 in micro mode +T} +micro_up mcuu1 Zd T{ +.ad l +Like cursor_up in micro mode +T} +order_of_pins porder Ze T{ +.ad l +Match software bits to print-head pins +T} +parm_down_micro mcud Zf T{ +.ad l +Like parm_down_cursor in micro mode +T} +parm_left_micro mcub Zg T{ +.ad l +Like parm_left_cursor in micro mode +T} +parm_right_micro mcuf Zh T{ +.ad l +Like parm_right_cursor in micro mode +T} +parm_up_micro mcuu Zi T{ +.ad l +Like parm_up_cursor in micro mode +T} +select_char_set scs Zj T{ +.ad l +Select character set, #1 +T} +set_bottom_margin smgb Zk T{ +.ad l +Set bottom margin at current line +T} +set_bottom_margin_parm smgbp Zl T{ +.ad l +Set bottom margin at line #1 or (if smgtp is not given) #2 lines from bottom +T} +set_left_margin_parm smglp Zm T{ +.ad l +Set left (right) margin at column #1 +T} +set_right_margin_parm smgrp Zn T{ +.ad l +Set right margin at column #1 +T} +set_top_margin smgt Zo T{ +.ad l +Set top margin at current line +T} +set_top_margin_parm smgtp Zp T{ +.ad l +Set top (bottom) margin at row #1 +T} +start_bit_image sbim Zq T{ +.ad l +Start printing bit image graphics +T} +start_char_set_def scsd Zr T{ +.ad l +Start character set definition #1, with #2 characters in the set +T} +stop_bit_image rbim Zs T{ +.ad l +Stop printing bit image graphics +T} +stop_char_set_def rcsd Zt T{ +.ad l +End definition of character set #1 +T} +subscript_characters subcs Zu T{ +.ad l +List of subscriptable characters +T} +superscript_characters supcs Zv T{ +.ad l +List of superscriptable characters +T} +these_cause_cr docr Zw T{ +.ad l +Printing any of these characters causes CR +T} +zero_motion zerom Zx T{ +.ad l +No motion for subsequent character +T} +.TE +.PP +. +The following string capabilities are present in the SVr4.0 term structure, +but were originally not documented in the man page. +. +.PP +.TS +center; +Lb Cb S Lb +Lb Lb Lb Lb +Lbw(25n)2 Lbw(8n)2 Lb2 Lx. +\& Code \& +String Capability Name TI TC Description +_ +char_set_names csnm Zy T{ +.ad l +Produce #1'th item from list of character set names +T} +key_mouse kmous Km T{ +.ad l +Mouse event has occurred +T} +mouse_info minfo Mi T{ +.ad l +Mouse status information +T} +req_mouse_pos reqmp RQ T{ +.ad l +Request mouse position +T} +get_mouse getm Gm T{ +.ad l +Curses should get button events, parameter #1 not documented. +T} +set_a_foreground setaf AF T{ +.ad l +Set foreground color to #1, using ANSI escape +T} +set_a_background setab AB T{ +.ad l +Set background color to #1, using ANSI escape +T} +pkey_plab pfxl xl T{ +.ad l +Program function key #1 to type string #2 and show string #3 +T} +device_type devt dv T{ +.ad l +Indicate language, codeset support +T} +code_set_init csin ci T{ +.ad l +Init sequence for multiple codesets +T} +set0_des_seq s0ds s0 T{ +.ad l +Shift to codeset 0 (EUC set 0, ASCII) +T} +set1_des_seq s1ds s1 T{ +.ad l +Shift to codeset 1 +T} +set2_des_seq s2ds s2 T{ +.ad l +Shift to codeset 2 +T} +set3_des_seq s3ds s3 T{ +.ad l +Shift to codeset 3 +T} +set_lr_margin smglr ML T{ +.ad l +Set both left and right margins to #1, #2. (ML is not in BSD termcap). +T} +set_tb_margin smgtb MT T{ +.ad l +Sets both top and bottom margins to #1, #2 +T} +bit_image_repeat birep Xy T{ +.ad l +Repeat bit image cell #1 #2 times +T} +bit_image_newline binel Zz T{ +.ad l +Move to next row of the bit image +T} +bit_image_carriage_return bicr Yv T{ +.ad l +Move to beginning of same row +T} +color_names colornm Yw T{ +.ad l +Give name for color #1 +T} +define_bit_image_region defbi Yx T{ +.ad l +Define rectangular bit image region +T} +end_bit_image_region endbi Yy T{ +.ad l +End a bit-image region +T} +set_color_band setcolor Yz T{ +.ad l +Change to ribbon color #1 +T} +set_page_length slines YZ T{ +.ad l +Set page length to #1 lines +T} +display_pc_char dispc S1 T{ +.ad l +Display PC character #1 +T} +enter_pc_charset_mode smpch S2 T{ +.ad l +Enter PC character display mode +T} +exit_pc_charset_mode rmpch S3 T{ +.ad l +Exit PC character display mode +T} +enter_scancode_mode smsc S4 T{ +.ad l +Enter PC scancode mode +T} +exit_scancode_mode rmsc S5 T{ +.ad l +Exit PC scancode mode +T} +pc_term_options pctrm S6 T{ +.ad l +PC terminal options +T} +scancode_escape scesc S7 T{ +.ad l +Escape for scancode emulation +T} +alt_scancode_esc scesa S8 T{ +.ad l +Alternate escape for scancode emulation +T} +.TE +.PP +. +The XSI Curses standard added these hardcopy capabilities. +They were used in some post-4.1 versions of System V curses, +e.g., Solaris 2.5 and IRIX 6.x. +Except for \fBYI\fP, the \fBncurses\fR termcap names for them are invented. +According to the XSI Curses standard, they have no termcap names. +If your compiled terminfo entries use these, +they may not be binary-compatible with System V terminfo +entries after SVr4.1; beware! +. +.PP +.TS +center; +Lb Cb S Lb +Lb Lb Lb Lb +Lbw(25n)2 Lbw(8n)2 Lb2 Lx. +\& Code \& +String Capability Name TI TC Description +_ +enter_horizontal_hl_mode ehhlm Xh T{ +.ad l +Enter horizontal highlight mode +T} +enter_left_hl_mode elhlm Xl T{ +.ad l +Enter left highlight mode +T} +enter_low_hl_mode elohlm Xo T{ +.ad l +Enter low highlight mode +T} +enter_right_hl_mode erhlm Xr T{ +.ad l +Enter right highlight mode +T} +enter_top_hl_mode ethlm Xt T{ +.ad l +Enter top highlight mode +T} +enter_vertical_hl_mode evhlm Xv T{ +.ad l +Enter vertical highlight mode +T} +set_a_attributes sgr1 sA T{ +.ad l +Define second set of video attributes #1-#6 +T} +set_pglen_inch slength YI T{ +.ad l +Set page length to #1 hundredth of an inch (some implementations use sL for termcap). +T} +.TE +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: terminfo.tail,v 1.143 2024/01/13 22:05:39 tom Exp $ +.ps +1 +.SS "User-Defined Capabilities" +. +The preceding section listed the \fIpredefined\fP capabilities. +They deal with some special features for terminals no longer +(or possibly never) produced. +Occasionally there are special features of newer terminals which +are awkward or impossible to represent by reusing the predefined +capabilities. +.PP +\fI\%ncurses\fP addresses this limitation by allowing user-defined +capabilities. +The \fBtic\fP and \fBinfocmp\fP programs provide +the \fB\-x\fP option for this purpose. +When \fB\-x\fP is set, +\fBtic\fP treats unknown capabilities as user-defined. +That is, if \fBtic\fP encounters a capability name +which it does not recognize, +it infers its type (Boolean, number or string) from the syntax +and makes an extended table entry for that capability. +The \fBuse_extended_names\fP(3X) function makes this information +conditionally available to applications. +The \fI\%ncurses\fP library provides the data leaving most of the +behavior to applications: +.bP +User-defined capability strings whose name begins +with \*(``k\*('' are treated as function keys. +.bP +The types (Boolean, number, string) determined by \fBtic\fP +can be inferred by successful calls on \fBtigetflag\fP, etc. +.bP +If the capability name happens to be two characters, +the capability is also available through the termcap interface. +.PP +While termcap is said to be extensible because it does not use a predefined set +of capabilities, +in practice it has been limited to the capabilities defined by +terminfo implementations. +As a rule, +user-defined capabilities intended for use by termcap applications should +be limited to Booleans and numbers to avoid running past the 1023 byte +limit assumed by termcap implementations and their applications. +In particular, providing extended sets of function keys (past the 60 +numbered keys and the handful of special named keys) is best done using +the longer names available using terminfo. +.PP +The \fI\%ncurses\fP library uses a few of these user-defined +capabilities, +as described in \fBuser_caps\fR(5). +Other user-defined capabilities (including function keys) are +described in the terminal database, in the section on +.I "NCURSES USER-DEFINABLE CAPABILITIES" +. +.SS "A Sample Entry" +. +The following entry, describing an ANSI-standard terminal, is representative +of what a \fBterminfo\fP entry for a modern terminal typically looks like. +.PP +.EX +\s-2ansi|ansi/pc\-term compatible with color, + am, mc5i, mir, msgr, + colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64, + acsc=+\e020\e,\e021\-\e030.\*^Y0\e333\(ga\e004a\e261f\e370g\e361h\e260 + j\e331k\e277l\e332m\e300n\e305o\*~p\e304q\e304r\e304s_t\e303 + u\e264v\e301w\e302x\e263y\e363z\e362{\e343|\e330}\e234\*~\e376, + bel=\*^G, blink=\eE[5m, bold=\eE[1m, cbt=\eE[Z, clear=\eE[H\eE[J, + cr=\*^M, cub=\eE[%p1%dD, cub1=\eE[D, cud=\eE[%p1%dB, cud1=\eE[B, + cuf=\eE[%p1%dC, cuf1=\eE[C, cup=\eE[%i%p1%d;%p2%dH, + cuu=\eE[%p1%dA, cuu1=\eE[A, dch=\eE[%p1%dP, dch1=\eE[P, + dl=\eE[%p1%dM, dl1=\eE[M, ech=\eE[%p1%dX, ed=\eE[J, el=\eE[K, + el1=\eE[1K, home=\eE[H, hpa=\eE[%i%p1%dG, ht=\eE[I, hts=\eEH, + ich=\eE[%p1%d@, il=\eE[%p1%dL, il1=\eE[L, ind=\*^J, + indn=\eE[%p1%dS, invis=\eE[8m, kbs=\*^H, kcbt=\eE[Z, kcub1=\eE[D, + kcud1=\eE[B, kcuf1=\eE[C, kcuu1=\eE[A, khome=\eE[H, kich1=\eE[L, + mc4=\eE[4i, mc5=\eE[5i, nel=\er\eE[S, op=\eE[39;49m, + rep=%p1%c\eE[%p2%{1}%\-%db, rev=\eE[7m, rin=\eE[%p1%dT, + rmacs=\eE[10m, rmpch=\eE[10m, rmso=\eE[m, rmul=\eE[m, + s0ds=\eE(B, s1ds=\eE)B, s2ds=\eE*B, s3ds=\eE+B, + setab=\eE[4%p1%dm, setaf=\eE[3%p1%dm, + sgr=\eE[0;10%?%p1%t;7%; + %?%p2%t;4%; + %?%p3%t;7%; + %?%p4%t;5%; + %?%p6%t;1%; + %?%p7%t;8%; + %?%p9%t;11%;m, + sgr0=\eE[0;10m, smacs=\eE[11m, smpch=\eE[11m, smso=\eE[7m, + smul=\eE[4m, tbc=\eE[3g, u6=\eE[%i%d;%dR, u7=\eE[6n, + u8=\eE[?%[;0123456789]c, u9=\eE[c, vpa=\eE[%i%p1%dd, +.EE +.PP +Entries may continue onto multiple lines by placing white space at +the beginning of each line except the first. +Comments may be included on lines beginning with \*(``#\*(''. +Capabilities in +.I terminfo +are of three types: +.bP +Boolean capabilities which indicate that the terminal has +some particular feature, +.bP +numeric capabilities giving the size of the terminal +or the size of particular delays, and +.bP +string +capabilities, which give a sequence which can be used to perform particular +terminal operations. +.SS "Types of Capabilities" +All capabilities have names. +For instance, the fact that +ANSI-standard terminals have +.I "automatic margins" +(i.e., an automatic return and line-feed +when the end of a line is reached) is indicated by the capability \fBam\fP. +Hence the description of ansi includes \fBam\fP. +Numeric capabilities are followed by the character \*(``#\*('' +and then a positive value. +Thus \fBcols\fP, which indicates the number of columns the terminal has, +gives the value \*(``80\*('' for ansi. +Values for numeric capabilities may be specified in +decimal, +octal, or +hexadecimal, +using the C programming language conventions +(e.g., 255, 0377 and 0xff or 0xFF). +.PP +Finally, string valued capabilities, +such as \fBel\fP (clear to end of line sequence) +are given by the two-character code, +an \*(``=\*('', and then +a string ending at the next following \*(``,\*(''. +.PP +A number of escape sequences are provided in the string valued capabilities +for easy encoding of characters there: +.bP +Both \fB\eE\fP and \fB\ee\fP +map to an \s-1ESCAPE\s0 character, +.bP +\fB\*^\f(BIx\fR maps to a control-\fIx\fP for any appropriate \fIx\fP, +and +.bP +the sequences +.RS 6 +.PP +\fB\en\fP, \fB\el\fP, \fB\er\fP, \fB\et\fP, \fB\eb\fP, \fB\ef\fP, and \fB\es\fP +.RE +.IP +produce +.RS 6 +.PP +\fInewline\fP, \fIline-feed\fP, \fIreturn\fP, \fItab\fP, \fIbackspace\fP, \fIform-feed\fP, and \fIspace\fP, +.RE +.IP +respectively. +.PP +X/Open Curses does not say what \*(``appropriate \fIx\fP\*('' might be. +In practice, that is a printable ASCII graphic character. +The special case \*(``\*^?\*('' is interpreted as DEL (127). +In all other cases, the character value is AND'd with 0x1f, +mapping to ASCII control codes in the range 0 through 31. +.PP +Other escapes include +.bP +\fB\e\*^\fP for \fB\*^\fP, +.bP +\fB\e\e\fP for \fB\e\fP, +.bP +\fB\e\fP, for comma, +.bP +\fB\e:\fP for \fB:\fP, +.bP +and \fB\e0\fP for null. +.IP +\fB\e0\fP will produce \e200, which does not terminate a string but behaves +as a null character on most terminals, providing CS7 is specified. +See \fBstty\fP(1). +.IP +The reason for this quirk is to maintain binary compatibility of the +compiled terminfo files with other implementations, +e.g., the SVr4 systems, which document this. +Compiled terminfo files use null-terminated strings, with no lengths. +Modifying this would require a new binary format, +which would not work with other implementations. +.PP +Finally, characters may be given as three octal digits after a \fB\e\fP. +.PP +A delay in milliseconds may appear anywhere in a string capability, enclosed in +$<..> brackets, as in \fBel\fP=\eEK$<5>, +and padding characters are supplied by \fBtputs\fP(3X) +to provide this delay. +.bP +The delay must be a number with at most one decimal +place of precision; +it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both. +.bP +A \*(``*\*('' +indicates that the padding required is proportional to the number of lines +affected by the operation, and the amount given is the per-affected-unit +padding required. +(In the case of insert character, the factor is still the +number of \fIlines\fP affected.) +.IP +Normally, padding is advisory if the device has the \fBxon\fP +capability; it is used for cost computation but does not trigger delays. +.bP +A \*(``/\*('' +suffix indicates that the padding is mandatory and forces a delay of the given +number of milliseconds even on devices for which \fBxon\fP is present to +indicate flow control. +.PP +Sometimes individual capabilities must be commented out. +To do this, put a period before the capability name. +For example, see the second +.B ind +in the example above. +.br +.ne 5 +.SS "Fetching Compiled Descriptions" +Terminal descriptions in \fI\%ncurses\fP are stored in terminal +databases. +These databases, which are found by their pathname, +may be configured either as directory trees or hashed databases +(see \fBterm\fR(5)), +.PP +The library uses a compiled-in list of pathnames, +which can be overridden by environment variables. +Before starting to search, +\fI\%ncurses\fP checks the search list, +eliminating duplicates and pathnames where no terminal database is found. +The \fI\%ncurses\fP library reads the first description +which passes its consistency checks. +.bP +The environment variable \fBTERMINFO\fR is checked first, for +a terminal database containing the terminal description. +.bP +Next, +\fI\%ncurses\fP looks in \fI$HOME/.terminfo\fP +for a compiled description. +.IP +This is an optional feature which may be omitted entirely from +the library, or limited to prevent accidental use by privileged applications. +.bP +Next, +if the environment variable \fI\%TERMINFO_DIRS\fP is set, +\fI\%ncurses\fP interprets the contents of that variable +as a list of colon-separated pathnames of terminal databases to be searched. +.IP +An empty pathname (i.e., if the variable begins or ends +with a colon, or contains adjacent colons) +is interpreted as the system location \fI\*d\fP. +.bP +Finally, \fI\%ncurses\fP searches these compiled-in locations: +.RS +.bP +a list of directories (/etc/terminfo:/usr/share/terminfo), and +.bP +the system terminfo directory, \fI\*d\fP +.RE +.PP +The \fBTERMINFO\fP variable can contain a terminal description instead +of the pathname of a terminal database. +If this variable begins with \*(``hex:\*('' or \*(``b64:\*('' +then \fI\%ncurses\fP reads a terminal description from +hexadecimal- or base64-encoded data, +and if that description matches the name sought, will use that. +This encoded data can be set using the \*(``\-Q\*('' option of +\fBtic\fR or \fBinfocmp\fR. +.PP +The preceding addresses the usual configuration of \fI\%ncurses\fP, +which uses terminal descriptions prepared in \fIterminfo\fP format. +While \fItermcap\fP is less expressive, +\fI\%ncurses\fP can also be configured to read \fItermcap\fP +descriptions. +In that configuration, +it checks the \fI\%TERMCAP\fP and \fI\%TERMPATH\fP variables +(for content and search path, +respectively) +after the system terminal database. +.SS "Preparing Descriptions" +We now outline how to prepare descriptions of terminals. +The most effective way to prepare a terminal description is by imitating +the description of a similar terminal in +.I terminfo +and to build up a description gradually, using partial descriptions +with +.I vi +or some other screen-oriented program to check that they are correct. +Be aware that a very unusual terminal may expose deficiencies in +the ability of the +.I terminfo +file to describe it +or bugs in the screen-handling code of the test program. +.PP +To get the padding for insert line right (if the terminal manufacturer +did not document it) a severe test is to edit a large file at 9600 baud, +delete 16 or so lines from the middle of the screen, then hit the \*(``u\*('' +key several times quickly. +If the terminal messes up, more padding is usually needed. +A similar test can be used for insert character. +.SS "Basic Capabilities" +The number of columns on each line for the terminal is given by the +\fBcols\fP numeric capability. +If the terminal is a \s-1CRT\s0, then the +number of lines on the screen is given by the \fBlines\fP capability. +If the terminal wraps around to the beginning of the next line when +it reaches the right margin, then it should have the \fBam\fP capability. +If the terminal can clear its screen, leaving the cursor in the home +position, then this is given by the \fBclear\fP string capability. +If the terminal overstrikes +(rather than clearing a position when a character is struck over) +then it should have the \fBos\fP capability. +If the terminal is a printing terminal, with no soft copy unit, +give it both +.B hc +and +.BR os . +.RB ( os +applies to storage scope terminals, such as \s-1TEKTRONIX\s+1 4010 +series, as well as hard copy and APL terminals.) +If there is a code to move the cursor to the left edge of the current +row, give this as +.BR cr . +(Normally this will be carriage return, control/M.) +If there is a code to produce an audible signal (bell, beep, etc) +give this as +.BR bel . +.PP +If there is a code to move the cursor one position to the left +(such as backspace) that capability should be given as +.BR cub1 . +Similarly, codes to move to the right, up, and down should be +given as +.BR cuf1 , +.BR cuu1 , +and +.BR cud1 . +These local cursor motions should not alter the text they pass over, +for example, you would not normally use \*(``\fBcuf1\fP=\ \*('' because the +space would erase the character moved over. +.PP +A very important point here is that the local cursor motions encoded +in +.I terminfo +are undefined at the left and top edges of a \s-1CRT\s0 terminal. +Programs should never attempt to backspace around the left edge, +unless +.B bw +is given, +and never attempt to go up locally off the top. +In order to scroll text up, a program will go to the bottom left corner +of the screen and send the +.B ind +(index) string. +.PP +To scroll text down, a program goes to the top left corner +of the screen and sends the +.B ri +(reverse index) string. +The strings +.B ind +and +.B ri +are undefined when not on their respective corners of the screen. +.PP +Parameterized versions of the scrolling sequences are +.B indn +and +.B rin +which have the same semantics as +.B ind +and +.B ri +except that they take one parameter, and scroll that many lines. +They are also undefined except at the appropriate edge of the screen. +.PP +The \fBam\fP capability tells whether the cursor sticks at the right +edge of the screen when text is output, but this does not necessarily +apply to a +.B cuf1 +from the last column. +The only local motion which is defined from the left edge is if +.B bw +is given, then a +.B cub1 +from the left edge will move to the right edge of the previous row. +If +.B bw +is not given, the effect is undefined. +This is useful for drawing a box around the edge of the screen, for example. +If the terminal has switch selectable automatic margins, +the +.I terminfo +file usually assumes that this is on; i.e., \fBam\fP. +If the terminal has a command which moves to the first column of the next +line, that command can be given as +.B nel +(newline). +It does not matter if the command clears the remainder of the current line, +so if the terminal has no +.B cr +and +.B lf +it may still be possible to craft a working +.B nel +out of one or both of them. +.PP +These capabilities suffice to describe +hard-copy and \*(``glass-tty\*('' terminals. +Thus the model 33 teletype is described as +.PP +.EX +.\".in -2 +\s-133\||\|tty33\||\|tty\||\|model 33 teletype, + bel=\*^G, cols#72, cr=\*^M, cud1=\*^J, hc, ind=\*^J, os,\s+1 +.\".in +2 +.EE +.PP +while the Lear Siegler \s-1ADM-3\s0 is described as +.PP +.EX +.\".in -2 +\s-1adm3\||\|3\||\|lsi adm3, + am, bel=\*^G, clear=\*^Z, cols#80, cr=\*^M, cub1=\*^H, cud1=\*^J, + ind=\*^J, lines#24,\s+1 +.\".in +2 +.EE +.SS "Parameterized Strings" +Cursor addressing and other strings requiring parameters +in the terminal are described by a +parameterized string capability, +with \fIprintf\fP-like escapes such as \fI%x\fP in it. +For example, to address the cursor, the +.B cup +capability is given, using two parameters: +the row and column to address to. +(Rows and columns are numbered from zero and refer to the +physical screen visible to the user, not to any unseen memory.) +If the terminal has memory relative cursor addressing, +that can be indicated by +.BR mrcup . +.PP +The parameter mechanism uses a stack and special \fB%\fP codes +to manipulate it. +Typically a sequence will push one of the +parameters onto the stack and then print it in some format. +Print (e.g., \*(``%d\*('') is a special case. +Other operations, including \*(``%t\*('' pop their operand from the stack. +It is noted that more complex operations are often necessary, +e.g., in the \fBsgr\fP string. +.PP +The \fB%\fP encodings have the following meanings: +.TP 5 +\fB%%\fP +outputs \*(``%\*('' +.TP +\fB%\fI[[\fR:\fI]flags][width[.precision]][\fBdoxXs\fI]\fR +as in \fBprintf\fP(3), flags are \fI[\-+#]\fP and \fIspace\fP. +Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag, +avoiding interpreting \*(``%\-\*('' as an operator. +.TP +\fB%c\fP +print \fIpop()\fP like %c in \fBprintf\fP +.TP +\fB%s\fP +print \fIpop()\fP like %s in \fBprintf\fP +.TP +\fB%p\fI[1\-9]\fR +push \fIi\fP'th parameter +.TP +\fB%P\fI[a\-z]\fR +set dynamic variable \fI[a\-z]\fP to \fIpop()\fP +.TP +\fB%g\fI[a\-z]\fR +get dynamic variable \fI[a\-z]\fP and push it +.TP +\fB%P\fI[A\-Z]\fR +set static variable \fI[a\-z]\fP to \fIpop()\fP +.TP +\fB%g\fI[A\-Z]\fR +get static variable \fI[a\-z]\fP and push it +.IP +The terms \*(``static\*('' and \*(``dynamic\*('' are misleading. +Historically, these are simply two different sets of variables, +whose values are not reset between calls to \fBtparm\fP(3X). +However, that fact is not documented in other implementations. +Relying on it will adversely impact portability to other implementations: +.RS +.bP +SVr2 curses supported \fIdynamic\fP variables. +Those are set only by a \fB%P\fP operator. +A \fB%g\fP for a given variable without first setting it with \fB%P\fP +will give unpredictable results, because dynamic variables are +an uninitialized local array on the stack in the \fBtparm\fP function. +.bP +SVr3.2 curses supported \fIstatic\fP variables. +Those are an array in the \fI\%TERMINAL\fP +structure (declared in \fBterm.h\fP), +and are zeroed automatically when the \fBsetupterm\fP function +allocates the data. +.bP +SVr4 curses made no further improvements +to the \fIdynamic/static\fP variable feature. +.bP +Solaris XPG4 curses does not distinguish between \fIdynamic\fP and +\fIstatic\fP variables. +They are the same. +Like SVr4 curses, XPG4 curses does not initialize these explicitly. +.bP +Before version 6.3, +\fI\%ncurses\fP stores both \fIdynamic\fP and \fIstatic\fP +variables in persistent storage, initialized to zeros. +.bP +Beginning with version 6.3, +\fI\%ncurses\fP stores \fIstatic\fP and \fIdynamic\fP +variables in the same manner as SVr4. +.RS +.bP +Unlike other implementations, \fI\%ncurses\fP zeros dynamic variables +before the first \fB%g\fP or \fB%P\fP operator. +.bP +Like SVr2, +the scope of dynamic variables in \fI\%ncurses\fP +is within the current call to +\fBtparm\fP. +Use static variables if persistent storage is needed. +.RE +.RE +.TP +\fB%\*'\fIc\fB\*'\fR +char constant \fIc\fP +.TP +\fB%{\fInn\fB}\fR +integer constant \fInn\fP +.TP +\fB%l\fP +push strlen(pop) +.TP +\fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP +arithmetic (%m is \fImod\fP): \fIpush(pop() op pop())\fP +.TP +\fB%&\fP, \fB%|\fP, \fB%\*^\fP +bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP +.TP +\fB%=\fP, \fB%>\fP, \fB%<\fP +logical operations: \fIpush(pop() op pop())\fP +.TP +\fB%A\fP, \fB%O\fP +logical AND and OR operations (for conditionals) +.TP +\fB%!\fP, \fB%\*~\fP +unary operations (logical and bit complement): \fIpush(op pop())\fP +.TP +\fB%i\fP +add 1 to first two parameters (for ANSI terminals) +.TP +\fB%?\fP \fIexpr\fP \fB%t\fP \fIthenpart\fP \fB%e\fP \fIelsepart\fP \fB%;\fP +This forms an if-then-else. +The \fB%e\fP \fIelsepart\fP is optional. +Usually the \fB%?\fP \fIexpr\fP part pushes a value onto the stack, +and \fB%t\fP pops it from the stack, testing if it is nonzero (true). +If it is zero (false), control passes to the \fB%e\fP (else) part. +.IP +It is possible to form else-if's a la Algol 68: +.RS +\fB%?\fP c\d1\u \fB%t\fP b\d1\u \fB%e\fP c\d2\u \fB%t\fP b\d2\u \fB%e\fP c\d3\u \fB%t\fP b\d3\u \fB%e\fP c\d4\u \fB%t\fP b\d4\u \fB%e\fP \fB%;\fP +.RE +.IP +where c\di\u are conditions, b\di\u are bodies. +.IP +Use the \fB\-f\fP option of \fBtic\fP or \fBinfocmp\fP to see +the structure of if-then-else's. +Some strings, e.g., \fBsgr\fP can be very complicated when written +on one line. +The \fB\-f\fP option splits the string into lines with the parts indented. +.PP +Binary operations are in postfix form with the operands in the usual order. +That is, to get x\-5 one would use \*(``%gx%{5}%\-\*(''. +\fB%P\fP and \fB%g\fP variables are +persistent across escape-string evaluations. +.PP +Consider the HP2645, which, to get to row 3 and column 12, needs +to be sent \eE&a12c03Y padded for 6 milliseconds. +The order of the rows and columns is inverted here, +and the row and column are printed as two digits. +The corresponding terminal description is expressed thus: +.RS +cup=\eE&a%p2%dc%p1%dY$<6>, +.RE +.PP +The Microterm \s-1ACT-IV\s0 needs the current row and column sent +preceded by a \fB\*^T\fP, with the row and column simply encoded in binary, +.RS +cup=\*^T%p1%c%p2%c +.RE +.PP +Terminals which use \*(``%c\*('' need to be able to +backspace the cursor (\fBcub1\fP), +and to move the cursor up one line on the screen (\fBcuu1\fP). +This is necessary because it is not always safe to transmit \fB\en\fP +\fB\*^D\fP and \fB\er\fP, as the system may change or discard them. +(The library routines dealing with terminfo set tty modes so that +tabs are never expanded, so \et is safe to send. +This turns out to be essential for the Ann Arbor 4080.) +.PP +A final example is the \s-1LSI ADM\s0-3a, which uses row and column +offset by a blank character, thus +.RS +cup=\eE=%p1%\*' \*'%+%c%p2%\*' \*'%+%c +.RE +.PP +After sending \*(``\eE=\*('', this pushes the first parameter, pushes the +ASCII value for a space (32), adds them (pushing the sum on the stack +in place of the two previous values) and outputs that value as a character. +Then the same is done for the second parameter. +More complex arithmetic is possible using the stack. +.SS "Cursor Motions" +If the terminal has a fast way to home the cursor +(to very upper left corner of screen) then this can be given as +\fBhome\fP; similarly a fast way of getting to the lower left-hand corner +can be given as \fBll\fP; this may involve going up with \fBcuu1\fP +from the home position, +but a program should never do this itself (unless \fBll\fP does) because it +can make no assumption about the effect of moving up from the home position. +Note that the home position is the same as addressing to (0,0): +to the top left corner of the screen, not of memory. +(Thus, the \eEH sequence on HP terminals cannot be used for +.BR home .) +.PP +If the terminal has row or column absolute cursor addressing, +these can be given as single parameter capabilities +.B hpa +(horizontal position absolute) +and +.B vpa +(vertical position absolute). +Sometimes these are shorter than the more general two parameter +sequence (as with the hp2645) and can be used in preference to +.BR cup . +If there are parameterized local motions (e.g., move +.I n +spaces to the right) these can be given as +.BR cud , +.BR cub , +.BR cuf , +and +.B cuu +with a single parameter indicating how many spaces to move. +These are primarily useful if the terminal does not have +.BR cup , +such as the \s-1TEKTRONIX\s+1 4025. +.PP +If the terminal needs to be in a special mode when running +a program that uses these capabilities, +the codes to enter and exit this mode can be given +as \fBsmcup\fP and \fBrmcup\fP. +This arises, for example, from terminals like the Concept with more than +one page of memory. +If the terminal has only memory relative cursor addressing and not screen +relative cursor addressing, a one screen-sized window must be fixed into +the terminal for cursor addressing to work properly. +This is also used for the \s-1TEKTRONIX\s+1 4025, +where +.B smcup +sets the command character to be the one used by terminfo. +If the \fBsmcup\fP sequence will not restore the screen after an +\fBrmcup\fP sequence is output (to the state prior to outputting +\fBrmcup\fP), specify \fBnrrmc\fP. +.SS Margins +SVr4 (and X/Open Curses) +list several string capabilities for setting margins. +Two were intended for use with terminals, +and another six were intended for use with printers. +.bP +The two terminal capabilities assume that the terminal may have +the capability of setting the left and/or right margin at the current +cursor column position. +.bP +The printer capabilities assume that the printer may have +two types of capability: +.RS +.bP +the ability to set a top and/or bottom margin using the current +line position, and +.bP +parameterized capabilities for setting the top, bottom, left, right margins +given the number of rows or columns. +.RE +.PP +In practice, the categorization into \*(``terminal\*('' and \*(``printer\*('' +is not suitable: +.bP +The AT&T SVr4 terminal database uses \fBsmgl\fP four times, +for AT&T hardware. +.IP +Three of the four are printers. +They lack the ability to set left/right margins by specifying the column. +.bP +Other (non-AT&T) terminals may support margins +but using different assumptions from AT&T. +.IP +For instance, the DEC VT420 supports left/right margins, +but only using a column parameter. +As an added complication, the VT420 uses two settings to fully enable +left/right margins (left/right margin mode, and origin mode). +The former enables the margins, which causes printed text +to wrap within margins, but the latter is needed to prevent +cursor-addressing outside those margins. +.bP +Both DEC VT420 left/right margins are set with a single control sequence. +If either is omitted, the corresponding margin is set to the left or +right edge of the display (rather than leaving the margin unmodified). +.PP +These are the margin-related capabilities: +.PP +.TS +center; +lb lb +lb l . +Name Description +_ +smgl Set left margin at current column +smgr Set right margin at current column +smgb Set bottom margin at current line +smgt Set top margin at current line +smgbp Set bottom margin at line \fIN\fP +smglp Set left margin at column \fIN\fP +smgrp Set right margin at column \fIN\fP +smgtp Set top margin at line \fIN\fP +smglr Set both left and right margins to \fIL\fP and \fIR\fP +smgtb Set both top and bottom margins to \fIT\fP and \fIB\fP +.TE +.PP +When writing an application that +uses these string capabilities, +the pairs should be first checked to see +if each capability in the pair is set or only one is set: +.bP +If both \fBsmglp\fP and \fBsmgrp\fP are set, +each is used with a single argument, \fIN\fP, +that gives the column number of the left and right margin, respectively. +.bP +If both \fBsmgtp\fP and \fBsmgbp\fP are set, +each is used to set the top and bottom margin, +respectively: +.RS 4 +.bP +\fBsmgtp\fP is used with a single argument, \fIN\fP, +the line number of the top margin. +.bP +\fBsmgbp\fP is used with two arguments, \fIN\fP and \fIM\fP, +that give the line number of the bottom margin, +the first counting from the top of the +page and the second counting from the bottom. +This accommodates the two styles of specifying +the bottom margin in different manufacturers' printers. +.RE +.IP +When designing a terminfo entry for a +printer that has a settable bottom margin, +only the first or second argument should be used, depending on the printer. +When developing an application that uses \fBsmgbp\fP to set the bottom margin, +both arguments must be given. +.PP +Conversely, when only one capability in the pair is set: +.bP +If only one of \fBsmglp\fP and \fBsmgrp\fP is set, +then it is used with two arguments, +the column number of the left and right margins, in that order. +.bP +Likewise, if only one of \fBsmgtp\fP and \fBsmgbp\fP is set, then it +is used with two arguments that give the top and bottom margins, +in that order, counting from the top of the page. +.IP +When designing a terminfo entry for a printer that requires setting both +left and right or top and bottom margins simultaneously, +only one capability in the pairs +\fBsmglp\fP and \fBsmgrp\fP or +\fBsmgtp\fP and \fBsmgbp\fP should be defined, +leaving the other unset. +.PP +Except for very old terminal descriptions, e.g., those developed for SVr4, +the scheme just described should be considered obsolete. +An improved set of capabilities was added late in the SVr4 releases +(\fBsmglr\fP and \fBsmgtb\fP), +which explicitly use two parameters for setting the left/right or top/bottom +margins. +.PP +When setting margins, the line- and column-values are zero-based. +.PP +The \fBmgc\fP string capability should be defined. +Applications such as \fBtabs\fP(1) rely upon this to reset all margins. +.\" +.SS "Area Clears" +If the terminal can clear from the current position to the end of the +line, leaving the cursor where it is, this should be given as \fBel\fP. +If the terminal can clear from the beginning of the line to the current +position inclusive, leaving +the cursor where it is, this should be given as \fBel1\fP. +If the terminal can clear from the current position to the end of the +display, then this should be given as \fBed\fP. +\fBEd\fP is only defined from the first column of a line. +(Thus, it can be simulated by a request to delete a large number of lines, +if a true +.B ed +is not available.) +.\" +.SS "Insert/Delete Line and Vertical Motions" +If the terminal can open a new blank line before the line where the cursor +is, this should be given as \fBil1\fP; this is done only from the first +position of a line. +The cursor must then appear on the newly blank line. +If the terminal can delete the line which the cursor is on, then this +should be given as \fBdl1\fP; this is done only from the first position on +the line to be deleted. +Versions of +.B il1 +and +.B dl1 +which take a single parameter and insert or delete that many lines can +be given as +.B il +and +.BR dl . +.PP +If the terminal has a settable scrolling region (like the vt100) +the command to set this can be described with the +.B csr +capability, which takes two parameters: +the top and bottom lines of the scrolling region. +The cursor position is, alas, undefined after using this command. +.PP +It is possible to get the effect of insert or delete line using +.B csr +on a properly chosen region; the +.B sc +and +.B rc +(save and restore cursor) commands may be useful for ensuring that +your synthesized insert/delete string does not move the cursor. +(Note that the \fB\%ncurses\fP(3X) library does this synthesis +automatically, so you need not compose insert/delete strings for +an entry with \fBcsr\fP). +.PP +Yet another way to construct insert and delete might be to use a combination of +index with the memory-lock feature found on some terminals (like the HP-700/90 +series, which however also has insert/delete). +.PP +Inserting lines at the top or bottom of the screen can also be +done using +.B ri +or +.B ind +on many terminals without a true insert/delete line, +and is often faster even on terminals with those features. +.PP +The Boolean \fBnon_dest_scroll_region\fP should be set if each scrolling +window is effectively a view port on a screen-sized canvas. +To test for +this capability, create a scrolling region in the middle of the screen, +write something to the bottom line, move the cursor to the top of the region, +and do \fBri\fP followed by \fBdl1\fP or \fBind\fP. +If the data scrolled +off the bottom of the region by the \fBri\fP re-appears, then scrolling +is non-destructive. +System V and XSI Curses expect that \fBind\fP, \fBri\fP, +\fBindn\fP, and \fBrin\fP will simulate destructive scrolling; their +documentation cautions you not to define \fBcsr\fP unless this is true. +This \fBcurses\fP implementation is more liberal and will do explicit erases +after scrolling if \fBndsrc\fP is defined. +.PP +If the terminal has the ability to define a window as part of +memory, which all commands affect, +it should be given as the parameterized string +.BR wind . +The four parameters are the starting and ending lines in memory +and the starting and ending columns in memory, in that order. +.PP +If the terminal can retain display memory above, then the +\fBda\fP capability should be given; if display memory can be retained +below, then \fBdb\fP should be given. +These indicate +that deleting a line or scrolling may bring non-blank lines up from below +or that scrolling back with \fBri\fP may bring down non-blank lines. +.SS "Insert/Delete Character" +There are two basic kinds of intelligent terminals with respect to +insert/delete character which can be described using +.I terminfo. +The most common insert/delete character operations affect only the characters +on the current line and shift characters off the end of the line rigidly. +Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make +a distinction between typed and untyped blanks on the screen, shifting +upon an insert or delete only to an untyped blank on the screen which is +either eliminated, or expanded to two untyped blanks. +.PP +You can determine the +kind of terminal you have by clearing the screen and then typing +text separated by cursor motions. +Type \*(``abc\ \ \ \ def\*('' using local +cursor motions (not spaces) between the \*(``abc\*('' and the \*(``def\*(''. +Then position the cursor before the \*(``abc\*('' and put the terminal in insert +mode. +If typing characters causes the rest of the line to shift +rigidly and characters to fall off the end, then your terminal does +not distinguish between blanks and untyped positions. +If the \*(``abc\*('' +shifts over to the \*(``def\*('' which then move together around the end of the +current line and onto the next as you insert, you have the second type of +terminal, and should give the capability \fBin\fP, which stands for +\*(``insert null\*(''. +.PP +While these are two logically separate attributes (one line versus multi-line +insert mode, and special treatment of untyped spaces) we have seen no +terminals whose insert mode cannot be described with the single attribute. +.PP +Terminfo can describe both terminals which have an insert mode, and terminals +which send a simple sequence to open a blank position on the current line. +Give as \fBsmir\fP the sequence to get into insert mode. +Give as \fBrmir\fP the sequence to leave insert mode. +Now give as \fBich1\fP any sequence needed to be sent just before sending +the character to be inserted. +Most terminals with a true insert mode +will not give \fBich1\fP; terminals which send a sequence to open a screen +position should give it here. +.PP +If your terminal has both, insert mode is usually preferable to \fBich1\fP. +Technically, you should not give both unless the terminal actually requires +both to be used in combination. +Accordingly, some non-curses applications get +confused if both are present; the symptom is doubled characters in an update +using insert. +This requirement is now rare; most \fBich\fP sequences do not +require previous smir, and most smir insert modes do not require \fBich1\fP +before each character. +Therefore, the new \fBcurses\fP actually assumes this +is the case and uses either \fBrmir\fP/\fBsmir\fP or \fBich\fP/\fBich1\fP as +appropriate (but not both). +If you have to write an entry to be used under +new curses for a terminal old enough to need both, include the +\fBrmir\fP/\fBsmir\fP sequences in \fBich1\fP. +.PP +If post insert padding is needed, give this as a number of milliseconds +in \fBip\fP (a string option). +Any other sequence which may need to be +sent after an insert of a single character may also be given in \fBip\fP. +If your terminal needs both to be placed into an \*(``insert mode\*('' and +a special code to precede each inserted character, then both +.BR smir / rmir +and +.B ich1 +can be given, and both will be used. +The +.B ich +capability, with one parameter, +.IR n , +will repeat the effects of +.B ich1 +.I n +times. +.PP +If padding is necessary between characters typed while not +in insert mode, give this as a number of milliseconds padding in \fBrmp\fP. +.PP +It is occasionally necessary to move around while in insert mode +to delete characters on the same line (e.g., if there is a tab after +the insertion position). +If your terminal allows motion while in +insert mode you can give the capability \fBmir\fP to speed up inserting +in this case. +Omitting \fBmir\fP will affect only speed. +Some terminals +(notably Datamedia's) must not have \fBmir\fP because of the way their +insert mode works. +.PP +Finally, you can specify +.B dch1 +to delete a single character, +.B dch +with one parameter, +.IR n , +to delete +.I n characters, +and delete mode by giving \fBsmdc\fP and \fBrmdc\fP +to enter and exit delete mode (any mode the terminal needs to be placed +in for +.B dch1 +to work). +.PP +A command to erase +.I n +characters (equivalent to outputting +.I n +blanks without moving the cursor) +can be given as +.B ech +with one parameter. +.SS "Highlighting, Underlining, and Visible Bells" +If your terminal has one or more kinds of display attributes, +these can be represented in a number of different ways. +You should choose one display form as +\f2standout mode\fP, +representing a good, high contrast, easy-on-the-eyes, +format for highlighting error messages and other attention getters. +(If you have a choice, reverse video plus half-bright is good, +or reverse video alone.) +The sequences to enter and exit standout mode +are given as \fBsmso\fP and \fBrmso\fP, respectively. +If the code to change into or out of standout +mode leaves one or even two blank spaces on the screen, +as the TVI 912 and Teleray 1061 do, +then \fBxmc\fP should be given to tell how many spaces are left. +.PP +Codes to begin underlining and end underlining can be given as \fBsmul\fP +and \fBrmul\fP respectively. +If the terminal has a code to underline the current character and move +the cursor one space to the right, +such as the Microterm Mime, +this can be given as \fBuc\fP. +.PP +Other capabilities to enter various highlighting modes include +.B blink +(blinking) +.B bold +(bold or extra bright) +.B dim +(dim or half-bright) +.B invis +(blanking or invisible text) +.B prot +(protected) +.B rev +(reverse video) +.B sgr0 +(turn off +.I all +attribute modes) +.B smacs +(enter alternate character set mode) +and +.B rmacs +(exit alternate character set mode). +Turning on any of these modes singly may or may not turn off other modes. +.PP +If there is a sequence to set arbitrary combinations of modes, +this should be given as +.B sgr +(set attributes), +taking 9 parameters. +Each parameter is either zero (0) or nonzero, +as the corresponding attribute is on or off. +The 9 parameters are, in order: +standout, underline, reverse, blink, dim, bold, blank, protect, alternate +character set. +Not all modes need be supported by +.BR sgr , +only those for which corresponding separate attribute commands exist. +.PP +For example, the DEC vt220 supports most of the modes: +.PP +.TS +center; +lb lb lb +l l l . +tparm Parameter Attribute Escape Sequence +_ +none none \eE[0m +p1 standout \eE[0;1;7m +p2 underline \eE[0;4m +p3 reverse \eE[0;7m +p4 blink \eE[0;5m +p5 dim not available +p6 bold \eE[0;1m +p7 invis \eE[0;8m +p8 protect not used +p9 altcharset \*^O (off) \*^N (on) +.TE +.PP +We begin each escape sequence by turning off any existing modes, since +there is no quick way to determine whether they are active. +Standout is set up to be the combination of reverse and bold. +The vt220 terminal has a protect mode, +though it is not commonly used in sgr +because it protects characters on the screen from the host's erasures. +The altcharset mode also is different in that it is either \*^O or \*^N, +depending on whether it is off or on. +If all modes are turned on, the resulting sequence is \eE[0;1;4;5;7;8m\*^N. +.PP +Some sequences are common to different modes. +For example, ;7 is output when either p1 or p3 is true, that is, if +either standout or reverse modes are turned on. +.PP +Writing out the above sequences, along with their dependencies yields +.PP +.ne 11 +.TS +center; +lb lb lb +l l l . +Sequence When to Output terminfo Translation +_ +\eE[0 always \eE[0 +;1 if p1 or p6 %?%p1%p6%|%t;1%; +;4 if p2 %?%p2%|%t;4%; +;5 if p4 %?%p4%|%t;5%; +;7 if p1 or p3 %?%p1%p3%|%t;7%; +;8 if p7 %?%p7%|%t;8%; +m always m +\*^N or \*^O if p9 \*^N, else \*^O %?%p9%t\*^N%e\*^O%; +.TE +.PP +Putting this all together into the sgr sequence gives: +.PP +.EX + sgr=\eE[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%; + %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\e016%e\e017%;, +.EE +.PP +Remember that if you specify sgr, you must also specify sgr0. +Also, some implementations rely on sgr being given if sgr0 is, +Not all terminfo entries necessarily have an sgr string, however. +Many terminfo entries are derived from termcap entries +which have no sgr string. +The only drawback to adding an sgr string is that termcap also +assumes that sgr0 does not exit alternate character set mode. +.PP +Terminals with the \*(``magic cookie\*('' glitch +.RB ( xmc ) +deposit special \*(``cookies\*('' when they receive mode-setting sequences, +which affect the display algorithm rather than having extra bits for +each character. +Some terminals, such as the HP 2621, automatically leave standout +mode when they move to a new line or the cursor is addressed. +Programs using standout mode should exit standout mode before +moving the cursor or sending a newline, +unless the +.B msgr +capability, asserting that it is safe to move in standout mode, is present. +.PP +If the terminal has +a way of flashing the screen to indicate an error quietly (a bell replacement) +then this can be given as \fBflash\fP; it must not move the cursor. +.PP +If the cursor needs to be made more visible than normal when it is +not on the bottom line (to make, for example, a non-blinking underline into an +easier to find block or blinking underline) +give this sequence as +.BR cvvis . +If there is a way to make the cursor completely invisible, give that as +.BR civis . +The capability +.B cnorm +should be given which undoes the effects of both of these modes. +.PP +If your terminal correctly generates underlined characters +(with no special codes needed) +even though it does not overstrike, +then you should give the capability \fBul\fP. +If a character overstriking another leaves both characters on the screen, +specify the capability \fBos\fP. +If overstrikes are erasable with a blank, +then this should be indicated by giving \fBeo\fP. +.SS "Keypad and Function Keys" +If the terminal has a keypad that transmits codes when the keys are pressed, +this information can be given. +Note that it is not possible to handle +terminals where the keypad only works in local (this applies, for example, +to the unshifted HP 2621 keys). +If the keypad can be set to transmit or not transmit, +give these codes as \fBsmkx\fP and \fBrmkx\fP. +Otherwise the keypad is assumed to always transmit. +.PP +The codes sent by the left arrow, right arrow, up arrow, down arrow, +and home keys can be given as +\fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fP respectively. +If there are function keys such as f0, f1, ..., f10, the codes they send +can be given as \fBkf0, kf1, ..., kf10\fP. +If these keys have labels other than the default f0 through f10, the labels +can be given as \fBlf0, lf1, ..., lf10\fP. +.PP +The codes transmitted by certain other special keys can be given: +.bP +.B kll +(home down), +.bP +.B kbs +(backspace), +.bP +.B ktbc +(clear all tabs), +.bP +.B kctab +(clear the tab stop in this column), +.bP +.B kclr +(clear screen or erase key), +.bP +.B kdch1 +(delete character), +.bP +.B kdl1 +(delete line), +.bP +.B krmir +(exit insert mode), +.bP +.B kel +(clear to end of line), +.bP +.B ked +(clear to end of screen), +.bP +.B kich1 +(insert character or enter insert mode), +.bP +.B kil1 +(insert line), +.bP +.B knp +(next page), +.bP +.B kpp +(previous page), +.bP +.B kind +(scroll forward/down), +.bP +.B kri +(scroll backward/up), +.bP +.B khts +(set a tab stop in this column). +.PP +In addition, if the keypad has a 3 by 3 array of keys including the four +arrow keys, the other five keys can be given as +.BR ka1 , +.BR ka3 , +.BR kb2 , +.BR kc1 , +and +.BR kc3 . +These keys are useful when the effects of a 3 by 3 directional pad are needed. +.PP +Strings to program function keys can be given as +.BR pfkey , +.BR pfloc , +and +.BR pfx . +A string to program screen labels should be specified as \fBpln\fP. +Each of these strings takes two parameters: the function key number to +program (from 0 to 10) and the string to program it with. +Function key numbers out of this range may program undefined keys in +a terminal dependent manner. +The difference between the capabilities is that +.B pfkey +causes pressing the given key to be the same as the user typing the +given string; +.B pfloc +causes the string to be executed by the terminal in local; and +.B pfx +causes the string to be transmitted to the computer. +.PP +The capabilities \fBnlab\fP, \fBlw\fP and \fBlh\fP +define the number of programmable +screen labels and their width and height. +If there are commands to turn the labels on and off, +give them in \fBsmln\fP and \fBrmln\fP. +\fBsmln\fP is normally output after one or more pln +sequences to make sure that the change becomes visible. +.SS "Tabs and Initialization" +A few capabilities are used only for tabs: +.bP +If the terminal has hardware tabs, the command to advance to the next +tab stop can be given as +.B ht +(usually control/I). +.bP +A \*(``back-tab\*('' command which moves leftward to the preceding tab stop can +be given as +.BR cbt . +.IP +By convention, if the teletype modes indicate that tabs are being +expanded by the computer rather than being sent to the terminal, +programs should not use +.B ht +or +.B cbt +even if they are present, since the user may not have the tab stops +properly set. +.bP +If the terminal has hardware tabs which are initially set every +.I n +spaces when the terminal is powered up, +the numeric parameter +.B it +is given, showing the number of spaces the tabs are set to. +.IP +The \fBit\fP capability is normally used by the \fBtset\fP +command to determine whether to set the mode for hardware tab expansion, +and whether to set the tab stops. +If the terminal has tab stops that can be saved in non-volatile memory, +the terminfo description can assume that they are properly set. +.PP +Other capabilities +include +.bP +.BR is1 , +.BR is2 , +and +.BR is3 , +initialization strings for the terminal, +.bP +.BR iprog , +the path name of a program to be run to initialize the terminal, +.bP +and \fBif\fP, the name of a file containing long initialization strings. +.PP +These strings are expected to set the terminal into modes consistent +with the rest of the terminfo description. +They are normally sent to the terminal, by the +.I init +option of the \fBtput\fP program, each time the user logs in. +They will be printed in the following order: +.RS +.TP +run the program +.B iprog +.TP +output +.br +\fBis1\fP and +.br +\fBis2\fP +.TP +set the margins using +\fBmgc\fP or +.br +\fBsmglp\fP and \fBsmgrp\fP or +.br +\fBsmgl\fP and \fBsmgr\fP +.TP +set tabs using +.B tbc +and +.B hts +.TP +print the file +\fBif\fP +.TP +and finally output +\fBis3\fP. +.RE +.PP +Most initialization is done with +.BR is2 . +Special terminal modes can be set up without duplicating strings +by putting the common sequences in +.B is2 +and special cases in +.B is1 +and +.BR is3 . +.PP +A set of sequences that does a harder reset from a totally unknown state +can be given as +.BR rs1 , +.BR rs2 , +.B rf +and +.BR rs3 , +analogous to +.B is1 , +.B is2 , +.B if +and +.B is3 +respectively. +These strings are output +by \fIreset\fP option of \fBtput\fP, +or by the \fBreset\fP program +(an alias of \fBtset\fP), +which is used when the terminal gets into a wedged state. +Commands are normally placed in +.BR rs1 , +.B rs2 +.B rs3 +and +.B rf +only if they produce annoying effects on the screen and are not +necessary when logging in. +For example, the command to set the vt100 into 80-column mode would +normally be part of +.BR is2 , +but it causes an annoying glitch of the screen and is not normally +needed since the terminal is usually already in 80-column mode. +.PP +The \fBreset\fP program writes strings including +.BR iprog , +etc., in the same order as the +.I init +program, using +.BR rs1 , +etc., instead of +.BR is1 , +etc. +If any of +.BR rs1 , +.BR rs2 , +.BR rs3 , +or +.B rf +reset capability strings are missing, +the \fBreset\fP program +falls back upon the corresponding initialization capability string. +.PP +If there are commands to set and clear tab stops, they can be given as +.B tbc +(clear all tab stops) +and +.B hts +(set a tab stop in the current column of every row). +If a more complex sequence is needed to set the tabs than can be +described by this, the sequence can be placed in +.B is2 +or +.BR if . +.PP +The \fBtput reset\fP command uses the same capability strings +as the \fBreset\fP command, +although the two programs (\fBtput\fP and \fBreset\fP) +provide different command-line options. +.PP +In practice, these terminfo capabilities are not often used in +initialization of tabs +(though they are required for the \fBtabs\fP program): +.bP +Almost all hardware terminals (at least those which supported tabs) +initialized those to every \fIeight\fP columns: +.IP +The only exception was the AT&T 2300 series, +which set tabs to every \fIfive\fP columns. +.bP +In particular, developers of the hardware terminals which are commonly used +as models for modern terminal emulators provided documentation demonstrating +that \fIeight\fP columns were the standard. +.bP +Because of this, the terminal initialization programs +\fBtput\fP and \fBtset\fP +use the +\fBtbc\fP (\fBclear_all_tabs\fP) and +\fBhts\fP (\fBset_tab\fP) capabilities directly +only when the \fBit\fP (\fBinit_tabs\fP) capability +is set to a value other than \fIeight\fP. +.SS "Delays and Padding" +Many older and slower terminals do not support either XON/XOFF or DTR +handshaking, including hard copy terminals and some very archaic CRTs +(including, for example, DEC VT100s). +These may require padding characters +after certain cursor motions and screen changes. +.PP +If the terminal uses xon/xoff handshaking for flow control (that is, +it automatically emits \*^S back to the host when its input buffers are +close to full), set +.BR xon . +This capability suppresses the emission of padding. +You can also set it +for memory-mapped console devices effectively that do not have a speed limit. +Padding information should still be included so that routines can +make better decisions about relative costs, but actual pad characters will +not be transmitted. +.PP +If \fBpb\fP (padding baud rate) is given, padding is suppressed at baud rates +below the value of \fBpb\fP. +If the entry has no padding baud rate, then +whether padding is emitted or not is completely controlled by \fBxon\fP. +.PP +If the terminal requires other than a null (zero) character as a pad, +then this can be given as \fBpad\fP. +Only the first character of the +.B pad +string is used. +.SS "Status Lines" +Some terminals have an extra \*(``status line\*('' which is not normally used by +software (and thus not counted in the terminal's \fBlines\fP capability). +.PP +The simplest case is a status line which is cursor-addressable but not +part of the main scrolling region on the screen; the Heathkit H19 has +a status line of this kind, as would a 24-line VT100 with a 23-line +scrolling region set up on initialization. +This situation is indicated +by the \fBhs\fP capability. +.PP +Some terminals with status lines need special sequences to access the +status line. +These may be expressed as a string with single parameter +\fBtsl\fP which takes the cursor to a given zero-origin column on the +status line. +The capability \fBfsl\fP must return to the main-screen +cursor positions before the last \fBtsl\fP. +You may need to embed the +string values of \fBsc\fP (save cursor) and \fBrc\fP (restore cursor) +in \fBtsl\fP and \fBfsl\fP to accomplish this. +.PP +The status line is normally assumed to be the same width as the width +of the terminal. +If this is untrue, you can specify it with the numeric +capability \fBwsl\fP. +.PP +A command to erase or blank the status line may be specified as \fBdsl\fP. +.PP +The Boolean capability \fBeslok\fP specifies that escape sequences, tabs, +etc., work ordinarily in the status line. +.PP +The \fI\%ncurses\fP implementation does not yet use any of these +capabilities. +They are documented here in case they ever become important. +.SS "Line Graphics" +Many terminals have alternate character sets useful for forms-drawing. +Terminfo and \fBcurses\fP have built-in support +for most of the drawing characters +supported by the VT100, with some characters from the AT&T 4410v1 added. +This alternate character set may be specified by the \fBacsc\fP capability. +.PP +.TS +center; +Lb Cb S L Lb +Lb2 Lb2 Lb Lb1 S +Lb L C Lb Lx. +\& acsc \& \& +ACS Name Value Symbol ASCII Fallback / Glyph Name +_ +ACS_RARROW 0x2b + > arrow pointing right +ACS_LARROW 0x2c , < arrow pointing left +ACS_UARROW 0x2d \- \*^ arrow pointing up +ACS_DARROW 0x2e . v arrow pointing down +ACS_BLOCK 0x30 0 # solid square block +ACS_DIAMOND 0x60 \(ga + diamond +ACS_CKBOARD 0x61 a : checker board (stipple) +ACS_DEGREE 0x66 f \e degree symbol +ACS_PLMINUS 0x67 g # plus/minus +ACS_BOARD 0x68 h # board of squares +ACS_LANTERN 0x69 i # lantern symbol +ACS_LRCORNER 0x6a j + lower right corner +ACS_URCORNER 0x6b k + upper right corner +ACS_ULCORNER 0x6c l + upper left corner +ACS_LLCORNER 0x6d m + lower left corner +ACS_PLUS 0x6e n + large plus or crossover +ACS_S1 0x6f o \*~ scan line 1 +ACS_S3 0x70 p \- scan line 3 +ACS_HLINE 0x71 q \- horizontal line +ACS_S7 0x72 r \- scan line 7 +ACS_S9 0x73 s \&_ scan line 9 +ACS_LTEE 0x74 t + tee pointing right +ACS_RTEE 0x75 u + tee pointing left +ACS_BTEE 0x76 v + tee pointing up +ACS_TTEE 0x77 w + tee pointing down +ACS_VLINE 0x78 x | vertical line +ACS_LEQUAL 0x79 y < less-than-or-equal-to +ACS_GEQUAL 0x7a z > greater-than-or-equal-to +ACS_PI 0x7b { * greek pi +ACS_NEQUAL 0x7c | ! not-equal +ACS_STERLING 0x7d } f UK pound sign +ACS_BULLET 0x7e \*~ o bullet +.TE +.PP +A few notes apply to the table itself: +.bP +X/Open Curses incorrectly states that the mapping for \fIlantern\fP is +uppercase \*(``I\*('' although Unix implementations use the +lowercase \*(``i\*('' mapping. +.bP +The DEC VT100 implemented graphics using the alternate character set +feature, temporarily switching \fImodes\fP and sending characters +in the range 0x60 (96) to 0x7e (126) +(the \fBacsc Value\fP column in the table). +.bP +The AT&T terminal added graphics characters outside that range. +.IP +Some of the characters within the range do not match the VT100; +presumably they were used in the AT&T terminal: +\fIboard of squares\fP replaces the VT100 \fInewline\fP symbol, while +\fIlantern symbol\fP replaces the VT100 \fIvertical tab\fP symbol. +The other VT100 symbols for control characters (\fIhorizontal tab\fP, +\fIcarriage return\fP and \fIline-feed\fP) are not (re)used in curses. +.PP +The best way to define a new device's graphics set is to add a column +to a copy of this table for your terminal, giving the character which +(when emitted between \fBsmacs\fP/\fBrmacs\fP switches) will be rendered +as the corresponding graphic. +Then read off the VT100/your terminal +character pairs right to left in sequence; these become the ACSC string. +.SS "Color Handling" +The curses library functions \fBinit_pair\fP and \fBinit_color\fP +manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this +section +(see \fBcurs_color\fP(3X) for details on these and related functions). +.PP +Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*('': +.bP +Tektronix-like +terminals have a predefined set of \fIN\fP colors +(where \fIN\fP is usually 8), +and can set +character-cell foreground and background characters independently, mixing them +into \fIN\fP\ *\ \fIN\fP color pairs. +.bP +On HP-like terminals, the user must set each color +pair up separately (foreground and background are not independently settable). +Up to \fIM\fP color pairs may be set up from 2*\fIM\fP different colors. +ANSI-compatible terminals are Tektronix-like. +.PP +Some basic color capabilities are independent of the color method. +The numeric +capabilities \fBcolors\fP and \fBpairs\fP specify the maximum numbers of colors +and color pairs that can be displayed simultaneously. +The \fBop\fP (original +pair) string resets foreground and background colors to their default values +for the terminal. +The \fBoc\fP string resets all colors or color pairs to +their default values for the terminal. +Some terminals (including many PC +terminal emulators) erase screen areas with the current background color rather +than the power-up default background; these should have the Boolean capability +\fBbce\fP. +.PP +While the curses library works with \fIcolor pairs\fP +(reflecting the inability of some devices to set foreground +and background colors independently), +there are separate capabilities for setting these features: +.bP +To change the current foreground or background color on a Tektronix-type +terminal, use \fBsetaf\fP (set ANSI foreground) and \fBsetab\fP (set ANSI +background) or \fBsetf\fP (set foreground) and \fBsetb\fP (set background). +These take one parameter, the color number. +The SVr4 documentation describes +only \fBsetaf\fP/\fBsetab\fP; the XPG4 draft says that "If the terminal +supports ANSI escape sequences to set background and foreground, they should +be coded as \fBsetaf\fP and \fBsetab\fP, respectively. +.bP +If the terminal +supports other escape sequences to set background and foreground, they should +be coded as \fBsetf\fP and \fBsetb\fP, respectively. +The \fBvidputs\fP and the \fBrefresh\fP(3X) functions +use the \fBsetaf\fP and \fBsetab\fP capabilities if they are defined. +.PP +The \fBsetaf\fP/\fBsetab\fP and \fBsetf\fP/\fBsetb\fP capabilities take a +single numeric argument each. +Argument values 0-7 of \fBsetaf\fP/\fBsetab\fP are portably defined as +follows (the middle column is the symbolic #define available in the header for +the \fBcurses\fP or \fI\%ncurses\fP libraries). +The terminal hardware is free to +map these as it likes, but the RGB values indicate normal locations in color +space. +.PP +.TS +center; +cb cb cb cb s s +l lb c l1 l1 l . +Color #define Value RGB +_ +black COLOR_BLACK 0 0, 0, 0 +red COLOR_RED 1 max, 0, 0 +green COLOR_GREEN 2 0, max, 0 +yellow COLOR_YELLOW 3 max, max, 0 +blue COLOR_BLUE 4 0, 0, max +magenta COLOR_MAGENTA 5 max, 0, max +cyan COLOR_CYAN 6 0, max, max +white COLOR_WHITE 7 max, max, max +.TE +.PP +The argument values of \fBsetf\fP/\fBsetb\fP historically correspond to +a different mapping, i.e., +.PP +.TS +center; +cb cb cb cb s s +l lb c l1 l1 l . +Color #define Value RGB +_ +black COLOR_BLACK 0 0, 0, 0 +blue COLOR_BLUE 1 0, 0, max +green COLOR_GREEN 2 0, max, 0 +cyan COLOR_CYAN 3 0, max, max +red COLOR_RED 4 max, 0, 0 +magenta COLOR_MAGENTA 5 max, 0, max +yellow COLOR_YELLOW 6 max, max, 0 +white COLOR_WHITE 7 max, max, max +.TE +.PP +It is important to not confuse the two sets of color capabilities; +otherwise red/blue will be interchanged on the display. +.PP +On an HP-like terminal, use \fBscp\fP with a color pair number parameter to set +which color pair is current. +.PP +Some terminals allow the \fIcolor values\fP to be modified: +.bP +On a Tektronix-like terminal, the capability \fBccc\fP may be present to +indicate that colors can be modified. +If so, the \fBinitc\fP capability will +take a color number (0 to \fBcolors\fP \- 1)and three more parameters which +describe the color. +These three parameters default to being interpreted as RGB +(Red, Green, Blue) values. +If the Boolean capability \fBhls\fP is present, +they are instead as HLS (Hue, Lightness, Saturation) indices. +The ranges are +terminal-dependent. +.bP +On an HP-like terminal, \fBinitp\fP may give a capability for changing a +color pair value. +It will take seven parameters; a color pair number (0 to +\fBmax_pairs\fP \- 1), and two triples describing first background and then +foreground colors. +These parameters must be (Red, Green, Blue) or +(Hue, Lightness, Saturation) depending on \fBhls\fP. +.PP +On some color terminals, colors collide with highlights. +You can register +these collisions with the \fBncv\fP capability. +This is a bit mask of +attributes not to be used when colors are enabled. +The correspondence with the +attributes understood by \fBcurses\fP is as follows: +.PP +.TS +center; +cb cb cb cb +lb n n lb. +Attribute Bit Decimal Set by +_ +A_STANDOUT 0 1 sgr +A_UNDERLINE 1 2 sgr +A_REVERSE 2 4 sgr +A_BLINK 3 8 sgr +A_DIM 4 16 sgr +A_BOLD 5 32 sgr +A_INVIS 6 64 sgr +A_PROTECT 7 128 sgr +A_ALTCHARSET 8 256 sgr +A_HORIZONTAL 9 512 sgr1 +A_LEFT 10 1024 sgr1 +A_LOW 11 2048 sgr1 +A_RIGHT 12 4096 sgr1 +A_TOP 13 8192 sgr1 +A_VERTICAL 14 16384 sgr1 +A_ITALIC 15 32768 sitm +.TE +.PP +For example, on many IBM PC consoles, the underline attribute collides with the +foreground color blue and is not available in color mode. +These should have +an \fBncv\fP capability of 2. +.PP +SVr4 curses does nothing with \fBncv\fP, +\fI\%ncurses\fP recognizes it and optimizes +the output in favor of colors. +.SS Miscellaneous +If the terminal requires other than a null (zero) character as a pad, then this +can be given as pad. +Only the first character of the pad string is used. +If the terminal does not have a pad character, specify npc. +Note that \fI\%ncurses\fP implements the termcap-compatible \fBPC\fP +variable; +though the application may set this value to something other than +a null, +\fI\%ncurses\fP will test \fBnpc\fP first and use napms if the terminal +has no pad character. +.PP +If the terminal can move up or down half a line, +this can be indicated with +.B hu +(half-line up) +and +.B hd +(half-line down). +This is primarily useful for superscripts and subscripts on hard-copy terminals. +If a hard-copy terminal can eject to the next page (form feed), give this as +.B ff +(usually control/L). +.PP +If there is a command to repeat a given character a given number of +times (to save time transmitting a large number of identical characters) +this can be indicated with the parameterized string +.BR rep . +The first parameter is the character to be repeated and the second +is the number of times to repeat it. +Thus, tparm(repeat_char, \*'x\*', 10) is the same as \*(``xxxxxxxxxx\*(''. +.PP +If the terminal has a settable command character, +such as the \s-1TEKTRONIX\s+1 4025, +this can be indicated with +.BR cmdch . +A prototype command character is chosen which is used in all capabilities. +This character is given in the +.B cmdch +capability to identify it. +The following convention is supported on some Unix systems: +The environment is to be searched for a +.B CC +variable, and if found, all +occurrences of the prototype character are replaced with the character +in the environment variable. +.PP +Terminal descriptions that do not represent a specific kind of known +terminal, such as +.IR switch , +.IR dialup , +.IR patch , +and +.IR network , +should include the +.B gn +(generic) capability so that programs can complain that they do not know +how to talk to the terminal. +(This capability does not apply to +.I virtual +terminal descriptions for which the escape sequences are known.) +.PP +If the terminal has a \*(``meta key\*('' which acts as a shift key, +setting the 8th bit of any character transmitted, this fact can +be indicated with +.BR km . +Otherwise, software will assume that the 8th bit is parity and it +will usually be cleared. +If strings exist to turn this \*(``meta mode\*('' on and off, they +can be given as +.B smm +and +.BR rmm . +.PP +If the terminal has more lines of memory than will fit on the screen +at once, the number of lines of memory can be indicated with +.BR lm . +A value of +.BR lm #0 +indicates that the number of lines is not fixed, +but that there is still more memory than fits on the screen. +.PP +If the terminal is one of those supported by the Unix virtual +terminal protocol, the terminal number can be given as +.BR vt . +.PP +Media copy +strings which control an auxiliary printer connected to the terminal +can be given as +.BR mc0 : +print the contents of the screen, +.BR mc4 : +turn off the printer, and +.BR mc5 : +turn on the printer. +When the printer is on, all text sent to the terminal will be sent +to the printer. +It is undefined whether the text is also displayed on the terminal screen +when the printer is on. +A variation +.B mc5p +takes one parameter, and leaves the printer on for as many characters +as the value of the parameter, then turns the printer off. +The parameter should not exceed 255. +All text, including +.BR mc4 , +is transparently passed to the printer while an +.B mc5p +is in effect. +.SS "Glitches and Brain Damage" +Hazeltine terminals, +which do not allow \*(``\*~\*('' characters to be displayed should +indicate \fBhz\fP. +.PP +Terminals which ignore a line-feed immediately after an \fBam\fP wrap, +such as the Concept and vt100, +should indicate \fBxenl\fP. +.PP +If +.B el +is required to get rid of standout +(instead of merely writing normal text on top of it), +\fBxhp\fP should be given. +.PP +Teleray terminals, where tabs turn all characters moved over to blanks, +should indicate \fBxt\fP (destructive tabs). +Note: the variable indicating this is now \*(``dest_tabs_magic_smso\*(''; in +older versions, it was teleray_glitch. +This glitch is also taken to mean that it is not possible to position +the cursor on top of a \*(``magic cookie\*('', +that to erase standout mode it is instead necessary to use +delete and insert line. +The \fI\%ncurses\fP implementation ignores this glitch. +.PP +The Beehive Superbee, which is unable to correctly transmit the escape +or control/C characters, has +.BR xsb , +indicating that the f1 key is used for escape and f2 for control/C. +(Only certain Superbees have this problem, depending on the ROM.) +Note that in older terminfo versions, this capability was called +\*(``beehive_glitch\*(''; it is now \*(``no_esc_ctl_c\*(''. +.PP +Other specific terminal problems may be corrected by adding more +capabilities of the form \fBx\fIx\fR. +.SS "Pitfalls of Long Entries" +Long terminfo entries are unlikely to be a problem; to date, no entry has even +approached terminfo's 4096-byte string-table maximum. +Unfortunately, the termcap +translations are much more strictly limited (to 1023 bytes), +thus termcap translations of long terminfo entries can cause problems. +.PP +The man pages for 4.3BSD +and older versions of \fBtgetent\fP instruct the user to +allocate a 1024-byte buffer for the termcap entry. +The entry gets null-terminated by +the termcap library, so that makes the maximum safe length for a termcap entry +1k\-1 (1023) bytes. +Depending on what the application and the termcap library being used does, +and where in the termcap file the terminal type that \fBtgetent\fP +is searching for is, several bad things can happen: +.bP +some termcap libraries print a warning message, +.bP +some exit if they find an entry that's longer than 1023 bytes, +.bP +some neither exit nor warn, doing nothing useful, and +.bP +some simply truncate the entries to 1023 bytes. +.PP +Some application programs allocate more than +the recommended 1K for the termcap entry; others do not. +.PP +Each termcap entry has two important sizes associated with it: before +\*(``tc\*('' expansion, and after \*(``tc\*('' expansion. +\*(``tc\*('' is the capability that +tacks on another termcap entry to the end of the current one, to add +on its capabilities. +If a termcap entry does not use the \*(``tc\*('' +capability, then of course the two lengths are the same. +.PP +The \*(``before tc expansion\*('' length is the most important one, because it +affects more than just users of that particular terminal. +This is the +length of the entry as it exists in /etc/termcap, minus the +backslash-newline pairs, which \fBtgetent\fP strips out while reading it. +Some termcap libraries strip off the final newline, too (GNU termcap does not). +Now suppose: +.bP +a termcap entry before expansion is more than 1023 bytes long, +.bP +and the application has only allocated a 1k buffer, +.bP +and the termcap library (like the one in BSD/OS 1.1 and GNU) reads +the whole entry into the buffer, no matter what its length, to see +if it is the entry it wants, +.bP +and \fBtgetent\fP is searching for a terminal type that either is the +long entry, appears in the termcap file after the long entry, or +does not appear in the file at all (so that \fBtgetent\fP has to search +the whole termcap file). +.PP +Then \fBtgetent\fP will overwrite memory, +perhaps its stack, +and probably core dump the program. +Programs like telnet are particularly vulnerable; modern telnets +pass along values like the terminal type automatically. +The results are almost +as undesirable with a termcap library, like SunOS 4.1.3 and Ultrix 4.4, that +prints warning messages when it reads an overly long termcap entry. +If a +termcap library truncates long entries, like OSF/1 3.0, it is immune to dying +here but will return incorrect data for the terminal. +.PP +The \*(``after tc expansion\*('' length will have a similar effect to the +above, but only for people who actually set \fITERM\fP to that terminal +type, since \fBtgetent\fP only does \*(``tc\*('' expansion once it is found the +terminal type it was looking for, not while searching. +.PP +In summary, a termcap entry that is longer than 1023 bytes can cause, +on various combinations of termcap libraries and applications, a core +dump, warnings, or incorrect operation. +If it is too long even before +\*(``tc\*('' expansion, it will have this effect even for users of some other +terminal types and users whose \fITERM\fP variable does not have a termcap +entry. +.PP +When in \-C (translate to termcap) mode, +the \fI\%ncurses\fP implementation of +\fBtic\fP(1M) issues warning messages when the pre-tc length of a termcap +translation is too long. +The \-c (check) option also checks resolved (after tc +expansion) lengths. +.SH FILES +.TP +.I \*d +compiled terminal description database directory +.SH EXTENSIONS +Searching for terminal descriptions in +\fI$HOME/.terminfo\fP and \fI\%TERMINFO_DIRS\fP +is not supported by older implementations. +.PP +Some SVr4 \fBcurses\fP implementations, and all previous to SVr4, do not +interpret the %A and %O operators in parameter strings. +.PP +SVr4/XPG4 do not specify whether \fBmsgr\fP licenses movement while in +an alternate-character-set mode (such modes may, among other things, map +CR and NL to characters that do not trigger local motions). +The \fI\%ncurses\fP implementation ignores \fBmsgr\fP in +\fBALTCHARSET\fP mode. +This raises the possibility that an XPG4 +implementation making the opposite interpretation may need terminfo +entries made for \fI\%ncurses\fP to have \fBmsgr\fP turned off. +.PP +The \fI\%ncurses\fP library handles insert-character and +insert-character modes in a slightly non-standard way to get better +update efficiency. +See +the \fBInsert/Delete Character\fP subsection above. +.PP +The parameter substitutions for \fBset_clock\fP and \fBdisplay_clock\fP are +not documented in SVr4 or the XSI Curses standard. +They are deduced from the +documentation for the AT&T 505 terminal. +.PP +Be careful assigning the \fBkmous\fP capability. +The \fI\%ncurses\fP library wants to interpret it as \fBKEY_MOUSE\fP, +for use by terminals and emulators like xterm +that can return mouse-tracking information in the keyboard-input stream. +.PP +X/Open Curses does not mention italics. +Portable applications must assume that numeric capabilities are +signed 16-bit values. +This includes the \fIno_color_video\fP (\fBncv\fP) capability. +The 32768 mask value used for italics with \fBncv\fP can be confused with +an absent or cancelled \fBncv\fP. +If italics should work with colors, +then the \fBncv\fP value must be specified, even if it is zero. +.PP +Different commercial ports of \fI\%terminfo\fP and \fIcurses\fP support +different subsets of XSI Curses and +(in some cases) +different extensions. +Here is a summary, +accurate as of October 1995, +after which the commercial Unix market contracted and lost diversity. +.bP +SVr4, +Solaris, +and \fI\%ncurses\fP support all SVr4 capabilities. +.bP +IRIX supports the SVr4 set and adds one undocumented extended string +capability (\fB\%set_pglen\fP). +.bP +SVr1 and Ultrix support a restricted subset of \fI\%terminfo\fP +capabilities. +The Booleans end with \fB\%xon_xoff\fP; +the numerics with \fB\%width_status_line\fP; +and the strings with \fB\%prtr_non\fP. +.bP +HP/UX supports the SVr1 subset, +plus the SVr[234] numerics +\fB\%num_labels\fP, +\fB\%label_height\fP, +\fB\%label_width\fP, +plus function keys 11 through 63, +plus +\fB\%plab_norm\fP, +\fB\%label_on\fP, +and +\fB\%label_off\fP, +plus a number of incompatible string table extensions. +.bP +AIX supports the SVr1 subset, +plus function keys 11 through 63, +plus a number of incompatible string table extensions. +.bP +OSF/1 supports both the SVr4 set and the AIX extensions. +.SH PORTABILITY +Do not count on compiled (binary) \fI\%terminfo\fP entries being +portable between commercial Unix systems. +At least two implementations of \fI\%terminfo\fP +(those of HP-UX and AIX) +diverged from those of other System V Unices after SVr1, +adding extension capabilities to the string table that +(in the binary format) +collide with subsequent System V and XSI Curses extensions. +.SH AUTHORS +Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. +Based on \fIpcurses\fP by Pavel Curtis. +.SH SEE ALSO +\fB\%infocmp\fP(1M), +\fB\%tabs\fP(1), +\fB\%tic\fP(1M), +\fB\%curses\fP(3X), +\fB\%curs_color\fP(3X), +\fB\%curs_terminfo\fP(3X), +\fB\%curs_variables\fP(3X), +\fB\%printf\fP(3), +\fB\%term_variables\fP(3X), +\fB\%term\fP(5), +\fB\%user_caps\fP(5) diff --git a/upstream/fedora-40/man5/texinfo.5 b/upstream/fedora-40/man5/texinfo.5 new file mode 100644 index 00000000..abf845ee --- /dev/null +++ b/upstream/fedora-40/man5/texinfo.5 @@ -0,0 +1,50 @@ +.\" texinfo(5) +.\" +.\" Copyright 1998-2019 Free Software Foundation, Inc. +.\" +.\" Copying and distribution of this file, with or without modification, +.\" are permitted in any medium without royalty provided the copyright +.\" notice and this notice are preserved. +.\" +.de EX +.nf +.ft CW +.in +5 +.. +.de EE +.in -5 +.ft R +.fi +.. +.TH TEXINFO 5 "GNU Texinfo" "FSF" +.SH NAME +texinfo \- software documentation system +.SH DESCRIPTION +Texinfo is a documentation system that uses a single source file to +produce both online information and printed output. It is primarily +designed for writing software manuals. +.PP +For a full description of the Texinfo language and associated tools, +please see the Texinfo manual (written in Texinfo itself). Most likely, +running this command from your shell: +.EX +info texinfo +.EE +or this key sequence from inside Emacs: +.EX +M-x info RET m texinfo RET +.EE +will get you there. +.SH AVAILABILITY +http://www.gnu.org/software/texinfo/ +.br +or any GNU mirror site. +.SH "REPORTING BUGS" +Please send bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +\fBinfo\fR(1), \fBinstall-info\fR(1), \fBmakeinfo\fR(1), \fBtexi2dvi\fR(1), \fBtexindex\fR(1). +.br +\fBemacs\fR(1), \fBtex\fR(1). +.br +\fBinfo\fR(5). diff --git a/upstream/fedora-40/man5/thinkfan.conf.5 b/upstream/fedora-40/man5/thinkfan.conf.5 new file mode 100644 index 00000000..08a8a5d7 --- /dev/null +++ b/upstream/fedora-40/man5/thinkfan.conf.5 @@ -0,0 +1,420 @@ +.TH THINKFAN.CONF 5 "December 2021" "thinkfan 1.3.1" +.SH NAME +thinkfan.conf \- YAML-formatted config for +.BR thinkfan (1) + + + +.SH DESCRIPTION + +YAML is a very powerful, yet concise notation for structured data. +Its full specification is available at https://yaml.org/spec/1.2/spec.html. +Thinkfan uses only a small subset of the full YAML syntax, so it may be helpful, +but not strictly necessary for users to take a look at the spec. + +The most important thing to note is that indentation is syntactically relevant. +In particular, tabs should not be mixed with spaces. +We recommend using two spaces for indentation, like it is shown below. + +The thinkfan config has three main sections: + +.TP 11m +.B sensors: +Where temperatures should be read from. All +.BR hwmon -style +drivers are supported, as well as +.BR /proc/acpi/ibm/thermal , +and, depending on the compile-time options, +.B libatasmart +(to read temperatures directly from hard disks) and +.B NVML +(via the proprietary nvidia driver). + +.TP +.B fans: +Which fans should be used (currently only one allowed). +Support for multiple fans is currently in development and planned for a future +release. +Both +.BR hwmon -style +PWM controls and +.B /proc/acpi/ibm/fan +can be used. + +.TP +.B levels: +Maps temperatures to fan speeds. +A \*(lqsimple mapping\*(rq just specifies one temperature as the lower and +upper bound (respectively) for a given fan speed. +In a \*(lqdetailed mapping\*(rq, the upper and lower bounds are specified for +each driver/sensor configured under +.BR sensors: . +This mode should be used when thinkfan is monitoring multiple devices that can +tolerate different amounts of heat. + +.PP +Under each of these sections, there must be a list of key-value maps, each of +which configures a sensor driver, fan driver or fan speed mapping. + + + +.SH SENSOR & FAN DRIVERS + +For thinkfan to work, it first needs to know which temperature sensor drivers +and which fan drivers it should use. +The mapping between temperature readings and fan speeds is specified in a +separate config section (see the +.B FAN SPEEDS +section below). + + +.SS Sensor Syntax + +The entries under the +.B sensors: +section can specify +.BR hwmon, +.BR thinkpad_acpi, +.BR NVML +or +.BR atasmart +drivers, where the latter two must be enabled at compile-time. +There can be any number (greater than zero) and combination of +.BR hwmon , +.BR tpacpi , +.BR nvml +and +.BR atasmart +entries. +However there may be at most one instance of the +.BR tpacpi +entry. + +.nf +.B "sensors:" +.BI " \- hwmon: " hwmon-path +.BI " name: " hwmon-name +.BI " indices: " index-list +.BI " correction: " correction-list +.BI " optional: " bool-allow-errors + +.B " \- tpacpi: /proc/acpi/ibm/thermal" +.BI " indices: " index-list +.BI " correction: " correction-list +.BI " optional: " bool-allow-errors + +.BI " \- nvml: " nvml-bus-id +.BI " correction: " correction-list +.BI " optional: " bool-allow-errors + +.BI " \- atasmart: " disk-device-file +.BI " correction: " correction-list +.BI " optional: " bool-allow-errors + +.BR " \- " ... +.fi + + +.SS Fan Syntax + +Currently, thinkfan supports only one fan, so there can be only one entry in the +list. +Support for multiple fans is currently in development and planned for a future +release. +The fan is either an +.B hwmon +fan: + +.nf +.B "fans:" +.BI " \- hwmon: " hwmon-path +.BI " name: " hwmon-name +.BI " indices: " index-list +.fi + +or a +.B tpacpi +fan: + +.nf +.B "fans:" +.B " \- tpacpi: /proc/acpi/ibm/fan" +.fi + + +.SS Values + +.TP 12m +.I hwmon-path +There are three ways of specifying hwmon fans or sensors: + +.TP +\h'8m'1) +A full path of a \*(lqtemp*_input\*(rq or \*(lqpwm*\*(rq file, like +\*(lq/sys/class/hwmon/hwmon0/pwm1\*(rq or +\*(lq/sys/class/hwmon/hwmon0/temp1_input\*(rq. +In this case, the \*(lq\c +.BI indices: " index-list"\c +\*(rq and \*(lq\c +.BI name: " hwmon-name"\c +\*(rq entries are unnecessary since the path uniquely identifies a specific fan or +sensor. + +Note that this method may lead to problems when the load order of the drivers +changes across bootups, because in the \*(lqhwmon\fIX\fR\*(rq folder name, the +.I X +actually corresponds to the load order. +Use method 2) or 3) to avoid this problem. + +.TP +\h'8m'2) +A directory that contains a specific hwmon driver, for example +\*(lq/sys/devices/platform/nct6775.2592\*(rq. +Note that this path does not contain the load-order dependent +\*(lqhwmon\fIX\fR\*(rq folder. +As long as it contains only a single hwmon driver/interface it is sufficient to +specify the +\*(lq\c +.BI indices: " index-list"\c +\*(rq +entry to tell thinkfan which specific sensors to use from that interface. +The +\*(lq\c +.BI name: " hwmon-name"\c +\*(rq +entry is unnecessary. + + +.TP +\h'8m'3) +A directory that contains multiple or all of the hwmon drivers, for example +\*(lq/sys/class/hwmon\*(rq. +Here, both the \*(lq\c +.BI name: " hwmon-name"\c +\*(rq and \*(lq\c +.BI indices: " index-list"\c +\*(rq entries are required to tell thinkfan which interface to select below that +path, and which sensors or which fan to use from that interface. + +.TP +.I hwmon-name +The name of a hwmon interface, typically found in a file called \*(lqname\*(rq. +This has to be specified if +.I hwmon-path +is a base path that contains multiple hwmons. +This method of specifying sensors is particularly useful if the full path to a +particular hwmon keeps changing between bootups, e.g. due to changing load order +of the driver modules. + +.TP +.I index-list +A YAML list +.BI "[ " X1 ", " X2 ", " "\fR...\fB ]" +that specifies which sensors, resp. which fan to use from a given +interface. +Both +.B /proc/acpi/ibm/thermal +and also many hwmon interfaces contain multiple sensors, and not +all of them may be relevant for fan control. + +.TP +\h'9m'\(bu +For +.B hwmon +entries, this is required if +.I hwmon-path +does not refer directly to a single \*(lqtemp\fIXi\fR_input\*(rq file, but to a folder +that contains one or more of them. +In this case, +.I index-list +specifies the +.I Xi +for the \*(lqtemp\fIXi\fR_input\*(rq files that should be used. +A hwmon interface may also contain multiple PWM controls for fans, so in that case, +.I index-list +must contain exactly one entry. + +.TP +\h'9m'\(bu +For +.B tpacpi +sensors, this entry is optional. +If it is omitted, all temperatures found in +.B /proc/acpi/ibm/thermal +will be used. + +.TP +.I nvml-bus-id +NOTE: only available if thinkfan was compiled with USE_NVML enabled. + +The PCI bus ID of an nVidia graphics card that is run with the proprietary +nVidia driver. Can be obtained with e.g. \*(lqlspci | grep \-i vga\*(rq. +Usually, nVidia cards will use the open source +.B nouveau +driver, which should support hwmon sensors instead. + +.TP +.I disk-device-file +NOTE: only available if thinkfan was compiled with USE_ATASMART enabled. + +Full path to a device file for a hard disk that supports S.M.A.R.T. +See also the +.B \-d +option in +.BR thinkfan (1) +that prevents thinkfan from waking up sleeping (mechanical) disks to read their +temperature. + +.TP +.IR correction-list " (always optional)" +A YAML list that specifies temperature offsets for each sensor in use by the +given driver. Use this if you want to use the \*(lqsimple\*(rq level syntax, +but need to compensate for devices with a lower heat tolerance. +Note however that the detailed level syntax is usually the better (i.e. more +fine-grained) choice. + +.TP +.IR bool-allow-errors " (always optional, \fBfalse\fR by default)" +A truth value +.RB ( yes / no / true / false ) +that specifies whether thinkfan should accept errors when reading from this +sensor. +Normally, thinkfan will exit with an error message if reading the temperature +from any configured sensor fails. +Marking a sensor as optional may be useful for removable hardware or devices +that may get switched off entirely to save power. + + + +.SH FAN SPEEDS + +The +.B levels: +section specifies a list of fan speeds with associated lower and upper +temperature bounds. +If temperature(s) drop below the lower bound, thinkfan switches to the previous +level, and if the upper bound is reached, thinkfan switches to the next level. + +.SS Simple Syntax +In the simplified form, only one temperature is specified as an upper/lower +limit for a given fan speed. +In that case, the +.I lower-bound +and +.I upper-bound +are compared only to the highest temperature found among all configured sensors. +All other temperatures are ignored. +This mode is suitable for small systems (like laptops) where there is only one +device (e.g. the CPU) whose temperature needs to be controlled, or where the +required fan behaviour is similar enough for all heat-generating devices. + +.nf +.B "levels:" +.BI " \- [ " fan-speed ", " lower-bound ", " upper-bound " ]" +.BR " \- " ... +.fi + + +.SS Detailed Syntax +This mode is suitable for more complex systems, with devices that have +different temperature ratings. +For example, many modern CPUs and GPUs can deal with temperatures above +80\[char176]C on a daily basis, whereas a hard disk will die quickly if it +reaches such temperatures. +In detailed mode, upper and lower temperature limits are specified for each +sensor individually: + +.nf +.B "levels:" +.BI " \- speed: " fan-speed +.BI " lower_limit: [ " l1 ", " l2 ", " "\fR..." " ]" +.BI " upper_limit: [ " u1 ", " u2 ", " "\fR..." " ]" +.BR " \- " ... +.fi + + +.SS Values + +.TP 12m +.I fan-speed +The possible speed values are different depending on which fan driver is used. + +For a +.B hwmon +fan, +.I fan-speed +is a numeric value ranging from +.B 0 +to +.BR 255 , +corresponding to the PWM values accepted by the various kernel drivers. + +For a +.B tpacpi +fan on Lenovo/IBM ThinkPads and some other Lenovo laptops (see \fBSENSORS & FAN +DRIVERS\fR above), numeric values and strings can be used. +The numeric values range from 0 to 7. +The string values take the form \fB"level \fIlvl-id\fB"\fR, where +.I lvl-id +may be a value from +.BR 0 " to " 7 , +.BR auto , +.B full-speed +or +.BR disengaged . +The numeric values +.BR 0 " to " 7 +correspond to the regular fan speeds used by the firmware, although many +firmwares don't even use level \fB7\fR. +The value \fB"level auto"\fR gives control back to the firmware, which may be +useful if the fan behavior only needs to be changed for certain specific +temperature ranges (usually at the high and low end of the range). +The values \fB"level full-speed"\fR and \fB"level disengaged"\fR take the fan +speed control away from the firmware, causing the fan to slowly ramp up to an +absolute maximum that can be achieved within electrical limits. +Note that this will run the fan out of specification and cause increased wear, +though it may be helpful to combat thermal throttling. + +.TP +.IB l1 ", " l2 ", " \fR... +.TP +.IB u1 ", " u2 ", " \fR... +The lower and upper limits refer to the sensors in the same order in which they +were found when processing the +.B sensors: +section (see +.B SENSOR & FAN DRIVERS +above). +For the first level entry, the +.B lower_limit +may be omitted, and for the last one, the +.B upper_limit +may be omitted. +For all levels in between, the lower limits must overlap with the upper limits +of the previous level, to make sure the entire temperature range is covered and +that there is some hysteresis between speed levels. + + +.SH SEE ALSO +.nf +The thinkfan manpage: +.BR thinkfan (1) + +Example configs shipped with the source distribution, also available at: +.hy 0 +https://github.com/vmatare/thinkfan/tree/master/examples + +The Linux hwmon user interface documentation: +https://www.kernel.org/doc/html/latest/hwmon/sysfs\-interface.html + +The thinkpad_acpi interface documentation: +https://www.kernel.org/doc/html/latest/admin\-guide/laptops/thinkpad\-acpi.html + + +.SH BUGS + +.hy 0 +.nf +Report bugs on the github issue tracker: +https://github.com/vmatare/thinkfan/issues + diff --git a/upstream/fedora-40/man5/thinkfan.conf.legacy.5 b/upstream/fedora-40/man5/thinkfan.conf.legacy.5 new file mode 100644 index 00000000..6aa945e1 --- /dev/null +++ b/upstream/fedora-40/man5/thinkfan.conf.legacy.5 @@ -0,0 +1,253 @@ +.TH THINKFAN.CONF.LEGACY 5 2020-04-09 "thinkfan 1.3.1" +.SH NAME +thinkfan.conf.legacy \- the old, backwards-compatible config syntax for +thinkfan +.BR thinkfan (1) + +.SH DESCRIPTION +The thinkfan config file specifies one or more temperature input(s), exactly +one fan to control and the fan levels. +A fan level associates a certain fan speed to a lower and an upper +temperature bound. +If the temperature reaches the upper bound, we switch to the next fan level, +and if it drops below the lower bound, we switch to the previous fan level. +Temperature bounds can either be a single temperature (\fIsimple mode\fR) or +consist of multiple temperatures (\fIcomplex mode\fR). +In simple mode, only the highest of all known temperature is compared to the +upper & lower bound. +If you have devices with very different temperature ratings (e.g. CPU vs. +mechanical hard drives), you should specify correction values to equalize +their temperature ranges, or better: use complex mode. +In complex mode, the upper and lower bounds of each fan level are specified +for each sensor individually. +Thinkfan then switches to the next fan level if one of the upper bounds is +reached, and to the previous fan level if all temperatures have dropped below +their respective lower bounds. + +.SH THERMAL SENSORS +Multiple sensor keywords can be combined in one config file, but note that the +ordering is significant with respect to the upper and lower fan level bounds if +you use \fIcomplex mode\fR. +I.e. if +.B /proc/acpi/ibm/thermal +contains 16 temperatures and you specify an +.B hwmon +sensor after the +.B tp_thermal +statement, the +.B hwmon +sensor will be the 17th temperature. +. +After each sensor path, an optional +.I correction-value +can be specified. +This value (can be negative) is always added to the temperature reading from +that sensor. +Correction values should be specified if you use +.B Simple Mode +with components that have a different temperature rating, like hard disks and +CPUs. +Note though that +.B Complex Mode +is generally the better solution since it gives you full control over fan +levels and temperature ranges for each sensor, instead of just adding a fixed +value to equalize temperature ranges. + +.TP +.BI "tp_thermal /proc/acpi/ibm/thermal" " \fR[\fB (\fIcorrection-value \fR...\fB) \fR]\fP" +Use the thermal sensors provided by the +.B thinkpad_acpi +kernel module on older thinkpads. These normally reside in +.B /proc/acpi/ibm/thermal, +so this keyword will hardly be used with other paths. +This file usually contains 8-16 temperatures, some of which may be +reserved for removable hardware or completely unused. Unused temperature slots +always contain the value -128. Since this file contains all temperatures the +.B thinkpad_acpi +module knows about, there cannot be more than one +.B tp_thermal +statement in a config file. + +.TP +.BI hwmon " sysfs-path \fR[ \fB(\fIcorrection-value\fB) \fR]\fP" +Use a standard hwmon temperature input that may be provided by all kinds of +kernel drivers. +.I sysfs-path +is usually a file named \[oq]temp*_input\[cq], somewhere under /sys, so you +can search for them e.g. with \[oq]find /sys -type f -name "temp*_input"\[cq]. +Each of these files contains one temperature, so you need to add a +.B hwmon +statement for each device whose temperature you wish to control. + +.TP +.BI atasmart " device-path \fR[ \fB(\fIcorrection-value\fB) \fR]\fP" +NOTE: only available if thinkfan was compiled with USE_ATASMART enabled. +. +.IP +Read the temperature directly from a hard disk using S.M.A.R.T. See also the +.B -d +option in +.BR thinkfan (1) +that prevents thinkfan from waking up sleeping (mechanical) disks to read +their temperature. + +.TP +.BI nv_thermal " pci-bus-id \fR[ \fB(\fIcorrection-value\fB) \fR]\fP" +NOTE: only available if thinkfan was compiled with USE_NVML enabled. +. +.IP +Read the temperature of an nVidia graphics card from the proprietary nVidia +driver. This does not work with the open-source Nouveau driver, it depends +specifially on libnvidia-ml.so that is usually installed with the binary nVidia +driver. +The correct +.I pci-bus-id +can be retrieved using e.g. lspci with: \[oq]lspci | grep -i vga\[cq]. +Most open-source graphics drivers (radeon, nouveau, possibly others too) can +instead be used with the +.B hwmon +keyword described above. + +.SH FANS +Currently, thinkfan can control only one fan at a time. +In theory, you can run multiple instances of the program simultaneously (with +multiple config files) to control multiple fans, but that requires enabling +DANGEROUS mode and will likely break most init scripts. +It is an error to have more than one fan statement per config file. + +.TP +.B tp_fan /proc/acpi/ibm/fan +Use the fan control provided by the +.B thinkpad_acpi +kernel module, which needs to be loaded with the option +.BR fan_control=1 . +The path is defined by the +.B thinkpad_acpi +kernel module and will hardly change. Besides the fan levels ranging from 0 to +7, it also supports the +.B disengaged +and +.B auto +modes. +. +.IP +The +.B auto +mode should delegate fan control to the firmware, so it can be regarded as a +\[oq]default\[cq] mode that does not change the fan behavior. +This is useful for example if you only want to change the fan behavior at high +and/or low temperatures. +. +.IP +The +.B disengaged +or +.B full-speed +mode effectively disables the fan RPM limiter. +Fan speed will slowly ramp up until the fan uses the maximum electrical power +available from the embedded controller. Use this only to prevent potentially +destructive overheating, since it runs the fan outside of specifications and +wears its bearings down quickly. + +.TP +.BI pwm_fan " sysfs-path" +Control a sysfs PWM fan. +Many hwmon drivers that provide a \[oq]temp*_input\[cq] file also allow fan control, +although there may also be drivers that are specific to either temperature +reading or fan control. +You can search for a PWM control file e.g. with \[oq]find /sys -type f -name +"pwm?"\[cq]. +Note that with PWM, fan levels usually range from 0 to 255, although besides a +file like \fBpwm1\fR there may also be \fBpwm1_min\fR and \fBpwm1_max\fR that specify +different (soft or recommended?) limits for a particular fan. + + +.SH FAN LEVELS +Defining the fan levels is the meat of the config file. Here you make use of +your previously defined temperature inputs to set the lower and upper bounds +for the fan speeds. +You cannot mix simple fan levels with complex fan levels. +The general syntax of a simple fan level is: +.RS +.PP +\fB( \fIfan-level \fR[\fB,\fR] \fIlower-bound \fR[\fB,\fR] \fIupper-bound\fB ) +.RE +.PP +The +.I fan-level +is either a numeric value (0-7 or 0-255, depending on whether a +.B tp_fan +or a +.B pwm_fan +is used) or a string enclosed in double quotes. +When a +.B tp_fan +is used, specifying +.B 0 +has the same effect as specifying \fB"level 0\fR". +In addition to the numeric fan levels, +.B tp_fan +also supports \fB"level auto"\fR and \fB"level disengaged"\fR or \fB"level +full-speed"\fR. +See above for an explanation of what these mean. +The format of +.I lower-bound +and +.I upper-bound +depends on whether you want to use +.B Simple Mode +or +.B Complex Mode. + + +.SS Simple Mode +In simple mode, the +.I lower-bound +and +.I upper-bound +of a fan level are each specified as a single temperature value. +Both are compared only to the highest temperature found in all of the +configured thermal sensors. +Using this mode of operation makes sense e.g. if all temperature readings come +from the on-DIE thermal sensors of a multicore processor. +The fan speed will affect all of these temperatures in the same way because +they share a single thermal connection to the heatsink, so it makes sense to +ignore all but the highest of these temperatures. +As a rule of thumb, if your thermal sensors cover multiple devices you should +use Complex Mode, or at least specify correction values to account for +different temperature ratings. + +.SS Complex Mode +In complex mode, both the +.I lower-bound +and +.I upper-bound +are lists of temperatures, the length of which must match the number of +temperature readings thinkfan knows about. +Each bound must be enclosed in braces, with individual values separated by +commas or spaces, so the specific syntax of a complex mode fan level is: +.RS +.PP +.nf +.B "{ \fIfan-level" +.B " ( \fIlower-1 \fR[\fIlower-2\fR ...] \fB)" +.B " ( \fIupper-1 \fR[\fIupper-2\fR ...] \fB)" +.B "}" +.fi +.RE +.PP +The optional commas have been omitted here for readability, and the curly +braces are interchangeable with round braces. +Note that it is not possible to mix simple fan levels with complex fan levels. +.P +Complex mode is generally the preferred mode of operation since it allows you +to specify precisely what the fan should to to keep each component within its +specified temperature range. + + +.SH SEE ALSO +.BR thinkfan (1) +.P +Example configs shipped with the source distribution, also available at +.IR https://github.com/vmatare/thinkfan/tree/master/examples . + diff --git a/upstream/fedora-40/man5/timesyncd.conf.5 b/upstream/fedora-40/man5/timesyncd.conf.5 new file mode 100644 index 00000000..33f0675d --- /dev/null +++ b/upstream/fedora-40/man5/timesyncd.conf.5 @@ -0,0 +1,140 @@ +'\" t +.TH "TIMESYNCD\&.CONF" "5" "" "systemd 255" "timesyncd.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +timesyncd.conf, timesyncd.conf.d \- Network Time Synchronization configuration files +.SH "SYNOPSIS" +.PP +/etc/systemd/timesyncd\&.conf +.PP +/etc/systemd/timesyncd\&.conf\&.d/*\&.conf +.PP +/run/systemd/timesyncd\&.conf\&.d/*\&.conf +.PP +/usr/lib/systemd/timesyncd\&.conf\&.d/*\&.conf +.SH "DESCRIPTION" +.PP +These configuration files control NTP network time synchronization\&. See +\fBsystemd.syntax\fR(7) +for a general description of the syntax\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is either in +/usr/lib/systemd/ +or +/etc/systemd/ +and contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in +/etc/ +if it\*(Aqs shipped in +/usr/) however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&. +.PP +In addition to the "main" configuration file, drop\-in configuration snippets are read from +/usr/lib/systemd/*\&.conf\&.d/, +/usr/local/lib/systemd/*\&.conf\&.d/, and +/etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the +*\&.conf\&.d/ +configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&. +.PP +When packages need to customize the configuration, they can install drop\-ins under +/usr/\&. Files in +/etc/ +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering of the files\&. This also defined a concept of drop\-in priority to allow distributions to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. +.PP +To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in the configuration directory in +/etc/, with the same filename as the vendor configuration file\&. +.SH "OPTIONS" +.PP +The following settings are configured in the [Time] section: +.PP +\fINTP=\fR +.RS 4 +A space\-separated list of NTP server host names or IP addresses\&. During runtime this list is combined with any per\-interface NTP servers acquired from +\fBsystemd-networkd.service\fR(8)\&. +\fBsystemd\-timesyncd\fR +will contact all configured system or per\-interface servers in turn, until one responds\&. When the empty string is assigned, the list of NTP servers is reset, and all prior assignments will have no effect\&. This setting defaults to an empty list\&. +.sp +Added in version 216\&. +.RE +.PP +\fIFallbackNTP=\fR +.RS 4 +A space\-separated list of NTP server host names or IP addresses to be used as the fallback NTP servers\&. Any per\-interface NTP servers obtained from +\fBsystemd-networkd.service\fR(8) +take precedence over this setting, as do any servers set via +\fINTP=\fR +above\&. This setting is hence only relevant if no other NTP server information is known\&. When the empty string is assigned, the list of NTP servers is reset, and all prior assignments will have no effect\&. If this option is not given, a compiled\-in list of NTP servers is used\&. +.sp +Added in version 216\&. +.RE +.PP +\fIRootDistanceMaxSec=\fR +.RS 4 +Maximum acceptable root distance, i\&.e\&. the maximum estimated time required for a packet to travel to the server we are connected to from the server with the reference clock\&. If the current server does not satisfy this limit, +\fBsystemd\-timesyncd\fR +will switch to a different server\&. +.sp +Takes a time span value\&. The default unit is seconds, but other units may be specified, see +\fBsystemd.time\fR(5)\&. Defaults to 5 seconds\&. +.sp +Added in version 236\&. +.RE +.PP +\fIPollIntervalMinSec=\fR, \fIPollIntervalMaxSec=\fR +.RS 4 +The minimum and maximum poll intervals for NTP messages\&. Polling starts at the minimum poll interval, and is adjusted within the specified limits in response to received packets\&. +.sp +Each setting takes a time span value\&. The default unit is seconds, but other units may be specified, see +\fBsystemd.time\fR(5)\&. +\fIPollIntervalMinSec=\fR +defaults to 32 seconds and must not be smaller than 16\ \&seconds\&. +\fIPollIntervalMaxSec=\fR +defaults to 34\ \&min\ \&8\ \&s (2048\ \&seconds) and must be larger than +\fIPollIntervalMinSec=\fR\&. +.sp +Added in version 236\&. +.RE +.PP +\fIConnectionRetrySec=\fR +.RS 4 +Specifies the minimum delay before subsequent attempts to contact a new NTP server are made\&. +.sp +Takes a time span value\&. The default unit is seconds, but other units may be specified, see +\fBsystemd.time\fR(5)\&. Defaults to 30 seconds and must not be smaller than 1 second\&. +.sp +Added in version 248\&. +.RE +.PP +\fISaveIntervalSec=\fR +.RS 4 +The interval at which the current time is periodically saved to disk, in the absence of any recent synchronisation from an NTP server\&. This is especially useful for offline systems with no local RTC, as it will guarantee that the system clock remains roughly monotonic across reboots\&. +.sp +Takes a time interval value\&. The default unit is seconds, but other units may be specified, see +\fBsystemd.time\fR(5)\&. Defaults to 60 seconds\&. +.sp +Added in version 250\&. +.RE +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-timesyncd.service\fR(8), +\fBsystemd-networkd.service\fR(8) diff --git a/upstream/fedora-40/man5/tmpfiles.d.5 b/upstream/fedora-40/man5/tmpfiles.d.5 new file mode 100644 index 00000000..9c32f27f --- /dev/null +++ b/upstream/fedora-40/man5/tmpfiles.d.5 @@ -0,0 +1,1051 @@ +'\" t +.TH "TMPFILES\&.D" "5" "" "systemd 255" "tmpfiles.d" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +tmpfiles.d \- Configuration for creation, deletion and cleaning of volatile and temporary files +.SH "SYNOPSIS" +.PP +.nf +/etc/tmpfiles\&.d/*\&.conf +/run/tmpfiles\&.d/*\&.conf +/usr/lib/tmpfiles\&.d/*\&.conf + +.fi +.PP +.nf +~/\&.config/user\-tmpfiles\&.d/*\&.conf +$XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf +~/\&.local/share/user\-tmpfiles\&.d/*\&.conf +\&... +/usr/share/user\-tmpfiles\&.d/*\&.conf + +.fi + +.sp +.nf +#Type Path Mode User Group Age Argument +f /file/to/create mode user group \- content +f+ /file/to/create\-or\-truncate mode user group \- content +w /file/to/write\-to \- \- \- \- content +w+ /file/to/append\-to \- \- \- \- content +d /directory/to/create\-and\-clean\-up mode user group cleanup\-age \- +D /directory/to/create\-and\-remove mode user group cleanup\-age \- +e /directory/to/clean\-up mode user group cleanup\-age \- +v /subvolume\-or\-directory/to/create mode user group cleanup\-age \- +q /subvolume\-or\-directory/to/create mode user group cleanup\-age \- +Q /subvolume\-or\-directory/to/create mode user group cleanup\-age \- +p /fifo/to/create mode user group \- \- +p+ /fifo/to/[re]create mode user group \- \- +L /symlink/to/create \- \- \- \- symlink/target/path +L+ /symlink/to/[re]create \- \- \- \- symlink/target/path +c /dev/char\-device\-to\-create mode user group \- major:minor +c+ /dev/char\-device\-to\-[re]create mode user group \- major:minor +b /dev/block\-device\-to\-create mode user group \- major:minor +b+ /dev/block\-device\-to\-[re]create mode user group \- major:minor +C /target/to/create \- \- \- cleanup\-age /source/to/copy +C+ /target/to/create \- \- \- cleanup\-age /source/to/copy +x /path\-or\-glob/to/ignore/recursively \- \- \- cleanup\-age \- +X /path\-or\-glob/to/ignore \- \- \- cleanup\-age \- +r /path\-or\-glob/to/remove \- \- \- \- \- +R /path\-or\-glob/to/remove/recursively \- \- \- \- \- +z /path\-or\-glob/to/adjust/mode mode user group \- \- +Z /path\-or\-glob/to/adjust/mode/recursively mode user group \- \- +t /path\-or\-glob/to/set/xattrs \- \- \- \- xattrs +T /path\-or\-glob/to/set/xattrs/recursively \- \- \- \- xattrs +h /path\-or\-glob/to/set/attrs \- \- \- \- file attrs +H /path\-or\-glob/to/set/attrs/recursively \- \- \- \- file attrs +a /path\-or\-glob/to/set/acls \- \- \- \- POSIX ACLs +a+ /path\-or\-glob/to/append/acls \- \- \- \- POSIX ACLs +A /path\-or\-glob/to/set/acls/recursively \- \- \- \- POSIX ACLs +A+ /path\-or\-glob/to/append/acls/recursively \- \- \- \- POSIX ACLs + +.fi +.SH "DESCRIPTION" +.PP +tmpfiles\&.d +configuration files provide a generic mechanism to define the +\fIcreation\fR +of regular files, directories, pipes, and device nodes, adjustments to their +\fIaccess mode, ownership, attributes, quota assignments, and contents\fR, and finally their time\-based +\fIremoval\fR\&. It is mostly commonly used for volatile and temporary files and directories (such as those located under +/run/, +/tmp/, +/var/tmp/, the API file systems such as +/sys/ +or +/proc/, as well as some other directories below +/var/)\&. +.PP +\fBsystemd-tmpfiles\fR(8) +uses this configuration to create volatile files and directories during boot and to do periodic cleanup afterwards\&. See +\fBsystemd-tmpfiles\fR(8) +for the description of +systemd\-tmpfiles\-setup\&.service, +systemd\-tmpfiles\-clean\&.service, and associated units\&. +.PP +System daemons frequently require private runtime directories below +/run/ +to store communication sockets and similar\&. For these, it is better to use +\fIRuntimeDirectory=\fR +in their unit files (see +\fBsystemd.exec\fR(5) +for details), if the flexibility provided by +tmpfiles\&.d +is not required\&. The advantages are that the configuration required by the unit is centralized in one place, and that the lifetime of the directory is tied to the lifetime of the service itself\&. Similarly, +\fIStateDirectory=\fR, +\fICacheDirectory=\fR, +\fILogsDirectory=\fR, and +\fIConfigurationDirectory=\fR +should be used to create directories under +/var/lib/, +/var/cache/, +/var/log/, and +/etc/\&. +tmpfiles\&.d +should be used for files whose lifetime is independent of any service or requires more complicated configuration\&. +.SH "CONFIGURATION DIRECTORIES AND PRECEDENCE" +.PP +Each configuration file shall be named in the style of +\fIpackage\fR\&.conf +or +\fIpackage\fR\-\fIpart\fR\&.conf\&. The second variant should be used when it is desirable to make it easy to override just this part of configuration\&. +.PP +Files in +/etc/tmpfiles\&.d +override files with the same name in +/usr/lib/tmpfiles\&.d +and +/run/tmpfiles\&.d\&. Files in +/run/tmpfiles\&.d +override files with the same name in +/usr/lib/tmpfiles\&.d\&. Packages should install their configuration files in +/usr/lib/tmpfiles\&.d\&. Files in +/etc/tmpfiles\&.d +are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. All configuration files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in\&. If multiple files specify the same path, the entry in the file with the lexicographically earliest name will be applied (note that lines suppressed due to the +"!" +are filtered before application, meaning that if an early line carries the exclamation mark and is suppressed because of that, a later line matching in path will be applied)\&. All other conflicting entries will be logged as errors\&. When two lines are prefix path and suffix path of each other, then the prefix line is always created first, the suffix later (and if removal applies to the line, the order is reversed: the suffix is removed first, the prefix later)\&. Lines that take globs are applied after those accepting no globs\&. If multiple operations shall be applied on the same file (such as ACL, xattr, file attribute adjustments), these are always done in the same fixed order\&. Except for those cases, the files/directories are processed in the order they are listed\&. +.PP +If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink to +/dev/null +in +/etc/tmpfiles\&.d/ +bearing the same filename\&. +.SH "CONFIGURATION FILE FORMAT" +.PP +The configuration format is one line per path, containing type, path, mode, ownership, age, and argument fields\&. The lines are separated by newlines, the fields by whitespace: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#Type Path Mode User Group Age Argument\&... +d /run/user 0755 root root 10d \- +L /tmp/foobar \- \- \- \- /dev/null +.fi +.if n \{\ +.RE +.\} +.PP +Fields may contain C\-style escapes\&. With the exception of the seventh field (the "argument") all fields may be enclosed in quotes\&. Note that any whitespace found in the line after the beginning of the argument field will be considered part of the argument field\&. To begin the argument field with a whitespace character, use C\-style escapes (e\&.g\&. +"\ex20")\&. +.SS "Type" +.PP +The type consists of a single letter and optionally one or more modifier characters: a plus sign ("+"), exclamation mark ("!"), minus sign ("\-"), equals sign ("="), tilde character ("~") and/or caret ("^")\&. +.PP +The following line types are understood: +.PP +\fIf\fR, \fIf+\fR +.RS 4 +\fIf\fR +will create a file if it does not exist yet\&. If the argument parameter is given and the file did not exist yet, it will be written to the file\&. +\fIf+\fR +will create or truncate the file\&. If the argument parameter is given, it will be written to the file\&. Does not follow symlinks\&. +.RE +.PP +\fIw\fR, \fIw+\fR +.RS 4 +Write the argument parameter to a file, if the file exists\&. If suffixed with +\fI+\fR, the line will be appended to the file\&. If your configuration writes multiple lines to the same file, use +\fIw+\fR\&. Lines of this type accept shell\-style globs in place of normal path names\&. The argument parameter will be written without a trailing newline\&. C\-style backslash escapes are interpreted\&. Follows symlinks\&. +.RE +.PP +\fId\fR +.RS 4 +Create a directory\&. The mode and ownership will be adjusted if specified\&. Contents of this directory are subject to time\-based cleanup if the age argument is specified\&. +.RE +.PP +\fID\fR +.RS 4 +Similar to +\fId\fR, but in addition the contents of the directory will be removed when +\fB\-\-remove\fR +is used\&. +.RE +.PP +\fIe\fR +.RS 4 +Adjust the mode and ownership of existing directories and remove their contents based on age\&. Lines of this type accept shell\-style globs in place of normal path names\&. Contents of the directories are subject to time\-based cleanup if the age argument is specified\&. If the age argument is +"0", contents will be unconditionally deleted every time +\fBsystemd-tmpfiles\fR(8) +\fB\-\-clean\fR +is run\&. +.sp +For this entry to be useful, at least one of the mode, user, group, or age arguments must be specified, since otherwise this entry has no effect\&. As an exception, an entry with no effect may be useful when combined with +\fI!\fR, see the examples\&. +.sp +Added in version 230\&. +.RE +.PP +\fIv\fR +.RS 4 +Create a subvolume if the path does not exist yet, the file system supports subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root directory +/ +is itself a subvolume)\&. Otherwise, create a normal directory, in the same way as +\fId\fR\&. +.sp +A subvolume created with this line type is not assigned to any higher\-level quota group\&. For that, use +\fIq\fR +or +\fIQ\fR, which allow creating simple quota group hierarchies, see below\&. +.sp +Added in version 219\&. +.RE +.PP +\fIq\fR +.RS 4 +Create a subvolume or directory the same as +\fIv\fR, but assign the subvolume to the same higher\-level quota groups as the parent\&. This ensures that higher\-level limits and accounting applied to the parent subvolume also include the specified subvolume\&. On non\-btrfs file systems, this line type is identical to +\fId\fR\&. +.sp +If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the subvolume is already attached to a quota group or not\&. Also see +\fIQ\fR +below\&. See +\fBbtrfs-qgroup\fR(8) +for details about the btrfs quota group concept\&. +.sp +Added in version 228\&. +.RE +.PP +\fIQ\fR +.RS 4 +Create the subvolume or directory the same as +\fIv\fR, but assign the new subvolume to a new leaf quota group\&. Instead of copying the higher\-level quota group assignments from the parent as is done with +\fIq\fR, the lowest quota group of the parent subvolume is determined that is not the leaf quota group\&. Then, an "intermediary" quota group is inserted that is one level below this level, and shares the same ID part as the specified subvolume\&. If no higher\-level quota group exists for the parent subvolume, a new quota group at level 255 sharing the same ID as the specified subvolume is inserted instead\&. This new intermediary quota group is then assigned to the parent subvolume\*(Aqs higher\-level quota groups, and the specified subvolume\*(Aqs leaf quota group is assigned to it\&. +.sp +Effectively, this has a similar effect as +\fIq\fR, however introduces a new higher\-level quota group for the specified subvolume that may be used to enforce limits and accounting to the specified subvolume and children subvolume created within it\&. Thus, by creating subvolumes only via +\fIq\fR +and +\fIQ\fR, a concept of "subtree quotas" is implemented\&. Each subvolume for which +\fIQ\fR +is set will get a "subtree" quota group created, and all child subvolumes created within it will be assigned to it\&. Each subvolume for which +\fIq\fR +is set will not get such a "subtree" quota group, but it is ensured that they are added to the same "subtree" quota group as their immediate parents\&. +.sp +It is recommended to use +\fIQ\fR +for subvolumes that typically contain further subvolumes, and where it is desirable to have accounting and quota limits on all child subvolumes together\&. Examples for +\fIQ\fR +are typically +/home/ +or +/var/lib/machines/\&. In contrast, +\fIq\fR +should be used for subvolumes that either usually do not include further subvolumes or where no accounting and quota limits are needed that apply to all child subvolumes together\&. Examples for +\fIq\fR +are typically +/var/ +or +/var/tmp/\&. +.sp +As with +\fIq\fR, +\fIQ\fR +has no effect on the quota group hierarchy if the subvolume already exists, regardless of whether the subvolume already belong to a quota group or not\&. +.sp +Added in version 228\&. +.RE +.PP +\fIp\fR, \fIp+\fR +.RS 4 +Create a named pipe (FIFO) if it does not exist yet\&. If suffixed with +\fI+\fR +and a file already exists where the pipe is to be created, it will be removed and be replaced by the pipe\&. +.RE +.PP +\fIL\fR, \fIL+\fR +.RS 4 +Create a symlink if it does not exist yet\&. If suffixed with +\fI+\fR +and a file or directory already exists where the symlink is to be created, it will be removed and be replaced by the symlink\&. If the argument is omitted, symlinks to files with the same name residing in the directory +/usr/share/factory/ +are created\&. Note that permissions and ownership on symlinks are ignored\&. +.RE +.PP +\fIc\fR, \fIc+\fR +.RS 4 +Create a character device node if it does not exist yet\&. If suffixed with +\fI+\fR +and a file already exists where the device node is to be created, it will be removed and be replaced by the device node\&. It is recommended to suffix this entry with an exclamation mark to only create static device nodes at boot, as udev will not manage static device nodes that are created at runtime\&. +.RE +.PP +\fIb\fR, \fIb+\fR +.RS 4 +Create a block device node if it does not exist yet\&. If suffixed with +\fI+\fR +and a file already exists where the device node is to be created, it will be removed and be replaced by the device node\&. It is recommended to suffix this entry with an exclamation mark to only create static device nodes at boot, as udev will not manage static device nodes that are created at runtime\&. +.RE +.PP +\fIC\fR, \fIC+\fR +.RS 4 +Recursively copy a file or directory, if the destination files or directories do not exist yet or the destination directory is empty\&. Note that this command will not descend into subdirectories if the destination directory already exists and is not empty, unless the action is suffixed with +\fI+\fR\&. Instead, the entire copy operation is skipped\&. If the argument is omitted, files from the source directory +/usr/share/factory/ +with the same name are copied\&. Does not follow symlinks\&. Contents of the directories are subject to time\-based cleanup if the age argument is specified\&. +.sp +Added in version 214\&. +.RE +.PP +\fIx\fR +.RS 4 +Ignore a path during cleaning\&. Use this type to exclude paths from clean\-up as controlled with the Age parameter\&. Note that lines of this type do not influence the effect of +\fIr\fR +or +\fIR\fR +lines\&. Lines of this type accept shell\-style globs in place of normal path names\&. +.RE +.PP +\fIX\fR +.RS 4 +Ignore a path during cleaning\&. Use this type to exclude paths from clean\-up as controlled with the Age parameter\&. Unlike +\fIx\fR, this parameter will not exclude the content if path is a directory, but only directory itself\&. Note that lines of this type do not influence the effect of +\fIr\fR +or +\fIR\fR +lines\&. Lines of this type accept shell\-style globs in place of normal path names\&. +.sp +Added in version 198\&. +.RE +.PP +\fIr\fR +.RS 4 +Remove a file or directory if it exists\&. This may not be used to remove non\-empty directories, use +\fIR\fR +for that\&. Lines of this type accept shell\-style globs in place of normal path names\&. Does not follow symlinks\&. +.RE +.PP +\fIR\fR +.RS 4 +Recursively remove a path and all its subdirectories (if it is a directory)\&. Lines of this type accept shell\-style globs in place of normal path names\&. Does not follow symlinks\&. +.RE +.PP +\fIz\fR +.RS 4 +Adjust the access mode, user and group ownership, and restore the SELinux security context of a file or directory, if it exists\&. Lines of this type accept shell\-style globs in place of normal path names\&. Does not follow symlinks\&. +.RE +.PP +\fIZ\fR +.RS 4 +Recursively set the access mode, user and group ownership, and restore the SELinux security context of a file or directory if it exists, as well as of its subdirectories and the files contained therein (if applicable)\&. Lines of this type accept shell\-style globs in place of normal path names\&. Does not follow symlinks\&. +.RE +.PP +\fIt\fR +.RS 4 +Set extended attributes, see +\fBattr\fR(5) +for details\&. The argument field should take one or more assignment expressions in the form +\fInamespace\fR\&.\fIattribute\fR=\fIvalue\fR, for examples see below\&. Lines of this type accept shell\-style globs in place of normal path names\&. This can be useful for setting SMACK labels\&. Does not follow symlinks\&. +.sp +Please note that extended attributes settable with this line type are a different concept from the Linux file attributes settable with +\fIh\fR/\fIH\fR, see below\&. +.sp +Added in version 218\&. +.RE +.PP +\fIT\fR +.RS 4 +Same as +\fIt\fR, but operates recursively\&. +.sp +Added in version 219\&. +.RE +.PP +\fIh\fR +.RS 4 +Set Linux file/directory attributes\&. Lines of this type accept shell\-style globs in place of normal path names\&. +.sp +The format of the argument field is +\fI[+\-=][aAcCdDeijPsStTu]\fR\&. The prefix +\fI+\fR +(the default one) causes the attributes to be added; +\fI\-\fR +causes the attributes to be removed; +\fI=\fR +causes the attributes to be set exactly as the following letters\&. The letters +"aAcCdDeijPsStTu" +select the new attributes for the files, see +\fBchattr\fR(1) +for further information\&. +.sp +Passing only +\fI=\fR +as argument resets all the file attributes listed above\&. It has to be pointed out that the +\fI=\fR +prefix limits itself to the attributes corresponding to the letters listed here\&. All other attributes will be left untouched\&. Does not follow symlinks\&. +.sp +Please note that the Linux file attributes settable with this line type are a different concept from the extended attributes settable with +\fIt\fR/\fIT\fR, see above\&. +.RE +.PP +\fIH\fR +.RS 4 +Sames as +\fIh\fR, but operates recursively\&. +.sp +Added in version 220\&. +.RE +.PP +\fIa\fR, \fIa+\fR +.RS 4 +Set POSIX ACLs (access control lists), see +\fBacl\fR(5)\&. Additionally, if \*(AqX\*(Aq is used, the execute bit is set only if the file is a directory or already has execute permission for some user, as mentioned in +\fBsetfacl\fR(1)\&. If suffixed with +\fI+\fR, the specified entries will be added to the existing set\&. +\fBsystemd-tmpfiles\fR(8) +will automatically add the required base entries for user and group based on the access mode of the file, unless base entries already exist or are explicitly specified\&. The mask will be added if not specified explicitly or already present\&. Lines of this type accept shell\-style globs in place of normal path names\&. This can be useful for allowing additional access to certain files\&. Does not follow symlinks\&. +.sp +Added in version 219\&. +.RE +.PP +\fIA\fR, \fIA+\fR +.RS 4 +Same as +\fIa\fR +and +\fIa+\fR, but recursive\&. Does not follow symlinks\&. +.sp +Added in version 219\&. +.RE +.SS "Type Modifiers" +.PP +If the exclamation mark ("!") is used, this line is only safe to execute during boot, and can break a running system\&. Lines without the exclamation mark are presumed to be safe to execute at any time, e\&.g\&. on package upgrades\&. +\fBsystemd-tmpfiles\fR(8) +will take lines with an exclamation mark only into consideration, if the +\fB\-\-boot\fR +option is given\&. +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Make sure these are created by default so that nobody else can +d /tmp/\&.X11\-unix 1777 root root 10d + +# Unlink the X11 lock files +r! /tmp/\&.X[0\-9]*\-lock +.fi +.if n \{\ +.RE +.\} +.sp +The second line in contrast to the first one would break a running system, and will only be executed with +\fB\-\-boot\fR\&. +.PP +If the minus sign ("\-") is used, this line failing to run successfully during create (and only create) will not cause the execution of +\fBsystemd\-tmpfiles\fR +to return an error\&. +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Modify sysfs but don\*(Aqt fail if we are in a container with a read\-only /proc +w\- /proc/sys/vm/swappiness \- \- \- \- 10 +.fi +.if n \{\ +.RE +.\} +.PP +If the equals sign ("=") is used, the file types of existing objects in the specified path are checked, and removed if they do not match\&. This includes any implicitly created parent directories (which can be either directories or directory symlinks)\&. For example, if there is a FIFO in place of one of the parent path components it will be replaced with a directory\&. +.PP +If the tilde character ("~") is used, the argument (i\&.e\&. 6th) column is +\m[blue]\fBBase64 decoded\fR\m[]\&\s-2\u[1]\d\s+2 +before use\&. This modifier is only supported on line types that can write file contents, i\&.e\&. +\fIf\fR, +\fIf+\fR, +\fIw\fR, +\fI+\fR\&. This is useful for writing arbitrary binary data (including newlines and NUL bytes) to files\&. Note that if this switch is used, the argument is not subject to specifier expansion, neither before nor after Base64 decoding\&. +.PP +If the caret character ("^") is used, the argument (i\&.e\&. 6th) column takes a service credential name to read the argument data from\&. See +\m[blue]\fBSystem and Service Credentials\fR\m[]\&\s-2\u[2]\d\s+2 +for details about the credentials concept\&. This modifier is only supported on line types that can write file contents, i\&.e\&. +\fIf\fR, +\fIf+\fR, +\fIw\fR, +\fIw+\fR\&. This is useful for writing arbitrary files with contents sourced from elsewhere, including from VM or container managers further up\&. If the specified credential is not set for the +\fBsystemd\-tmpfiles\fR +service, the line is silently skipped\&. If +"^" +and +"~" +are combined Base64 decoding is applied to the credential contents\&. +.PP +Note that for all line types that result in creation of any kind of file node (i\&.e\&. +\fIf\fR/\fIF\fR, +\fId\fR/\fID\fR/\fIv\fR/\fIq\fR/\fIQ\fR, +\fIp\fR, +\fIL\fR, +\fIc\fR/\fIb\fR +and +\fIC\fR) leading directories are implicitly created if needed, owned by root with an access mode of 0755\&. In order to create them with different modes or ownership make sure to add appropriate +\fId\fR +lines\&. +.SS "Path" +.PP +The file system path specification supports simple specifier expansion, see below\&. The path (after expansion) must be absolute\&. +.SS "Mode" +.PP +The file access mode to use when creating this file or directory\&. If omitted or when set to +"\-", the default is used: 0755 for directories, 0644 for all other file objects\&. For +\fIz\fR, +\fIZ\fR +lines, if omitted or when set to +"\-", the file access mode will not be modified\&. This parameter is ignored for +\fIx\fR, +\fIr\fR, +\fIR\fR, +\fIL\fR, +\fIt\fR, and +\fIa\fR +lines\&. +.PP +Optionally, if prefixed with +"~", the access mode is masked based on the already set access bits for existing file or directories: if the existing file has all executable bits unset, all executable bits are removed from the new access mode, too\&. Similarly, if all read bits are removed from the old access mode, they will be removed from the new access mode too, and if all write bits are removed, they will be removed from the new access mode too\&. In addition, the sticky/SUID/SGID bit is removed unless applied to a directory\&. This functionality is particularly useful in conjunction with +\fIZ\fR\&. +.PP +By default the access mode of listed inodes is set to the specified mode regardless if it is created anew, or already existed\&. Optionally, if prefixed with +":", the configured access mode is only applied when creating new inodes, and if the inode the line refers to already exists, its access mode is left in place unmodified\&. +.SS "User, Group" +.PP +The user and group to use for this file or directory\&. This may either be a numeric ID or a user/group name\&. If omitted or when set to +"\-", the user and group of the user who invokes +\fBsystemd-tmpfiles\fR(8) +is used\&. For +\fIz\fR +and +\fIZ\fR +lines, when omitted or when set to +"\-", the file ownership will not be modified\&. These parameters are ignored for +\fIx\fR, +\fIr\fR, +\fIR\fR, +\fIL\fR, +\fIt\fR, and +\fIa\fR +lines\&. +.PP +This field should generally only reference system users/groups, i\&.e\&. users/groups that are guaranteed to be resolvable during early boot\&. If this field references users/groups that only become resolveable during later boot (i\&.e\&. after NIS, LDAP or a similar networked directory service become available), execution of the operations declared by the line will likely fail\&. Also see +\m[blue]\fBNotes on Resolvability of User and Group Names\fR\m[]\&\s-2\u[3]\d\s+2 +for more information on requirements on system user/group definitions\&. +.PP +By default the ownership of listed inodes is set to the specified user/group regardless if it is created anew, or already existed\&. Optionally, if prefixed with +":", the configured user/group information is only applied when creating new inodes, and if the inode the line refers to already exists, its user/group is left in place unmodified\&. +.SS "Age" +.PP +The date field, when set, is used to decide what files to delete when cleaning\&. If a file or directory is older than the current time minus the age field, it is deleted\&. The field format is a series of integers each followed by one of the following suffixes for the respective time units: +\fBs\fR, +\fBm\fR +or +\fBmin\fR, +\fBh\fR, +\fBd\fR, +\fBw\fR, +\fBms\fR, and +\fBus\fR, meaning seconds, minutes, hours, days, weeks, milliseconds, and microseconds, respectively\&. Full names of the time units can be used too\&. +.PP +If multiple integers and units are specified, the time values are summed\&. If an integer is given without a unit, +\fBs\fR +is assumed\&. +.PP +When the age is set to zero, the files are cleaned unconditionally\&. +.PP +The age field only applies to lines starting with +\fId\fR, +\fID\fR, +\fIe\fR, +\fIv\fR, +\fIq\fR, +\fIQ\fR, +\fIC\fR, +\fIx\fR +and +\fIX\fR\&. If omitted or set to +"\-", no automatic clean\-up is done\&. +.PP +If the age field starts with a tilde character +"~", clean\-up is only applied to files and directories one level inside the directory specified, but not the files and directories immediately inside it\&. +.PP +The age of a file system entry is determined from its last modification timestamp (mtime), its last access timestamp (atime), and (except for directories) its last status change timestamp (ctime)\&. By default, any of these three (or two) values will prevent cleanup if it is more recent than the current time minus the age field\&. To restrict the deletion based on particular type of file timestamps, the age\-by argument can be used\&. +.PP +The age\-by argument overrides the timestamp types to be used for the age check\&. It can be specified by prefixing the age argument with a sequence of characters to specify the timestamp types and a colon (":"): +"\fIage\-by\fR\&.\&.\&.:\fIcleanup\-age\fR"\&. The argument can consist of +\fBa\fR +(\fBA\fR +for directories), +\fBb\fR +(\fBB\fR +for directories), +\fBc\fR +(\fBC\fR +for directories), or +\fBm\fR +(\fBM\fR +for directories)\&. Those respectively indicate access, creation, last status change, and last modification time of a file system entry\&. The lower\-case letter signifies that the given timestamp type should be considered for files, while the upper\-case letter signifies that the given timestamp type should be considered for directories\&. See +\fBstatx\fR(2) +file timestamp fields for more details about timestamp types\&. +.PP +If not specified, the age\-by field defaults to +\fBabcmABM\fR, i\&.e\&. by default all file timestamps are taken into consideration, with the exception of the last status change timestamp (ctime) for directories\&. This is because the aging logic itself will alter the ctime whenever it deletes a file inside it\&. To ensure that running the aging logic does not feed back into the next iteration of itself, ctime for directories is ignored by default\&. +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# Files created and modified, and directories accessed more than +# an hour ago in "/tmp/foo/bar", are subject to time\-based cleanup\&. +d /tmp/foo/bar \- \- \- bmA:1h \- +.fi +.if n \{\ +.RE +.\} +.PP +Note that while the aging algorithm is run an exclusive BSD file lock (see +\fBflock\fR(2)) is taken on each directory/file the algorithm decides to remove\&. If the aging algorithm finds a lock (shared or exclusive) is already taken on some directory/file, it (and everything below it) is skipped\&. Applications may use this to temporarily exclude certain directory subtrees from the aging algorithm: the applications can take a BSD file lock themselves, and as long as they keep it aging of the directory/file and everything below it is disabled\&. +.PP +This behavior can be used to ensure guaranteed cleanup of files or directories whose lifetime should be aligned with the process that created them by having that process create them in a location monitored by +\fBsystemd\-tmpfiles\fR +with an age of +"0", and having the process immediately lock the directory or file before using it\&. Because the BSD lock is process specific, the file is guaranteed to be unlocked as soon as the process exits, meaning that even if the process crashes, those files and directories will be unlocked and cleaned up by +\fBsystemd\-tmpfiles\fR\&. +.SS "Argument" +.PP +For +\fIL\fR +lines determines the destination path of the symlink\&. For +\fIc\fR +and +\fIb\fR, determines the major/minor of the device node, with major and minor formatted as integers, separated by +":", e\&.g\&. +"1:3"\&. For +\fIf\fR, +\fIF\fR, and +\fIw\fR, the argument may be used to specify a short string that is written to the file, suffixed by a newline\&. For +\fIC\fR, specifies the source file or directory\&. For +\fIt\fR +and +\fIT\fR, determines extended attributes to be set\&. For +\fIa\fR +and +\fIA\fR, determines ACL attributes to be set\&. For +\fIh\fR +and +\fIH\fR, determines the file attributes to set\&. Ignored for all other lines\&. +.PP +This field can contain specifiers, see below\&. +.SH "SPECIFIERS" +.PP +Specifiers can be used in the "path" and "argument" fields\&. An unknown or unresolvable specifier is treated as invalid configuration\&. The following expansions are understood: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Specifiers available +.TS +allbox tab(:); +lB lB lB. +T{ +Specifier +T}:T{ +Meaning +T}:T{ +Details +T} +.T& +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l +l l l. +T{ +"%a" +T}:T{ +Architecture +T}:T{ +A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&. +T} +T{ +"%A" +T}:T{ +Operating system image version +T}:T{ +The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%b" +T}:T{ +Boot ID +T}:T{ +The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&. +T} +T{ +"%B" +T}:T{ +Operating system build ID +T}:T{ +The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%C" +T}:T{ +System or user cache directory +T}:T{ +In \fB\-\-user\fR mode, this is the same as \fI$XDG_CACHE_HOME\fR, and /var/cache otherwise\&. +T} +T{ +"%g" +T}:T{ +User group +T}:T{ +This is the name of the group running the command\&. In case of the system instance this resolves to "root"\&. +T} +T{ +"%G" +T}:T{ +User GID +T}:T{ +This is the numeric GID of the group running the command\&. In case of the system instance this resolves to \fB0\fR\&. +T} +T{ +"%h" +T}:T{ +User home directory +T}:T{ +This is the home directory of the user running the command\&. In case of the system instance this resolves to "/root"\&. +T} +T{ +"%H" +T}:T{ +Host name +T}:T{ +The hostname of the running system\&. +T} +T{ +"%l" +T}:T{ +Short host name +T}:T{ +The hostname of the running system, truncated at the first dot to remove any domain component\&. +T} +T{ +"%L" +T}:T{ +System or user log directory +T}:T{ +In \fB\-\-user\fR mode, this is the same as \fI$XDG_STATE_HOME\fR with /log appended, and /var/log otherwise\&. +T} +T{ +"%m" +T}:T{ +Machine ID +T}:T{ +The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&. +T} +T{ +"%M" +T}:T{ +Operating system image identifier +T}:T{ +The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%o" +T}:T{ +Operating system ID +T}:T{ +The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%S" +T}:T{ +System or user state directory +T}:T{ +In \fB\-\-user\fR mode, this is the same as \fI$XDG_STATE_HOME\fR, and /var/lib otherwise\&. +T} +T{ +"%t" +T}:T{ +System or user runtime directory +T}:T{ +In \fB\-\-user\fR mode, this is the same \fI$XDG_RUNTIME_DIR\fR, and /run/ otherwise\&. +T} +T{ +"%T" +T}:T{ +Directory for temporary files +T}:T{ +This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%u" +T}:T{ +User name +T}:T{ +This is the name of the user running the command\&. In case of the system instance this resolves to "root"\&. +T} +T{ +"%U" +T}:T{ +User UID +T}:T{ +This is the numeric UID of the user running the command\&. In case of the system instance this resolves to \fB0\fR\&. +T} +T{ +"%v" +T}:T{ +Kernel release +T}:T{ +Identical to \fBuname \-r\fR output\&. +T} +T{ +"%V" +T}:T{ +Directory for larger and persistent temporary files +T}:T{ +This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.) +T} +T{ +"%w" +T}:T{ +Operating system version ID +T}:T{ +The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%W" +T}:T{ +Operating system variant ID +T}:T{ +The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&. +T} +T{ +"%%" +T}:T{ +Single percent sign +T}:T{ +Use "%%" in place of "%" to specify a single percent sign\&. +T} +.TE +.sp 1 +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Create directories with specific mode and ownership\fR +.PP +\fBscreen\fR(1), needs two directories created at boot with specific modes and ownership: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/tmpfiles\&.d/screen\&.conf +d /run/screens 1777 root screen 10d +d /run/uscreens 0755 root screen 10d12h +.fi +.if n \{\ +.RE +.\} +.PP +Contents of +/run/screens +and /run/uscreens will be cleaned up after 10 and 10\(12 days, respectively\&. +.PP +\fBExample\ \&2.\ \&Create a directory with a SMACK attribute\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +D /run/cups \- \- \- \- +t /run/cups \- \- \- \- security\&.SMACK64=printing user\&.attr\-with\-spaces="foo bar" + +.fi +.if n \{\ +.RE +.\} +.PP +The directory will be owned by root and have default mode\&. Its contents are not subject to time\-based cleanup, but will be obliterated when +\fBsystemd\-tmpfiles \-\-remove\fR +runs\&. +.PP +\fBExample\ \&3.\ \&Create a directory and prevent its contents from cleanup\fR +.PP +\fBabrt\fR(1), needs a directory created at boot with specific mode and ownership and its content should be preserved from the automatic cleanup applied to the contents of +/var/tmp: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/tmpfiles\&.d/tmp\&.conf +d /var/tmp 1777 root root 30d +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/tmpfiles\&.d/abrt\&.conf +d /var/tmp/abrt 0755 abrt abrt \- +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&Apply clean up during boot and based on time\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/tmpfiles\&.d/dnf\&.conf +r! /var/cache/dnf/*/*/download_lock\&.pid +r! /var/cache/dnf/*/*/metadata_lock\&.pid +r! /var/lib/dnf/rpmdb_lock\&.pid +e /var/cache/dnf/ \- \- \- 30d +.fi +.if n \{\ +.RE +.\} +.PP +The lock files will be removed during boot\&. Any files and directories in +/var/cache/dnf/ +will be removed after they have not been accessed in 30 days\&. +.PP +\fBExample\ \&5.\ \&Empty the contents of a cache directory on boot\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /usr/lib/tmpfiles\&.d/krb5rcache\&.conf +e! /var/cache/krb5rcache \- \- \- 0 +.fi +.if n \{\ +.RE +.\} +.PP +Any files and subdirectories in +/var/cache/krb5rcache/ +will be removed on boot\&. The directory will not be created\&. +.PP +\fBExample\ \&6.\ \&Provision SSH public key access for root user via Credentials in QEMU\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +\-smbios type=11,value=io\&.systemd\&.credential\&.binary:tmpfiles\&.extra=$(echo "f~ /root/\&.ssh/authorized_keys 700 root root \- $(ssh\-add \-L | base64 \-w 0)" | base64 \-w 0) +.fi +.if n \{\ +.RE +.\} +.PP +By passing this line to QEMU, the public key of the current user will be encoded in base64, added to a tmpfiles\&.d line that tells +\fBsystemd\-tmpfiles\fR +to decode it into +/root/\&.ssh/authorized_keys, encode that line itself in base64 and pass it as a Credential that will be picked up by systemd from SMBIOS on boot\&. +.SH "/RUN/ AND /VAR/RUN/" +.PP +/var/run/ +is a deprecated symlink to +/run/, and applications should use the latter\&. +\fBsystemd\-tmpfiles\fR +will warn if +/var/run/ +is used\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-tmpfiles\fR(8), +\fBsystemd-delta\fR(1), +\fBsystemd.exec\fR(5), +\fBattr\fR(5), +\fBgetfattr\fR(1), +\fBsetfattr\fR(1), +\fBsetfacl\fR(1), +\fBgetfacl\fR(1), +\fBchattr\fR(1), +\fBbtrfs-subvolume\fR(8), +\fBbtrfs-qgroup\fR(8) +.SH "NOTES" +.IP " 1." 4 +Base64 decoded +.RS 4 +\%https://www.rfc-editor.org/rfc/rfc4648.html +.RE +.IP " 2." 4 +System and Service Credentials +.RS 4 +\%https://systemd.io/CREDENTIALS +.RE +.IP " 3." 4 +Notes on Resolvability of User and Group Names +.RS 4 +\%https://systemd.io/UIDS-GIDS/#notes-on-resolvability-of-user-and-group-names +.RE diff --git a/upstream/fedora-40/man5/tmpfs.5 b/upstream/fedora-40/man5/tmpfs.5 new file mode 100644 index 00000000..b7c5f407 --- /dev/null +++ b/upstream/fedora-40/man5/tmpfs.5 @@ -0,0 +1,281 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tmpfs 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +tmpfs \- a virtual memory filesystem +.SH DESCRIPTION +The +.B tmpfs +facility allows the creation of filesystems whose contents reside +in virtual memory. +Since the files on such filesystems typically reside in RAM, +file access is extremely fast. +.P +The filesystem is automatically created when mounting +a filesystem with the type +.B tmpfs +via a command such as the following: +.P +.in +4n +.EX +$ sudo mount \-t tmpfs \-o size=10M tmpfs /mnt/mytmpfs +.EE +.in +.P +A +.B tmpfs +filesystem has the following properties: +.IP \[bu] 3 +The filesystem can employ swap space when physical memory pressure +demands it. +.IP \[bu] +The filesystem consumes only as much physical memory and swap space +as is required to store the current contents of the filesystem. +.IP \[bu] +During a remount operation +.RI ( "mount\ \-o\ remount" ), +the filesystem size can be changed +(without losing the existing contents of the filesystem). +.P +If a +.B tmpfs +filesystem is unmounted, its contents are discarded (lost). +.\" See mm/shmem.c:shmem_parse_options for options it supports. +.SS Mount options +The +.B tmpfs +filesystem supports the following mount options: +.TP +.BR size "=\fIbytes\fP" +Specify an upper limit on the size of the filesystem. +The size is given in bytes, and rounded up to entire pages. +The limit is removed if the size is +.BR 0 . +.IP +The size may have a +.BR k , +.BR m , +or +.B g +suffix for Ki, Mi, Gi (binary kilo (kibi), binary mega (mebi), and binary giga +(gibi)). +.IP +The size may also have a % suffix to limit this instance to a percentage of +physical RAM. +.IP +The default, when neither +.B size +nor +.B nr_blocks +is specified, is +.IR size=50% . +.TP +.BR nr_blocks "=\fIblocks\fP" +The same as +.BR size , +but in blocks of +.BR PAGE_CACHE_SIZE . +.IP +Blocks may be specified with +.BR k , +.BR m , +or +.B g +suffixes like +.BR size , +but not a % suffix. +.TP +.BR nr_inodes "=\fIinodes\fP" +The maximum number of inodes for this instance. +The default is half of the number of your physical RAM pages, or (on a +machine with highmem) the number of lowmem RAM pages, whichever is smaller. +The limit is removed if the number is +.BR 0 . +.IP +Inodes may be specified with +.BR k , +.BR m , +or +.B g +suffixes like +.BR size , +but not a % suffix. +.TP +.BR noswap "(since Linux 6.4)" +.\" commit 2c6efe9cf2d7841b75fe38ed1adbd41a90f51ba0 +Disables swap. +Remounts must respect the original settings. +By default swap is enabled. +.TP +.BR mode "=\fImode\fP" +Set initial permissions of the root directory. +.TP +.BR gid "=\fIgid\fP (since Linux 2.5.7)" +.\" Technically this is also in some version of Linux 2.4. +.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096 +Set the initial group ID of the root directory. +.TP +.BR uid "=\fIuid\fP (since Linux 2.5.7)" +.\" Technically this is also in some version of Linux 2.4. +.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096 +Set the initial user ID of the root directory. +.TP +.BR huge "=\fIhuge_option\fR (since Linux 4.7.0)" +.\" commit 5a6e75f8110c97e2a5488894d4e922187e6cb343 +Set the huge table memory allocation policy for all files in this instance (if +.B CONFIG_TRANSPARENT_HUGEPAGE +is enabled). +.IP +The +.I huge_option +value is one of the following: +.RS +.TP +.B never +Do not allocate huge pages. +This is the default. +.TP +.B always +Attempt to allocate huge pages every time a new page is needed. +.TP +.B within_size +Only allocate huge page if it will be fully within +.IR i_size . +Also respect +.BR fadvise (2) +and +.BR madvise (2) +hints +.TP +.B advise +Only allocate huge pages if requested with +.BR fadvise (2) +or +.BR madvise (2). +.TP +.B deny +For use in emergencies, to force the huge option off from all mounts. +.TP +.B force +Force the huge option on for all mounts; useful for testing. +.RE +.TP +.BR mpol "=\fImpol_option\fR (since Linux 2.6.15)" +.\" commit 7339ff8302fd70aabf5f1ae26e0c4905fa74a495 +Set the NUMA memory allocation policy for all files in this instance (if +.B CONFIG_NUMA +is enabled). +.IP +The +.I mpol_option +value is one of the following: +.RS +.TP +.B default +Use the process allocation policy (see +.BR set_mempolicy (2)). +.TP +.BR prefer ":\fInode\fP" +Preferably allocate memory from the given +.IR node . +.TP +.BR bind ":\fInodelist\fP" +Allocate memory only from nodes in +.IR nodelist . +.TP +.B interleave +Allocate from each node in turn. +.TP +.BR interleave ":\fInodelist\fP" +Allocate from each node of +.I in +turn. +.TP +.B local +Preferably allocate memory from the local node. +.RE +.IP +In the above, +.I nodelist +is a comma-separated list of decimal numbers and ranges +that specify NUMA nodes. +A range is a pair of hyphen-separated decimal numbers, +the smallest and largest node numbers in the range. +For example, +.IR mpol=bind:0\-3,5,7,9\-15 . +.SH VERSIONS +The +.B tmpfs +facility was added in Linux 2.4, as a successor to the older +.B ramfs +facility, which did not provide limit checking or +allow for the use of swap space. +.SH NOTES +In order for user-space tools and applications to create +.B tmpfs +filesystems, the kernel must be configured with the +.B CONFIG_TMPFS +option. +.P +The +.B tmpfs +filesystem supports extended attributes (see +.BR xattr (7)), +but +.I user +extended attributes are not permitted. +.P +An internal shared memory filesystem is used for +System V shared memory +.RB ( shmget (2)) +and shared anonymous mappings +.RB ( mmap (2) +with the +.B MAP_SHARED +and +.B MAP_ANONYMOUS +flags). +This filesystem is available regardless of whether +the kernel was configured with the +.B CONFIG_TMPFS +option. +.P +A +.B tmpfs +filesystem mounted at +.I /dev/shm +is used for the implementation of POSIX shared memory +.RB ( shm_overview (7)) +and POSIX semaphores +.RB ( sem_overview (7)). +.P +The amount of memory consumed by all +.B tmpfs +filesystems is shown in the +.I Shmem +field of +.I /proc/meminfo +and in the +.I shared +field displayed by +.BR free (1). +.P +The +.B tmpfs +facility was formerly called +.BR shmfs . +.SH SEE ALSO +.BR df (1), +.BR du (1), +.BR memfd_create (2), +.BR mmap (2), +.BR set_mempolicy (2), +.BR shm_open (3), +.BR mount (8) +.P +The kernel source files +.I Documentation/filesystems/tmpfs.txt +and +.IR Documentation/admin\-guide/mm/transhuge.rst . diff --git a/upstream/fedora-40/man5/ttytype.5 b/upstream/fedora-40/man5/ttytype.5 new file mode 100644 index 00000000..3e9a5a3d --- /dev/null +++ b/upstream/fedora-40/man5/ttytype.5 @@ -0,0 +1,56 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:17:50 1993 by Rik Faith +.\" Modified Thu Oct 19 21:25:21 MET 1995 by Martin Schulze +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.\" xk +.TH ttytype 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +ttytype \- terminal device to default terminal type mapping +.SH DESCRIPTION +The +.I /etc/ttytype +file associates +.BR termcap (5) +and +.BR terminfo (5) +terminal type names +with tty lines. +Each line consists of a terminal type, followed by +whitespace, followed by a tty name (a device name without the +.I /dev/ +prefix). +.P +This association is used by the program +.BR tset (1) +to set the environment variable +.B TERM +to the default terminal name for +the user's current tty. +.P +This facility was designed for a traditional time-sharing environment +featuring character-cell terminals hardwired to a UNIX minicomputer. +It is little used on modern workstation and personal UNIX systems. +.SH FILES +.TP +.I /etc/ttytype +the tty definitions file. +.SH EXAMPLES +A typical +.I /etc/ttytype +is: +.P +.in +4n +.EX +con80x25 tty1 +vt320 ttys0 +.EE +.in +.SH SEE ALSO +.BR termcap (5), +.BR terminfo (5), +.BR agetty (8), +.BR mingetty (8) diff --git a/upstream/fedora-40/man5/tzfile.5 b/upstream/fedora-40/man5/tzfile.5 new file mode 100644 index 00000000..45afecc1 --- /dev/null +++ b/upstream/fedora-40/man5/tzfile.5 @@ -0,0 +1,496 @@ +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. +.TH tzfile 5 "" "Time Zone Database" +.SH NAME +tzfile \- timezone information +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.ie \n(.g .ds - \f(CR-\fP +.el .ds - \- +The timezone information files used by +.BR tzset (3) +are typically found under a directory with a name like +.IR /usr/share/zoneinfo . +These files use the format described in Internet RFC 8536. +Each file is a sequence of 8-bit bytes. +In a file, a binary integer is represented by a sequence of one or +more bytes in network order (bigendian, or high-order byte first), +with all bits significant, +a signed binary integer is represented using two's complement, +and a boolean is represented by a one-byte binary integer that is +either 0 (false) or 1 (true). +The format begins with a 44-byte header containing the following fields: +.IP * 2 +The magic four-byte ASCII sequence +.q "TZif" +identifies the file as a timezone information file. +.IP * +A byte identifying the version of the file's format +(as of 2021, either an ASCII NUL, +.q "2", +.q "3", +or +.q "4" ). +.IP * +Fifteen bytes containing zeros reserved for future use. +.IP * +Six four-byte integer values, in the following order: +.RS +.TP +.B tzh_ttisutcnt +The number of UT/local indicators stored in the file. +(UT is Universal Time.) +.TP +.B tzh_ttisstdcnt +The number of standard/wall indicators stored in the file. +.TP +.B tzh_leapcnt +The number of leap seconds for which data entries are stored in the file. +.TP +.B tzh_timecnt +The number of transition times for which data entries are stored +in the file. +.TP +.B tzh_typecnt +The number of local time types for which data entries are stored +in the file (must not be zero). +.TP +.B tzh_charcnt +The number of bytes of time zone abbreviation strings +stored in the file. +.RE +.P +The above header is followed by the following fields, whose lengths +depend on the contents of the header: +.IP * 2 +.B tzh_timecnt +four-byte signed integer values sorted in ascending order. +These values are written in network byte order. +Each is used as a transition time (as returned by +.BR time (2)) +at which the rules for computing local time change. +.IP * +.B tzh_timecnt +one-byte unsigned integer values; +each one but the last tells which of the different types of local time types +described in the file is associated with the time period +starting with the same-indexed transition time +and continuing up to but not including the next transition time. +(The last time type is present only for consistency checking with the +POSIX-style TZ string described below.) +These values serve as indices into the next field. +.IP * +.B tzh_typecnt +.B ttinfo +entries, each defined as follows: +.in +.5i +.sp +.nf +.ta .5i +\w'unsigned char\0\0'u +struct ttinfo { + int32_t tt_utoff; + unsigned char tt_isdst; + unsigned char tt_desigidx; +}; +.in -.5i +.fi +.sp +Each structure is written as a four-byte signed integer value for +.BR tt_utoff , +in network byte order, followed by a one-byte boolean for +.B tt_isdst +and a one-byte value for +.BR tt_desigidx . +In each structure, +.B tt_utoff +gives the number of seconds to be added to UT, +.B tt_isdst +tells whether +.B tm_isdst +should be set by +.BR localtime (3) +and +.B tt_desigidx +serves as an index into the array of time zone abbreviation bytes +that follow the +.B ttinfo +entries in the file; if the designated string is "\*-00", the +.B ttinfo +entry is a placeholder indicating that local time is unspecified. +The +.B tt_utoff +value is never equal to \-2**31, to let 32-bit clients negate it without +overflow. +Also, in realistic applications +.B tt_utoff +is in the range [\-89999, 93599] (i.e., more than \-25 hours and less +than 26 hours); this allows easy support by implementations that +already support the POSIX-required range [\-24:59:59, 25:59:59]. +.IP * +.B tzh_charcnt +bytes that represent time zone designations, +which are null-terminated byte strings, each indexed by the +.B tt_desigidx +values mentioned above. +The byte strings can overlap if one is a suffix of the other. +The encoding of these strings is not specified. +.IP * +.B tzh_leapcnt +pairs of four-byte values, written in network byte order; +the first value of each pair gives the nonnegative time +(as returned by +.BR time (2)) +at which a leap second occurs or at which the leap second table expires; +the second is a signed integer specifying the correction, which is the +.I total +number of leap seconds to be applied during the time period +starting at the given time. +The pairs of values are sorted in strictly ascending order by time. +Each pair denotes one leap second, either positive or negative, +except that if the last pair has the same correction as the previous one, +the last pair denotes the leap second table's expiration time. +Each leap second is at the end of a UTC calendar month. +The first leap second has a nonnegative occurrence time, +and is a positive leap second if and only if its correction is positive; +the correction for each leap second after the first differs +from the previous leap second by either 1 for a positive leap second, +or \-1 for a negative leap second. +If the leap second table is empty, the leap-second correction is zero +for all timestamps; +otherwise, for timestamps before the first occurrence time, +the leap-second correction is zero if the first pair's correction is 1 or \-1, +and is unspecified otherwise (which can happen only in files +truncated at the start). +.IP * +.B tzh_ttisstdcnt +standard/wall indicators, each stored as a one-byte boolean; +they tell whether the transition times associated with local time types +were specified as standard time or local (wall clock) time. +.IP * +.B tzh_ttisutcnt +UT/local indicators, each stored as a one-byte boolean; +they tell whether the transition times associated with local time types +were specified as UT or local time. +If a UT/local indicator is set, the corresponding standard/wall indicator +must also be set. +.P +The standard/wall and UT/local indicators were designed for +transforming a TZif file's transition times into transitions appropriate +for another time zone specified via a POSIX-style TZ string that lacks rules. +For example, when TZ="EET\*-2EEST" and there is no TZif file "EET\*-2EEST", +the idea was to adapt the transition times from a TZif file with the +well-known name "posixrules" that is present only for this purpose and +is a copy of the file "Europe/Brussels", a file with a different UT offset. +POSIX does not specify this obsolete transformational behavior, +the default rules are installation-dependent, and no implementation +is known to support this feature for timestamps past 2037, +so users desiring (say) Greek time should instead specify +TZ="Europe/Athens" for better historical coverage, falling back on +TZ="EET\*-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required +and older timestamps need not be handled accurately. +.P +The +.BR localtime (3) +function +normally uses the first +.B ttinfo +structure in the file +if either +.B tzh_timecnt +is zero or the time argument is less than the first transition time recorded +in the file. +.SS Version 2 format +For version-2-format timezone files, +the above header and data are followed by a second header and data, +identical in format except that +eight bytes are used for each transition time or leap second time. +(Leap second counts remain four bytes.) +After the second header and data comes a newline-enclosed, +POSIX-TZ-environment-variable-style string for use in handling instants +after the last transition time stored in the file +or for all instants if the file has no transitions. +The POSIX-style TZ string is empty (i.e., nothing between the newlines) +if there is no POSIX-style representation for such instants. +If nonempty, the POSIX-style TZ string must agree with the local time +type after the last transition time if present in the eight-byte data; +for example, given the string +.q "WET0WEST,M3.5.0/1,M10.5.0" +then if a last transition time is in July, the transition's local time +type must specify a daylight-saving time abbreviated +.q "WEST" +that is one hour east of UT. +Also, if there is at least one transition, time type 0 is associated +with the time period from the indefinite past up to but not including +the earliest transition time. +.SS Version 3 format +For version-3-format timezone files, the POSIX-TZ-style string may +use two minor extensions to the POSIX TZ format, as described in +.BR newtzset (3). +First, the hours part of its transition times may be signed and range from +\-167 through 167 instead of the POSIX-required unsigned values +from 0 through 24. +Second, DST is in effect all year if it starts +January 1 at 00:00 and ends December 31 at 24:00 plus the difference +between daylight saving and standard time. +.SS Version 4 format +For version-4-format TZif files, +the first leap second record can have a correction that is neither ++1 nor \-1, to represent truncation of the TZif file at the start. +Also, if two or more leap second transitions are present and the last +entry's correction equals the previous one, the last entry +denotes the expiration of the leap second table instead of a leap second; +timestamps after this expiration are unreliable in that future +releases will likely add leap second entries after the expiration, and +the added leap seconds will change how post-expiration timestamps are treated. +.SS Interoperability considerations +Future changes to the format may append more data. +.P +Version 1 files are considered a legacy format and +should not be generated, as they do not support transition +times after the year 2038. +Readers that understand only Version 1 must ignore +any data that extends beyond the calculated end of the version +1 data block. +.P +Other than version 1, writers should generate +the lowest version number needed by a file's data. +For example, a writer should generate a version 4 file +only if its leap second table either expires or is truncated at the start. +Likewise, a writer not generating a version 4 file +should generate a version 3 file only if +TZ string extensions are necessary to accurately +model transition times. +.P +The sequence of time changes defined by the version 1 +header and data block should be a contiguous sub-sequence +of the time changes defined by the version 2+ header and data +block, and by the footer. +This guideline helps obsolescent version 1 readers +agree with current readers about timestamps within the +contiguous sub-sequence. It also lets writers not +supporting obsolescent readers use a +.B tzh_timecnt +of zero +in the version 1 data block to save space. +.P +When a TZif file contains a leap second table expiration +time, TZif readers should either refuse to process +post-expiration timestamps, or process them as if the expiration +time did not exist (possibly with an error indication). +.P +Time zone designations should consist of at least three (3) +and no more than six (6) ASCII characters from the set of +alphanumerics, +.q "\*-", +and +.q "+". +This is for compatibility with POSIX requirements for +time zone abbreviations. +.P +When reading a version 2 or higher file, readers +should ignore the version 1 header and data block except for +the purpose of skipping over them. +.P +Readers should calculate the total lengths of the +headers and data blocks and check that they all fit within +the actual file size, as part of a validity check for the file. +.P +When a positive leap second occurs, readers should append an extra +second to the local minute containing the second just before the leap +second. If this occurs when the UTC offset is not a multiple of 60 +seconds, the leap second occurs earlier than the last second of the +local minute and the minute's remaining local seconds are numbered +through 60 instead of the usual 59; the UTC offset is unaffected. +.SS Common interoperability issues +This section documents common problems in reading or writing TZif files. +Most of these are problems in generating TZif files for use by +older readers. +The goals of this section are: +.IP * 2 +to help TZif writers output files that avoid common +pitfalls in older or buggy TZif readers, +.IP * +to help TZif readers avoid common pitfalls when reading +files generated by future TZif writers, and +.IP * +to help any future specification authors see what sort of +problems arise when the TZif format is changed. +.P +When new versions of the TZif format have been defined, a +design goal has been that a reader can successfully use a TZif +file even if the file is of a later TZif version than what the +reader was designed for. +When complete compatibility was not achieved, an attempt was +made to limit glitches to rarely used timestamps and allow +simple partial workarounds in writers designed to generate +new-version data useful even for older-version readers. +This section attempts to document these compatibility issues and +workarounds, as well as to document other common bugs in +readers. +.P +Interoperability problems with TZif include the following: +.IP * 2 +Some readers examine only version 1 data. +As a partial workaround, a writer can output as much version 1 +data as possible. +However, a reader should ignore version 1 data, and should use +version 2+ data even if the reader's native timestamps have only +32 bits. +.IP * +Some readers designed for version 2 might mishandle +timestamps after a version 3 or higher file's last transition, because +they cannot parse extensions to POSIX in the TZ-like string. +As a partial workaround, a writer can output more transitions +than necessary, so that only far-future timestamps are +mishandled by version 2 readers. +.IP * +Some readers designed for version 2 do not support +permanent daylight saving time with transitions after 24:00 +\(en e.g., a TZ string +.q "EST5EDT,0/0,J365/25" +denoting permanent Eastern Daylight Time +(\-04). +As a workaround, a writer can substitute standard time +for two time zones east, e.g., +.q "XXX3EDT4,0/0,J365/23" +for a time zone with a never-used standard time (XXX, \-03) +and negative daylight saving time (EDT, \-04) all year. +Alternatively, +as a partial workaround a writer can substitute standard time +for the next time zone east \(en e.g., +.q "AST4" +for permanent +Atlantic Standard Time (\-04). +.IP * +Some readers designed for version 2 or 3, and that require strict +conformance to RFC 8536, reject version 4 files whose leap second +tables are truncated at the start or that end in expiration times. +.IP * +Some readers ignore the footer, and instead predict future +timestamps from the time type of the last transition. +As a partial workaround, a writer can output more transitions +than necessary. +.IP * +Some readers do not use time type 0 for timestamps before +the first transition, in that they infer a time type using a +heuristic that does not always select time type 0. +As a partial workaround, a writer can output a dummy (no-op) +first transition at an early time. +.IP * +Some readers mishandle timestamps before the first +transition that has a timestamp not less than \-2**31. +Readers that support only 32-bit timestamps are likely to be +more prone to this problem, for example, when they process +64-bit transitions only some of which are representable in 32 +bits. +As a partial workaround, a writer can output a dummy +transition at timestamp \-2**31. +.IP * +Some readers mishandle a transition if its timestamp has +the minimum possible signed 64-bit value. +Timestamps less than \-2**59 are not recommended. +.IP * +Some readers mishandle POSIX-style TZ strings that +contain +.q "<" +or +.q ">". +As a partial workaround, a writer can avoid using +.q "<" +or +.q ">" +for time zone abbreviations containing only alphabetic +characters. +.IP * +Many readers mishandle time zone abbreviations that contain +non-ASCII characters. +These characters are not recommended. +.IP * +Some readers may mishandle time zone abbreviations that +contain fewer than 3 or more than 6 characters, or that +contain ASCII characters other than alphanumerics, +.q "\*-", +and +.q "+". +These abbreviations are not recommended. +.IP * +Some readers mishandle TZif files that specify +daylight-saving time UT offsets that are less than the UT +offsets for the corresponding standard time. +These readers do not support locations like Ireland, which +uses the equivalent of the POSIX TZ string +.q "IST\*-1GMT0,M10.5.0,M3.5.0/1", +observing standard time +(IST, +01) in summer and daylight saving time (GMT, +00) in winter. +As a partial workaround, a writer can output data for the +equivalent of the POSIX TZ string +.q "GMT0IST,M3.5.0/1,M10.5.0", +thus swapping standard and daylight saving time. +Although this workaround misidentifies which part of the year +uses daylight saving time, it records UT offsets and time zone +abbreviations correctly. +.IP * +Some readers generate ambiguous timestamps for positive leap seconds +that occur when the UTC offset is not a multiple of 60 seconds. +For example, in a timezone with UTC offset +01:23:45 and with +a positive leap second 78796801 (1972-06-30 23:59:60 UTC), some readers will +map both 78796800 and 78796801 to 01:23:45 local time the next day +instead of mapping the latter to 01:23:46, and they will map 78796815 to +01:23:59 instead of to 01:23:60. +This has not yet been a practical problem, since no civil authority +has observed such UTC offsets since leap seconds were +introduced in 1972. +.P +Some interoperability problems are reader bugs that +are listed here mostly as warnings to developers of readers. +.IP * 2 +Some readers do not support negative timestamps. +Developers of distributed applications should keep this +in mind if they need to deal with pre-1970 data. +.IP * +Some readers mishandle timestamps before the first +transition that has a nonnegative timestamp. +Readers that do not support negative timestamps are likely to +be more prone to this problem. +.IP * +Some readers mishandle time zone abbreviations like +.q "\*-08" +that contain +.q "+", +.q "\*-", +or digits. +.IP * +Some readers mishandle UT offsets that are out of the +traditional range of \-12 through +12 hours, and so do not +support locations like Kiritimati that are outside this +range. +.IP * +Some readers mishandle UT offsets in the range [\-3599, \-1] +seconds from UT, because they integer-divide the offset by +3600 to get 0 and then display the hour part as +.q "+00". +.IP * +Some readers mishandle UT offsets that are not a multiple +of one hour, or of 15 minutes, or of 1 minute. +.SH SEE ALSO +.BR time (2), +.BR localtime (3), +.BR tzset (3), +.BR tzselect (8), +.BR zdump (8), +.BR zic (8). +.P +Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif). +2019 Feb. +.UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536 +Internet RFC 8536 +.UE +.UR https://\:doi.org/\:10.17487/\:RFC8536 +doi:10.17487/RFC8536 +.UE . diff --git a/upstream/fedora-40/man5/udev.conf.5 b/upstream/fedora-40/man5/udev.conf.5 new file mode 100644 index 00000000..db1e9cec --- /dev/null +++ b/upstream/fedora-40/man5/udev.conf.5 @@ -0,0 +1,112 @@ +'\" t +.TH "UDEV\&.CONF" "5" "" "systemd 255" "udev.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +udev.conf \- Configuration for device event managing daemon +.SH "SYNOPSIS" +.PP +/etc/udev/udev\&.conf +.SH "DESCRIPTION" +.PP +\fBsystemd-udevd\fR(8) +expects its main configuration file at +/etc/udev/udev\&.conf\&. It consists of a set of variables allowing the user to override default udev values\&. All empty lines or lines beginning with \*(Aq#\*(Aq are ignored\&. The following variables can be set: +.PP +\fIudev_log=\fR +.RS 4 +The log level\&. Valid values are the numerical syslog priorities or their textual representations: +\fBerr\fR, +\fBinfo\fR +and +\fBdebug\fR\&. +.sp +Added in version 216\&. +.RE +.PP +\fIchildren_max=\fR +.RS 4 +An integer\&. The maximum number of events executed in parallel\&. When unspecified or 0 is specified, the maximum is determined based on the system resources\&. +.sp +This is the same as the +\fB\-\-children\-max=\fR +option\&. +.sp +Added in version 240\&. +.RE +.PP +\fIexec_delay=\fR +.RS 4 +An integer\&. Delay the execution of each +\fIRUN{\fR\fI\fIprogram\fR\fR\fI}\fR +parameter by the given number of seconds\&. This option might be useful when debugging system crashes during coldplug caused by loading non\-working kernel modules\&. +.sp +This is the same as the +\fB\-\-exec\-delay=\fR +option\&. +.sp +Added in version 240\&. +.RE +.PP +\fIevent_timeout=\fR +.RS 4 +An integer\&. The number of seconds to wait for events to finish\&. After this time, the event will be terminated\&. The default is 180 seconds\&. +.sp +This is the same as the +\fB\-\-event\-timeout=\fR +option\&. +.sp +Added in version 240\&. +.RE +.PP +\fIresolve_names=\fR +.RS 4 +Specifies when systemd\-udevd should resolve names of users and groups\&. When set to +\fBearly\fR +(the default), names will be resolved when the rules are parsed\&. When set to +\fBlate\fR, names will be resolved for every event\&. When set to +\fBnever\fR, names will never be resolved and all devices will be owned by root\&. +.sp +This is the same as the +\fB\-\-resolve\-names=\fR +option\&. +.sp +Added in version 240\&. +.RE +.PP +\fItimeout_signal=\fR +.RS 4 +Specifies a signal that +systemd\-udevd +will send on worker timeouts\&. Note that both workers and spawned processes will be killed using this signal\&. Defaults to +\fBSIGKILL\fR\&. +.sp +Added in version 246\&. +.RE +.PP +In addition, +systemd\-udevd +can be configured by command line options and the kernel command line (see +\fBsystemd-udevd\fR(8))\&. +.SH "SEE ALSO" +.PP +\fBsystemd-udevd\fR(8), +\fBudev\fR(7), +\fBudevadm\fR(8) diff --git a/upstream/fedora-40/man5/updatedb.conf.5 b/upstream/fedora-40/man5/updatedb.conf.5 new file mode 100644 index 00000000..89181379 --- /dev/null +++ b/upstream/fedora-40/man5/updatedb.conf.5 @@ -0,0 +1,138 @@ +.\" A man page for updatedb.conf. -*- nroff -*- +.\" +.\" Copyright (C) 2005, 2007, 2008 Red Hat, Inc. All rights reserved. +.\" +.\" This copyrighted material is made available to anyone wishing to use, +.\" modify, copy, or redistribute it subject to the terms and conditions of the +.\" GNU General Public License v.2. +.\" +.\" This program is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +.\" more details. +.\" +.\" You should have received a copy of the GNU General Public License along +.\" with this program; if not, write to the Free Software Foundation, Inc., +.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +.\" +.\" Author: Miloslav Trmac +.TH updatedb.conf 5 "Jun 2008" mlocate + +.SH NAME +/etc/updatedb.conf \- a configuration file for updatedb(8) + +.SH DESCRIPTION +.B /etc/updatedb.conf +is a text file. +Blank lines are ignored. +A +.B # +character outside of a quoted string starts a comment +extending until end of line. + +Other lines must be of the following form: +.RS +.I VARIABLE +.B = +\fB"\fIVALUE\fB"\fR +.RE + +White space between tokens is ignored. +.I VARIABLE +is an alphanumeric string which does not start with a digit. +.I VALUE +can contain any character except for \fB\(dq\fR. +No escape mechanism is supported within +.I VALUE +and there is no way to write +.I VALUE +spanning more than one line. + +Unknown +.I VARIABLE +values are considered an error. +The defined variables are: + +.TP +\fBPRUNEFS\fR +A whitespace-separated list of file system types (as used in \fB/etc/mtab\fR) +which should not be scanned by +.BR updatedb (8). +The file system type matching is case-insensitive. By default, no file system +types are skipped. + +When scanning a file system is skipped, +all file systems mounted in the subtree are skipped too, +even if their type does not match any entry in \fBPRUNEFS\fR. + +.TP +\fBPRUNENAMES\fR +A whitespace-separated list of directory names (without paths) which should not +be scanned by +.BR updatedb (8). +By default, no directory names are skipped. + +Note that only directories can be specified, and no pattern mechanism (e.g. +globbing) is used. + +.TP +\fBPRUNEPATHS\fR +A whitespace-separated list of path names of directories which should not be +scanned by +.BR updatedb (8). +Each path name must be exactly in the form +in which the directory would be reported by +.BR locate (1). + +By default, no paths are skipped. + +.TP +\fBPRUNE_BIND_MOUNTS\FR +One of the strings \fB0\fR, \fBno\fR, \fB1\fR or \fByes\fR. +If +.B PRUNE_BIND_MOUNTS +is \fB1\fR or \fByes\fR, +bind mounts are not scanned by +.BR updatedb (8). +All file systems mounted in the subtree of a bind mount are skipped as well, +even if they are not bind mounts. +As an exception, bind mounts of a directory on itself are not skipped. + +By default, bind mounts are not skipped. + +.SH NOTES +When a directory is matched by \fBPRUNEFS\fR, \fBPRUNENAMES\fR or +\fBPRUNEPATHS\fR, +.BR updatedb (8) +does not scan the contents of the directory. +The path of the directory itself is, however, entered in the created database. +For example, if +.I /tmp +is in \fBPRUNEPATHS\fR, +.BR locate (1) +will not show any files stored in \fI/tmp\fR, +but it can show the +.I /tmp +directory. +This behavior differs from traditional +.B locate +implementations. + +In some +.BR updatedb (8) +implementations \fBPRUNEPATHS\fR can be used to exclude non-directory files. +This is not the case in this implementation. + +.B /etc/updatedb.conf +is a shell script in some implementations, +which allows much more flexibility in defining the variables. +Equivalent functionality can be achieved by using the command-line options +to +.BR updatedb (8). + +.SH AUTHOR +Miloslav Trmac + +.SH SEE ALSO +.BR locate (1), +.BR updatedb (8) diff --git a/upstream/fedora-40/man5/user@.service.5 b/upstream/fedora-40/man5/user@.service.5 new file mode 100644 index 00000000..0f068135 --- /dev/null +++ b/upstream/fedora-40/man5/user@.service.5 @@ -0,0 +1,197 @@ +'\" t +.TH "USER@\&.SERVICE" "5" "" "systemd 255" "user@.service" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +user@.service, user-runtime-dir@.service, systemd-user-runtime-dir \- System units to start the user manager +.SH "SYNOPSIS" +.PP +user@\fIUID\fR\&.service +.PP +user\-runtime\-dir@\fIUID\fR\&.service +.PP +/usr/lib/systemd/systemd\-user\-runtime\-dir +.PP +user\-\fIUID\fR\&.slice +.SH "DESCRIPTION" +.PP +The +\fBsystemd\fR(1) +system manager (PID 1) starts user manager instances as +user@\fIUID\fR\&.service, with the user\*(Aqs numerical UID used as the instance identifier\&. These instances use the same executable as the system manager, but running in a mode where it starts a different set of units\&. Each +\fBsystemd \-\-user\fR +instance manages a hierarchy of units specific to that user\&. See +\fBsystemd\fR(1) +for a discussion of units and +\fBsystemd.special\fR(7) +for a list of units that form the basis of the unit hierarchies of system and user units\&. +.PP +user@\fIUID\fR\&.service +is accompanied by the system unit +user\-runtime\-dir@\fIUID\fR\&.service, which creates the user\*(Aqs runtime directory +/run/user/\fIUID\fR, and then removes it when this unit is stopped\&. +user\-runtime\-dir@\fIUID\fR\&.service +executes the +systemd\-user\-runtime\-dir +binary to do the actual work\&. +.PP +User processes may be started by the +user@\&.service +instance, in which case they will be part of that unit in the system hierarchy\&. They may also be started elsewhere, for example by +\fBsshd\fR(8) +or a display manager like +\fBgdm\fR, in which case they form a \&.scope unit (see +\fBsystemd.scope\fR(5))\&. Both +user@\fIUID\fR\&.service +and the scope units are collected under the +user\-\fIUID\fR\&.slice\&. +.PP +Individual +user\-\fIUID\fR\&.slice +slices are collected under +user\&.slice, see +\fBsystemd.special\fR(7)\&. +.SH "CONTROLLING RESOURCES FOR LOGGED\-IN USERS" +.PP +Options that control resources available to logged\-in users can be configured at a few different levels\&. As described in the previous section, +user\&.slice +contains processes of all users, so any resource limits on that slice apply to all users together\&. The usual way to configure them would be through drop\-ins, e\&.g\&. +/etc/systemd/system/user\&.slice\&.d/resources\&.conf\&. +.PP +The processes of a single user are collected under +user\-\fIUID\fR\&.slice\&. Resource limits for that user can be configured through drop\-ins for that unit, e\&.g\&. +/etc/systemd/system/user\-1000\&.slice\&.d/resources\&.conf\&. If the limits should apply to all users instead, they may be configured through drop\-ins for the truncated unit name, +user\-\&.slice\&. For example, configuration in +/etc/systemd/system/user\-\&.slice\&.d/resources\&.conf +is included in all +user\-\fIUID\fR\&.slice +units, see +\fBsystemd.unit\fR(5) +for a discussion of the drop\-in mechanism\&. +.PP +When a user logs in and a \&.scope unit is created for the session (see previous section), the creation of the scope may be managed through +\fBpam_systemd\fR(8)\&. This PAM module communicates with +\fBsystemd-logind\fR(8) +to create the session scope and provide access to hardware resources\&. Resource limits for the scope may be configured through the PAM module configuration, see +\fBpam_systemd\fR(8)\&. Configuring them through the normal unit configuration is also possible, but since the name of the slice unit is generally unpredictable, this is less useful\&. +.PP +In general any resources that apply to units may be set for +user@\fIUID\fR\&.service +and the slice units discussed above, see +\fBsystemd.resource-control\fR(5) +for an overview\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Hierarchy of control groups with two logged in users\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemd\-cgls +Control group /: +\-\&.slice +├─user\&.slice +│ ├─user\-1000\&.slice +│ │ ├─user@1000\&.service +│ │ │ ├─pulseaudio\&.service +│ │ │ │ └─2386 /usr/bin/pulseaudio \-\-daemonize=no +│ │ │ └─gnome\-terminal\-server\&.service +│ │ │ └─init\&.scope +│ │ │ ├─ 4127 /usr/libexec/gnome\-terminal\-server +│ │ │ └─ 4198 zsh +│ │ \&... +│ │ └─session\-4\&.scope +│ │ ├─ 1264 gdm\-session\-worker [pam/gdm\-password] +│ │ ├─ 2339 /usr/bin/gnome\-shell +│ │ \&... +│ │ ├─session\-19\&.scope +│ │ ├─6497 sshd: zbyszek [priv] +│ │ ├─6502 sshd: zbyszek@pts/6 +│ │ ├─6509 \-zsh +│ │ └─6602 systemd\-cgls \-\-no\-pager +│ \&... +│ └─user\-1001\&.slice +│ ├─session\-20\&.scope +│ │ ├─6675 sshd: guest [priv] +│ │ ├─6708 sshd: guest@pts/6 +│ │ └─6717 \-bash +│ └─user@1001\&.service +│ ├─init\&.scope +│ │ ├─6680 /usr/lib/systemd/systemd \-\-user +│ │ └─6688 (sd\-pam) +│ └─sleep\&.service +│ └─6706 /usr/bin/sleep 30 +\&... +.fi +.if n \{\ +.RE +.\} +.PP +User with UID 1000 is logged in using +\fBgdm\fR +(session\-4\&.scope) and +\fBssh\fR(1) +(session\-19\&.scope), and also has a user manager instance running (user@1000\&.service)\&. User with UID 1001 is logged in using +\fBssh\fR +(session\-20\&.scope) and also has a user manager instance running (user@1001\&.service)\&. Those are all (leaf) system units, and form part of the slice hierarchy, with +user\-1000\&.slice +and +user\-1001\&.slice +below +user\&.slice\&. User units are visible below the +user@\&.service +instances (pulseaudio\&.service, +gnome\-terminal\-server\&.service, +init\&.scope, +sleep\&.service)\&. +.PP +\fBExample\ \&2.\ \&Default user resource limits\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemctl cat user\-1000\&.slice +# /usr/lib/systemd/system/user\-\&.slice\&.d/10\-defaults\&.conf +# \&... +[Unit] +Description=User Slice of UID %j +After=systemd\-user\-sessions\&.service + +[Slice] +TasksMax=33% +.fi +.if n \{\ +.RE +.\} +.PP +The +user\-\fIUID\fR\&.slice +units by default don\*(Aqt have a unit file\&. The resource limits are set through a drop\-in, which can be easily replaced or extended following standard drop\-in mechanisms discussed in the first section\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd.service\fR(5), +\fBsystemd.slice\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.special\fR(7), +\fBpam\fR(8) diff --git a/upstream/fedora-40/man5/user_caps.5 b/upstream/fedora-40/man5/user_caps.5 new file mode 100644 index 00000000..ad809362 --- /dev/null +++ b/upstream/fedora-40/man5/user_caps.5 @@ -0,0 +1,464 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: user_caps.5,v 1.47 2024/01/13 22:05:39 tom Exp $ +.TH user_caps 5 2024-01-13 "ncurses 6.4" "File formats" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +user_caps \- +user-defined \fIterminfo\fR capability format +.SH SYNOPSIS +.B infocmp \-x +.PP +.B tic \-x +.SH DESCRIPTION +.SS Background +Before \fI\%ncurses\fP 5.0, +terminfo databases used a \fIfixed repertoire\fP of terminal +capabilities designed for the SVr2 terminal database in 1984, +and extended in stages through SVr4 (1989), +and standardized in the Single Unix Specification beginning in 1995. +.PP +Most of the \fIextensions\fP in this fixed repertoire were additions +to the tables of Boolean, numeric and string capabilities. +Rather than change the meaning of an existing capability, a new name was added. +The terminfo database uses a binary format; binary compatibility was +ensured by using a header which gave the number of items in the +tables for each type of capability. +The standardization was incomplete: +.bP +The \fIbinary format\fP itself is not described +in the X/Open Curses documentation. +Only the \fIsource format\fP is described. +.IP +Library developers rely upon the SVr4 documentation, +and reverse-engineering the compiled terminfo files to match the binary format. +.bP +Lacking a standard for the binary format, most implementations +copy the SVr2 binary format, which uses 16-bit signed integers, +and is limited to 4096-byte entries. +.IP +The format cannot represent very large numeric capabilities, +nor can it represent large numbers of special keyboard definitions. +.bP +The tables of capability names differ between implementations. +.IP +Although they \fImay\fP provide all of the standard capability names, +the position in the tables differs because some features were added as needed, +while others were added (out of order) to comply with X/Open Curses. +.IP +While \fI\%ncurses\fP' repertoire of predefined capabilities is closest +to Solaris, +Solaris's terminfo database has a few differences from +the list published by X/Open Curses. +For example, +\fI\%ncurses\fP can be configured with tables which match the terminal +databases for AIX, HP-UX or OSF/1, +rather than the default Solaris-like configuration. +.bP +In SVr4 curses and \fI\%ncurses\fP, +the terminal database is defined at compile-time using a text file +which lists the different terminal capabilities. +.IP +In principle, the text-file can be extended, +but doing this requires recompiling and reinstalling the library. +The text-file used in \fI\%ncurses\fP for terminal capabilities includes +details for various systems past the documented X/Open Curses features. +For example, \fI\%ncurses\fP supports these capabilities in each configuration: +.RS 8 +.TP 5 +memory_lock +(meml) +lock memory above cursor +.TP 5 +memory_unlock +(memu) +unlock memory +.TP 5 +box_chars_1 +(box1) +box characters primary set +.RE +.IP +The memory lock/unlock capabilities were included because they were used +in the X11R6 terminal description for \fBxterm\fP(1). +The \fIbox1\fP capability is used in tic to help with terminal descriptions +written for AIX. +.PP +During the 1990s, some users were reluctant to use terminfo +in spite of its performance advantages over termcap: +.bP +The fixed repertoire prevented users from adding features +for unanticipated terminal improvements +(or required them to reuse existing capabilities as a workaround). +.bP +The limitation to 16-bit signed integers was also mentioned. +Because termcap stores everything as a string, +it could represent larger numbers. +.PP +Although termcap's extensibility was rarely used +(it was never the \fIspeaker\fP who had actually used the feature), +the criticism had a point. +\fI\%ncurses\fP 5.0 provided a way to detect nonstandard capabilities, +determine their +type and optionally store and retrieve them in a way which did not interfere +with other applications. +These are referred to as \fIuser-defined capabilities\fP because no +modifications to the toolset's predefined capability names are needed. +.PP +The \fI\%ncurses\fP utilities \fBtic\fP and \fBinfocmp\fP have a +command-line option \*(``\-x\*('' to control whether the nonstandard +capabilities are stored or retrieved. +A library function \fBuse_extended_names\fP +is provided for the same purpose. +.PP +When compiling a terminal database, if \*(``\-x\*('' is set, +\fBtic\fP will store a user-defined capability if the capability name is not +one of the predefined names. +.PP +Because \fI\%ncurses\fP provides a termcap library interface, +these user-defined capabilities may be visible to termcap applications: +.bP +The termcap interface (like all implementations of termcap) +requires that the capability names are 2-characters. +.IP +When the capability is simple enough for use in a termcap application, +it is provided as a 2-character name. +.bP +There are other +user-defined capabilities which refer to features not usable in termcap, +e.g., parameterized strings that use more than two parameters +or use more than the trivial expression support provided by termcap. +For these, the terminfo database should have only capability names with +3 or more characters. +.bP +Some terminals can send distinct strings for special keys (cursor-, +keypad- or function-keys) depending on modifier keys (shift, control, etc.). +While terminfo and termcap have a set of 60 predefined function-key names, +to which a series of keys can be assigned, +that is insufficient for more than a dozen keys multiplied by more than +a couple of modifier combinations. +The \fI\%ncurses\fP database uses a convention based on \fBxterm\fP(1) +to provide extended special-key names. +.IP +Fitting that into termcap's limitation of 2-character names +would be pointless. +These extended keys are available only with terminfo. +.SS "Recognized Capabilities" +The \fI\%ncurses\fP library uses the user-definable capabilities. +While the terminfo database may have other extensions, +\fI\%ncurses\fP makes explicit checks for these: +.RS 3 +.TP 3 +AX +\fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49 +by resetting the foreground and background color, respectively, to the default. +.IP +This is a feature recognized by the \fBscreen\fP program as well. +.TP 3 +E3 +\fIstring\fP, tells how to clear the terminal's scrollback buffer. +When present, the \fBclear\fP(1) program sends this before clearing +the terminal. +.IP +The command \*(``\fBtput clear\fP\*('' does the same thing. +.TP 3 +NQ +\fIBoolean\fP, +used to suppress a consistency check in tic for the \fI\%ncurses\fP +capabilities +in user6 through user9 (u6, u7, u8 and u9) +which tell how to query the terminal's cursor position +and its device attributes. +.TP 3 +RGB +\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP, +used to assert that the +\fBset_a_foreground\fP and +\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP, +using an RGB (red/green/blue) convention. +This capability allows the \fBcolor_content\fP function to +return appropriate values without requiring the application +to initialize colors using \fBinit_color\fP. +.IP +The capability type determines the values which \fI\%ncurses\fP sees: +.RS 3 +.TP 3 +\fIBoolean\fP +implies that the number of bits for red, green and blue are the same. +Using the maximum number of colors, +\fI\%ncurses\fP adds two, +divides that sum by three, +and assigns the result to red, +green and blue in that order. +.IP +If the number of bits needed for the number of colors is not a multiple +of three, the blue (and green) components lose in comparison to red. +.TP 3 +\fInumber\fP +tells \fI\%ncurses\fP what result to add to red, green and blue. +If \fI\%ncurses\fP runs out of bits, +blue (and green) lose just as in the \fIBoolean\fP case. +.TP 3 +\fIstring\fP +explicitly list the number of bits used for red, green and blue components +as a slash-separated list of decimal integers. +.RE +.IP +Because there are several RGB encodings in use, +applications which make assumptions about the number of bits per color +are unlikely to work reliably. +As a trivial case, for example, one could define \fBRGB#1\fP +to represent the standard eight ANSI colors, i.e., one bit per color. +.TP 3 +U8 +\fInumber\fP, +asserts that \fI\%ncurses\fP must use Unicode values for line-drawing +characters, +and that it should ignore the alternate character set capabilities +when the locale uses UTF-8 encoding. +For more information, see the discussion of +\fBNCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3X). +.IP +Set this capability to a nonzero value to enable it. +.TP 3 +XM +\fIstring\fP, +override \fI\%ncurses\fP's built-in string which +enables/disables \fBxterm\fP(1) mouse mode. +.IP +\fI\%ncurses\fP sends a character sequence to the terminal to initialize mouse mode, +and when the user clicks the mouse buttons or (in certain modes) moves the +mouse, handles the characters sent back by the terminal to tell it what +was done with the mouse. +.IP +The mouse protocol is enabled when +the \fImask\fP passed in the \fBmousemask\fP function is nonzero. +By default, +\fI\%ncurses\fP handles the responses for the X11 xterm mouse protocol. +It also knows about the \fISGR 1006\fP xterm mouse protocol, +but must to be told to look for this specifically. +It will not be able to guess which mode is used, +because the responses are enough alike that only confusion would result. +.IP +The \fBXM\fP capability has a single parameter. +If nonzero, the mouse protocol should be enabled. +If zero, the mouse protocol should be disabled. +\fI\%ncurses\fP inspects this capability if it is present, +to see whether the 1006 protocol is used. +If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol. +.IP +The xterm mouse protocol is used by other terminal emulators. +The terminal database uses building-blocks for the various xterm mouse +protocols which can be used in customized terminal descriptions. +.IP +The terminal database building blocks for this mouse +feature also have an experimental capability \fIxm\fP. +The \*(``xm\*('' capability describes the mouse response. +Currently there is no interpreter which would use this +information to make the mouse support completely data-driven. +.IP +\fIxm\fP shows the format of the mouse responses. +In this experimental capability, the parameters are +.RS 5 +.TP 5 +.I p1 +y-ordinate +.TP 5 +.I p2 +x-ordinate +.TP 5 +.I p3 +button +.TP 5 +.I p4 +state, e.g., pressed or released +.TP 5 +.I p5 +y-ordinate starting region +.TP 5 +.I p6 +x-ordinate starting region +.TP 5 +.I p7 +y-ordinate ending region +.TP 5 +.I p8 +x-ordinate ending region +.RE +.IP +Here are examples from the terminal database for the most commonly used +xterm mouse protocols: +.IP +.nf + xterm+x11mouse|X11 xterm mouse protocol, + kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;, + xm=\eE[M + %?%p4%t%p3%e%{3}%;%'\ '%+%c + %p2%'!'%+%c + %p1%'!'%+%c, + + xterm+sm+1006|xterm SGR-mouse, + kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;, + xm=\eE[<%i%p3%d; + %p1%d; + %p2%d; + %?%p4%tM%em%;, +.fi +. +.SS "Extended Key Definitions" +Several terminals provide the ability to send distinct strings for +combinations of modified special keys. +There is no standard for what those keys can send. +.PP +Since 1999, \fBxterm\fP(1) has supported +\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce +distinct special-key strings. +In a terminal description, +\fI\%ncurses\fP has no special knowledge of the modifiers used. +Applications can use the \fInaming convention\fP established for \fBxterm\fP +to find these special keys in the terminal description. +.PP +Starting with the +.I curses +convention that capability codes describing the input generated by a +terminal's key caps begin with \*(``k\*('', +and that shifted special keys use uppercase letters in their names, +.IR \%ncurses 's +terminal database defines the following names and codes to which a +suffix is added. +.PP +.RS 5 +.TS +Lb Lb +Lb Lx. +Code Description +_ +kDC shifted kdch1 (delete character) +.\" kDC is a standard capability; see X/Open Curses Issue 7, p. 345. +kDN shifted kcud1 (cursor down) +kEND shifted kend (end) +kHOM shifted khome (home) +kLFT shifted kcub1 (cursor back) +kNXT shifted knext (next) +kPRV shifted kprev (previous) +kRIT shifted kcuf1 (cursor forward) +kUP shifted kcuu1 (cursor up) +.TE +.RE +.PP +Keycap nomenclature on the Unix systems for which +.I curses +was developed differs from today's ubiquitous descendants of the IBM +PC/AT keyboard layout. +In the foregoing, +interpret \*(``backward\*('' as \*(``left\*('', +\*(``forward\*('' as \*(``right\*('', +\*(``next\*('' as \*(``page down\*('', +and +\*(``prev(ious)\*('' as \*(``page up\*(''. +.PP +These are the suffixes used to denote the modifiers: +.PP +.RS 5 +.TS +tab(/) ; +l l . +\fBValue\fP/\fBDescription\fP +_ +2/Shift +3/Alt +4/Shift + Alt +5/Control +6/Shift + Control +7/Alt + Control +8/Shift + Alt + Control +9/Meta +10/Meta + Shift +11/Meta + Alt +12/Meta + Alt + Shift +13/Meta + Ctrl +14/Meta + Ctrl + Shift +15/Meta + Ctrl + Alt +16/Meta + Ctrl + Alt + Shift +.TE +.RE +.PP +None of these are predefined; terminal descriptions can refer to \fInames\fP +which \fI\%ncurses\fP will allocate at runtime to \fIkey-codes\fP. +To use these keys in an \fI\%ncurses\fP program, +an application could do this: +.bP +using a list of extended key \fInames\fP, +ask \fBtigetstr\fP(3X) for their values, and +.bP +given the list of values, +ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which +would be returned for those keys by \fBwgetch\fP(3X). +.\" +.SH PORTABILITY +The \*(``\-x\*('' extension feature of \fBtic\fP and \fBinfocmp\fP +has been adopted in NetBSD curses. +That implementation stores user-defined capabilities, +but makes no use of these capabilities itself. +.\" +.SH AUTHORS +Thomas E. Dickey +.br +beginning with \fI\%ncurses\fP 5.0 (1999) +.\" +.SH SEE ALSO +\fB\%infocmp\fP(1M), +\fB\%tic\fP(1M) +.PP +The terminal database section +.I "NCURSES USER-DEFINABLE CAPABILITIES" +summarizes commonly-used user-defined capabilities +which are used in the terminal descriptions. +Some of those features are mentioned in \fB\%screen\fP(1) or +\fBtmux\fP(1). +.PP +.I "XTerm Control Sequences" +provides further information on the \fB\%xterm\fP(1) features +that are used in these extended capabilities. diff --git a/upstream/fedora-40/man5/utmp.5 b/upstream/fedora-40/man5/utmp.5 new file mode 100644 index 00000000..99d3fed5 --- /dev/null +++ b/upstream/fedora-40/man5/utmp.5 @@ -0,0 +1,348 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-02-26 by Michael Haardt +.\" Modified 1996-07-20 by Michael Haardt +.\" Modified 1997-07-02 by Nicolás Lichtmaier +.\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne +.TH utmp 5 2023-10-31 "Linux man-pages 6.06" +.SH NAME +utmp, wtmp \- login records +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.I utmp +file allows one to discover information about who is currently using the +system. +There may be more users currently using the system, because not +all programs use utmp logging. +.P +.B Warning: +.I utmp +must not be writable by the user class "other", +because many system programs (foolishly) +depend on its integrity. +You risk faked system logfiles and +modifications of system files if you leave +.I utmp +writable to any user other than the owner and group owner of the file. +.P +The file is a sequence of +.I utmp +structures, +declared as follows in +.I +(note that this is only one of several definitions +around; details depend on the version of libc): +.P +.in +4n +.EX +/* Values for ut_type field, below */ +\& +#define EMPTY 0 /* Record does not contain valid info + (formerly known as UT_UNKNOWN on Linux) */ +#define RUN_LVL 1 /* Change in system run\-level (see + \fBinit\fP(1)) */ +#define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */ +#define NEW_TIME 3 /* Time after system clock change + (in \fIut_tv\fP) */ +#define OLD_TIME 4 /* Time before system clock change + (in \fIut_tv\fP) */ +#define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(1) */ +#define LOGIN_PROCESS 6 /* Session leader process for user login */ +#define USER_PROCESS 7 /* Normal process */ +#define DEAD_PROCESS 8 /* Terminated process */ +#define ACCOUNTING 9 /* Not implemented */ +\& +#define UT_LINESIZE 32 +#define UT_NAMESIZE 32 +#define UT_HOSTSIZE 256 +\& +struct exit_status { /* Type for ut_exit, below */ + short e_termination; /* Process termination status */ + short e_exit; /* Process exit status */ +}; +\& +struct utmp { + short ut_type; /* Type of record */ + pid_t ut_pid; /* PID of login process */ + char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */ + char ut_id[4]; /* Terminal name suffix, + or inittab(5) ID */ + char ut_user[UT_NAMESIZE]; /* Username */ + char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or + kernel version for run\-level + messages */ + struct exit_status ut_exit; /* Exit status of a process + marked as DEAD_PROCESS; not + used by Linux init(1) */ + /* The ut_session and ut_tv fields must be the same size when + compiled 32\- and 64\-bit. This allows data files and shared + memory to be shared between 32\- and 64\-bit applications. */ +#if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32 + int32_t ut_session; /* Session ID (\fBgetsid\fP(2)), + used for windowing */ + struct { + int32_t tv_sec; /* Seconds */ + int32_t tv_usec; /* Microseconds */ + } ut_tv; /* Time entry was made */ +#else + long ut_session; /* Session ID */ + struct timeval ut_tv; /* Time entry was made */ +#endif +\& + int32_t ut_addr_v6[4]; /* Internet address of remote + host; IPv4 address uses + just ut_addr_v6[0] */ + char __unused[20]; /* Reserved for future use */ +}; +\& +/* Backward compatibility hacks */ +#define ut_name ut_user +#ifndef _NO_UT_TIME +#define ut_time ut_tv.tv_sec +#endif +#define ut_xtime ut_tv.tv_sec +#define ut_addr ut_addr_v6[0] +.EE +.in +.P +This structure gives the name of the special file associated with the +user's terminal, the user's login name, and the time of login in the form +of +.BR time (2). +String fields are terminated by a null byte (\[aq]\e0\[aq]) +if they are shorter than the size +of the field. +.P +The first entries ever created result from +.BR init (1) +processing +.BR inittab (5). +Before an entry is processed, though, +.BR init (1) +cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing +\fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each +record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP +and where no process with PID \fIut_pid\fP exists. +If no empty record +with the needed \fIut_id\fP can be found, +.BR init (1) +creates a new one. +It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the +current values, and \fIut_type\fP to \fBINIT_PROCESS\fP. +.P +.BR mingetty (8) +(or +.BR agetty (8)) +locates the entry by the PID, changes \fIut_type\fP to +\fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits +for connection to be established. +.BR login (1), +after a user has been +authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes +\fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP. +Depending on +.BR mingetty (8) +(or +.BR agetty (8)) +and +.BR login (1), +records may be located by +\fIut_line\fP instead of the preferable \fIut_pid\fP. +.P +When +.BR init (1) +finds that a process has exited, it locates its utmp entry by +.IR ut_pid , +sets +.I ut_type +to +.BR DEAD_PROCESS , +and clears +.IR ut_user , +.IR ut_host , +and +.I ut_time +with null bytes. +.P +.BR xterm (1) +and other terminal emulators directly create a +\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the +string that suffix part of the terminal name (the characters +following +.IR /dev/ [pt] ty ). +If they find a \fBDEAD_PROCESS\fP for this ID, +they recycle it, otherwise they create a new entry. +If they can, they +will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that +they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP +as well. +.P +.BR telnetd (8) +sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to +.BR login (1) +as usual. +After the telnet session ends, +.BR telnetd (8) +cleans up utmp in the described way. +.P +The \fIwtmp\fP file records all logins and logouts. +Its format is exactly like \fIutmp\fP except that a null username +indicates a logout +on the associated terminal. +Furthermore, the terminal name \fB\[ti]\fP +with username \fBshutdown\fP or \fBreboot\fP indicates a system +shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP +logs the old/new system time when +.BR date (1) +changes it. +\fIwtmp\fP is maintained by +.BR login (1), +.BR init (1), +and some versions of +.BR getty (8) +(e.g., +.BR mingetty (8) +or +.BR agetty (8)). +None of these programs creates the file, so if it is +removed, record-keeping is turned off. +.SH FILES +.I /var/run/utmp +.br +.I /var/log/wtmp +.SH VERSIONS +POSIX.1 does not specify a +.I utmp +structure, but rather one named +.I utmpx +(as part of the XSI extension), +with specifications for the fields +.IR ut_type , +.IR ut_pid , +.IR ut_line , +.IR ut_id , +.IR ut_user , +and +.IR ut_tv . +POSIX.1 does not specify the lengths of the +.I ut_line +and +.I ut_user +fields. +.P +Linux defines the +.I utmpx +structure to be the same as the +.I utmp +structure. +.SH STANDARDS +Linux. +.SH HISTORY +Linux utmp entries conform neither to v7/BSD nor to System V; they are a +mix of the two. +.P +v7/BSD has fewer fields; most importantly it lacks +\fIut_type\fP, which causes native v7/BSD-like programs to display (for +example) dead or login entries. +Further, there is no configuration file +which allocates slots to sessions. +BSD does so because it lacks \fIut_id\fP fields. +.P +In Linux (as in System V), the \fIut_id\fP field of a +record will never change once it has been set, which reserves that slot +without needing a configuration file. +Clearing \fIut_id\fP may result +in race conditions leading to corrupted utmp entries and potential +security holes. +Clearing the abovementioned fields by filling them +with null bytes is not required by System V semantics, +but makes it possible to run +many programs which assume BSD semantics and which do not modify utmp. +Linux uses the BSD conventions for line contents, as documented above. +.P +.\" mtk: What is the referrent of "them" in the following sentence? +.\" System V only uses the type field to mark them and logs +.\" informative messages such as \fB"new time"\fP in the line field. +System V has no \fIut_host\fP or \fIut_addr_v6\fP fields. +.SH NOTES +Unlike various other +systems, where utmp logging can be disabled by removing the file, utmp +must always exist on Linux. +If you want to disable +.BR who (1), +then do not make utmp world readable. +.P +The file format is machine-dependent, so it is recommended that it be +processed only on the machine architecture where it was created. +.P +Note that on \fIbiarch\fP platforms, that is, systems which can run both +32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.), +\fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode. +The same goes for \fIut_session\fP and \fIut_time\fP if they are present. +This allows data files and shared memory to be shared between +32-bit and 64-bit applications. +This is achieved by changing the type of +.I ut_session +to +.IR int32_t , +and that of +.I ut_tv +to a struct with two +.I int32_t +fields +.I tv_sec +and +.IR tv_usec . +Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP, +then instead of the call: +.P +.in +4n +.EX +gettimeofday((struct timeval *) &ut.ut_tv, NULL); +.EE +.in +.P +the following method of setting this field is recommended: +.P +.in +4n +.EX +struct utmp ut; +struct timeval tv; +\& +gettimeofday(&tv, NULL); +ut.ut_tv.tv_sec = tv.tv_sec; +ut.ut_tv.tv_usec = tv.tv_usec; +.EE +.in +.\" .P +.\" Note that the \fIutmp\fP struct from libc5 has changed in libc6. +.\" Because of this, +.\" binaries using the old libc5 struct will corrupt +.\" .IR /var/run/utmp " and/or " /var/log/wtmp . +.\" .SH BUGS +.\" This man page is based on the libc5 one, things may work differently now. +.SH SEE ALSO +.BR ac (1), +.BR date (1), +.BR init (1), +.BR last (1), +.BR login (1), +.BR logname (1), +.BR lslogins (1), +.BR users (1), +.BR utmpdump (1), +.BR who (1), +.BR getutent (3), +.BR getutmp (3), +.BR login (3), +.BR logout (3), +.BR logwtmp (3), +.BR updwtmp (3) diff --git a/upstream/fedora-40/man5/uuencode.5 b/upstream/fedora-40/man5/uuencode.5 new file mode 100644 index 00000000..27cc21b4 --- /dev/null +++ b/upstream/fedora-40/man5/uuencode.5 @@ -0,0 +1,140 @@ +.\" Copyright (c) 1989-2015 +.\" The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.TH UUENCODE 5 +.SH NAME +uuencode \- format of an encoded uuencode file +.SH DESCRIPTION +Files output by +uuencode(1) +consist of a header line, +followed by a number of body lines, +and a trailer line. +The +uudecode(1) +command will ignore any lines preceding the header or +following the trailer. +Lines preceding a header must not, of course, look like a header. +.PP +The header line is distinguished by having the first 5 characters be +.I begin +followed by a space, or else a hyphen and either +.I base64 +or +.I encoded +or both (also separated with a hyphen). +The +.I base64 +option says the file has been encoded using base64. +The +.I encoded +option says the output file +.I name +has been base64 encoded. It is never encoded with traditional uuencoding. +This is a GNU extension. +These are followed by a mode (in octal), and a string which names the +remote file. The mode is separated from the +.I begin +clause and the file name by a single space character. +.SS "Traditional uuencoding" +.PP +The traditional +.I uuencoded +file body consists of a number of lines, each at most 62 characters +long (including the trailing newline). These consist of a character +count letter, followed by the encoded characters, followed by a newline. +The character count is a single printing character, +and represents an integer, the number of bytes +the rest of the line represents. +Such integers are always in the range from 0 to 63 and can +be determined by subtracting the character space (octal 40) +from the character. +.PP +Groups of 3 bytes are stored in 4 characters, 6 bits per character. +All are offset by a space to make the characters printing. +The last line may be shorter than the normal 45 bytes. +If the size is not a multiple of 3, this fact can be determined +by the value of the count on the last line. +Extra garbage will be included to make the character count a multiple +of 4. +The body is terminated by a line with a count of zero. +This line consists of one ASCII space. +.PP +The trailer line consists of +.I end +on a line by itself. +.PP +.SS "base64 encoding" +.I base64 +encoded files follow the specified format for the body, but +also include a +.I begin-base64 +header and a trailer line of four \fI=\fP characters. +.SH EXAMPLES +.nf +.na +.in +5 +begin-base64-encoded 644 VE9ETw== +.in -5 +.fi +.ad +This introduces a base64 encoded file named, +.I TODO +with that name encoded using base64 encoding. +.sp +.nf +.na +.in +5 +begin-encoded 644 5$]$3P`` +.in -5 +.fi +.ad +This introduces an encoded file named, +.I TODO +with that name encoded using uuencoding. +The encoding is a lot less friendly. Please prefer base64 encoding. +.SH CONFORMING TO +IEEE Std 1003.1, plus extensions +.sp +The +.I \-encoded +suffix to the +.I begin +header line is a GNU extension. Recipients must have the GNU +.I uudecode +program to decode them. +.SH SEE ALSO +uuencode(1), uudecode(1), base64(1GNU) +.SH HISTORY +The +.I uuencode +file format appeared in BSD 4.0 . diff --git a/upstream/fedora-40/man5/vconsole.conf.5 b/upstream/fedora-40/man5/vconsole.conf.5 new file mode 100644 index 00000000..ef220e50 --- /dev/null +++ b/upstream/fedora-40/man5/vconsole.conf.5 @@ -0,0 +1,127 @@ +'\" t +.TH "VCONSOLE\&.CONF" "5" "" "systemd 255" "vconsole.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +vconsole.conf \- Configuration file for the virtual console +.SH "SYNOPSIS" +.PP +/etc/vconsole\&.conf +.SH "DESCRIPTION" +.PP +The +/etc/vconsole\&.conf +file configures the virtual console, i\&.e\&. keyboard mapping and console font\&. It is applied at boot by udev using +90\-vconsole\&.rules +file\&. You can safely mask this file if you want to avoid this kind of initialization\&. +.PP +The format of +vconsole\&.conf +is a newline\-separated list of environment\-like shell\-compatible variable assignments, ignoring comments and empty lines\&. It is possible to source the configuration from shell scripts, however, beyond mere variable assignments no shell features are supported, allowing applications to read the file without implementing a shell compatible execution engine\&. See +\fBos-release\fR(5) +for a detailed description of the format\&. +.PP +Note that the kernel command line options +\fIvconsole\&.keymap=\fR, +\fIvconsole\&.keymap_toggle=\fR, +\fIvconsole\&.font=\fR, +\fIvconsole\&.font_map=\fR, +\fIvconsole\&.font_unimap=\fR +may be used to override the console settings at boot\&. +.PP +Depending on the operating system other configuration files might be checked for configuration of the virtual console as well, however only as fallback\&. +.PP +/etc/vconsole\&.conf +is usually created and updated using +\fBsystemd-localed.service\fR(8)\&. +\fBlocalectl\fR(1) +may be used to instruct +\fBsystemd\-localed\&.service\fR +to query or update configuration\&. +.SH "OPTIONS" +.PP +The following options are understood: +.PP +\fIKEYMAP=\fR, \fIKEYMAP_TOGGLE=\fR +.RS 4 +Configures the key mapping table for the keyboard\&. +\fIKEYMAP=\fR +defaults to +"us" +if not set\&. Specially, if +"@kernel" +is specified, no keymap will be loaded, i\&.e\&. the kernel\*(Aqs default keymap is used\&. The +\fIKEYMAP_TOGGLE=\fR +can be used to configure a second toggle keymap and is by default unset\&. +.RE +.PP +\fIFONT=\fR, \fIFONT_MAP=\fR, \fIFONT_UNIMAP=\fR +.RS 4 +Configures the console font, the console map and the unicode font map\&. +.RE +.SH "KERNEL COMMAND LINE" +.PP +A few configuration parameters from +vconsole\&.conf +may be overridden on the kernel command line: +.PP +\fIvconsole\&.keymap=\fR, \fIvconsole\&.keymap_toggle=\fR +.RS 4 +Overrides +\fIKEYMAP=\fR +and +\fIKEYMAP_TOGGLE=\fR\&. +.sp +Added in version 232\&. +.RE +.PP +\fIvconsole\&.font=\fR, \fIvconsole\&.font_map=\fR, \fIvconsole\&.font_unimap=\fR +.RS 4 +Overrides +\fIFONT=\fR, +\fIFONT_MAP=\fR, and +\fIFONT_UNIMAP=\fR\&. +.sp +Added in version 232\&. +.RE +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&German keyboard and console\fR +.PP +/etc/vconsole\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +KEYMAP=de\-latin1 +FONT=eurlatgr +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-vconsole-setup.service\fR(8), +\fBloadkeys\fR(1), +\fBsetfont\fR(8), +\fBlocale.conf\fR(5), +\fBsystemd-localed.service\fR(8) diff --git a/upstream/fedora-40/man5/veritytab.5 b/upstream/fedora-40/man5/veritytab.5 new file mode 100644 index 00000000..d68a8af4 --- /dev/null +++ b/upstream/fedora-40/man5/veritytab.5 @@ -0,0 +1,275 @@ +'\" t +.TH "VERITYTAB" "5" "" "systemd 255" "veritytab" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +veritytab \- Configuration for verity block devices +.SH "SYNOPSIS" +.PP +/etc/veritytab +.SH "DESCRIPTION" +.PP +The +/etc/veritytab +file describes verity protected block devices that are set up during system boot\&. +.PP +Empty lines and lines starting with the +"#" +character are ignored\&. Each of the remaining lines describes one verity protected block device\&. Fields are delimited by white space\&. +.PP +Each line is in the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIvolume\-name\fR \fIdata\-device\fR \fIhash\-device\fR \fIroothash\fR \fIoptions\fR +.fi +.if n \{\ +.RE +.\} +.sp +The first four fields are mandatory, the remaining one is optional\&. +.PP +The first field contains the name of the resulting verity volume; its block device is set up below +/dev/mapper/\&. +.PP +The second field contains a path to the underlying block data device, or a specification of a block device via +"UUID=" +followed by the UUID\&. +.PP +The third field contains a path to the underlying block hash device, or a specification of a block device via +"UUID=" +followed by the UUID\&. +.PP +The fourth field is the +"roothash" +in hexadecimal\&. +.PP +The fifth field, if present, is a comma\-delimited list of options\&. The following options are recognized: +.PP +\fBsuperblock=\fR\fB\fIBOOL\fR\fR +.RS 4 +Use dm\-verity with or without permanent on\-disk superblock\&. +.sp +Added in version 254\&. +.RE +.PP +\fBformat=\fR\fB\fINUMBER\fR\fR +.RS 4 +Specifies the hash version type\&. Format type 0 is original Chrome OS version\&. Format type 1 is modern version\&. +.sp +Added in version 254\&. +.RE +.PP +\fBdata\-block\-size=\fR\fB\fIBYTES\fR\fR +.RS 4 +Used block size for the data device\&. (Note kernel supports only page\-size as maximum here; Multiples of 512 bytes\&.) +.sp +Added in version 254\&. +.RE +.PP +\fBhash\-block\-size=\fR\fB\fIBYTES\fR\fR +.RS 4 +Used block size for the hash device\&. (Note kernel supports only page\-size as maximum here; Multiples of 512 bytes\&.) +.sp +Added in version 254\&. +.RE +.PP +\fBdata\-blocks=\fR\fB\fIBLOCKS\fR\fR +.RS 4 +Number of blocks of data device used in verification\&. If not specified, the whole device is used\&. +.sp +Added in version 254\&. +.RE +.PP +\fBhash\-offset=\fR\fB\fIBYTES\fR\fR +.RS 4 +Offset of hash area/superblock on +"hash\-device"\&. (Multiples of 512 bytes\&.) +.sp +Added in version 254\&. +.RE +.PP +\fBsalt=\fR\fB\fIHEX\fR\fR +.RS 4 +Salt used for format or verification\&. Format is a hexadecimal string; 256 bytes long maximum; +"\-"is the special value for empty\&. +.sp +Added in version 254\&. +.RE +.PP +\fBuuid=\fR\fB\fIUUID\fR\fR +.RS 4 +Use the provided UUID for format command instead of generating new one\&. The UUID must be provided in standard UUID format, e\&.g\&. 12345678\-1234\-1234\-1234\-123456789abc\&. +.sp +Added in version 254\&. +.RE +.PP +\fBignore\-corruption\fR, \fBrestart\-on\-corruption\fR, \fBpanic\-on\-corruption\fR +.RS 4 +Defines what to do if a data verity problem is detected (data corruption)\&. Without these options kernel fails the IO operation with I/O error\&. With +"\-\-ignore\-corruption" +option the corruption is only logged\&. With +"\-\-restart\-on\-corruption" +or +"\-\-panic\-on\-corruption" +the kernel is restarted (panicked) immediately\&. (You have to provide way how to avoid restart loops\&.) +.sp +Added in version 248\&. +.RE +.PP +\fBignore\-zero\-blocks\fR +.RS 4 +Instruct kernel to not verify blocks that are expected to contain zeroes and always directly return zeroes instead\&. WARNING: Use this option only in very specific cases\&. This option is available since Linux kernel version 4\&.5\&. +.sp +Added in version 248\&. +.RE +.PP +\fBcheck\-at\-most\-once\fR +.RS 4 +Instruct kernel to verify blocks only the first time they are read from the data device, rather than every time\&. WARNING: It provides a reduced level of security because only offline tampering of the data device\*(Aqs content will be detected, not online tampering\&. This option is available since Linux kernel version 4\&.17\&. +.sp +Added in version 248\&. +.RE +.PP +\fBhash=\fR\fB\fIHASH\fR\fR +.RS 4 +Hash algorithm for dm\-verity\&. This should be the name of the algorithm, like "sha1"\&. For default see +\fBveritysetup \-\-help\fR\&. +.sp +Added in version 254\&. +.RE +.PP +\fBfec\-device=\fR\fB\fIPATH\fR\fR +.RS 4 +Use forward error correction (FEC) to recover from corruption if hash verification fails\&. Use encoding data from the specified device\&. The fec device argument can be block device or file image\&. For format, if fec device path doesn\*(Aqt exist, it will be created as file\&. Note: block sizes for data and hash devices must match\&. Also, if the verity data_device is encrypted the fec_device should be too\&. +.sp +Added in version 254\&. +.RE +.PP +\fBfec\-offset=\fR\fB\fIBYTES\fR\fR +.RS 4 +This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data\&. (Aligned on 512 bytes\&.) +.sp +Added in version 254\&. +.RE +.PP +\fBfec\-roots=\fR\fB\fINUM\fR\fR +.RS 4 +Number of generator roots\&. This equals to the number of parity bytes in the encoding data\&. In RS(M, N) encoding, the number of roots is M\-N\&. M is 255 and M\-N is between 2 and 24 (including)\&. +.sp +Added in version 254\&. +.RE +.PP +\fBroot\-hash\-signature=\fR\fB\fIPATH\fR\fR\fB|base64:\fR\fB\fIHEX\fR\fR +.RS 4 +A base64 string encoding the root hash signature prefixed by +"base64:" +or a path to roothash signature file used to verify the root hash (in kernel)\&. This feature requires Linux kernel version 5\&.4 or more recent\&. +.sp +Added in version 248\&. +.RE +.PP +\fB_netdev\fR +.RS 4 +Marks this veritysetup device as requiring network\&. It will be started after the network is available, similarly to +\fBsystemd.mount\fR(5) +units marked with +\fB_netdev\fR\&. The service unit to set up this device will be ordered between +remote\-fs\-pre\&.target +and +remote\-veritysetup\&.target, instead of +veritysetup\-pre\&.target +and +veritysetup\&.target\&. +.sp +Hint: if this device is used for a mount point that is specified in +\fBfstab\fR(5), the +\fB_netdev\fR +option should also be used for the mount point\&. Otherwise, a dependency loop might be created where the mount point will be pulled in by +local\-fs\&.target, while the service to configure the network is usually only started +\fIafter\fR +the local file system has been mounted\&. +.sp +Added in version 248\&. +.RE +.PP +\fBnoauto\fR +.RS 4 +This device will not be added to +veritysetup\&.target\&. This means that it will not be automatically enabled on boot, unless something else pulls it in\&. In particular, if the device is used for a mount point, it\*(Aqll be enabled automatically during boot, unless the mount point itself is also disabled with +\fBnoauto\fR\&. +.sp +Added in version 248\&. +.RE +.PP +\fBnofail\fR +.RS 4 +This device will not be a hard dependency of +veritysetup\&.target\&. It\*(Aqll still be pulled in and started, but the system will not wait for the device to show up and be enabled, and boot will not fail if this is unsuccessful\&. Note that other units that depend on the enabled device may still fail\&. In particular, if the device is used for a mount point, the mount point itself also needs to have the +\fBnofail\fR +option, or the boot will fail if the device is not enabled successfully\&. +.sp +Added in version 248\&. +.RE +.PP +\fBx\-initrd\&.attach\fR +.RS 4 +Setup this verity protected block device in the initrd, similarly to +\fBsystemd.mount\fR(5) +units marked with +\fBx\-initrd\&.mount\fR\&. +.sp +Although it\*(Aqs not necessary to mark the mount entry for the root file system with +\fBx\-initrd\&.mount\fR, +\fBx\-initrd\&.attach\fR +is still recommended with the verity protected block device containing the root file system as otherwise systemd will attempt to detach the device during the regular system shutdown while it\*(Aqs still in use\&. With this option the device will still be detached but later after the root file system is unmounted\&. +.sp +All other verity protected block devices that contain file systems mounted in the initrd should use this option\&. +.sp +Added in version 248\&. +.RE +.PP +At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by +\fBsystemd-veritysetup-generator\fR(8)\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&/etc/veritytab example\fR +.PP +Set up two verity protected block devices\&. One using device blocks, another using files\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +usr PARTUUID=783e45ae\-7aa3\-484a\-beef\-a80ff9c19cbb PARTUUID=21dc1dfe\-4c33\-8b48\-98a9\-918a22eb3e37 36e3f740ad502e2c25e2a23d9c7c17bf0fdad2300b7580842d4b7ec1fb0fa263 auto +data /etc/data /etc/hash a5ee4b42f70ae1f46a08a7c92c2e0a20672ad2f514792730f5d49d7606ab8fdf auto +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemd-veritysetup@.service\fR(8), +\fBsystemd-veritysetup-generator\fR(8), +\fBfstab\fR(5), +\fBveritysetup\fR(8), diff --git a/upstream/fedora-40/man5/whois.conf.5 b/upstream/fedora-40/man5/whois.conf.5 new file mode 100644 index 00000000..dd13bca2 --- /dev/null +++ b/upstream/fedora-40/man5/whois.conf.5 @@ -0,0 +1,50 @@ +.TH "WHOIS.CONF" "5" "2019-12-30" "Petr Písař" "Debian GNU/Linux" + +.SH NAME +whois.conf \- alternative WHOIS servers list for whois client + +.SH SYNOPSIS +.B /etc/whois.conf + +.SH DESCRIPTION +This file contains a list of WHOIS servers which can augment or override +the built-in list of the client. + +It's a plain text file in ASCII encoding. Each line consists of two fields: +a pattern to match WHOIS object identifier and a corresponding WHOIS server +domain name. + +Fields are separated by non-empty sequence of space or a tabular characters. +A line starting with a hash character is a free comment and it's not +considered. + +The pattern is case-insensitive extended regular expression if whois client +has been compiled with POSIX regular expressions support. Otherwise, simple +case-insensitive suffix comparison against WHOIS object identifier is used. + +Internationalized domain names (IDN) must be specified in ascii-compatible +encoding (ACE) format. + +.SH EXAMPLE +\\.nz$ nz.whois-servers.net +.br +# Hangul Korean TLD +.br +\\.xn--3e0b707e$ whois.kr +.br +# Private ASNs +.br +^as645(1[2-9]|2[0-9]|3[0-4])$ whois.example.net + +.SH FILES +/etc/whois.conf + +.SH "SEE ALSO" +.IR whois (1) + +.SH AUTHOR +This manual page was written by Petr Písař +.RI < ppisar@redhat.com > +and is licensed under the terms of the GNU General Public License, +version 2 or higher. +\" SPDX-License-Identifier: GPL-2.0-or-later diff --git a/upstream/fedora-40/man5/xfs.5 b/upstream/fedora-40/man5/xfs.5 new file mode 100644 index 00000000..0c1edc53 --- /dev/null +++ b/upstream/fedora-40/man5/xfs.5 @@ -0,0 +1,370 @@ +\." tbl +.TH xfs 5 +.SH NAME +xfs \- layout, mount options, and supported file attributes for the XFS filesystem +.SH DESCRIPTION +An XFS filesystem can reside on a regular disk partition or on a +logical volume. +An XFS filesystem has up to three parts: +a data section, a log section, and a realtime section. +Using the default +.BR mkfs.xfs (8) +options, the realtime section is absent, and +the log area is contained within the data section. +The log section can be either separate from the data section +or contained within it. +The filesystem sections are divided into a certain number of +.IR blocks , +whose size is specified at +.BR mkfs.xfs (8) +time with the +.B \-b +option. +.PP +The data section contains all the filesystem metadata +(inodes, directories, indirect blocks) +as well as the user file data for ordinary (non-realtime) files +and the log area if the log is +.I internal +to the data section. +The data section is divided into a number of +.IR "allocation groups" . +The number and size of the allocation groups are chosen by +.BR mkfs.xfs (8) +so that there is normally a small number of equal-sized groups. +The number of allocation groups controls the amount of parallelism +available in file and block allocation. +It should be increased from +the default if there is sufficient memory and a lot of allocation +activity. +The number of allocation groups should not be set very high, +since this can cause large amounts of CPU time to be used by +the filesystem, especially when the filesystem is nearly full. +More allocation groups are added (of the original size) when +.BR xfs_growfs (8) +is run. +.PP +The log section (or area, if it is internal to the data section) +is used to store changes to filesystem metadata while the +filesystem is running until those changes are made to the data +section. +It is written sequentially during normal operation and read only +during mount. +When mounting a filesystem after a crash, the log +is read to complete operations that were +in progress at the time of the crash. +.PP +The realtime section is used to store the data of realtime files. +These files had an attribute bit set through +.BR xfsctl (3) +after file creation, before any data was written to the file. +The realtime section is divided into a number of +.I extents +of fixed size (specified at +.BR mkfs.xfs (8) +time). +Each file in the realtime section has an extent size that +is a multiple of the realtime section extent size. +.PP +Each allocation group contains several data structures. +The first sector contains the superblock. +For allocation groups after the first, +the superblock is just a copy and is not updated after +.BR mkfs.xfs (8). +The next three sectors contain information for block and inode +allocation within the allocation group. +Also contained within each allocation group are data structures +to locate free blocks and inodes; +these are located through the header structures. +.PP +Each XFS filesystem is labeled with a Universal Unique +Identifier (UUID). +The UUID is stored in every allocation group header and +is used to help distinguish one XFS filesystem from another, +therefore you should avoid using +.BR dd (1) +or other block-by-block copying programs to copy XFS filesystems. +If two XFS filesystems on the same machine have the same UUID, +.BR xfsdump (8) +may become confused when doing incremental and resumed dumps. +.BR xfsdump (8) +and +.BR xfsrestore (8) +are recommended for making copies of XFS filesystems. +.SH OPERATIONS +Some functionality specific to the XFS filesystem is accessible to +applications through the +.BR xfsctl (3) +and by-handle (see +.BR open_by_handle (3)) +interfaces. +.SH MOUNT OPTIONS +The following XFS-specific mount options may be used when mounting +an XFS filesystem. Other generic options may be used as well; refer to the +.BR mount (8) +manual page for more details. +.TP +.B allocsize=size +Sets the buffered I/O end-of-file preallocation size when +doing delayed allocation writeout. Valid values for this +option are page size (typically 4KiB) through to 1GiB, +inclusive, in power-of-2 increments. +.sp +The default behavior is for dynamic end-of-file +preallocation size, which uses a set of heuristics to +optimise the preallocation size based on the current +allocation patterns within the file and the access patterns +to the file. Specifying a fixed allocsize value turns off +the dynamic behavior. +.TP +.BR attr2 | noattr2 +Note: These options have been +.B deprecated +as of kernel v5.10; The noattr2 option will be removed no +earlier than in September 2025 and attr2 option will be immutable +default. +.sp +The options enable/disable an "opportunistic" improvement to +be made in the way inline extended attributes are stored +on-disk. When the new form is used for the first time when +attr2 is selected (either when setting or removing extended +attributes) the on-disk superblock feature bit field will be +updated to reflect this format being in use. +.sp +The default behavior is determined by the on-disk feature +bit indicating that attr2 behavior is active. If either +mount option it set, then that becomes the new default used +by the filesystem. +.sp +CRC enabled filesystems always use the attr2 format, and so +will reject the noattr2 mount option if it is set. +.TP +.BR dax=value +Set CPU direct access (DAX) behavior for the current filesystem. This mount +option accepts the following values: + +"dax=inode" DAX will be enabled only on regular files with FS_XFLAG_DAX applied. + +"dax=never" DAX will not be enabled for any files. FS_XFLAG_DAX will be ignored. + +"dax=always" DAX will be enabled for all regular files, regardless of the +FS_XFLAG_DAX state. + +If no option is used when mounting a filesystem stored on a DAX capable device, +dax=inode will be used as default. + +For details regarding DAX behavior in kernel, please refer to kernel's +documentation at filesystems/dax.txt +.TP +.BR discard | nodiscard +Enable/disable the issuing of commands to let the block +device reclaim space freed by the filesystem. This is +useful for SSD devices, thinly provisioned LUNs and virtual +machine images, but may have a performance impact. +.sp +Note: It is currently recommended that you use the fstrim +application to discard unused blocks rather than the discard +mount option because the performance impact of this option +is quite severe. For this reason, nodiscard is the default. +.TP +.BR grpid | bsdgroups | nogrpid | sysvgroups +These options define what group ID a newly created file +gets. When grpid is set, it takes the group ID of the +directory in which it is created; otherwise it takes the +fsgid of the current process, unless the directory has the +setgid bit set, in which case it takes the gid from the +parent directory, and also gets the setgid bit set if it is +a directory itself. +.TP +.B filestreams +Make the data allocator use the filestreams allocation mode +across the entire filesystem rather than just on directories +configured to use it. +.TP +.BR ikeep | noikeep +Note: These options have been +.B deprecated +as of kernel v5.10; The noikeep option will be removed no +earlier than in September 2025 and ikeep option will be +immutable default. + +.sp +When ikeep is specified, XFS does not delete empty inode +clusters and keeps them around on disk. When noikeep is +specified, empty inode clusters are returned to the free +space pool. noikeep is the default. +.TP +.BR inode32 | inode64 +When inode32 is specified, it indicates that XFS limits +inode creation to locations which will not result in inode +numbers with more than 32 bits of significance. +.sp +When inode64 is specified, it indicates that XFS is allowed +to create inodes at any location in the filesystem, +including those which will result in inode numbers occupying +more than 32 bits of significance. +.sp +inode32 is provided for backwards compatibility with older +systems and applications, since 64 bits inode numbers might +cause problems for some applications that cannot handle +large inode numbers. If applications are in use which do +not handle inode numbers bigger than 32 bits, the inode32 +option should be specified. +.sp +For kernel v3.7 and later, inode64 is the default. +.TP +.BR largeio | nolargeio +If "nolargeio" is specified, the optimal I/O reported in +st_blksize by stat(2) will be as small as possible to allow +user applications to avoid inefficient read/modify/write +I/O. This is typically the page size of the machine, as +this is the granularity of the page cache. +.sp +If "largeio" specified, a filesystem that was created with a +"swidth" specified will return the "swidth" value (in bytes) +in st_blksize. If the filesystem does not have a "swidth" +specified but does specify an "allocsize" then "allocsize" +(in bytes) will be returned instead. Otherwise the behavior +is the same as if "nolargeio" was specified. nolargeio +is the default. +.TP +.B logbufs=value +Set the number of in-memory log buffers. Valid numbers +range from 2\(en8 inclusive. +.sp +The default value is 8 buffers. +.sp +If the memory cost of 8 log buffers is too high on small +systems, then it may be reduced at some cost to performance +on metadata intensive workloads. The logbsize option below +controls the size of each buffer and so is also relevant to +this case. +.TP +.B logbsize=value +Set the size of each in-memory log buffer. The size may be +specified in bytes, or in kibibytes (KiB) with a "k" suffix. +Valid sizes for version 1 and version 2 logs are 16384 (value=16k) +and 32768 (value=32k). Valid sizes for version 2 logs also +include 65536 (value=64k), 131072 (value=128k) and 262144 (value=256k). The +logbsize must be an integer multiple of the log +stripe unit configured at mkfs time. +.sp +The default value for version 1 logs is 32768, while the +default value for version 2 logs is max(32768, log_sunit). +.TP +.BR logdev=device " and " rtdev=device +Use an external log (metadata journal) and/or real-time device. +An XFS filesystem has up to three parts: a data section, a log +section, and a real-time section. The real-time section is +optional, and the log section can be separate from the data +section or contained within it. +.TP +.B noalign +Data allocations will not be aligned at stripe unit +boundaries. This is only relevant to filesystems created +with non-zero data alignment parameters (sunit, swidth) by +mkfs. +.TP +.B norecovery +The filesystem will be mounted without running log recovery. +If the filesystem was not cleanly unmounted, it is likely to +be inconsistent when mounted in "norecovery" mode. +Some files or directories may not be accessible because of this. +Filesystems mounted "norecovery" must be mounted read-only or +the mount will fail. +.TP +.B nouuid +Don't check for double mounted file systems using the file +system uuid. This is useful to mount LVM snapshot volumes, +and often used in combination with "norecovery" for mounting +read-only snapshots. +.TP +.B noquota +Forcibly turns off all quota accounting and enforcement +within the filesystem. +.TP +.B uquota/usrquota/quota/uqnoenforce/qnoenforce +User disk quota accounting enabled, and limits (optionally) +enforced. Refer to xfs_quota(8) for further details. +.TP +.B gquota/grpquota/gqnoenforce +Group disk quota accounting enabled and limits (optionally) +enforced. Refer to xfs_quota(8) for further details. +.TP +.B pquota/prjquota/pqnoenforce +Project disk quota accounting enabled and limits (optionally) +enforced. Refer to xfs_quota(8) for further details. +.TP +.BR sunit=value " and " swidth=value +Used to specify the stripe unit and width for a RAID device +or a stripe volume. "value" must be specified in 512-byte +block units. These options are only relevant to filesystems +that were created with non-zero data alignment parameters. +.sp +The sunit and swidth parameters specified must be compatible +with the existing filesystem alignment characteristics. In +general, that means the only valid changes to sunit are +increasing it by a power-of-2 multiple. Valid swidth values +are any integer multiple of a valid sunit value. +.sp +Typically the only time these mount options are necessary if +after an underlying RAID device has had it's geometry +modified, such as adding a new disk to a RAID5 lun and +reshaping it. +.TP +.B swalloc +Data allocations will be rounded up to stripe width boundaries +when the current end of file is being extended and the file +size is larger than the stripe width size. +.TP +.B wsync +When specified, all filesystem namespace operations are +executed synchronously. This ensures that when the namespace +operation (create, unlink, etc) completes, the change to the +namespace is on stable storage. This is useful in HA setups +where failover must not result in clients seeing +inconsistent namespace presentation during or after a +failover event. +.SH REMOVED MOUNT OPTIONS +The following mount options have been removed from the kernel, and will +yield mount failures if specified. Mount options are deprecated for +a significant period time prior to removal. +.TS +tab(@); +lbl. +Name@Removed +----@------- +delaylog/nodelaylog@v4.0 +ihashsize@v4.0 +irixsgid@v4.0 +osyncisdsync/osyncisosync@v4.0 +barrier/nobarrier@v4.19 +.TE +.SH FILE ATTRIBUTES +The XFS filesystem supports setting the following file +attributes on Linux systems using the +.BR chattr (1) +utility: +.sp +.BR a " - append only" +.sp +.BR A " - no atime updates" +.sp +.BR d " - no dump" +.sp +.BR i " - immutable" +.sp +.BR S " - synchronous updates" +.sp +For descriptions of these attribute flags, please refer to the +.BR chattr (1) +man page. +.SH SEE ALSO +.BR chattr (1), +.BR xfsctl (3), +.BR mount (8), +.BR mkfs.xfs (8), +.BR xfs_info (8), +.BR xfs_admin (8), +.BR xfsdump (8), +.BR xfsrestore (8). -- cgit v1.2.3