$Id: utilities,v 1.32 2021/12/17 17:19:57 nanons Exp $

Utilities
=========

This is an ever-growing list of utilities included in the OpenBSD base
system that deserve more attention and some random tips about them.
Read their man pages for usage information, they will not be described
in much detail here.

* adduser, rmuser(8) - add and delete users from the system
Easier to do interactively than remembering useradd(8) options.
rmuser(8) removes empty groups and prompts to delete home directories.

* apropos(1) - search manual page databases
It can search for specific mdoc(7) macros, for a useful list see:

	$ man -Otag=Macro_Keys apropos

e.g., to list man pages where Theo de Raadt is listed as an author:

	$ apropos An="Theo de Raadt"

To list man pages where PAGER is mentioned in any macro, use "any":

	$ apropos any=PAGER

* arp(8) - address resolution display and control
Use the -W option to send Wake on LAN packets over Ethernet.
To allow incoming Wake on LAN, see:

	$ man -Otag=wol ifconfig

* b64encode, b64decode(1) - encode/decode a binary file
Use -r when decoding raw Base64.  More forgiving Base64 decoding can
also be achieved with:

	$ openssl base64 -d

* bc(1) - arbitrary-precision arithmetic language and calculator
Converts between number bases with the "ibase" (input) and "obase"
(output) variables, e.g. "ibase=16; obase=2; 12F" converts the
hexadecimal number "12F" into a binary number.
Number of decimal digits can be adjusted with the "scale" variable, e.g.
"scale=10; sqrt(2)" prints the square root of 2 with 10 decimals.

* cal(1) - displays a calendar

* calendar(1) - reminder service
If the file ~/.calendar/calendar exists, daily(8) will send mail to
your user (viewable with mail(1); see also MAIL in shell/dot.profile)
automatically a few days in advance of events in the calendar file.

	$ printf "Dec 15\tTerry Davis' birthday, 1969\n" >> ~/.calendar/calendar

* dump(8) - filesystem backup
* restore(8) - restore files or file systems from backups made with dump
dump(8) doesn't need root privileges when backing up filesystems or
mountpoints (as opposed to arbitrary directories) if ran as a user from
the "operator" group.
With dump(8)'s -u option, daily(8) will send mail to root's account
(see etc/daily.local) if a filesystem hasn't been dumped since the
number of days specified by the fifth field of its fstab(5) entry.
See also changelist(5) and scripts/backup.

* fmt(1) - simple text formatter
In vi(1), a commonly used command is "!}fmt" to format a paragraph, or
"~|fmt" in mail(1)'s composing mode to format an entire mail.
The shell built-in variable $COLUMNS as an argument to the -w option
will format text to perfectly fit the screen.

* getent(1) - get entries from administrative database
Find which Internet protocol listens on port 70:

	$ getent services 70

Print your user's passwd(5) entry:

	$ getent passwd $USER

Print users from the "wheel" group:

	$ getent group wheel

* jot(1) - print sequential or random data
BSD alternative to GNU seq(1).  See shell/aliases and shell/functions.

* kdump(1) - display kernel trace data
* ktrace(1) - enable kernel process tracing
* ltrace(1) - shared library function call tracer
Use the -i flag to trace fork(2)ed processes.  See also gprof(1).

* lldb(1) - LLVM debugger
Modern alternative to gdb(1) with a similar command-line interface.
Works with clang(1).  Requires compilation with the -g option for better
usability.

* locate(1) - find filenames quickly
See also the pkglocate utility to find filenames from packages(7) that
aren't installed.  To install it:

	# pkg_add pkglocatedb

* nc(1) - arbitrary TCP and UDP connections and listens
While nc(1) is already well known, OpenBSD's version is greatly extended
compared to most others.  It can speak TLS with -c, scan for open ports
with -z, connect through SOCKS/HTTP proxies with -x and -X, and more.
And the best feature: -e doesn't give hackers easy remote shells.

* openrsync(1) - synchronise local and remote files
Needs --rsync-path=openrsync if transferring to another openrsync(1).
High RAM usage when sending very big files.

* pcidump(8) - show PCI device data
* usbdevs(8) - show USB devices connected to the system
Alternatives for "lspci" from the pciutils package and "lsusb" from the
usbutils package.

* pkill, pgrep(1) - find or signal processes by name
Print processes that contain the word "getty" anywhere in their name:

	$ pgrep -lf getty

Kill processes with a program name of "ssh", but not "sshd", or
processes that contain the word "ssh" in arguments:

	$ pkill -x ssh

* rcs(1) - RCS file management program
Commonly used to keep change history of configuration files in /etc:

	# vi /etc/file
	# ci -l /etc/file

Suitable as version control for small private projects and easy to
convert to a cvs(1) repository if needed later.

* signify(1) - cryptographically sign and verify files
See also ssh-keygen(1) -Y sign and -Y verify for signing with SSH keys:
https://undeadly.org/cgi?action=article;sid=20201016053038 (the FIDO
authenticator is not necessary)
See also reop for encryption: https://humungus.tedunangst.com/r/reop
To install it:

	# pkg_add reop

* spell(1) - find spelling errors
Works well for man pages.  Use look(1) to check the spelling of only
one word (no output indicates a mispelling).

* systat(1) - display system statistics
Switch between views with the arrows or number keys 0-9.

* top(1) - display and update information about the top CPU processes
Has many features making it as usable as alternatives, such as process
name searching with the '/' key, scrolling with the '0' and '9' keys,
displaying the process arguments with 'C', and more.
Can set default options in the TOP environment variable.
If process names don't fit on the screen, use:

	$ top -bC
	$ ps axww

* unifdef(1) - remove preprocessor conditionals from code
Requires the -D, -U, or -f options to do anything.  To follow #include
directives and define built-in macros, simply use cpp(1).

* units(1) - conversion program
Converts between currencies as well.  Currency exchange rates are
updated every month on -current, or every 6 months on -release.
See /usr/share/misc/units.lib for the list of unit names.

* vis(1) - display non-printable characters in a visual format
* unvis(1) - revert visual representation of data back to original form
Different visual formats can also be achieved with:

	$ sed -n l
	$ cat -v

* xmessage(1) - display a message or query in a window
Emulate on-screen notification, commonly seen in desktop environments:

	$ xmessage -buttons "" -timeout 10 -geometry -5+5 "New mail!"

Window size and color can also be changed, see:

	$ man -Otag=OPTIONS X

* xtsscale(1) - X touch screen calibration tool
Append the resulting "mouse.scale=..." line to /etc/wsconsctl.conf.

* xwd(1) - dump an image of an X window
* xwud(1) - image displayer for X
To screenshot the entire screen instead of one window:

	$ xwd -root

Images are quite big, compress(1) them if sharing with others.
Be warned, xwd(1) records the window's title in the image file.
Use xpr(1) or xdpr(1) to print the image on a printer.
