summaryrefslogtreecommitdiff
path: root/share/man
AgeCommit message (Collapse)Author
2023-07-09versioningsyscalls(9): markup fixesuwe
While here, fix the pasto for the new ino_t and time_t size.
2023-07-08Document how system call versioning is done. From this summer's compat-linuxchristos
GSoC, by Theodore Preduta.
2023-07-08curcpu_stable(9): New function for asserting curcpu() is stable.riastradh
2023-07-07heartbeat(9): markup fixesuwe
Use .Cd for options. Don't use the usual <space><tab>, which is superfluous in the man page. Paragraph break after the config section of synopsis, before the C API section.
2023-07-07heartbeat(9): Fix grammaro in man page.riastradh
2023-07-07Replace main(9) reference with code locationwiz
2023-07-07Sort SEE ALSOwiz
2023-07-07heartbeat(9): New mechanism to check progress of kernel.riastradh
This uses hard interrupts to check progress of low-priority soft interrupts, and one CPU to check progress of another CPU. If no progress has been made after a configurable number of seconds (kern.heartbeat.max_period, default 15), then the system panics -- preferably on the CPU that is stuck so we get a stack trace in dmesg of where it was stuck, but if the stuckness was detected by another CPU and the stuck CPU doesn't acknowledge the request to panic within one second, the detecting CPU panics instead. This doesn't supplant hardware watchdog timers. It is possible for hard interrupts to be stuck on all CPUs for some reason too; in that case heartbeat(9) has no opportunity to complete. Downside: heartbeat(9) relies on hardclock to run at a reasonably consistent rate, which might cause trouble for the glorious tickless future. However, it could be adapted to take a parameter for an approximate number of units that have elapsed since the last call on the current CPU, rather than treating that as a constant 1. XXX kernel revbump -- changes struct cpu_info layout
2023-07-05mk.conf(5): document rump variableslukem
Update mk.conf(5) with the rump variables from - lib/librumpuser/README.compileopts - sys/rump/README.compileopts Add cross-references back to mk.conf(5) in those files. Ensure that the Default: is listed last in a description, for consistency with the convention in this file.
2023-06-30rc.conf(5): Set entropy=wait by default.riastradh
We no longer block indefinitely -- if nothing else, the hardclock timer should yield enough samples to unblock /dev/random on all but the most severely deterministic machines -- so it should be generally safe for availability to set entropy=wait. This doesn't guarantee that HWRNG/seed has been provided before you run ssh-keygen or call getentropy(3) in a user application, but it does raise the security above netbsd<=9. PR security/55659 PR lib/56905 XXX pullup-10
2023-06-30entropy(9): Reintroduce netbsd<=9 time-delta estimator for unblocking.riastradh
The system will (in a subsequent change) by default block for this condition before almost all of userland is running (including /etc/rc.d/sshd key generation). That way, a never-blocking getentropy(3) API will never return any data without at least best-effort entropy like netbsd<=9 did to applications except in single-user mode (where you have to be careful about everything anyway) or in the few processes that run before a seed can even be loaded (where blocking indefinitely, e.g. when generating a stack protector cookie in libc, could pose a severe availability problem that can't be configured away, but where the security impact is low). However, (in another subsequent change) we will continue to use _only_ HWRNG driver estimates and seed estimates, and _not_ time-delta estimator, for _warning_ about security in motd, daily security report, etc. And if HWRNG/seed provides enough entropy before time-delta estimator does, that will unblock /dev/random too. The result is: - Machines with HWRNG or seed won't warn about entropy and will essentially never block -- even on first boot without a seed, it will take only as long as the fastest HWRNG to unblock. - Machines with neither HWRNG nor seed: . will warn about entropy, giving feedback about security; and . will avoid returning anything more predictable than netbsd<=9; but . won't block (much) longer than netbsd<=9 would (and won't block again after blocking once, except with kern.entropy.depletion=1 for testing). (The threshold for unblocking is now somewhat higher than before: 512 samples that pass the time-delta estimator, rather than 80 as it used to be.) And, of course, adding a seed (or HWRNG) will prevent both warnings and blocking. The mechanism is: 1. /dev/random will block until _either_ (a) enough bits of entropy (256) from reliable sources have been added to the pool, _or_ (b) enough samples have been added from any sources (512), passing the old time-delta entropy estimator, that the possible security benefit doesn't justify holding up availability any longer (`best effort'), except on systems with higher security requirements like securelevel=2 which can disable non-HWRNG, non-seed sources with rndctl_flags in rc.conf(5). 2. dmesg will report `entropy: ready' when 1(a) is satisfied, but if 1(b) is satisfied first, it will report `entropy: best effort', so the concise log messages will reflect the timing and whether in any period of time any of the system might be relying on best effort entropy. 3. The sysctl knob kern.entropy.needed (and the ioctl RNDGETPOOLSTAT variable rndpoolstat_t::added) still reflects the number of bits of entropy from reliable sources, so we can still use this to suggest regenerating ssh keys. This matters on platforms that can only be reached, after flashing an installation image, by sshing in over a (private) network, like small network appliances or remote virtual machines without (interactive) serial consoles. If we blocked indefinitely at boot when generating ssh keys, such platforms would be unusable. This way, platforms are usable, but operators can still be advised at login time to regenerate keys as soon as they can actually load entropy onto the system, e.g. with rndctl(8) on a seed file copied from a local machine over the (private) network. 4. On machines without HWRNG, using a seed file still suppresses warnings for users who need more confident security. But it is no longer necessary for availability. This is a compromise between availability and security: - The security mechanism of blocking indefinitely on machines without HWRNG hurts availability too much, as painful experience over the multiple years since I made the mistake of introducing it have shown. (Sorry!) - The other main alternative, not having a blocking path at all (as I pushed for, and as OpenBSD has done for a long time) could potentially reduce security vs netbsd<=9, and would run against the expectations set by many popular operating systems to the severe detriment of public perception of NetBSD security. Even though we can't _confidently_ assess enough entropy from, e.g., sampling interrupt timings, this is the traditional behaviour that most operating systems provide -- and the result here is a net nondecrease in security over netbsd<=9, because all paths from the entropy pool to userland now have at least as high a standard before returning data as they did in netbsd<=9. PR kern/55641 PR pkg/55847 PR kern/57185 https://mail-index.netbsd.org/current-users/2020/09/02/msg039470.html https://mail-index.netbsd.org/current-users/2020/11/21/msg039931.html https://mail-index.netbsd.org/current-users/2020/12/05/msg040019.html XXX pullup-10
2023-06-30Add npflog.4 to setsgutteridge
2023-06-29npflog.4: add and adjust some detailsgutteridge
Add details about the header structure (though the if_npflog.h file is not presently installed and has a _KERNEL guard). Also adjust some sentences (requested by riastradh@), and include the original OpenBSD RCS ID, since much of this content shares that origin.
2023-06-20npflog.4: add a man page for the npflog devicegutteridge
Addresses PR misc/57441 from Taylor R Campbell. (Not yet hooked into source sets, will be done separately.) (Borrows heavily from the equivalent pflog.4 man page already in tree, and so retains the original copyright attribution as well.)
2023-06-18sysctl(7): Note nodev,nosuid requirement for user-mounted fs.riastradh
While here, tidy up language and markup a smidge.
2023-06-15VOP_IOCTL() is a wrapper around spec_ioctl() aka Xdev_ioctl() andhannken
protected with spec_io_enter()/spec_io_exit() so there is no need to force specific vnode locking. Set locking requirement to '= = =' (unchanged, locked or unlocked). PR kern/57450 (unplugging hung USB disk triggers panic via _vstate_assert)
2023-06-14Fix previous. Patch mistakenly applied somehow...rin
2023-06-14Cite src/sys/rump/README.compileopts as a reference for MKRUMP.rin
2023-06-11mk.conf(5): more variables from BUILDING and build.shlukem
Add more variables from build.sh, BUILDING, and various Makefile's documentation: CDEXTRA CONFIGOPTS KERNARCHDIR KERNCONFDIR KERNOBJDIR KERNSRCDIR LOCALTIME Default sentences now consistently end with ".". Consistency tweaks in "otherwise". Editorial tweaks.
2023-06-11mk.conf(5): add remaining vars from BUILDINGlukem
Add more variables from BUILDING: INSTALLBOOT_BOARDS INSTALLWORLDDIR NOCLEANDIR NODISTRIBDIRS NOINCLUDES. Add build.sh related notes (from BUILDING). Clarify "target" as "target architecture" where appropriate (versus a make target where that's obvious from context.) Move all obsolete and deprecated variables to new "OBSOLETE VARIABLES" section at the end. Add some per-variable editorial improvements from BUILDING. Change sub headings to headings; it's easier to read. (I don't know why mdoc doesn't allow blank lines around .Ss)
2023-06-05mk.conf(5): editoriallukem
MKDTB and MKPIE are .YorN. MKX11=yes wants MKINET6=yes. MKLINKLIB deserves a dash list (like bsd.README). Expand per bsd.README: MKSTATICPIC, MKUNPRIVED, MKX11, MKZFS, USE_LIBCSANITIZER, USE_SSP Change the width of the variable lists to 14n (from 15n) so that when the lists are rendered and then left aligned, the column is 16 characters (aka 2 tabs) which makes copypasta to bsd.README easier.
2023-06-04mk.conf(5): add more from BUILDING and bsd.READMElukem
Add from BUILDING or bsd.README: BUILDINFO, BUILDSEED, EXTERNAL_TOOLCHAIN, MKCROSSGDB, MKREPRO_TIMESTAMP, TOOLCHAIN_MISSING, X11SRCDIR Clarify BUILDID. Improve MKDEBUG, MKOBJ, MKX11, NETBSDSRCDIR, USETOOLS, Consistent Note: formatting.
2023-06-03mk.conf: fix the yearlukem
2023-06-02follow the steps of Andrew Doran (ad) commit and fix more s/loose/lose/ typos.andvar
also s/beyound/beyond/ and few others along the way, mainly in comments.
2023-06-01mk.conf(5): update to realitylukem
- Document: MKAMDGPUFIRMWARE, MKARGON2, MKARZERO, MKBSDGREP, MKCOMPATMODULES, MKCOMPATTESTS, MKCOMPATX11, MKCXX, MKDEPINCLUDES, MKDTB, MKDTC, MKFIRMWARE, MKGROFF, MKGROFFHTMLDOC, MKLIBCSANITIZER, MKLIBCXX, MKLIBSTDCXX, MKLLVM, MKLLVMRT, MKMAKEMANDB, MKMANDOC, MKNSD, MKRADEONFIRMWARE, MKRELRO, MKSANITIZER, MKSLJIT, MKSTATICPIE, MKTEGRAFIRMWARE, MKTPM, MKUNBOUND, MKXORG_SERVER, NETBSD_OFFICIAL_RELEASE, USE_LIBCSANITIZER, USE_PIGZGZIP, USE_SANITIZER, USE_XZ_SETS, X11MOTIFPATH - Document obsolete/deprecated: EXTSRCSRCDIR, MKBFD, MKCRYPTO, MKEXTSRC, MKKDEBUG, MKKERBEROS4, MKLLD, MKLLDB, MKMCLINKER, MKPERFUSE, MKTOOLSDEBUG, SHAREDSTRINGS, USE_COMBINE - Fix defaults: MKLINT=no MKPICINSTALL=no USE_SKEY=no - Expand upon defaults that are platform specific. - Sort variable entries. - If a NOxxx variable disables a variable, describe it. - Layout of each variable: supported values, description, any other variables that change this variable, optional note, default value. - Consistent double quotes around default strings (even paths). - Consistent "will be" instead of "is" or "are". - Sort order of internal macro definitions. - Add NODEF and NOVAR macros. - Oxford comma and semi-colons where appropriate. - Fix mandoc -Tlint.
2023-05-29sysctl.7: be a little more descriptive about kern.osrevisiongutteridge
It's expressed as an integer, and is also returned as an integer type should one retrieve it via sysctl(3) (as this man page already correctly documents in the table above its description).
2023-05-22uiomove(9): Add uiopeek/uioskip operations.riastradh
This allows a caller to grab some data, consume part of it, and atomically update the uio with only the amount it consumed. This way, the caller can use a buffer of a size that doesn't depend on how much it will actually consume, which it may not know in advance -- e.g., because it depends on how much an underlying hardware tty device will accept before it decides it has had too much. Proposed on tech-kern: https://mail-index.netbsd.org/tech-kern/2023/05/09/msg028883.html (Opinions were divided between `uioadvance' and `uioskip'. I stuck with `uioskip' because that was less work for me.)
2023-05-22man0: support objdirs, tools, parallel buildslukem
man0 creates files, so write to the the OBJDIR instead of the source directory. Use TOOL_ appropriately. Add MAKEVERBOSE support. Add separate rules to generate: - all.files: the list of all man files to process (based on mkman) - manNpages.files: per-section files from all.files. (based on mkman) - manNpages.ps: per-section .ps from manNpages.files, with per-file MAKEVERBOSE messages to stderr (as before, just prettier). - manNpages.pdf: per-section .pdf from manNpages.ps. Remove the now-obsolete mkman script. Add TOOL_GROPS and _MKSHMSG_FORMAT to <bsd.own.mk>
2023-05-22man0: add bind/dist/bin/tests to nomanlukem
2023-05-14x86/boot(8): Nix trailing whitespace.riastradh
2023-05-14options(4): Nix trailing whitespace.riastradh
2023-05-09video(4): fix a typokhorben
From Li-Wen Hsu in PR misc/57364; thanks!
2023-05-08Remove XXX todo marker left by mistakemanu
2023-05-07s/inferface/interface/andvar
2023-05-05Add a SELFRELOC kernel option for the sake of documentation clarity.manu
Instead of telling that x86/boot(8) reloc command needs a kernel able to self relocate, we can tell it needs a kernel built with the SELFRELOC option. This keeps the reader from wondering what could make a kernel able to self relocate.
2023-05-04Fix spelling of Kurt Shoens surname.uwe
PR misc/57389
2023-05-04zz9k.4: clean up manual pagerillig
New sentence, new line; spelling, duplicate words.
2023-05-03Driver for the MNT ZZ9000 Zorro board. Submitted by Alain Runa.phx
It was formerly known as mntzz, which Alain released three years ago. Since then, the ZZ9000 had several firmware updates which changed some hardware interface details rendering the former driver non functional in some aspects. Also the audio card plug-in ZZ9000AX became available from MNT Research. Considering the major rewrite of the driver in some areas he decided to rename it to zz9k(9). The driver consists of several sub-drivers each addressing different functionality of the MNT ZZ9000 & ZZ9000AX combo card. zz9k* is the main card driver and need to be enabled if any of the sub-driver is enabled. zz9k on its own is not very useful, it only provides a common zz9kbus for the other sub-drivers to connect to, so only enable it if one of the zz9k sub-drivers are enabled. zzfb* represents the graphics driver for the boot console and the dumb framebuffer for X11 based on WSCONS. ZZFB_CONSOLE option enables the ZZ9000 to become the boot console. zz* represents the ethernet interface of the ZZ9000. It basically works but is considered experimental. zzax* represents the ZZ9000AX audio card driver, audio* attaches to it to provide audio output and input functionality. The driver is not functional yet. zzusb* represents the ZZ9000AX usb driver. It was not implemented yet and probably never will.
2023-04-24Merge x86 boot options in x86/boot(8) and add undocumented UEFI optionsmanu
We were supposed to keep the option list in x86/boot(8), x86/dosoot(8) and x86/pxeboot(8) in sync, but it did not happen, hence it may work better with all the options in x86/boot(8). Also add the undocumented UEFI boot options.
2023-04-20optstr(9): markup fixesuwe
While here, wrap long .Fn lines for readability and make the optstr_get_item list compact.
2023-04-20Update to include value conversion routines.skrll
2023-03-23entropy(7): don't use .Nx inside .Ssuwe
These macros don't adapt to context style, so in PostScript output the .Nx inside .Ss is suddenly in a different font.
2023-03-23entropy(7): use .Ql instead of .Sc Liuwe
2023-03-23entropy(7): don't try to cram things into one-linersuwe
2023-03-23entropy(7): Omit needless offset for diagnostic listing.riastradh
2023-03-19PR misc/57276 from Nan Xiaokre
Remove redundant word ("to").
2023-03-06Document __HAVE_UCAS_FULL and __HAVE_UCAS_MP.thorpej
2023-03-06fix typoswiz
2023-03-06portfeatures(9): the man page for the __HAVE macrosuwe
The man page itself is a skeleton/template for now. Please add short descriptions and xrefs. If the target man page doesn't yet document relevant __HAVE macros (hi, mutex(9)), please add something there, possibly in a .Sh IMPLEMENTATION NOTES section.
2023-03-01delete attribution per request of contributornia