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/debian-unstable/man5/acct.5 | 161 + upstream/debian-unstable/man5/aliases.sendmail.5 | 131 + upstream/debian-unstable/man5/anacrontab.5 | 63 + upstream/debian-unstable/man5/at.allow.5 | 40 + upstream/debian-unstable/man5/autolog.conf.5 | 114 + upstream/debian-unstable/man5/binfmt.d.5 | 104 + upstream/debian-unstable/man5/bootchart.conf.5 | 123 + upstream/debian-unstable/man5/btrfs.5 | 2847 ++++ upstream/debian-unstable/man5/charmap.5 | 105 + upstream/debian-unstable/man5/config.5ssl | 632 + upstream/debian-unstable/man5/core.5 | 684 + upstream/debian-unstable/man5/coredump.conf.5 | 157 + upstream/debian-unstable/man5/crontab.5 | 407 + upstream/debian-unstable/man5/crypt.5 | 312 + upstream/debian-unstable/man5/crypttab.5 | 499 + upstream/debian-unstable/man5/depmod.d.5 | 126 + upstream/debian-unstable/man5/dir_colors.5 | 414 + .../debian-unstable/man5/dnssec-trust-anchors.d.5 | 227 + upstream/debian-unstable/man5/e2fsck.conf.5 | 501 + upstream/debian-unstable/man5/elf.5 | 2196 +++ upstream/debian-unstable/man5/environment.d.5 | 151 + upstream/debian-unstable/man5/erofs.5 | 97 + upstream/debian-unstable/man5/ethers.5 | 27 + upstream/debian-unstable/man5/exports.5 | 678 + upstream/debian-unstable/man5/ext4.5 | 815 ++ upstream/debian-unstable/man5/extendedopacity.5 | 166 + upstream/debian-unstable/man5/filesystems.5 | 227 + upstream/debian-unstable/man5/fips_config.5ssl | 160 + upstream/debian-unstable/man5/ftpchroot.5 | 28 + upstream/debian-unstable/man5/ftpusers.5 | 42 + upstream/debian-unstable/man5/gai.conf.5 | 89 + upstream/debian-unstable/man5/genisoimagerc.5 | 144 + upstream/debian-unstable/man5/gpm.conf.5 | 102 + upstream/debian-unstable/man5/groff_font.5 | 1114 ++ upstream/debian-unstable/man5/groff_out.5 | 1966 +++ upstream/debian-unstable/man5/groff_tmac.5 | 1478 ++ upstream/debian-unstable/man5/group.5 | 55 + upstream/debian-unstable/man5/halt.5 | 49 + upstream/debian-unstable/man5/hdparm.conf.5 | 63 + upstream/debian-unstable/man5/homed.conf.5 | 110 + upstream/debian-unstable/man5/host.conf.5 | 204 + upstream/debian-unstable/man5/hostname.5 | 130 + upstream/debian-unstable/man5/hosts.5 | 122 + upstream/debian-unstable/man5/hosts.equiv.5 | 212 + upstream/debian-unstable/man5/hwclock.5 | 34 + upstream/debian-unstable/man5/icewm-env.5 | 206 + upstream/debian-unstable/man5/icewm-focus_mode.5 | 195 + upstream/debian-unstable/man5/icewm-keys.5 | 299 + upstream/debian-unstable/man5/icewm-menu.5 | 298 + upstream/debian-unstable/man5/icewm-preferences.5 | 1761 +++ upstream/debian-unstable/man5/icewm-prefoverride.5 | 187 + upstream/debian-unstable/man5/icewm-programs.5 | 350 + upstream/debian-unstable/man5/icewm-shutdown.5 | 186 + upstream/debian-unstable/man5/icewm-startup.5 | 199 + upstream/debian-unstable/man5/icewm-theme.5 | 218 + upstream/debian-unstable/man5/icewm-toolbar.5 | 246 + upstream/debian-unstable/man5/icewm-winoptions.5 | 422 + upstream/debian-unstable/man5/inetutils-netrc.5 | 138 + upstream/debian-unstable/man5/info.5 | 59 + upstream/debian-unstable/man5/integritytab.5 | 189 + upstream/debian-unstable/man5/intro.5 | 23 + upstream/debian-unstable/man5/iocost.conf.5 | 96 + upstream/debian-unstable/man5/issue.5 | 24 + upstream/debian-unstable/man5/issue.net.5 | 43 + .../debian-unstable/man5/journal-remote.conf.5 | 140 + .../debian-unstable/man5/journal-upload.conf.5 | 115 + upstream/debian-unstable/man5/journald.conf.5 | 509 + upstream/debian-unstable/man5/keymaps.5 | 434 + upstream/debian-unstable/man5/lmhosts.5 | 123 + upstream/debian-unstable/man5/loader.conf.5 | 427 + upstream/debian-unstable/man5/locale.5 | 1316 ++ upstream/debian-unstable/man5/locale.conf.5 | 115 + upstream/debian-unstable/man5/locale.gen.5 | 41 + upstream/debian-unstable/man5/localtime.5 | 67 + upstream/debian-unstable/man5/locatedb.5 | 177 + upstream/debian-unstable/man5/logind.conf.5 | 370 + upstream/debian-unstable/man5/lpd.conf.5 | 747 + upstream/debian-unstable/man5/lpd.perms.5 | 377 + upstream/debian-unstable/man5/machine-id.5 | 254 + upstream/debian-unstable/man5/machine-info.5 | 157 + upstream/debian-unstable/man5/magic.5 | 830 ++ upstream/debian-unstable/man5/maildir.maildrop.5 | 354 + upstream/debian-unstable/man5/mbox.5 | 187 + upstream/debian-unstable/man5/mke2fs.conf.5 | 566 + upstream/debian-unstable/man5/mmdf.5 | 164 + upstream/debian-unstable/man5/modprobe.d.5 | 174 + upstream/debian-unstable/man5/modules-load.d.5 | 90 + upstream/debian-unstable/man5/modules.dep.5 | 70 + upstream/debian-unstable/man5/moduli.5 | 126 + upstream/debian-unstable/man5/motd.5 | 37 + upstream/debian-unstable/man5/mtools.5 | 575 + upstream/debian-unstable/man5/muttrc.5 | 8134 +++++++++++ upstream/debian-unstable/man5/nanorc.5 | 1057 ++ upstream/debian-unstable/man5/networkd.conf.5 | 269 + upstream/debian-unstable/man5/networks.5 | 60 + upstream/debian-unstable/man5/nfs.5 | 1968 +++ upstream/debian-unstable/man5/nfs.conf.5 | 330 + upstream/debian-unstable/man5/nfsmount.conf.5 | 131 + upstream/debian-unstable/man5/nfsrahead.5 | 72 + upstream/debian-unstable/man5/nologin.5 | 22 + upstream/debian-unstable/man5/nscd.conf.5 | 243 + upstream/debian-unstable/man5/nss.5 | 101 + upstream/debian-unstable/man5/nsswitch.conf.5 | 432 + upstream/debian-unstable/man5/oomd.conf.5 | 114 + .../man5/org.freedesktop.LogControl1.5 | 391 + .../debian-unstable/man5/org.freedesktop.home1.5 | 508 + .../man5/org.freedesktop.hostname1.5 | 618 + .../debian-unstable/man5/org.freedesktop.import1.5 | 347 + .../debian-unstable/man5/org.freedesktop.locale1.5 | 202 + .../debian-unstable/man5/org.freedesktop.login1.5 | 1649 +++ .../man5/org.freedesktop.machine1.5 | 587 + .../man5/org.freedesktop.network1.5 | 376 + .../debian-unstable/man5/org.freedesktop.oom1.5 | 105 + .../man5/org.freedesktop.portable1.5 | 769 + .../man5/org.freedesktop.resolve1.5 | 935 ++ .../man5/org.freedesktop.systemd1.5 | 7609 ++++++++++ .../man5/org.freedesktop.timedate1.5 | 217 + upstream/debian-unstable/man5/os-release.5 | 718 + upstream/debian-unstable/man5/pam.5 | 331 + upstream/debian-unstable/man5/pam.conf.5 | 416 + upstream/debian-unstable/man5/pbm.5 | 212 + upstream/debian-unstable/man5/pci.ids.5 | 97 + upstream/debian-unstable/man5/pfm.5 | 96 + upstream/debian-unstable/man5/pgm.5 | 247 + upstream/debian-unstable/man5/pnm.5 | 85 + upstream/debian-unstable/man5/ppm.5 | 240 + upstream/debian-unstable/man5/printcap.5 | 1232 ++ upstream/debian-unstable/man5/proc.5 | 6965 +++++++++ upstream/debian-unstable/man5/procmailex.5 | 568 + upstream/debian-unstable/man5/procmailrc.5 | 929 ++ upstream/debian-unstable/man5/procmailsc.5 | 324 + upstream/debian-unstable/man5/projects.5 | 31 + upstream/debian-unstable/man5/projid.5 | 29 + upstream/debian-unstable/man5/protocols.5 | 66 + upstream/debian-unstable/man5/pstore.conf.5 | 97 + upstream/debian-unstable/man5/quotagrpadmins.5 | 28 + upstream/debian-unstable/man5/quotatab.5 | 31 + upstream/debian-unstable/man5/rcS.5 | 121 + upstream/debian-unstable/man5/rcsfile.5 | 457 + upstream/debian-unstable/man5/repart.d.5 | 1113 ++ upstream/debian-unstable/man5/repertoiremap.5 | 58 + upstream/debian-unstable/man5/resolv.conf.5 | 408 + upstream/debian-unstable/man5/resolved.conf.5 | 389 + upstream/debian-unstable/man5/rhosts.5 | 40 + upstream/debian-unstable/man5/rpc.5 | 83 + upstream/debian-unstable/man5/rsyncd.conf.5 | 1313 ++ upstream/debian-unstable/man5/sane-abaton.5 | 142 + upstream/debian-unstable/man5/sane-agfafocus.5 | 188 + upstream/debian-unstable/man5/sane-airscan.5 | 223 + upstream/debian-unstable/man5/sane-apple.5 | 277 + upstream/debian-unstable/man5/sane-artec.5 | 179 + .../debian-unstable/man5/sane-artec_eplus48u.5 | 161 + upstream/debian-unstable/man5/sane-as6e.5 | 49 + upstream/debian-unstable/man5/sane-avision.5 | 187 + upstream/debian-unstable/man5/sane-bh.5 | 581 + upstream/debian-unstable/man5/sane-canon.5 | 111 + upstream/debian-unstable/man5/sane-canon630u.5 | 123 + upstream/debian-unstable/man5/sane-canon_dr.5 | 232 + upstream/debian-unstable/man5/sane-canon_lide70.5 | 104 + upstream/debian-unstable/man5/sane-canon_pp.5 | 237 + upstream/debian-unstable/man5/sane-cardscan.5 | 117 + upstream/debian-unstable/man5/sane-coolscan.5 | 111 + upstream/debian-unstable/man5/sane-coolscan2.5 | 206 + upstream/debian-unstable/man5/sane-coolscan3.5 | 204 + upstream/debian-unstable/man5/sane-dc210.5 | 121 + upstream/debian-unstable/man5/sane-dc240.5 | 131 + upstream/debian-unstable/man5/sane-dc25.5 | 109 + upstream/debian-unstable/man5/sane-dll.5 | 183 + upstream/debian-unstable/man5/sane-dmc.5 | 153 + upstream/debian-unstable/man5/sane-epjitsu.5 | 124 + upstream/debian-unstable/man5/sane-epson.5 | 327 + upstream/debian-unstable/man5/sane-epson2.5 | 380 + upstream/debian-unstable/man5/sane-epsonds.5 | 114 + upstream/debian-unstable/man5/sane-escl.5 | 94 + upstream/debian-unstable/man5/sane-fujitsu.5 | 273 + upstream/debian-unstable/man5/sane-genesys.5 | 306 + upstream/debian-unstable/man5/sane-gphoto2.5 | 147 + upstream/debian-unstable/man5/sane-gt68xx.5 | 232 + upstream/debian-unstable/man5/sane-hp.5 | 304 + upstream/debian-unstable/man5/sane-hp3500.5 | 53 + upstream/debian-unstable/man5/sane-hp3900.5 | 124 + upstream/debian-unstable/man5/sane-hp4200.5 | 115 + upstream/debian-unstable/man5/sane-hp5400.5 | 113 + upstream/debian-unstable/man5/sane-hp5590.5 | 343 + upstream/debian-unstable/man5/sane-hpljm1005.5 | 50 + upstream/debian-unstable/man5/sane-hpsj5s.5 | 121 + upstream/debian-unstable/man5/sane-hs2p.5 | 131 + upstream/debian-unstable/man5/sane-ibm.5 | 96 + upstream/debian-unstable/man5/sane-kodak.5 | 154 + upstream/debian-unstable/man5/sane-kodakaio.5 | 49 + upstream/debian-unstable/man5/sane-kvs1025.5 | 32 + upstream/debian-unstable/man5/sane-kvs20xx.5 | 31 + upstream/debian-unstable/man5/sane-kvs40xx.5 | 33 + upstream/debian-unstable/man5/sane-leo.5 | 167 + upstream/debian-unstable/man5/sane-lexmark.5 | 172 + upstream/debian-unstable/man5/sane-ma1509.5 | 142 + upstream/debian-unstable/man5/sane-magicolor.5 | 90 + upstream/debian-unstable/man5/sane-matsushita.5 | 176 + upstream/debian-unstable/man5/sane-microtek.5 | 205 + upstream/debian-unstable/man5/sane-microtek2.5 | 321 + upstream/debian-unstable/man5/sane-mustek.5 | 421 + upstream/debian-unstable/man5/sane-mustek_pp.5 | 524 + upstream/debian-unstable/man5/sane-mustek_usb.5 | 213 + upstream/debian-unstable/man5/sane-mustek_usb2.5 | 82 + upstream/debian-unstable/man5/sane-nec.5 | 65 + upstream/debian-unstable/man5/sane-net.5 | 167 + upstream/debian-unstable/man5/sane-niash.5 | 81 + upstream/debian-unstable/man5/sane-p5.5 | 162 + upstream/debian-unstable/man5/sane-pie.5 | 59 + upstream/debian-unstable/man5/sane-pieusb.5 | 120 + upstream/debian-unstable/man5/sane-pixma.5 | 493 + upstream/debian-unstable/man5/sane-plustek.5 | 529 + upstream/debian-unstable/man5/sane-plustek_pp.5 | 350 + upstream/debian-unstable/man5/sane-pnm.5 | 67 + upstream/debian-unstable/man5/sane-qcam.5 | 101 + upstream/debian-unstable/man5/sane-ricoh.5 | 89 + upstream/debian-unstable/man5/sane-ricoh2.5 | 68 + upstream/debian-unstable/man5/sane-rts8891.5 | 171 + upstream/debian-unstable/man5/sane-s9036.5 | 81 + upstream/debian-unstable/man5/sane-sceptre.5 | 184 + upstream/debian-unstable/man5/sane-scsi.5 | 355 + upstream/debian-unstable/man5/sane-sharp.5 | 443 + upstream/debian-unstable/man5/sane-sm3600.5 | 92 + upstream/debian-unstable/man5/sane-sm3840.5 | 106 + upstream/debian-unstable/man5/sane-snapscan.5 | 122 + upstream/debian-unstable/man5/sane-sp15c.5 | 83 + upstream/debian-unstable/man5/sane-st400.5 | 162 + upstream/debian-unstable/man5/sane-stv680.5 | 180 + upstream/debian-unstable/man5/sane-tamarack.5 | 91 + upstream/debian-unstable/man5/sane-teco1.5 | 201 + upstream/debian-unstable/man5/sane-teco2.5 | 257 + upstream/debian-unstable/man5/sane-teco3.5 | 168 + upstream/debian-unstable/man5/sane-test.5 | 351 + upstream/debian-unstable/man5/sane-u12.5 | 192 + upstream/debian-unstable/man5/sane-umax.5 | 284 + upstream/debian-unstable/man5/sane-umax1220u.5 | 120 + upstream/debian-unstable/man5/sane-umax_pp.5 | 332 + upstream/debian-unstable/man5/sane-usb.5 | 186 + upstream/debian-unstable/man5/sane-xerox_mfp.5 | 76 + upstream/debian-unstable/man5/scr_dump.5 | 476 + upstream/debian-unstable/man5/securetty.5 | 35 + upstream/debian-unstable/man5/services.5 | 199 + upstream/debian-unstable/man5/shells.5 | 40 + upstream/debian-unstable/man5/slabinfo.5 | 220 + upstream/debian-unstable/man5/smb.conf.5 | 14640 +++++++++++++++++++ upstream/debian-unstable/man5/smbpasswd.5 | 175 + upstream/debian-unstable/man5/ssh_config.5 | 2446 ++++ upstream/debian-unstable/man5/sshd_config.5 | 2127 +++ upstream/debian-unstable/man5/sysctl.d.5 | 245 + upstream/debian-unstable/man5/sysfs.5 | 275 + upstream/debian-unstable/man5/sysstat.5 | 176 + upstream/debian-unstable/man5/systemd-sleep.conf.5 | 236 + .../debian-unstable/man5/systemd-system.conf.5 | 837 ++ upstream/debian-unstable/man5/systemd.automount.5 | 192 + upstream/debian-unstable/man5/systemd.device.5 | 138 + upstream/debian-unstable/man5/systemd.dnssd.5 | 336 + upstream/debian-unstable/man5/systemd.exec.5 | 5667 +++++++ upstream/debian-unstable/man5/systemd.kill.5 | 225 + upstream/debian-unstable/man5/systemd.link.5 | 2045 +++ upstream/debian-unstable/man5/systemd.mount.5 | 671 + upstream/debian-unstable/man5/systemd.netdev.5 | 2746 ++++ upstream/debian-unstable/man5/systemd.network.5 | 6224 ++++++++ upstream/debian-unstable/man5/systemd.nspawn.5 | 592 + upstream/debian-unstable/man5/systemd.path.5 | 211 + upstream/debian-unstable/man5/systemd.pcrlock.5 | 276 + upstream/debian-unstable/man5/systemd.preset.5 | 220 + .../man5/systemd.resource-control.5 | 1826 +++ upstream/debian-unstable/man5/systemd.scope.5 | 170 + upstream/debian-unstable/man5/systemd.service.5 | 2211 +++ upstream/debian-unstable/man5/systemd.slice.5 | 120 + upstream/debian-unstable/man5/systemd.socket.5 | 915 ++ upstream/debian-unstable/man5/systemd.swap.5 | 247 + upstream/debian-unstable/man5/systemd.target.5 | 177 + upstream/debian-unstable/man5/systemd.timer.5 | 388 + upstream/debian-unstable/man5/systemd.unit.5 | 3015 ++++ upstream/debian-unstable/man5/sysupdate.d.5 | 1340 ++ upstream/debian-unstable/man5/sysusers.d.5 | 377 + upstream/debian-unstable/man5/term.5 | 452 + upstream/debian-unstable/man5/termcap.5 | 466 + upstream/debian-unstable/man5/terminfo.5 | 4345 ++++++ upstream/debian-unstable/man5/texinfo.5 | 50 + upstream/debian-unstable/man5/thinkfan.conf.5 | 420 + .../debian-unstable/man5/thinkfan.conf.legacy.5 | 253 + upstream/debian-unstable/man5/timesyncd.conf.5 | 140 + upstream/debian-unstable/man5/tmpfiles.d.5 | 1051 ++ upstream/debian-unstable/man5/tmpfs-config.5 | 207 + upstream/debian-unstable/man5/tmpfs.5 | 271 + upstream/debian-unstable/man5/ttytype.5 | 56 + upstream/debian-unstable/man5/tzfile.5 | 512 + upstream/debian-unstable/man5/udev.conf.5 | 112 + upstream/debian-unstable/man5/updatedb.conf.5 | 143 + upstream/debian-unstable/man5/user@.service.5 | 197 + upstream/debian-unstable/man5/user_caps.5 | 464 + upstream/debian-unstable/man5/utmp.5 | 348 + upstream/debian-unstable/man5/uuencode.5 | 140 + upstream/debian-unstable/man5/veritytab.5 | 275 + upstream/debian-unstable/man5/vlock-plugins.5 | 45 + upstream/debian-unstable/man5/warnquota.conf.5 | 184 + upstream/debian-unstable/man5/whois.conf.5 | 50 + upstream/debian-unstable/man5/x509v3_config.5ssl | 684 + upstream/debian-unstable/man5/xfs.5 | 370 + .../debian-unstable/man5/yum-versionlock.conf.5 | 182 + 302 files changed, 156606 insertions(+) create mode 100644 upstream/debian-unstable/man5/acct.5 create mode 100644 upstream/debian-unstable/man5/aliases.sendmail.5 create mode 100644 upstream/debian-unstable/man5/anacrontab.5 create mode 100644 upstream/debian-unstable/man5/at.allow.5 create mode 100644 upstream/debian-unstable/man5/autolog.conf.5 create mode 100644 upstream/debian-unstable/man5/binfmt.d.5 create mode 100644 upstream/debian-unstable/man5/bootchart.conf.5 create mode 100644 upstream/debian-unstable/man5/btrfs.5 create mode 100644 upstream/debian-unstable/man5/charmap.5 create mode 100644 upstream/debian-unstable/man5/config.5ssl create mode 100644 upstream/debian-unstable/man5/core.5 create mode 100644 upstream/debian-unstable/man5/coredump.conf.5 create mode 100644 upstream/debian-unstable/man5/crontab.5 create mode 100644 upstream/debian-unstable/man5/crypt.5 create mode 100644 upstream/debian-unstable/man5/crypttab.5 create mode 100644 upstream/debian-unstable/man5/depmod.d.5 create mode 100644 upstream/debian-unstable/man5/dir_colors.5 create mode 100644 upstream/debian-unstable/man5/dnssec-trust-anchors.d.5 create mode 100644 upstream/debian-unstable/man5/e2fsck.conf.5 create mode 100644 upstream/debian-unstable/man5/elf.5 create mode 100644 upstream/debian-unstable/man5/environment.d.5 create mode 100644 upstream/debian-unstable/man5/erofs.5 create mode 100644 upstream/debian-unstable/man5/ethers.5 create mode 100644 upstream/debian-unstable/man5/exports.5 create mode 100644 upstream/debian-unstable/man5/ext4.5 create mode 100644 upstream/debian-unstable/man5/extendedopacity.5 create mode 100644 upstream/debian-unstable/man5/filesystems.5 create mode 100644 upstream/debian-unstable/man5/fips_config.5ssl create mode 100644 upstream/debian-unstable/man5/ftpchroot.5 create mode 100644 upstream/debian-unstable/man5/ftpusers.5 create mode 100644 upstream/debian-unstable/man5/gai.conf.5 create mode 100644 upstream/debian-unstable/man5/genisoimagerc.5 create mode 100644 upstream/debian-unstable/man5/gpm.conf.5 create mode 100644 upstream/debian-unstable/man5/groff_font.5 create mode 100644 upstream/debian-unstable/man5/groff_out.5 create mode 100644 upstream/debian-unstable/man5/groff_tmac.5 create mode 100644 upstream/debian-unstable/man5/group.5 create mode 100644 upstream/debian-unstable/man5/halt.5 create mode 100644 upstream/debian-unstable/man5/hdparm.conf.5 create mode 100644 upstream/debian-unstable/man5/homed.conf.5 create mode 100644 upstream/debian-unstable/man5/host.conf.5 create mode 100644 upstream/debian-unstable/man5/hostname.5 create mode 100644 upstream/debian-unstable/man5/hosts.5 create mode 100644 upstream/debian-unstable/man5/hosts.equiv.5 create mode 100644 upstream/debian-unstable/man5/hwclock.5 create mode 100644 upstream/debian-unstable/man5/icewm-env.5 create mode 100644 upstream/debian-unstable/man5/icewm-focus_mode.5 create mode 100644 upstream/debian-unstable/man5/icewm-keys.5 create mode 100644 upstream/debian-unstable/man5/icewm-menu.5 create mode 100644 upstream/debian-unstable/man5/icewm-preferences.5 create mode 100644 upstream/debian-unstable/man5/icewm-prefoverride.5 create mode 100644 upstream/debian-unstable/man5/icewm-programs.5 create mode 100644 upstream/debian-unstable/man5/icewm-shutdown.5 create mode 100644 upstream/debian-unstable/man5/icewm-startup.5 create mode 100644 upstream/debian-unstable/man5/icewm-theme.5 create mode 100644 upstream/debian-unstable/man5/icewm-toolbar.5 create mode 100644 upstream/debian-unstable/man5/icewm-winoptions.5 create mode 100644 upstream/debian-unstable/man5/inetutils-netrc.5 create mode 100644 upstream/debian-unstable/man5/info.5 create mode 100644 upstream/debian-unstable/man5/integritytab.5 create mode 100644 upstream/debian-unstable/man5/intro.5 create mode 100644 upstream/debian-unstable/man5/iocost.conf.5 create mode 100644 upstream/debian-unstable/man5/issue.5 create mode 100644 upstream/debian-unstable/man5/issue.net.5 create mode 100644 upstream/debian-unstable/man5/journal-remote.conf.5 create mode 100644 upstream/debian-unstable/man5/journal-upload.conf.5 create mode 100644 upstream/debian-unstable/man5/journald.conf.5 create mode 100644 upstream/debian-unstable/man5/keymaps.5 create mode 100644 upstream/debian-unstable/man5/lmhosts.5 create mode 100644 upstream/debian-unstable/man5/loader.conf.5 create mode 100644 upstream/debian-unstable/man5/locale.5 create mode 100644 upstream/debian-unstable/man5/locale.conf.5 create mode 100644 upstream/debian-unstable/man5/locale.gen.5 create mode 100644 upstream/debian-unstable/man5/localtime.5 create mode 100644 upstream/debian-unstable/man5/locatedb.5 create mode 100644 upstream/debian-unstable/man5/logind.conf.5 create mode 100644 upstream/debian-unstable/man5/lpd.conf.5 create mode 100644 upstream/debian-unstable/man5/lpd.perms.5 create mode 100644 upstream/debian-unstable/man5/machine-id.5 create mode 100644 upstream/debian-unstable/man5/machine-info.5 create mode 100644 upstream/debian-unstable/man5/magic.5 create mode 100644 upstream/debian-unstable/man5/maildir.maildrop.5 create mode 100644 upstream/debian-unstable/man5/mbox.5 create mode 100644 upstream/debian-unstable/man5/mke2fs.conf.5 create mode 100644 upstream/debian-unstable/man5/mmdf.5 create mode 100644 upstream/debian-unstable/man5/modprobe.d.5 create mode 100644 upstream/debian-unstable/man5/modules-load.d.5 create mode 100644 upstream/debian-unstable/man5/modules.dep.5 create mode 100644 upstream/debian-unstable/man5/moduli.5 create mode 100644 upstream/debian-unstable/man5/motd.5 create mode 100644 upstream/debian-unstable/man5/mtools.5 create mode 100644 upstream/debian-unstable/man5/muttrc.5 create mode 100644 upstream/debian-unstable/man5/nanorc.5 create mode 100644 upstream/debian-unstable/man5/networkd.conf.5 create mode 100644 upstream/debian-unstable/man5/networks.5 create mode 100644 upstream/debian-unstable/man5/nfs.5 create mode 100644 upstream/debian-unstable/man5/nfs.conf.5 create mode 100644 upstream/debian-unstable/man5/nfsmount.conf.5 create mode 100644 upstream/debian-unstable/man5/nfsrahead.5 create mode 100644 upstream/debian-unstable/man5/nologin.5 create mode 100644 upstream/debian-unstable/man5/nscd.conf.5 create mode 100644 upstream/debian-unstable/man5/nss.5 create mode 100644 upstream/debian-unstable/man5/nsswitch.conf.5 create mode 100644 upstream/debian-unstable/man5/oomd.conf.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.LogControl1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.home1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.hostname1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.import1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.locale1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.login1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.machine1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.network1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.oom1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.portable1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.resolve1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.systemd1.5 create mode 100644 upstream/debian-unstable/man5/org.freedesktop.timedate1.5 create mode 100644 upstream/debian-unstable/man5/os-release.5 create mode 100644 upstream/debian-unstable/man5/pam.5 create mode 100644 upstream/debian-unstable/man5/pam.conf.5 create mode 100644 upstream/debian-unstable/man5/pbm.5 create mode 100644 upstream/debian-unstable/man5/pci.ids.5 create mode 100644 upstream/debian-unstable/man5/pfm.5 create mode 100644 upstream/debian-unstable/man5/pgm.5 create mode 100644 upstream/debian-unstable/man5/pnm.5 create mode 100644 upstream/debian-unstable/man5/ppm.5 create mode 100644 upstream/debian-unstable/man5/printcap.5 create mode 100644 upstream/debian-unstable/man5/proc.5 create mode 100644 upstream/debian-unstable/man5/procmailex.5 create mode 100644 upstream/debian-unstable/man5/procmailrc.5 create mode 100644 upstream/debian-unstable/man5/procmailsc.5 create mode 100644 upstream/debian-unstable/man5/projects.5 create mode 100644 upstream/debian-unstable/man5/projid.5 create mode 100644 upstream/debian-unstable/man5/protocols.5 create mode 100644 upstream/debian-unstable/man5/pstore.conf.5 create mode 100644 upstream/debian-unstable/man5/quotagrpadmins.5 create mode 100644 upstream/debian-unstable/man5/quotatab.5 create mode 100644 upstream/debian-unstable/man5/rcS.5 create mode 100644 upstream/debian-unstable/man5/rcsfile.5 create mode 100644 upstream/debian-unstable/man5/repart.d.5 create mode 100644 upstream/debian-unstable/man5/repertoiremap.5 create mode 100644 upstream/debian-unstable/man5/resolv.conf.5 create mode 100644 upstream/debian-unstable/man5/resolved.conf.5 create mode 100644 upstream/debian-unstable/man5/rhosts.5 create mode 100644 upstream/debian-unstable/man5/rpc.5 create mode 100644 upstream/debian-unstable/man5/rsyncd.conf.5 create mode 100644 upstream/debian-unstable/man5/sane-abaton.5 create mode 100644 upstream/debian-unstable/man5/sane-agfafocus.5 create mode 100644 upstream/debian-unstable/man5/sane-airscan.5 create mode 100644 upstream/debian-unstable/man5/sane-apple.5 create mode 100644 upstream/debian-unstable/man5/sane-artec.5 create mode 100644 upstream/debian-unstable/man5/sane-artec_eplus48u.5 create mode 100644 upstream/debian-unstable/man5/sane-as6e.5 create mode 100644 upstream/debian-unstable/man5/sane-avision.5 create mode 100644 upstream/debian-unstable/man5/sane-bh.5 create mode 100644 upstream/debian-unstable/man5/sane-canon.5 create mode 100644 upstream/debian-unstable/man5/sane-canon630u.5 create mode 100644 upstream/debian-unstable/man5/sane-canon_dr.5 create mode 100644 upstream/debian-unstable/man5/sane-canon_lide70.5 create mode 100644 upstream/debian-unstable/man5/sane-canon_pp.5 create mode 100644 upstream/debian-unstable/man5/sane-cardscan.5 create mode 100644 upstream/debian-unstable/man5/sane-coolscan.5 create mode 100644 upstream/debian-unstable/man5/sane-coolscan2.5 create mode 100644 upstream/debian-unstable/man5/sane-coolscan3.5 create mode 100644 upstream/debian-unstable/man5/sane-dc210.5 create mode 100644 upstream/debian-unstable/man5/sane-dc240.5 create mode 100644 upstream/debian-unstable/man5/sane-dc25.5 create mode 100644 upstream/debian-unstable/man5/sane-dll.5 create mode 100644 upstream/debian-unstable/man5/sane-dmc.5 create mode 100644 upstream/debian-unstable/man5/sane-epjitsu.5 create mode 100644 upstream/debian-unstable/man5/sane-epson.5 create mode 100644 upstream/debian-unstable/man5/sane-epson2.5 create mode 100644 upstream/debian-unstable/man5/sane-epsonds.5 create mode 100644 upstream/debian-unstable/man5/sane-escl.5 create mode 100644 upstream/debian-unstable/man5/sane-fujitsu.5 create mode 100644 upstream/debian-unstable/man5/sane-genesys.5 create mode 100644 upstream/debian-unstable/man5/sane-gphoto2.5 create mode 100644 upstream/debian-unstable/man5/sane-gt68xx.5 create mode 100644 upstream/debian-unstable/man5/sane-hp.5 create mode 100644 upstream/debian-unstable/man5/sane-hp3500.5 create mode 100644 upstream/debian-unstable/man5/sane-hp3900.5 create mode 100644 upstream/debian-unstable/man5/sane-hp4200.5 create mode 100644 upstream/debian-unstable/man5/sane-hp5400.5 create mode 100644 upstream/debian-unstable/man5/sane-hp5590.5 create mode 100644 upstream/debian-unstable/man5/sane-hpljm1005.5 create mode 100644 upstream/debian-unstable/man5/sane-hpsj5s.5 create mode 100644 upstream/debian-unstable/man5/sane-hs2p.5 create mode 100644 upstream/debian-unstable/man5/sane-ibm.5 create mode 100644 upstream/debian-unstable/man5/sane-kodak.5 create mode 100644 upstream/debian-unstable/man5/sane-kodakaio.5 create mode 100644 upstream/debian-unstable/man5/sane-kvs1025.5 create mode 100644 upstream/debian-unstable/man5/sane-kvs20xx.5 create mode 100644 upstream/debian-unstable/man5/sane-kvs40xx.5 create mode 100644 upstream/debian-unstable/man5/sane-leo.5 create mode 100644 upstream/debian-unstable/man5/sane-lexmark.5 create mode 100644 upstream/debian-unstable/man5/sane-ma1509.5 create mode 100644 upstream/debian-unstable/man5/sane-magicolor.5 create mode 100644 upstream/debian-unstable/man5/sane-matsushita.5 create mode 100644 upstream/debian-unstable/man5/sane-microtek.5 create mode 100644 upstream/debian-unstable/man5/sane-microtek2.5 create mode 100644 upstream/debian-unstable/man5/sane-mustek.5 create mode 100644 upstream/debian-unstable/man5/sane-mustek_pp.5 create mode 100644 upstream/debian-unstable/man5/sane-mustek_usb.5 create mode 100644 upstream/debian-unstable/man5/sane-mustek_usb2.5 create mode 100644 upstream/debian-unstable/man5/sane-nec.5 create mode 100644 upstream/debian-unstable/man5/sane-net.5 create mode 100644 upstream/debian-unstable/man5/sane-niash.5 create mode 100644 upstream/debian-unstable/man5/sane-p5.5 create mode 100644 upstream/debian-unstable/man5/sane-pie.5 create mode 100644 upstream/debian-unstable/man5/sane-pieusb.5 create mode 100644 upstream/debian-unstable/man5/sane-pixma.5 create mode 100644 upstream/debian-unstable/man5/sane-plustek.5 create mode 100644 upstream/debian-unstable/man5/sane-plustek_pp.5 create mode 100644 upstream/debian-unstable/man5/sane-pnm.5 create mode 100644 upstream/debian-unstable/man5/sane-qcam.5 create mode 100644 upstream/debian-unstable/man5/sane-ricoh.5 create mode 100644 upstream/debian-unstable/man5/sane-ricoh2.5 create mode 100644 upstream/debian-unstable/man5/sane-rts8891.5 create mode 100644 upstream/debian-unstable/man5/sane-s9036.5 create mode 100644 upstream/debian-unstable/man5/sane-sceptre.5 create mode 100644 upstream/debian-unstable/man5/sane-scsi.5 create mode 100644 upstream/debian-unstable/man5/sane-sharp.5 create mode 100644 upstream/debian-unstable/man5/sane-sm3600.5 create mode 100644 upstream/debian-unstable/man5/sane-sm3840.5 create mode 100644 upstream/debian-unstable/man5/sane-snapscan.5 create mode 100644 upstream/debian-unstable/man5/sane-sp15c.5 create mode 100644 upstream/debian-unstable/man5/sane-st400.5 create mode 100644 upstream/debian-unstable/man5/sane-stv680.5 create mode 100644 upstream/debian-unstable/man5/sane-tamarack.5 create mode 100644 upstream/debian-unstable/man5/sane-teco1.5 create mode 100644 upstream/debian-unstable/man5/sane-teco2.5 create mode 100644 upstream/debian-unstable/man5/sane-teco3.5 create mode 100644 upstream/debian-unstable/man5/sane-test.5 create mode 100644 upstream/debian-unstable/man5/sane-u12.5 create mode 100644 upstream/debian-unstable/man5/sane-umax.5 create mode 100644 upstream/debian-unstable/man5/sane-umax1220u.5 create mode 100644 upstream/debian-unstable/man5/sane-umax_pp.5 create mode 100644 upstream/debian-unstable/man5/sane-usb.5 create mode 100644 upstream/debian-unstable/man5/sane-xerox_mfp.5 create mode 100644 upstream/debian-unstable/man5/scr_dump.5 create mode 100644 upstream/debian-unstable/man5/securetty.5 create mode 100644 upstream/debian-unstable/man5/services.5 create mode 100644 upstream/debian-unstable/man5/shells.5 create mode 100644 upstream/debian-unstable/man5/slabinfo.5 create mode 100644 upstream/debian-unstable/man5/smb.conf.5 create mode 100644 upstream/debian-unstable/man5/smbpasswd.5 create mode 100644 upstream/debian-unstable/man5/ssh_config.5 create mode 100644 upstream/debian-unstable/man5/sshd_config.5 create mode 100644 upstream/debian-unstable/man5/sysctl.d.5 create mode 100644 upstream/debian-unstable/man5/sysfs.5 create mode 100644 upstream/debian-unstable/man5/sysstat.5 create mode 100644 upstream/debian-unstable/man5/systemd-sleep.conf.5 create mode 100644 upstream/debian-unstable/man5/systemd-system.conf.5 create mode 100644 upstream/debian-unstable/man5/systemd.automount.5 create mode 100644 upstream/debian-unstable/man5/systemd.device.5 create mode 100644 upstream/debian-unstable/man5/systemd.dnssd.5 create mode 100644 upstream/debian-unstable/man5/systemd.exec.5 create mode 100644 upstream/debian-unstable/man5/systemd.kill.5 create mode 100644 upstream/debian-unstable/man5/systemd.link.5 create mode 100644 upstream/debian-unstable/man5/systemd.mount.5 create mode 100644 upstream/debian-unstable/man5/systemd.netdev.5 create mode 100644 upstream/debian-unstable/man5/systemd.network.5 create mode 100644 upstream/debian-unstable/man5/systemd.nspawn.5 create mode 100644 upstream/debian-unstable/man5/systemd.path.5 create mode 100644 upstream/debian-unstable/man5/systemd.pcrlock.5 create mode 100644 upstream/debian-unstable/man5/systemd.preset.5 create mode 100644 upstream/debian-unstable/man5/systemd.resource-control.5 create mode 100644 upstream/debian-unstable/man5/systemd.scope.5 create mode 100644 upstream/debian-unstable/man5/systemd.service.5 create mode 100644 upstream/debian-unstable/man5/systemd.slice.5 create mode 100644 upstream/debian-unstable/man5/systemd.socket.5 create mode 100644 upstream/debian-unstable/man5/systemd.swap.5 create mode 100644 upstream/debian-unstable/man5/systemd.target.5 create mode 100644 upstream/debian-unstable/man5/systemd.timer.5 create mode 100644 upstream/debian-unstable/man5/systemd.unit.5 create mode 100644 upstream/debian-unstable/man5/sysupdate.d.5 create mode 100644 upstream/debian-unstable/man5/sysusers.d.5 create mode 100644 upstream/debian-unstable/man5/term.5 create mode 100644 upstream/debian-unstable/man5/termcap.5 create mode 100644 upstream/debian-unstable/man5/terminfo.5 create mode 100644 upstream/debian-unstable/man5/texinfo.5 create mode 100644 upstream/debian-unstable/man5/thinkfan.conf.5 create mode 100644 upstream/debian-unstable/man5/thinkfan.conf.legacy.5 create mode 100644 upstream/debian-unstable/man5/timesyncd.conf.5 create mode 100644 upstream/debian-unstable/man5/tmpfiles.d.5 create mode 100644 upstream/debian-unstable/man5/tmpfs-config.5 create mode 100644 upstream/debian-unstable/man5/tmpfs.5 create mode 100644 upstream/debian-unstable/man5/ttytype.5 create mode 100644 upstream/debian-unstable/man5/tzfile.5 create mode 100644 upstream/debian-unstable/man5/udev.conf.5 create mode 100644 upstream/debian-unstable/man5/updatedb.conf.5 create mode 100644 upstream/debian-unstable/man5/user@.service.5 create mode 100644 upstream/debian-unstable/man5/user_caps.5 create mode 100644 upstream/debian-unstable/man5/utmp.5 create mode 100644 upstream/debian-unstable/man5/uuencode.5 create mode 100644 upstream/debian-unstable/man5/veritytab.5 create mode 100644 upstream/debian-unstable/man5/vlock-plugins.5 create mode 100644 upstream/debian-unstable/man5/warnquota.conf.5 create mode 100644 upstream/debian-unstable/man5/whois.conf.5 create mode 100644 upstream/debian-unstable/man5/x509v3_config.5ssl create mode 100644 upstream/debian-unstable/man5/xfs.5 create mode 100644 upstream/debian-unstable/man5/yum-versionlock.conf.5 (limited to 'upstream/debian-unstable/man5') diff --git a/upstream/debian-unstable/man5/acct.5 b/upstream/debian-unstable/man5/acct.5 new file mode 100644 index 00000000..e1d88d4a --- /dev/null +++ b/upstream/debian-unstable/man5/acct.5 @@ -0,0 +1,161 @@ +.\" Copyright (C) 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH acct 5 2023-05-03 "Linux man-pages 6.05.01" +.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: +.PP +.in +4n +acct("/var/log/pacct"); +.in +.PP +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: +.PP +.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 +.PP +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: +.PP +.nf + v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3); +.fi +.PP +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: +.PP +.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. +.PP +Process accounting originated on BSD. +.SH NOTES +Records in the accounting file are ordered by termination time of +the process. +.PP +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. +.PP +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/debian-unstable/man5/aliases.sendmail.5 b/upstream/debian-unstable/man5/aliases.sendmail.5 new file mode 100644 index 00000000..cb675087 --- /dev/null +++ b/upstream/debian-unstable/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/mail +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/mail/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/debian-unstable/man5/anacrontab.5 b/upstream/debian-unstable/man5/anacrontab.5 new file mode 100644 index 00000000..f03ede2b --- /dev/null +++ b/upstream/debian-unstable/man5/anacrontab.5 @@ -0,0 +1,63 @@ +.TH ANACRONTAB 5 2004-07-11 "Pascal Hakim" "Anacron Users' Manual" +.SH NAME +/etc/anacrontab \- configuration file for anacron +.SH DESCRIPTION +The file +.I /etc/anacrontab +describes the jobs controlled by \fBanacron\fR(8).\& +Its lines can be of three kinds: job-description lines, environment +assignments, or empty lines.\& +.PP +Job-description lines are of one of these two forms: +.PP + period delay job-identifier command +.PP + @period_name delay job-identify command +.PP +The +.I period +is specified in days, the +.I delay +in minutes.\& +The +.I job-identifier +can contain any non-blank character, except slashes.\& +It is used to identify the job in Anacron messages, and as the name for the +job's timestamp file.\& +The +.I command +can be any shell command.\& +The fields can be separated by blank spaces or tabs.\& +The +.I period_name +can only be set to monthly at the present time.\& +This will ensure jobs are only run once a month, no matter the number of days +in this month, or the previous month.\& +.PP +Environment assignment lines are of the form: +.PP + VAR = VALUE +.PP +Spaces around +.I VAR +are removed.\& +No spaces around +.I VALUE +are allowed \%(unless you want them to be part of the value).\& +The assignment takes effect from the next line to the end of the file, or to +the next assignment of the same variable.\& +.PP +Empty lines are either blank lines, line containing white-space only, or lines +with white-space followed by a \&'#'\& followed by an arbitrary comment.\& +.PP +You can continue a line onto the next line by ending it with a \&'\e'.\& +.SH "SEE ALSO" +\fBanacron\fR(8) +.PP +The Anacron +.I README +file.\& +.SH AUTHOR +Itai Tzur \% +.PP +Currently maintained by Lance Lin \%.\& diff --git a/upstream/debian-unstable/man5/at.allow.5 b/upstream/debian-unstable/man5/at.allow.5 new file mode 100644 index 00000000..ece2f507 --- /dev/null +++ b/upstream/debian-unstable/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/debian-unstable/man5/autolog.conf.5 b/upstream/debian-unstable/man5/autolog.conf.5 new file mode 100644 index 00000000..75da4a7c --- /dev/null +++ b/upstream/debian-unstable/man5/autolog.conf.5 @@ -0,0 +1,114 @@ +.TH autolog.conf 5 "Configuration Files" "Linux" \" -*- nroff -*- +.SH NAME +autolog.conf \- Configuration file for the autolog command +.SH DESCRIPTION +The configuration file consists of multiple lines, each of which describes +a class of processes subject (or not subject) to a certain auto logout +procedure. A line consists of any number of switches. Value switches are +of the form: "name=value". Boolean switches are of the form: "name" or +"noname". +.PP +Using these switches, you can define a username, a group, and a tty line. +These descriptions can contain wildcard characters (regular expressions). +You can also define an idle time, a grace period and a few other options. +When reading the configuration file, the program creates a record for each +configuration line. A value is assigned to each variable in the record +regardless of whether or not you specify one explicitly. Values for +missing variables are provided by defaults which are compiled in and can +be modified from the command line. +.PP +If no entries are found matching a given process, that process will be +spared from an untimely demise. Therefore, it is a good idea to always +have a "cleanup" line at the end of the configuration file to catch +anything that might have been missed by the more explicit definitions. +Since the default name, group, and line are all ".+", a simple line like: + + idle=30 + +will do. Actually, any one switch can be specified on the line and all the +others will get the default values. +.PP +If no configuration file is found, the program will create a single +entry which has all values set from the defaults. This entry will match +any process on any port (name=.+ line=.+ group=.+). Therefore, the default +action is to kill all processes. +.SH ENTRIES +.TP +.B name= +A regular expression specifying which username(s) to match. +.TP +.B group= +A regular expression specifying which group(s) to match. +.TP +.B line= +A regular expression specifying which tty line(s) to match. +Omit the "/dev/" part of the special name. +.TP +.B idle= +An integer specifying the number of \-\-minutes\-\- of idle +(or connect) time to allow before beginning automatic logoff. +An idle time of 0 exempts the process from automatic logoff. +.TP +.B grace= +An integer specifying the number of \-\-seconds\-\- from the initial +warning to killing the process. +.TP +.B ban= +An integer specifying the number of \-\-minutes\-\- from killing the process +to the moment, the user may login again. (after exceeding his session). + +.TP +.B hard +A boolean value indicating total connect time will be +considered rather than idle time. +.TP +.B mail +A boolean value indicating that mail will be sent to the +user explaining that he was killed. +.TP +.B clear +A boolean value indicating that the screen will be cleared +before a warning message is sent. +.TP +.B warn +A boolean value indicating that a warning message will be +sent at the beginning of the "grace" period. +.TP +.B log +A boolean value indicating that activities will be logged +to the logfile (if it exists). + +.SH FURTHER ENTRIES +.PP +There is another group of entries, which allows one to set some +general options. Each of them takes a whole line. +Don't mix them with the other entries from before. +.TP +.B nolostkill +A boolean value indicating whether lost processes should be killed. +If there is a process with uid between 500 and 60000 and the owner +is not logged in, it is assumed as lost and will be killed. + +.TP +.B ps=command +on some strange or old systems the ps-command has different parameters. +This makes it possible to set a completely different command. It is only +important, that this command delivers one heading line and then lines +with usernames and process-ids (pid). e.g.: ps=ps aux + +.SH EXAMPLE + name=root line=tty[1-7] idle=0 + name=guest idle=5 grace=60 nomail hard warn + group=lynx-.* idle=10 grace=60 clear + idle=60 grace=30 + +.SH AUTHOR +Kyle Bateman (autolog 0.35), +.PD 0 +.TP +James Dingwall +.TP + (autolog 0.41) +.PD +.PP +This manual page was modified for \fBDebian\fP by Paul Telford diff --git a/upstream/debian-unstable/man5/binfmt.d.5 b/upstream/debian-unstable/man5/binfmt.d.5 new file mode 100644 index 00000000..f03a5a39 --- /dev/null +++ b/upstream/debian-unstable/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/debian-unstable/man5/bootchart.conf.5 b/upstream/debian-unstable/man5/bootchart.conf.5 new file mode 100644 index 00000000..17ef2f19 --- /dev/null +++ b/upstream/debian-unstable/man5/bootchart.conf.5 @@ -0,0 +1,123 @@ +'\" t +.TH "BOOTCHART\&.CONF" "5" "" "systemd 235" "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/debian-unstable/man5/btrfs.5 b/upstream/debian-unstable/man5/btrfs.5 new file mode 100644 index 00000000..28511197 --- /dev/null +++ b/upstream/debian-unstable/man5/btrfs.5 @@ -0,0 +1,2847 @@ +'\" t +.\" 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 28, 2024" "6.6.3" "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 +.EX +# truncate \-s 0 swapfile +# chattr +C swapfile +# fallocate \-l 2G swapfile +# chmod 0600 swapfile +# mkswap swapfile +# swapon swapfile +.EE +.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 +.EX +# btrfs filesystem mkswapfile \-\-size 2G swapfile +# swapon swapfile +.EE +.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 +.EX +# cat /proc/swaps +Filename Type Size Used Priority +/path/swapfile file 2097152 0 \-2 +.EE +.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 +.EX +/path/swapfile none swap defaults 0 0 +.EE +.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 +.EX +# btrfs filesystem mkswapfile swapfile +# btrfs inspect\-internal map\-swapfile swapfile +Physical start: 811511726080 +Resume offset: 198122980 +.EE +.UNINDENT +.UNINDENT +.sp +For scripting and convenience the option \fI\-r\fP will print just the offset: +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +# btrfs inspect\-internal map\-swapfile \-r swapfile +198122980 +.EE +.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 +.EX +# swapon /path/swapfile +swapon: /path/swapfile: swapon failed: Invalid argument +.EE +.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 +.EX +# journalctl \-t kernel | grep swapfile +kernel: BTRFS warning (device sda): swapfile must have single data profile +.EE +.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 reference software implementations on a 3.5GHz 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{ +1700 +T} T{ +1.00 +T} T{ +CPU instruction +T} +_ +T{ +XXHASH +T} T{ +2500 +T} T{ +1.44 +T} T{ +reference impl. +T} +_ +T{ +SHA256 +T} T{ +105000 +T} T{ +61 +T} T{ +reference impl. +T} +_ +T{ +SHA256 +T} T{ +36000 +T} T{ +21 +T} T{ +libgcrypt/AVX2 +T} +_ +T{ +SHA256 +T} T{ +63000 +T} T{ +37 +T} T{ +libsodium/AVX2 +T} +_ +T{ +BLAKE2b +T} T{ +22000 +T} T{ +13 +T} T{ +reference impl. +T} +_ +T{ +BLAKE2b +T} T{ +19000 +T} T{ +11 +T} T{ +libgcrypt/AVX2 +T} +_ +T{ +BLAKE2b +T} T{ +19000 +T} T{ +11 +T} T{ +libsodium/AVX2 +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 +.EX +name : sha256 +driver : sha256\-generic +module : kernel +priority : 100 +\&... +.EE +.UNINDENT +.UNINDENT +.sp +while accelerated implementation is e.g. +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +name : sha256 +driver : sha256\-avx2 +module : sha256_ssse3 +priority : 170 +\&... +.EE +.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 +.EX +$ mount \-o compress=zstd /dev/sdx /mnt +.EE +.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 +.EX +$ btrfs filesystem defrag \-czstd file +.EE +.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 +.EX +$ chattr +c file +$ btrfs property set file compression zstd +.EE +.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 +.EX +$ lsattr file +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-m file +.EE +.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 +.EX +modprobe\ configfs +modprobe\ null_blk\ nr_devices=0 +.EE +.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 +.EX +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 +.EE +.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 +.EX +rmdir\ /sys/kernel/config/nullb/mydev +.EE +.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 +.EX +nullb setup +nullb create \-s 2g \-z 256 +mkfs.btrfs /dev/nullb0 +\&... +nullb rm nullb0 +.EE +.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 +.EX +$ ls \-l /dev/btrfs\-control +crw\-\-\-\-\-\-\- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs\-control +.EE +.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 +.EX +# mknod \-\-mode=600 /dev/btrfs\-control c 10 234 +.EE +.UNINDENT +.UNINDENT +.sp +or (since 5.11) by a convenience command +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +# btrfs rescue create\-control\-device +.EE +.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 +.EX +WARNING: Multiple block group profiles detected, see \(aqman btrfs(5)\(aq. +WARNING: Data: single, raid1 +WARNING: Metadata: single, raid1 +.EE +.UNINDENT +.UNINDENT +.sp +The corresponding output of \fBbtrfs filesystem df\fP might look like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +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 +.EE +.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 +.EX +Multiple profiles: yes (data, metadata) +.EE +.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 +.EX +# 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 +.EE +.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 +.EX +# 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 +.EE +.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 +.EX +# btrfs device delete /dev/sda /mnt/mnt1 +.EE +.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 +.EX +# 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 +.EE +.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/debian-unstable/man5/charmap.5 b/upstream/debian-unstable/man5/charmap.5 new file mode 100644 index 00000000..280ba4e5 --- /dev/null +++ b/upstream/debian-unstable/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 2022-10-30 "Linux man-pages 6.05.01" +.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 >. +.PP +The character set definition section starts with the keyword +.I CHARMAP +in the first column. +.PP +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. +.PP +The character set definition section ends with the string +.IR "END CHARMAP" . +.PP +The character set definition section may optionally be followed by a +section to define widths of characters. +.PP +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. +.PP +The width section for individual characters starts with the keyword +.I WIDTH +in the first column. +.PP +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. +.PP +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: +.PP +.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/debian-unstable/man5/config.5ssl b/upstream/debian-unstable/man5/config.5ssl new file mode 100644 index 00000000..c9d3cb55 --- /dev/null +++ b/upstream/debian-unstable/man5/config.5ssl @@ -0,0 +1,632 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 "CONFIG 5SSL" +.TH CONFIG 5SSL 2024-02-03 3.1.5 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +config \- OpenSSL CONF library configuration files +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This page documents the syntax of OpenSSL configuration files, +as parsed by \fBNCONF_load\fR\|(3) and related functions. +This format is used by many of the OpenSSL commands, and to +initialize the libraries when used by any application. +.PP +The first part describes the general syntax of the configuration +files, and subsequent sections describe the semantics of individual +modules. Other modules are described in \fBfips_config\fR\|(5) and +\&\fBx509v3_config\fR\|(5). +The syntax for defining ASN.1 values is described in +\&\fBASN1_generate_nconf\fR\|(3). +.SH SYNTAX +.IX Header "SYNTAX" +A configuration file is a series of lines. Blank lines, and whitespace +between the elements of a line, have no significance. A comment starts +with a \fB#\fR character; the rest of the line is ignored. If the \fB#\fR +is the first non-space character in a line, the entire line is ignored. +.SS Directives +.IX Subsection "Directives" +Two directives can be used to control the parsing of configuration files: +\&\fB.include\fR and \fB.pragma\fR. +.PP +For compatibility with older versions of OpenSSL, an equal sign after the +directive will be ignored. Older versions will treat it as an assignment, +so care should be taken if the difference in semantics is important. +.PP +A file can include other files using the include syntax: +.PP +.Vb 1 +\& .include [=] pathname +.Ve +.PP +If \fBpathname\fR is a simple filename, that file is included directly at +that point. Included files can have \fB.include\fR statements that specify +other files. If \fBpathname\fR is a directory, all files within that directory +that have a \f(CW\*(C`.cnf\*(C'\fR or \f(CW\*(C`.conf\*(C'\fR extension will be included. (This is only +available on systems with POSIX IO support.) Any sub-directories found +inside the \fBpathname\fR are \fBignored\fR. Similarly, if a file is opened +while scanning a directory, and that file has an \fB.include\fR directive +that specifies a directory, that is also ignored. +.PP +As a general rule, the \fBpathname\fR should be an absolute path; this can +be enforced with the \fBabspath\fR and \fBincludedir\fR pragmas, described below. +The environment variable \fBOPENSSL_CONF_INCLUDE\fR, if it exists, +is prepended to all relative pathnames. +If the pathname is still relative, it is interpreted based on the +current working directory. +.PP +To require all file inclusions to name absolute paths, use the following +directive: +.PP +.Vb 1 +\& .pragma [=] abspath:value +.Ve +.PP +The default behavior, where the \fBvalue\fR is \fBfalse\fR or \fBoff\fR, is to allow +relative paths. To require all \fB.include\fR pathnames to be absolute paths, +use a \fBvalue\fR of \fBtrue\fR or \fBon\fR. +.PP +In these files, the dollar sign, \fB$\fR, is used to reference a variable, as +described below. On some platforms, however, it is common to treat \fB$\fR +as a regular character in symbol names. Supporting this behavior can be +done with the following directive: +.PP +.Vb 1 +\& .pragma [=] dollarid:value +.Ve +.PP +The default behavior, where the \fBvalue\fR is \fBfalse\fR or \fBoff\fR, is to treat +the dollarsign as indicating a variable name; \f(CW\*(C`foo$bar\*(C'\fR is interpreted as +\&\f(CW\*(C`foo\*(C'\fR followed by the expansion of the variable \f(CW\*(C`bar\*(C'\fR. If \fBvalue\fR is +\&\fBtrue\fR or \fBon\fR, then \f(CW\*(C`foo$bar\*(C'\fR is a single seven-character name and +variable expansions must be specified using braces or parentheses. +.PP +.Vb 1 +\& .pragma [=] includedir:value +.Ve +.PP +If a relative pathname is specified in the \fB.include\fR directive, and +the \fBOPENSSL_CONF_INCLUDE\fR environment variable doesn't exist, then +the value of the \fBincludedir\fR pragma, if it exists, is prepended to the +pathname. +.SS Settings +.IX Subsection "Settings" +A configuration file is divided into a number of \fIsections\fR. A section +begins with the section name in square brackets, and ends when a new +section starts, or at the end of the file. The section name can consist +of alphanumeric characters and underscores. +Whitespace between the name and the brackets is removed. +.PP +The first section of a configuration file is special and is referred to +as the \fBdefault\fR section. This section is usually unnamed and spans from +the start of file until the first named section. When a name is being +looked up, it is first looked up in the current or named section, +and then the default section if necessary. +.PP +The environment is mapped onto a section called \fBENV\fR. +.PP +Within a section are a series of name/value assignments, described in more +detail below. As a reminder, the square brackets shown in this example +are required, not optional: +.PP +.Vb 7 +\& [ section ] +\& name1 = This is value1 +\& name2 = Another value +\& ... +\& [ newsection ] +\& name1 = New value1 +\& name3 = Value 3 +.Ve +.PP +The \fBname\fR can contain any alphanumeric characters as well as a few +punctuation symbols such as \fB.\fR \fB,\fR \fB;\fR and \fB_\fR. +Whitespace after the name and before the equal sign is ignored. +.PP +If a name is repeated in the same section, then all but the last +value are ignored. In certain circumstances, such as with +Certificate DNs, the same field may occur multiple times. +In order to support this, commands like \fBopenssl\-req\fR\|(1) ignore any +leading text that is preceded with a period. For example: +.PP +.Vb 2 +\& 1.OU = First OU +\& 2.OU = Second OU +.Ve +.PP +The \fBvalue\fR consists of the string following the \fB=\fR character until end +of line with any leading and trailing whitespace removed. +.PP +The value string undergoes variable expansion. The text \f(CW$var\fR or \f(CW\*(C`${var}\*(C'\fR +inserts the value of the named variable from the current section. +To use a value from another section use \f(CW$section::name\fR +or \f(CW\*(C`${section::name}\*(C'\fR. +By using \f(CW$ENV::name\fR, the value of the specified environment +variable will be substituted. +.PP +Variables must be defined before their value is referenced, otherwise +an error is flagged and the file will not load. +This can be worked around by specifying a default value in the \fBdefault\fR +section before the variable is used. +.PP +Any name/value settings in an \fBENV\fR section are available +to the configuration file, but are not propagated to the environment. +.PP +It is an error if the value ends up longer than 64k. +.PP +It is possible to escape certain characters by using a single \fB'\fR or +double \fB"\fR quote around the value, or using a backslash \fB\e\fR before the +character, +By making the last character of a line a \fB\e\fR +a \fBvalue\fR string can be spread across multiple lines. In addition +the sequences \fB\en\fR, \fB\er\fR, \fB\eb\fR and \fB\et\fR are recognized. +.PP +The expansion and escape rules as described above that apply to \fBvalue\fR +also apply to the pathname of the \fB.include\fR directive. +.SH "OPENSSL LIBRARY CONFIGURATION" +.IX Header "OPENSSL LIBRARY CONFIGURATION" +The sections below use the informal term \fImodule\fR to refer to a part +of the OpenSSL functionality. This is not the same as the formal term +\&\fIFIPS module\fR, for example. +.PP +The OpenSSL configuration looks up the value of \fBopenssl_conf\fR +in the default section and takes that as the name of a section that specifies +how to configure any modules in the library. It is not an error to leave +any module in its default configuration. An application can specify a +different name by calling \fBCONF_modules_load_file()\fR, for example, directly. +.PP +OpenSSL also looks up the value of \fBconfig_diagnostics\fR. +If this exists and has a nonzero numeric value, any error suppressing flags +passed to \fBCONF_modules_load()\fR will be ignored. +This is useful for diagnosing misconfigurations but its use in +production requires additional consideration. With this option enabled, +a configuration error will completely prevent access to a service. +Without this option and in the presence of a configuration error, access +will be allowed but the desired configuration will \fBnot\fR be used. +.PP +.Vb 3 +\& # These must be in the default section +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& [openssl_init] +\& oid_section = oids +\& providers = providers +\& alg_section = evp_properties +\& ssl_conf = ssl_configuration +\& engines = engines +\& random = random +\& +\& [oids] +\& ... new oids here ... +\& +\& [providers] +\& ... provider stuff here ... +\& +\& [evp_properties] +\& ... EVP properties here ... +\& +\& [ssl_configuration] +\& ... SSL/TLS configuration properties here ... +\& +\& [engines] +\& ... engine properties here ... +\& +\& [random] +\& ... random properties here ... +.Ve +.PP +The semantics of each module are described below. The phrase "in the +initialization section" refers to the section identified by the +\&\fBopenssl_conf\fR or other name (given as \fBopenssl_init\fR in the +example above). The examples below assume the configuration above +is used to specify the individual sections. +.SS "ASN.1 Object Identifier Configuration" +.IX Subsection "ASN.1 Object Identifier Configuration" +The name \fBoid_section\fR in the initialization section names the section +containing name/value pairs of OID's. +The name is the short name; the value is an optional long name followed +by a comma, and the numeric value. +While some OpenSSL commands have their own section for specifying OID's, +this section makes them available to all commands and applications. +.PP +.Vb 4 +\& [oids] +\& shortName = a very long OID name, 1.2.3.4 +\& newoid1 = 1.2.3.4.1 +\& some_other_oid = 1.2.3.5 +.Ve +.PP +If a full configuration with the above fragment is in the file +\&\fIexample.cnf\fR, then the following command line: +.PP +.Vb 1 +\& OPENSSL_CONF=example.cnf openssl asn1parse \-genstr OID:1.2.3.4.1 +.Ve +.PP +will output: +.PP +.Vb 1 +\& 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 +.Ve +.PP +showing that the OID "newoid1" has been added as "1.2.3.4.1". +.SS "Provider Configuration" +.IX Subsection "Provider Configuration" +The name \fBproviders\fR in the initialization section names the section +containing cryptographic provider configuration. The name/value assignments +in this section each name a provider, and point to the configuration section +for that provider. The provider-specific section is used to specify how +to load the module, activate it, and set other parameters. +.PP +Within a provider section, the following names have meaning: +.IP \fBidentity\fR 4 +.IX Item "identity" +This is used to specify an alternate name, overriding the default name +specified in the list of providers. For example: +.Sp +.Vb 2 +\& [providers] +\& foo = foo_provider +\& +\& [foo_provider] +\& identity = my_fips_module +.Ve +.IP \fBmodule\fR 4 +.IX Item "module" +Specifies the pathname of the module (typically a shared library) to load. +.IP \fBactivate\fR 4 +.IX Item "activate" +If present, the module is activated. The value assigned to this name is not +significant. +.PP +All parameters in the section as well as sub-sections are made +available to the provider. +.PP +\fIDefault provider and its activation\fR +.IX Subsection "Default provider and its activation" +.PP +If no providers are activated explicitly, the default one is activated implicitly. +See \fBOSSL_PROVIDER\-default\fR\|(7) for more details. +.PP +If you add a section explicitly activating any other provider(s), +you most probably need to explicitly activate the default provider, +otherwise it becomes unavailable in openssl. It may make the system remotely unavailable. +.SS "EVP Configuration" +.IX Subsection "EVP Configuration" +The name \fBalg_section\fR in the initialization section names the section +containing algorithmic properties when using the \fBEVP\fR API. +.PP +Within the algorithm properties section, the following names have meaning: +.IP \fBdefault_properties\fR 4 +.IX Item "default_properties" +The value may be anything that is acceptable as a property query +string for \fBEVP_set_default_properties()\fR. +.IP "\fBfips_mode\fR (deprecated)" 4 +.IX Item "fips_mode (deprecated)" +The value is a boolean that can be \fByes\fR or \fBno\fR. If the value is +\&\fByes\fR, this is exactly equivalent to: +.Sp +.Vb 1 +\& default_properties = fips=yes +.Ve +.Sp +If the value is \fBno\fR, nothing happens. Using this name is deprecated, and +if used, it must be the only name in the section. +.SS "SSL Configuration" +.IX Subsection "SSL Configuration" +The name \fBssl_conf\fR in the initialization section names the section +containing the list of SSL/TLS configurations. +As with the providers, each name in this section identifies a +section with the configuration for that name. For example: +.PP +.Vb 4 +\& [ssl_configuration] +\& server = server_tls_config +\& client = client_tls_config +\& system_default = tls_system_default +\& +\& [server_tls_config] +\& ... configuration for SSL/TLS servers ... +\& +\& [client_tls_config] +\& ... configuration for SSL/TLS clients ... +.Ve +.PP +The configuration name \fBsystem_default\fR has a special meaning. If it +exists, it is applied whenever an \fBSSL_CTX\fR object is created. For example, +to impose system-wide minimum TLS and DTLS protocol versions: +.PP +.Vb 3 +\& [tls_system_default] +\& MinProtocol = TLSv1.2 +\& MinProtocol = DTLSv1.2 +.Ve +.PP +The minimum TLS protocol is applied to \fBSSL_CTX\fR objects that are TLS-based, +and the minimum DTLS protocol to those are DTLS-based. +The same applies also to maximum versions set with \fBMaxProtocol\fR. +.PP +Each configuration section consists of name/value pairs that are parsed +by \fBSSL_CONF_cmd\|(3)\fR, which will be called by \fBSSL_CTX_config()\fR or +\&\fBSSL_config()\fR, appropriately. Note that any characters before an initial +dot in the configuration section are ignored, so that the same command can +be used multiple times. This probably is most useful for loading different +key types, as shown here: +.PP +.Vb 3 +\& [server_tls_config] +\& RSA.Certificate = server\-rsa.pem +\& ECDSA.Certificate = server\-ecdsa.pem +.Ve +.SS "Engine Configuration" +.IX Subsection "Engine Configuration" +The name \fBengines\fR in the initialization section names the section +containing the list of ENGINE configurations. +As with the providers, each name in this section identifies an engine +with the configuration for that engine. +The engine-specific section is used to specify how to load the engine, +activate it, and set other parameters. +.PP +Within an engine section, the following names have meaning: +.IP \fBengine_id\fR 4 +.IX Item "engine_id" +This is used to specify an alternate name, overriding the default name +specified in the list of engines. If present, it must be first. +For example: +.Sp +.Vb 2 +\& [engines] +\& foo = foo_engine +\& +\& [foo_engine] +\& engine_id = myfoo +.Ve +.IP \fBdynamic_path\fR 4 +.IX Item "dynamic_path" +This loads and adds an ENGINE from the given path. It is equivalent to +sending the ctrls \fBSO_PATH\fR with the path argument followed by \fBLIST_ADD\fR +with value \fB2\fR and \fBLOAD\fR to the dynamic ENGINE. If this is not the +required behaviour then alternative ctrls can be sent directly to the +dynamic ENGINE using ctrl commands. +.IP \fBinit\fR 4 +.IX Item "init" +This specifies whether to initialize the ENGINE. If the value is \fB0\fR the +ENGINE will not be initialized, if the value is \fB1\fR an attempt is made +to initialize +the ENGINE immediately. If the \fBinit\fR command is not present then an +attempt will be made to initialize the ENGINE after all commands in its +section have been processed. +.IP \fBdefault_algorithms\fR 4 +.IX Item "default_algorithms" +This sets the default algorithms an ENGINE will supply using the function +\&\fBENGINE_set_default_string()\fR. +.PP +All other names are taken to be the name of a ctrl command that is +sent to the ENGINE, and the value is the argument passed with the command. +The special value \fBEMPTY\fR means no value is sent with the command. +For example: +.PP +.Vb 2 +\& [engines] +\& foo = foo_engine +\& +\& [foo_engine] +\& dynamic_path = /some/path/fooengine.so +\& some_ctrl = some_value +\& default_algorithms = ALL +\& other_ctrl = EMPTY +.Ve +.SS "Random Configuration" +.IX Subsection "Random Configuration" +The name \fBrandom\fR in the initialization section names the section +containing the random number generator settings. +.PP +Within the random section, the following names have meaning: +.IP \fBrandom\fR 4 +.IX Item "random" +This is used to specify the random bit generator. +For example: +.Sp +.Vb 2 +\& [random] +\& random = CTR\-DRBG +.Ve +.Sp +The available random bit generators are: +.RS 4 +.IP \fBCTR-DRBG\fR 4 +.IX Item "CTR-DRBG" +.PD 0 +.IP \fBHASH-DRBG\fR 4 +.IX Item "HASH-DRBG" +.IP \fBHMAC-DRBG\fR 4 +.IX Item "HMAC-DRBG" +.RE +.RS 4 +.RE +.IP \fBcipher\fR 4 +.IX Item "cipher" +.PD +This specifies what cipher a \fBCTR-DRBG\fR random bit generator will use. +Other random bit generators ignore this name. +The default value is \fBAES\-256\-CTR\fR. +.IP \fBdigest\fR 4 +.IX Item "digest" +This specifies what digest the \fBHASH-DRBG\fR or \fBHMAC-DRBG\fR random bit +generators will use. Other random bit generators ignore this name. +.IP \fBproperties\fR 4 +.IX Item "properties" +This sets the property query used when fetching the random bit generator and +any underlying algorithms. +.IP \fBseed\fR 4 +.IX Item "seed" +This sets the randomness source that should be used. By default \fBSEED-SRC\fR +will be used outside of the FIPS provider. The FIPS provider uses call backs +to access the same randomness sources from outside the validated boundary. +.IP \fBseed_properties\fR 4 +.IX Item "seed_properties" +This sets the property query used when fetching the randomness source. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example shows how to use quoting and escaping. +.PP +.Vb 3 +\& # This is the default section. +\& HOME = /temp +\& configdir = $ENV::HOME/config +\& +\& [ section_one ] +\& # Quotes permit leading and trailing whitespace +\& any = " any variable name " +\& other = A string that can \e +\& cover several lines \e +\& by including \e\e characters +\& message = Hello World\en +\& +\& [ section_two ] +\& greeting = $section_one::message +.Ve +.PP +This example shows how to expand environment variables safely. +In this example, the variable \fBtempfile\fR is intended to refer +to a temporary file, and the environment variable \fBTEMP\fR or +\&\fBTMP\fR, if present, specify the directory where the file +should be put. +Since the default section is checked if a variable does not +exist, it is possible to set \fBTMP\fR to default to \fI/tmp\fR, and +\&\fBTEMP\fR to default to \fBTMP\fR. +.PP +.Vb 3 +\& # These two lines must be in the default section. +\& TMP = /tmp +\& TEMP = $ENV::TMP +\& +\& # This can be used anywhere +\& tmpfile = ${ENV::TEMP}/tmp.filename +.Ve +.PP +This example shows how to enforce FIPS mode for the application +\&\fIsample\fR. +.PP +.Vb 1 +\& sample = fips_config +\& +\& [fips_config] +\& alg_section = evp_properties +\& +\& [evp_properties] +\& default_properties = "fips=yes" +.Ve +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +.IP \fBOPENSSL_CONF\fR 4 +.IX Item "OPENSSL_CONF" +The path to the config file, or the empty string for none. +Ignored in set-user-ID and set-group-ID programs. +.IP \fBOPENSSL_ENGINES\fR 4 +.IX Item "OPENSSL_ENGINES" +The path to the engines directory. +Ignored in set-user-ID and set-group-ID programs. +.IP \fBOPENSSL_MODULES\fR 4 +.IX Item "OPENSSL_MODULES" +The path to the directory with OpenSSL modules, such as providers. +Ignored in set-user-ID and set-group-ID programs. +.IP \fBOPENSSL_CONF_INCLUDE\fR 4 +.IX Item "OPENSSL_CONF_INCLUDE" +The optional path to prepend to all \fB.include\fR paths. +.SH BUGS +.IX Header "BUGS" +There is no way to include characters using the octal \fB\ennn\fR form. Strings +are all null terminated so nulls cannot form part of the value. +.PP +The escaping isn't quite right: if you want to use sequences like \fB\en\fR +you can't use any quote escaping on the same line. +.PP +The limit that only one directory can be opened and read at a time +can be considered a bug and should be fixed. +.SH HISTORY +.IX Header "HISTORY" +An undocumented API, \fBNCONF_WIN32()\fR, used a slightly different set +of parsing rules there were intended to be tailored to +the Microsoft Windows platform. +Specifically, the backslash character was not an escape character and +could be used in pathnames, only the double-quote character was recognized, +and comments began with a semi-colon. +This function was deprecated in OpenSSL 3.0; applications with +configuration files using that syntax will have to be modified. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-x509\fR\|(1), \fBopenssl\-req\fR\|(1), \fBopenssl\-ca\fR\|(1), +\&\fBopenssl\-fipsinstall\fR\|(1), +\&\fBASN1_generate_nconf\fR\|(3), +\&\fBEVP_set_default_properties\fR\|(3), +\&\fBCONF_modules_load\fR\|(3), +\&\fBCONF_modules_load_file\fR\|(3), +\&\fBfips_config\fR\|(5), and +\&\fBx509v3_config\fR\|(5). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/upstream/debian-unstable/man5/core.5 b/upstream/debian-unstable/man5/core.5 new file mode 100644 index 00000000..c19846ee --- /dev/null +++ b/upstream/debian-unstable/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-05-03 "Linux man-pages 6.05.01" +.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). +.PP +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. +.PP +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. +.PP +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. +.PP +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: +.PP +.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 +.PP +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. +.PP +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)). +.PP +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 . +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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: +.PP +.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 +.PP +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. +.PP +The value of this file is displayed in hexadecimal. +(The default value is thus displayed as 33.) +.PP +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. +.PP +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). +.PP +It can be useful to set +.I coredump_filter +in the parent shell before running a program, for example: +.PP +.in +4n +.EX +.RB "$" " echo 0x7 > /proc/self/coredump_filter" +.RB "$" " ./some_program" +.EE +.in +.PP +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: +.PP +.in +4n +.EX +$ \fBcat /proc/sys/kernel/core_pattern\fP +|/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e +.EE +.in +.PP +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): +.PP +.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 +.PP +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: +.PP +.in +4n +.EX +$ \fBcoredumpctl dump 2955 \-o core\fP +.EE +.in +.PP +For more extensive details, see the +.BR coredumpctl (1) +manual page. +.PP +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: +.PP +.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 +.PP +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): +.PP +.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. +.PP +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 ): +.PP +.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/debian-unstable/man5/coredump.conf.5 b/upstream/debian-unstable/man5/coredump.conf.5 new file mode 100644 index 00000000..10f56339 --- /dev/null +++ b/upstream/debian-unstable/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/debian-unstable/man5/crontab.5 b/upstream/debian-unstable/man5/crontab.5 new file mode 100644 index 00000000..b3f3d158 --- /dev/null +++ b/upstream/debian-unstable/man5/crontab.5 @@ -0,0 +1,407 @@ +.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie +.\" * All rights reserved +.\" * +.\" * Distribute freely, except: don't remove my name from the source or +.\" * documentation (don't take credit for my work), mark your changes (don't +.\" * get me blamed for your possible bugs), don't alter or remove this +.\" * notice. May be sold if buildable source is provided to buyer. No +.\" * warrantee of any kind, express or implied, is included with this +.\" * software; use at your own risk, responsibility for damages (if any) to +.\" * anyone resulting from the use of this software rests entirely with the +.\" * user. +.\" * +.\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and +.\" * I'll try to keep a version up to date. I can be reached as follows: +.\" * Paul Vixie uunet!decwrl!vixie!paul +.\" */ +.\" +.\" $Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp $ +.\" +.TH CRONTAB 5 "19 April 2010" +.UC 4 +.SH NAME +crontab \- tables for driving cron +.SH DESCRIPTION +A +.I crontab +file contains instructions to the +.IR cron (8) +daemon of the general form: ``run this command at this time on this date''. +Each user has their own crontab, and commands in any given crontab will be +executed as the user who owns the crontab. Uucp and News will usually have +their own crontabs, eliminating the need for explicitly running +.IR su (1) +as part of a cron command. +.PP +Note that comments on the same line as cron commands are not interpreted as +comments in the cron sense, but are considered part of the command and passed +to the shell. This is similarly true for comments on the same line as +environment variable settings. +.PP +An active line in a crontab will be either an environment setting or a cron +command. An environment setting is of the form, +.PP + name = value +.PP +where the spaces around the equal-sign (=) are optional, and any subsequent +non-leading spaces in +.I value +will be 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 blanks. To define an empty variable, quotes +.B must +be used. +.PP +The +.I value +string is +.B not +parsed for environmental substitutions or replacement of variables or +tilde(~) expansion, thus lines like +.PP +.in +4n +.nf +PATH=$HOME/bin:$PATH +PATH=~/bin:/usr/bin +.fi +.in +.PP +will not work as you might expect. And neither will this work +.PP +.in +4n +.nf +A=1 +B=2 +C=$A $B +.fi +.in +.PP +There will not be any substitution for the defined variables in the +last value. However, with most shells you can also try e.g.,: +.PP + P=PATH=/a/b/c:$PATH + 33 22 1 2 3 eval $P && some commands +.PP +Several environment variables are set up automatically by the +.IR cron (8) +daemon. +SHELL is set to /usr/bin/sh, and LOGNAME and HOME are set from the /etc/passwd +line of the crontab's owner. +HOME and SHELL may be overridden by settings in the crontab; LOGNAME may not. +.PP +(Another note: the LOGNAME variable is sometimes called USER on BSD systems... +on these systems, USER will be set also.) +.PP +In addition to LOGNAME, HOME, and SHELL, +.IR cron (8) +will look at MAILTO if it has any reason to send mail as a result of running +commands in ``this'' crontab. If MAILTO is defined (and non-empty), mail is +sent to the user so named. If MAILTO is defined but empty (MAILTO=""), no +mail will be sent. Otherwise mail is sent to the owner of the crontab. This +option is useful if you decide on /usr/bin/mail instead of /usr/lib/sendmail as +your mailer when you install cron -- /usr/bin/mail doesn't do aliasing, and UUCP +usually doesn't read its mail. +.PP +The format of a cron command is very much the V7 standard, with a number of +upward-compatible extensions. Each line has five time and date fields, +followed by a command, followed by a newline character ('\en'). +The system crontab (/etc/crontab) uses the same format, except that +the username for the command is specified after the time and +date fields and before the command. The fields may be separated +by spaces or tabs. The maximum permitted length for the command field is +998 characters. +.PP +Commands are executed by +.IR cron (8) +when the minute, hour, and month of year fields match the current time, +.I and +when at least one of the two day fields (day of month, or day of week) +match the current time (see ``Note'' below). +.IR cron (8) +examines cron entries once every minute. +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 0-31 +.br +month 0-12 (or names, see below) +.br +day of week 0-7 (0 or 7 is Sun, or use names) +.br +.PP +A field may be 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. +.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 every other hour (the alternative +in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are +also permitted after an asterisk, so if you want to say ``every two +hours'', just use ``*/2''. +.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 doesn't matter). Ranges or +lists of names are not allowed. +.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 % +character, will be executed by /usr/bin/sh or by the shell +specified in the SHELL variable of the cronfile. +Percent-signs (%) in the command, unless escaped with 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 by two +fields \(em day of month, and day of week. If both fields are +restricted (i.e., aren't *), 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. One can, however, achieve the desired result +by adding a test to the command (see the last example in EXAMPLE CRON FILE +below). +.PP +Instead of the first five fields, one of eight special strings may appear: +.IP +.ta 1.5i +string meaning +.br +------ ------- +.br +@reboot Run once, at startup. +.br +@yearly Run once a year, "0 0 1 1 *". +.br +@annually (same as @yearly) +.br +@monthly Run once a month, "0 0 1 * *". +.br +@weekly Run once a week, "0 0 * * 0". +.br +@daily Run once a day, "0 0 * * *". +.br +@midnight (same as @daily) +.br +@hourly Run once an hour, "0 * * * *". +.br +.PP +Please note that startup, as far as @reboot is concerned, is the time when +the +.IR cron (8) +daemon startup. In particular, it may be before some system daemons, +or other facilities, were startup. This is due to the boot order +sequence of the machine. + +.SH EXAMPLE CRON FILE +.nf + +# use /usr/bin/sh to run commands, no matter what /etc/passwd says +SHELL=/usr/bin/sh +# mail any output to `paul', no matter whose crontab this is +MAILTO=paul +# +# 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" +0 */4 1 * mon echo "run every 4th hour on the 1st and on every Monday" +0 0 */2 * sun echo "run at midn on every Sunday that's an uneven date" +# Run on every second Saturday of the month +0 4 8\-14 * * test $(date +\e%u) \-eq 6 && echo "2nd Saturday" +# Same thing, efficient too: +0 4 * * * Sat d=$(date +\%e) && test $d -ge 8 -a $d -le 14 && echo "2nd Saturday" +#Execute early the next morning following the first +#Thursday of each month +57 2 * * 5 case $(date +\%d) in 0[2-8]) echo "After 1st Thursday"; esac +.fi + +.PP +All the above examples run non-interactive programs. If you wish to run a +program that interacts with the user's desktop you have to make sure the proper +environment variable +.I DISPLAY +is set. + +.\" Note: Based on some web searches, below example might not fully +.\" work in all systems, as notify-send might require also +.\" to have knowledge of the dbus session in use (through the environment) +.\" However, adding that code here is an overkill +.nf +# Execute a program and run a notification every day at 10:00 am +0 10 * * * $HOME/bin/program | DISPLAY=:0 notify-send "Program run" "$(cat)" +.fi + +.SH EXAMPLE SYSTEM CRON FILE + +The following lists the content of a regular system-wide crontab file. Unlike a +user's crontab, this file has the username field, as used by /etc/crontab. + +.nf +# /etc/crontab: system-wide crontab +# Unlike any other crontab you don't have to run the `crontab' +# command to install the new version when you edit this file +# and files in /etc/cron.d. These files also have username fields, +# that none of the other crontabs do. + +SHELL=/bin/sh +PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin + +# Example of job definition: +# .---------------- minute (0 - 59) +# | .------------- hour (0 - 23) +# | | .---------- day of month (1 - 31) +# | | | .------- month (1 - 12) OR jan,feb,mar,apr ... +# | | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat +# | | | | | +# m h dom mon dow user command +17 * * * * root cd / && run-parts \-\-report /etc/cron.hourly +25 6 * * * root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.daily ) +47 6 * * 7 root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.weekly ) +52 6 1 * * root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.monthly ) +# +.fi + +Note that all the system-wide tasks will run, by default, from 6 am to 7 am. In +the case of systems that are not powered on during that period of time, only +the hourly tasks will be executed unless the defaults above are changed. + +.SH YET ANOTHER EXAMPLE + +In that example one can see that numbers can be prepended some 0, in order +to line up columns. + +.nf +17 * * * * root cd / && run-parts --report /etc/cron.hourly +25 16 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily ) +47 06 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly ) +52 06 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly ) +.fi + +.SH SEE ALSO +cron(8), crontab(1) +.SH EXTENSIONS +When specifying day of week, both day 0 and day 7 will be considered Sunday. +BSD and AT&T seem to disagree about this. +.PP +Lists and ranges are allowed to co-exist in the same field. "1-3,7-9" would +be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY. +.PP +Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". +.PP +Names of monts or days of the week can be specified by name. +.PP +Environment variables can be set in the crontab. In BSD or AT&T, the +environment handed to child processes is basically the one from /etc/rc. +.PP +Command output is mailed to the crontab owner (BSD can't do this), can be +mailed to a person other than the crontab owner (SysV can't do this), or the +feature can be turned off and no mail will be sent at all (SysV can't do this +either). +.PP +All of the `@' commands that can appear in place of the first five fields +are extensions. +.SH LIMITATIONS +The +.I cron +daemon runs with a defined timezone. It currently does not support +per-user timezones. All the tasks: system's and user's will be run based on the +configured timezone. Even if a user specifies the +.I TZ +environment variable in his +.I crontab +this will affect only the commands executed in the crontab, not the execution +of the crontab tasks themselves. If one wants to specify a particular +timezone for crontab tasks, one may check the date in the child script, +for example: + +.nf + # m h dom mon dow command + + TZ=UTC + 0 * * * * [ "$(date +\e%R)" = 00:00 ] && run_some_script +.fi + +POSIX specifies that the day of month and the day of week fields both need to +match the current time if either of them +.I is +a *. However, this implementation only checks if the +.I first character +is a *. This is why "0 0 */2 * sun" runs every Sunday that's an +uneven date while the POSIX standard would have it run every Sunday and on +every uneven date. + +The +.I crontab +syntax does not make it possible to define all possible periods one can +imagine. For example, it is not straightforward to define the last +weekday of a month. +To have a task run in a time period that cannot be defined using +.I crontab +syntax, the best approach would be to have the program itself check the +date and time information and continue execution only if the period +matches the desired one. + +If the program itself cannot do the checks then a wrapper script would be +required. Useful tools that could be used for date analysis are +.I ncal +or +.I calendar +For example, to run a program the last Saturday of every month you could use +the following wrapper code: + +.nf +0 4 * * Sat [ "$(date +\e%e)" = "$(LANG=C ncal | sed \-n 's/^Sa .* \e([0\-9]\e+\e) *$/\e1/p')" ] && echo "Last Saturday" && program_to_run +.fi + +.SH USING EVAL TO WRAP MISC ENVIRONMENT SETTINGS +The following tip is kindly provided by 積丹尼 Dan Jacobson: +.PP + CONTENT_TYPE="text/plain; charset=UTF-8" + d=eval LANG=zh_TW.UTF-8 w3m -dump + 26 22 16 1-12 * $d https://www.ptt.cc/bbs/transgender/index.html +.PP + it won't work without the eval. Saying + d=LANG=zh_TW.UTF-8 w3m -dump + will get + /bin/sh: LANG=zh_TW.UTF-8: command not found + +.SH DIAGNOSTICS +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 +Paul Vixie is the author of +.I cron +and original creator of this manual page. This page has also been modified for +Debian by Steve Greenland, Javier Fernandez-Sanguino, Christian Kastner, +Christian Pekeler, Georges Khaznadar. diff --git a/upstream/debian-unstable/man5/crypt.5 b/upstream/debian-unstable/man5/crypt.5 new file mode 100644 index 00000000..e3186bc7 --- /dev/null +++ b/upstream/debian-unstable/man5/crypt.5 @@ -0,0 +1,312 @@ +.\" Written and revised by Solar Designer in 2000-2011. +.\" Revised by Zack Weinberg in 2017. +.\" Converted to mdoc format by Zack Weinberg in 2018. +.\" +.\" No copyright is claimed, and this man page is hereby placed in the public +.\" domain. In case this attempt to disclaim copyright and place the man page +.\" in the public domain is deemed null and void, then the man page is +.\" Copyright 2000-2011 Solar Designer, 2017 Zack Weinberg, and it is +.\" hereby released to the general public under the following terms: +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted. +.\" +.\" There's ABSOLUTELY NO WARRANTY, express or implied. +.\" +.Dd October 11, 2017 +.Dt CRYPT 5 +.Os "Openwall Project" +.Sh NAME +.Nm crypt +.Nd storage format for hashed passphrases and available hashing methods +.Sh DESCRIPTION +The hashing methods implemented by +.Xr crypt 3 +are designed only to process user passphrases for storage and authentication; +they are not suitable for use as general-purpose cryptographic hashes. +.Pp +Passphrase hashing is not a replacement for strong passphrases. +It is always possible +for an attacker with access to the hashed passphrases +to guess and check possible cleartext passphrases. +However, with a strong hashing method, +guessing will be too slow for the attacker +to discover a strong passphrase. +.Pp +All of the hashing methods use a +.Dq salt +to perturb the hash function, +so that the same passphrase may produce many possible hashes. +Newer methods accept longer salt strings. +The salt should be chosen at random for each user. +Salt defeats a number of attacks: +.Bl -enum +.It +It is not possible to hash a passphrase once +and then test it against each account's stored hash; +the hash calculation must be repeated for each account. +.It +It is not possible to tell whether two accounts use the same passphrase +without successfully guessing one of the phrases. +.It +Tables of precalculated hashes of commonly used passphrases +must have an entry for each possible salt, +which makes them impractically large. +.El +.Pp +All of the hashing methods are also deliberately engineered to be slow; +they use many iterations of an underlying cryptographic primitive +to increase the cost of each guess. +The newer hashing methods allow the number of iterations to be adjusted, +using the +.Dq CPU time cost +parameter to +.Xr crypt_gensalt 3 . +This makes it possible to keep the hash slow as hardware improves. +.Sh FORMAT OF HASHED PASSPHRASES +All of the hashing methods supported by +.Xr crypt 3 +produce a hashed passphrase which consists of four components: +.Ar prefix , +.Ar options , +.Ar salt , +and +.Ar hash . +The prefix controls which hashing method is to be used, and is the +appropriate string to pass to +.Xr crypt_gensalt 3 +to select that method. +The contents of +.Ar options , +.Ar salt , +and +.Ar hash +are up to the method. +Depending on the method, the +.Ar prefix +and +.Ar options +components may be empty. +.Pp +The +.Fa setting +argument to +.Xr crypt 3 +must begin with the first three components of a valid hashed passphrase, +but anything after that is ignored. +This makes authentication simple: +hash the input passphrase using the stored passphrase as the setting, +and then compare the result to the stored passphrase. +.Pp +Hashed passphrases are always entirely printable ASCII, +and do not contain any whitespace +or the characters +.Sq Li \&: , +.Sq Li \&; , +.Sq Li \&* , +.Sq Li \&! , +or +.Sq Li \&\e . +(These characters are used as delimiters and special markers in the +.Xr passwd 5 +and +.Xr shadow 5 +files.) +.Pp +The syntax of each component of a hashed passphrase +is up to the hashing method. +.Sq Li \&$ +characters usually delimit components, +and the salt and hash are usually encoded as numerals in base 64. +The details of this base-64 encoding vary among hashing methods. +The common +.Dq base64 +encoding specified by RFC 4648 is usually +.Em not +used. +.Sh AVAILABLE HASHING METHODS +This is a list of +.Em all +the hashing methods supported by +.Xr crypt 3 , +in decreasing order of strength. +Many of the older methods +are now considered too weak to use for new passphrases. +The hashed passphrase format is expressed +with extended regular expressions (see +.Xr regex 7 ) +and does not show the division into prefix, options, salt, and hash. +.de hash +.Bl -tag -width 2n +.It Sy Prefix +.\" mandoc bug: .Qq comes out with curly quotes. +.\" mandoc bug: .Li is hyperlinked to itself for no apparent reason. +.Bf Li +"\\$1" +.Ef +.if "\\$1"" (empty string) +.It Sy Hashed passphrase format +.\" mandoc bug: .Li is hyperlinked to itself for no apparent reason. +.Bf -literal +\&\\$2 +.Ef +.It Sy Maximum passphrase length +.ie "\\$3"unlimited" unlimited +.el \\$3 characters +.if "\\$4"7" (ignores 8th bit) +.It Sy Hash size +\\$6 bits +.if !"\\$5"\\$6" \{\ +.It Sy Effective key size +\&\\$5 bits +.\} +.It Sy Salt size +\\$7 bits +.It Sy CPU time cost parameter +\\$8 +.El +.. +.Ss yescrypt +yescrypt is a scalable passphrase hashing scheme designed by Solar Designer, +which is based on Colin Percival's scrypt. +Recommended for new hashes. +.hash "$y$" "\e$y\e$[./A-Za-z0-9]+\e$[./A-Za-z0-9]{,86}\e$[./A-Za-z0-9]{43}" unlimited 8 256 256 "up to 512 (128+ recommended)" "1 to 11 (logarithmic)" +.Ss gost-yescrypt +gost-yescrypt uses the output from the yescrypt hashing method in place of a +hmac message. Thus, the yescrypt crypto properties are superseded by the +GOST R 34.11-2012 (Streebog) hash function with a 256 bit digest. +This hashing method is useful in applications that need modern passphrase +hashing methods, but require to rely on the cryptographic properties of GOST +algorithms. +The GOST R 34.11-2012 (Streebog) hash function has been published by the IETF +as RFC 6986. +Recommended for new hashes. +.hash "$gy$" "\e$gy\e$[./A-Za-z0-9]+\e$[./A-Za-z0-9]{,86}\e$[./A-Za-z0-9]{43}" unlimited 8 256 256 "up to 512 (128+ recommended)" "1 to 11 (logarithmic)" +.Ss scrypt +scrypt is a password-based key derivation function created by Colin Percival, +originally for the Tarsnap online backup service. +The algorithm was specifically designed to make it costly to perform +large-scale custom hardware attacks by requiring large amounts of memory. +In 2016, the scrypt algorithm was published by IETF as RFC 7914. +.hash "$7$" "\e$7\e$[./A-Za-z0-9]{11,97}\e$[./A-Za-z0-9]{43}" unlimited 8 256 256 "up to 512 (128+ recommended)" "6 to 11 (logarithmic)" +.Ss bcrypt +A hash based on the Blowfish block cipher, +modified to have an extra-expensive key schedule. +Originally developed by Niels Provos and David Mazieres for OpenBSD +and also supported on recent versions of FreeBSD and NetBSD, +on Solaris 10 and newer, and on several GNU/*/Linux distributions. +.hash "$2b$" "\e$2[abxy]\e$[0-9]{2}\e$[./A-Za-z0-9]{53}" 72 8 184 184 128 "4 to 31 (logarithmic)" +.Pp +The alternative prefix "$2y$" is equivalent to "$2b$". +It exists for historical reasons only. +The alternative prefixes "$2a$" and "$2x$" +provide bug-compatibility with crypt_blowfish 1.0.4 and earlier, +which incorrectly processed characters with the 8th bit set. +.Ss sha512crypt +A hash based on SHA-2 with 512-bit output, +originally developed by Ulrich Drepper for GNU libc. +Supported on Linux but not common elsewhere. +Acceptable for new hashes. +The default CPU time cost parameter is 5000, +which is too low for modern hardware. +.hash "$6$" "\e$6\e$(rounds=[1-9][0-9]+\e$)?[^$:\(rsn]{1,16}\e$[./0-9A-Za-z]{86}" unlimited 8 512 512 "6 to 96" "1000 to 999,999,999" +.Ss sha256crypt +A hash based on SHA-2 with 256-bit output, +originally developed by Ulrich Drepper for GNU libc. +Supported on Linux but not common elsewhere. +Acceptable for new hashes. +The default CPU time cost parameter is 5000, +which is too low for modern hardware. +.hash "$5$" "\e$5\e$(rounds=[1-9][0-9]+\e$)?[^$:\(rsn]{1,16}\e$[./0-9A-Za-z]{43}" unlimited 8 256 256 "6 to 96" "1000 to 999,999,999" +.Ss sha1crypt +A hash based on HMAC-SHA1. +Originally developed by Simon Gerraty for NetBSD. +Not as weak as the DES-based hashes below, +but SHA1 is so cheap on modern hardware +that it should not be used for new hashes. +.hash "$sha1" "\e$sha1\e$[1-9][0-9]+\e$[./0-9A-Za-z]{1,64}\e$[./0-9A-Za-z]{8,64}[./0-9A-Za-z]{32}" unlimited 8 160 160 "6 to 384" "4 to 4,294,967,295" +.Ss SunMD5 +A hash based on the MD5 algorithm, +with additional cleverness to make precomputation difficult, +originally developed by Alec David Muffet for Solaris. +Not adopted elsewhere, to our knowledge. +Not as weak as the DES-based hashes below, +but MD5 is so cheap on modern hardware +that it should not be used for new hashes. +.hash "$md5" "\e$md5(,rounds=[1-9][0-9]+)?\e$[./0-9A-Za-z]{8}\e${1,2}[./0-9A-Za-z]{22}" unlimited 8 128 128 48 "4096 to 4,294,963,199" +.Ss md5crypt +A hash based on the MD5 algorithm, originally developed by +Poul-Henning Kamp for FreeBSD. +Supported on most free Unixes and newer versions of Solaris. +Not as weak as the DES-based hashes below, +but MD5 is so cheap on modern hardware +that it should not be used for new hashes. +CPU time cost is not adjustable. +.hash "$1$" "\e$1\e$[^$:\(rsn]{1,8}\e$[./0-9A-Za-z]{22}" unlimited 8 128 128 "6 to 48" 1000 +.Ss bsdicrypt (BSDI extended DES) +A weak extension of traditional DES, +which eliminates the length limit, +increases the salt size, +and makes the time cost tunable. +It originates with BSDI +and is also available on at least NetBSD, OpenBSD, and FreeBSD +due to the use of David Burren's FreeSec library. +It is better than bigcrypt and traditional DES, +but still should not be used for new hashes. +.hash _ "_[./0-9A-Za-z]{19}" unlimited 7 56 64 24 "1 to 16,777,215 (must be odd)" +.Ss bigcrypt +A weak extension of traditional DES, +available on some System V-derived Unixes. +All it does is raise the length limit from 8 to 128 characters, +and it does this in a crude way that allows attackers to +guess chunks of a long passphrase in parallel. +It should not be used for new hashes. +.hash "" "[./0-9A-Za-z]{13,178}" 128 7 "up to 896" "up to 1024" 12 25 +.Ss descrypt (Traditional DES) +The original hashing method from Unix V7, based on the DES block cipher. +Because DES is cheap on modern hardware, +because there are only 4096 possible salts and 2**56 possible hashes, +and because it truncates passphrases to 8 characters, +it is feasible to discover +.Em any +passphrase hashed with this method. +It should only be used if you absolutely have to generate hashes +that will work on an old operating system that supports nothing else. +.hash "" "[./0-9A-Za-z]{13}" 8 7 56 64 12 25 +.Ss NT +The hashing method used for network authentication +in some versions of the SMB/CIFS protocol. +Available, for cross-compatibility's sake, on FreeBSD. +Based on MD4. +Has no salt or tunable cost parameter. +Like traditional DES, it is so weak that +.Em any +passphrase hashed with this method is guessable. +It should only be used if you absolutely have to generate hashes +that will work on an old operating system that supports nothing else. +.hash "$3$" "\e$3\e$\e$[0-9a-f]{32}" unlimited 8 256 256 0 1 +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypt_gensalt 3 , +.Xr getpwent 3 , +.Xr passwd 5 , +.Xr shadow 5 , +.Xr pam 8 +.Rs +.%A Niels Provos +.%A David Mazieres +.%T A Future-Adaptable Password Scheme +.%B Proceedings of the 1999 USENIX Annual Technical Conference +.%D June 1999 +.%U https://www.usenix.org/events/usenix99/provos.html +.Re +.Rs +.%A Robert Morris +.%A Ken Thompson +.%T Password Security: A Case History +.%J Communications of the ACM +.%V 22 +.%N 11 +.%D 1979 +.%U http://wolfram.schneider.org/bsd/7thEdManVol2/password/password.pdf +.Re diff --git a/upstream/debian-unstable/man5/crypttab.5 b/upstream/debian-unstable/man5/crypttab.5 new file mode 100644 index 00000000..729a3b43 --- /dev/null +++ b/upstream/debian-unstable/man5/crypttab.5 @@ -0,0 +1,499 @@ +'\" t +.\" Title: crypttab +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 2024-02-26 +.\" Manual: cryptsetup manual +.\" Source: cryptsetup 2:2.7.0-1 +.\" Language: English +.\" +.TH "CRYPTTAB" "5" "2024\-02\-26" "cryptsetup 2:2\&.7\&.0\-1" "cryptsetup 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" +crypttab \- static information about encrypted filesystems +.SH "DESCRIPTION" +.sp +The file /etc/crypttab contains descriptive information about encrypted devices\&. crypttab is only read by programs (e\&.g\&. \fBcryptdisks_start\fR and \fBcryptdisks_stop\fR), and not written; it is the duty of the system administrator to properly create and maintain this file\&. crypttab entries are treated sequentially, so their order matters (dependencies need to listed first)\&. +.sp +Each encrypted device is described on a separate line\&. Fields on each line are separated by tabs or spaces\&. Lines starting with \*(Aq#\*(Aq are comments, and blank lines are ignored\&. Octal sequences \e0\fInum\fR within a field are decoded, which can be used for values containing spaces or special characters\&. A backslash which doesn\*(Aqt start an octal sequence yields undefined behavior\&. +.sp +The first field, \fItarget\fR, describes the mapped device name\&. It must be a plain filename without any directory components\&. A mapped device which encrypts/decrypts data to/from the \fIsource device\fR will be created at /dev/mapper/target by \fBcryptsetup\fR\&. +.sp +The second field, \fIsource device\fR, describes either the block special device or file that contains the encrypted data\&. Instead of giving the \fIsource device\fR explicitly, the UUID (resp\&. LABEL, PARTUUID and PARTLABEL) is supported as well, using \(lqUUID=\(rq (resp\&. \(lqLABEL=