Tested on OpenBSD 6.3 and 6.4

Deploy VM on OpenBSD Amsterdam

OpenBSD in Amsterdam is running dedicated vmd(8) servers to host opinionated VMs.

Send your name, email address, hostname, username, and public SSH key to OpenBSDAms via contact form, Twitter, or Mastodon, before you pay.

For example:

Roman Zolotarev
hi@romanzolotarev.com
www.romanzolotarev.com
romanzolotarev
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIqh7BmO...

Please allow few hours for your VM to be started. You'll get a IPv4 and IPv6 address as soon as your VM is deployed. Login to the VM (assuming your private SSH key is in its default location):

$ ssh username@XXX.XXX.XXX.XXX
OpenBSD 6.4-current (GENERIC) #358: Sat Oct 20 01:44:18 MDT 2018

Welcome to OpenBSD: The proactively secure Unix-like operating system.

Please use the sendbug(1) utility to report bugs in the system.
Before reporting a bug, please try to reproduce it with the latest
version of the code.  With bug reports, please try to ensure that
enough information to reproduce the problem is enclosed, and if a
known fix for it exists, include that as well.

$

Get the password from ~/.ssh/authorized_keys and switch to root.

$ awk '{print$NF}' .ssh/authorized_keys
XXXXXXXXXXXXXXXXXXXXXXXXXX
$ su -
password:
#

Add your username to /etc/doas.conf:

# echo 'permit username' > /etc/doas.conf
#

Edit /etc/ssh/sshd_config:

PermitRootLogin no
PasswordAuthentication no

Verify the new config and restart sshd:

# sshd -t
# rcctl restart sshd
sshd(ok)
sshd(ok)
#

It has been reported by some users that IPv6 needs -soii in order to work properly. In that case you can edit /etc/hostname.vio0:

dhcp
inet6 2a03:6000:9xxx::xxx 64 -soii

When you don't want the IPv4 address to be provided by dhcpd you can change /etc/hostname.vio0 to:

inet 46.23.xx.xx 255.255.255.0
inet6 2a03:6000:9xxx::xxx 64 -soii

When you do, make sure to edit /etc/mygate:

46.23.xx.1
2a03:6000:9xxx::1

Reinitialize the network:

# sh /etc/netstart vio0
#

Add to your crontab:

# crontab -e

These are workarounds for known issues. Replace 46.23.88.1 with your default gateway from /etc/mygate.

*/15 * * * * /usr/sbin/rdate pool.ntp.org > /dev/null
*/5 * * * * /sbin/ping -c3 46.23.88.1 > /dev/null

Update /etc/pf.conf, test, and load it:

# echo 'pass in quick proto { icmp, icmp6 } all' >> /etc/pf.conf
# pfctl -nf /etc/pf.conf
# pfctl -f /etc/pf.conf
# pfctl -sr
block return all
pass all flags S/SA
block return in on ! lo0 proto tcp from any to any port 6000:6010
block return out log proto tcp all user = 55
block return out log proto udp all user = 55
pass in quick proto icmp all
pass in quick proto ipv6-icmp all
#

Check 6.4 errata and apply available patches.

# syspatch
...
Relinking to create unique kernel... done.
# reboot
Connection to XXX.XXX.XXX.XXX closed.

Now you may want to setup a web server.

Thanks to Mischa Peters for reading drafts of this, to Mike Larkin, Bryan Steele, h3artbl33d, and Jeff Neitzel for tips and hints.

Tested on OpenBSD 6.3 and 6.4

Install OpenBSD on Vultr

If you need a new OpenBSD server, make sure you have your public SSH key handy, then...

register at Vultr

Deploy an instance, for example:

1. Server Location: pick your prefered location
2. Server Type: 64 bit OS, OpenBSD 6.3 x64
3. Server Size:
   • For IPv6 only: $2.50/mo 20 GB SSD 512MB Memory
   • IPv4 and IPv6: $3.50/mo 20 GB SSD 512MB Memory
4. Additional Features: None
5. Start Script: None
6. SSH Keys: Add new key
7. Firewall Group: No firewall
8. Server Hostname & Label: www

In a minute your sever will be deployed. Login using the new IP address and your private SSH key (assuming it's in the default location: ~/.ssh/id_ed25519):

$ ssh root@XXX.XXX.XXX.XXX
OpenBSD 6.3 (GENERIC) #349: Thu Oct 11 13:25:13 MDT 2018

Welcome to OpenBSD: The proactively secure Unix-like operating system.

Please use the sendbug(1) utility to report bugs in the system.
Before reporting a bug, please try to reproduce it with the latest
version of the code.  With bug reports, please try to ensure that
enough information to reproduce the problem is enclosed, and if a
known fix for it exists, include that as well.

www#

Read afterboot(8).

Setup a web server.

Install OpenBSD on a desktop

Prepare an USB drive with OpenBSD installer.
For example, on macOS.

Backup everything.

Check BIOS: Secure Boot disabled, UEFI Boot enabled.
For example, on ThinkPad X1C5.

Boot the installer.

Select (S)hell to create encrypt the drive.

# sysctl hw.disknames
hw.disknames=sd0:xxxxxxxxxxx,rd0:xxxxxxxxxxx,sd1:xxxxxxxxxxx

In this case sd0 is the target drive.
rd0 is ramdisk for installer kernel.
sd1 is USB drive with OpenBSD installer.

Erase all data on sd0. Create GUID Partition Table (GPT) and a partition layout.

# dd if=/dev/urandom of=/dev/rsd0c bs=1m
# fdisk -iy -g -b 960 sd0
# disklabel -E sd0
Label editor (enter '?' for help at any prompt)
a a
offset: [1024]
size: [500117105]
FS type: [4.2BSD] RAID
w
q
No label changes.
#

Generate a strong passphrase. Use diceware, for example.

# bioctl -c C -l sd0a softraid0
New passphrase:
Re-type passphrase:
sd2 at scsibus2 targ 1 lun 0: <OPENBSD, SR CRYPTO, 006> SCSI2 0/direct fixed
sd2: 244190MB, 512 bytes/sector, 500102858 sectors
softraid0: CRYPTO volume attached as sd2
# cd /dev && sh MAKEDEV sd2
# dd if=/dev/zero of=/dev/rsd2c bs=1m count=1
1+0 records in
1+0 records out
1048576 bytes transferred in 0.003 secs (265557618 bytes/sec)
# exit

Select (I)nstall and answer questions.

System hostname? = foo
Which network interface do you wish to configure? = em0
DNS domain name? = romanzolotarev.com
Password for root account? = **************************
Do you want the X Window System to be started by xenodm(1)? = yes
Setup a user? = romanzolotarev
Full name for user romanzolotarev? = Roman Zolotarev
Password for user romanzolotarev? = *******************
What timezone are you in? = UTC
Which disk is the root disk? = sd2
Use (W)hole disk MBR, whole disk (G)PT or (E)dit? = gpt
Location of sets? = disk
Is the disk partition already mounted? = no
Which disk contains the install media? = sd1
Directory does not contain SHA256.sig. Continue without verification? = yes

Unplug USB drive with the installer and boot OpenBSD from the target drive. Login as a regular user and run this command in xterm(1) to switch to root.

$ su -
Password:
#

Set install URL and run syspatch(8):

# echo 'https://fastly.cdn.openbsd.org/pub/OpenBSD'>/etc/installurl
# syspatch
...
Relinking to create unique kernel... done.
#

Update fstab(5) to add noatime:

# cp /etc/fstab /etc/fstab.bak
# sed -i 's/rw/rw,noatime/' /etc/fstab
#

Update login.conf(5) to increase memory limits:

# cp /etc/login.conf /etc/login.conf.bak
# sed -i 's/datasize-cur=768M/datasize-cur=4096M/' /etc/login.conf
# sed -i 's/datasize-max=768M/datasize-max=4096M/' /etc/login.conf
#

Enable apmd(8):

# rcctl enable apmd
# rcctl set apmd flags -A -z 7
# rcctl start apmd
ampd (ok)
#

Add your username /etc/doas.conf:

# echo 'permit username' > /etc/doas.conf
#

Reboot and login as a regular user.

Upgrade OpenBSD on bare metal

If you have OpenBSD installed and want to upgrate it, then backup your data first.

Prepare

Download and verify install64.fs:

# ftp -V https://cdn.openbsd.org/pub/OpenBSD/6.4/amd64/install64.fs
install64.fs 100% |*******************************|  360 MB     00:34
# ftp -V https://cdn.openbsd.org/pub/OpenBSD/6.4/amd64/SHA256.sig
SHA256.sig   100% |*******************************|  2141       00:00
# signify -C -p /etc/signify/openbsd-64-base.pub -x SHA256.sig install64.fs
Signature Verified
install64.fs: OK
#

Read the official FAQ.

Update your configuration files, if needed for 6.4.

Create bootable USB drive

Plug in a USB drive:

# dmesg | grep removable | tail -n1
sd3 at scsibus5 targ 1 lun 0: ... removable serial.12345...
#

In this case it appears as sd3. Copy the installer image to the USB flash drive (be extremely cautious):

# dd if=install64.fs of=/dev/rsd3c bs=1m
...

Upgrade

Boot from that USB drive, then choose the (S)hell option to mount the encrypted drive.

# bioctl -c C -l /dev/sd0a softraid0
passphrase:
scsibus1 at softraid0: 1 targets
sd3 at scsibus2 targ 0 lun 0: <OPENBSD, SR RAID 1, 005> SCSI2 0/direct fixed
sd3: 10244MB, 512 bytes/sec, 20980362 sec total
# exit

Choose (U)pgrade and answer the questions.

Which disk is the root disk = sd3
Location of sets = disk

Update packages

Login and update the installed packages:

# pkg_add -uv
...
#

Generate random string with random(4)

The urandom device produces high quality pseudo-random output data.

"Never use /dev/random. On OpenBSD, it does the same as /dev/urandom, but on many other systems, it misbehaves. For example, it may block, directly return entropy instead of using a stream cipher, or only return data from hardware random generators."
— random(4)

Limit character set

Keep characters you need and exclude everything else tr(1). For example, keep characters from 1 to 6.

$ tr -cd '1-6' < /dev/urandom
4135234354265156412324163535634456635452512413235
163421554662651365144426161433312335
^C
$

Trim

fold(1) into twenty-character wide lines, then head(1) the first line:

$ tr -cd '1-6' < /dev/urandom |
fold -w 20 |
head -n 1
15521625233645245322
$

Another way to take first 20 characters, use dd(1):

$ tr -cd '1-6' < /dev/urandom |
echo $(dd count=20 bs=1 status=none)
35611246252555226656
$

Adjust character set

Use any range of characters. For, example from the first printable char, space, to tilde.

$ tr -cd ' -~' < /dev/urandom |
fold -w 20 | head -n 1
a(k#$(K ?I?d!^NM^(5x
$

Or all alphanumeric characters, comma, and dot.

$ tr -cd '[:alnum:],.' < /dev/urandom |
fold -w 20 | head -n 1
3zgoNRosNuznXUxzENI.
$

Or just use jot(1)

Run jot(1) with the option -r to print random numbers.

$ jot -r 3
95
23
58
$

Set the range from 32 to 126 (ASCII codes of space and tilde), print a character represented by this number (-c), and separate characters with an empty string (-s '').

$ jot -rcs '' 20 32 126
L(k&C%M{E}7FFT9*H5tt
$

Or use openssl(1)

openssl(1) with rand command outputs pseudo-random bytes and with the -base64 option it encodes the output to its printable form.

$ openssl rand -base64 20
zM+i3ms6UGh8TkS4azknU+ncMIY=
$

"I'd be wary of using openssl(1)→Base64 unless you know that "=" can only come at the end because it's used as padding and so it's not adding anything extra to the password's entropy."
— Tim Chase (@gumnos)

See also

diceware, pass

Thanks to David Dahlberg, Tim Chase, Bojan Nastic, horia, Ben Bai for the hints, and to Theo de Raadt for arc4random.

Find disk name and partition with sysctl(1) and dmesg(1)

Make sure you are using the device name and partition you need, before your destroy all your data run any destructive commands like dd(1).

Disk names

You can address disk/partitions...

a raw device (or character device) is accessed directly, bypassing the operating system's caches and buffers.

When to use block devices then?

"Use block dev only for mounting, use raw for anything else"
— Otto Moerbeek (@ottom6k)

There are programs like disklabel(8), they accept all kinds of names (/dev/sd0c, or /dev/sd0, or even sd0) and parse them into full path /dev/rsd0c.

# disklabel sd1
# /dev/rsd1c:
...
#

Some programs, like fdisk(8), accept some abbreviations, like sd1 or sd1c, but refuse to work with block devices.

# fdisk /dev/sd1c
fdisk: /dev/sd1c is not a character device
#

Other programs, for example, dd(1), just do what you told them to do.

Don't repeat at home:

# dd if=/dev/zero of=/dev/sd3 bs=1m

/: write failed, file system is full
dd: /dev/sd3: No space left on device
919+0 records in
918+0 records out
962592768 bytes transferred in 2.466 secs (390316750 bytes/sec)
#

This dd creates the file /dev/sd3 and fills up your root partition.

Find disks

$ sysctl hw.disknames
hw.disknames=sd0:ew9w8ueO9m0t1wda,sd1:66160c68a67e00e6
$

sd0 is the device connected first, its DUID is ew9w8ueO9m0t1wda
sd1 is the second and DUID is 66160c68a67e00e6.

These numbers (sd0 and sd1) may change after reboot or pluging/unpluging USB devices, but DUIDs are persitent until you rewrite it with disklabel.

If you are looking for a just connected USB drive, then grep(1) word removable in the output of dmesg(1).

$ dmesg | grep removable | tail -1
sd1 at scsibus5 ...  SCSI3 0/direct removable ...
$

sd1 is what you are looking for.

Find partitions

Run disklabel(1) with a disk name or DUID.

# disklabel sd1
# /dev/rsd1c:
type: SCSI
disk: SCSI disk
label: XXXXXXXXXX
duid: 66160c68a67e00e6
flags:
bytes/sector: 512
sectors/track: 63
tracks/cylinder: 255
sectors/cylinder: 16065
cylinders: 1945
total sectors: 31260672
boundstart: 0
boundend: 31260672
drivedata: 0

16 partitions:
#                size      offset  fstype [fsize bsize   cpg]
  a:         31260672           0  4.2BSD   2048 16384     1
  c:         31260672           0  unused
#

If you are looking for OpenBSD partition (4.2BSD) it's the partition a.

The entire disk is represented as the partition c (marked as unused, because you can't create a file system on this partition).

Thanks to Tim Chase, Devin Teske, Mischa Peters, Bryan Steele for reading drafts of this.

Make bootable image with geteltorito(1) and dd(1)

For example, make a bootable USB disk to update BIOS on ThinkPad X1 Carbon 6th gen with ISO provided by Lenovo.

Download BIOS Update 1.30 06 Sep 2018 and verify the checksum:

$ ftp -V https://download.lenovo.com/pccbbs/mobiles/n23ur11w.iso
n23ur11w.iso 100% |**************************| 21868 KB    00:16
$ sha256 n23ur11w.iso
SHA256 (n23ur11w.iso) = e308a5...

Install geteltorito(1) and convert the ISO to El Torito boot image.

$ doas pkg_add geteltorito
$ geteltorito -o bios.img n23ur11w.iso
Booting catalog starts at sector: 20
Manufacturer of CD: NERO BURNING ROM VER 12
Image architecture: x86
Boot media type is: harddisk
El Torito image starts at sector 27 and has 43008 sector(s) of 512 Bytes
$ sha256 bios.img
SHA256 (bios.img) = c6a11b...
$

Plug in a USB drive:

$ dmesg | grep removable | tail -n1
sd3 at scsibus5 targ 1 lun 0: <Vendor, Model, 1.11>
SCSI3 0/direct removable serial.12345678901234567890987654

In this case it appears as sd3.

Copy the image (replace /dev/rsdXc with your drive). For example, for sd3 that would be /dev/rsd3c, where r means raw and c is a whole device. All data on sdX will be erased!

# dd if=bios.img of=/dev/rsdXc bs=1m
21+0 records in
21+0 records out
22020096 bytes transferred in 2.201 secs (10002851 bytes/sec)
#

Check the content of the drive:

# disklabel sdX
# /dev/rsd3c:
type: SCSI
disk: SCSI disk
label: XXXXXXXXXXXXXXX
duid: 0000000000000000
flags:
bytes/sector: 512
sectors/track: 63
tracks/cylinder: 255
sectors/cylinder: 16065
cylinders: 1945
total sectors: 31260672
boundstart: 0
boundend: 31260672
drivedata: 0

16 partitions:
#                size           offset  fstype [fsize bsize   cpg]
  c:         31260672                0  unused
  i:            42976               32   MSDOS
# mkdir ./sdXi
# mount /dev/sdXi ./sdXi
# cd /mnt/sdXi
# find .
.
./System Volume Information
./System Volume Information/WPSettings.dat
./System Volume Information/IndexerVolumeGuid
./EFI
./EFI/Boot
./EFI/Boot/BootX64.efi
./FLASH
./FLASH/406E8.PAT
./FLASH/806E9.PAT
./FLASH/806EA.PAT
./FLASH/BCP.EVS
./FLASH/NoDCCheck_BootX64.efi
./FLASH/README.TXT
./FLASH/SHELLFLASH.EFI
./FLASH/N23ET55W
./FLASH/N23ET55W/$0AN2300.FL1
./FLASH/N23ET55W/$0AN2300.FL2
#

Reboot and flash the BIOS.

Thanks to Mikko Nyman for testing and Peter Hessler for the pointer.

Dock laptop with xrandr(1), xinput(1), xrdb(1), and sysctl(8)

TL;DR: Check out my dock and undock.

Screens

Toggle displays with xrandr(1). For example, only laptop's display (eDP-1) is on, then an external one (HDMI-1), then both side by side:

$ xrandr --output eDP-1 --auto --output HDMI-1 --off
$ xrandr --output HDMI-1 --auto --output eDP-1 --off
$ xrandr --output HDMI-1 --auto --output eDP-1 --auto --right-of HDMI-1
$

Mouse and touchpad

List all connected devices with xinput(1):

$ xinput
⎡ Virtual core pointer                          id=2    [master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer                id=4    [slave  pointer  (2)]
⎜   ↳ /dev/wsmouse0                             id=7    [slave  pointer  (2)]
⎜   ↳ /dev/wsmouse                              id=8    [slave  pointer  (2)]
⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
    ↳ Virtual core XTEST keyboard               id=5    [slave  keyboard (3)]
    ↳ /dev/wskbd                                id=6    [slave  keyboard (3)]

Then adjust button mapping and pointer acceleration. For example, reverse touchpad scrolling (id=7) and slow down trackball (id=8).

$ xinput set-button-map 7 1 2 3 5 4 7 6
$ xinput set-prop 8 'Device Accel Constant Deceleration' 5
$

See also my .xsession.

Fonts

Toggle DPI for all X programs (including Firefox) and fonts for xterm(1). On high DPI screens, use large TrueType fonts:

Xft.dpi: 133
XTerm*font:
XTerm*faceName: DejaVu Sans Mono:size=12

On low DPI screens, use bitmap ones:

Xft.dpi: 92
XTerm*font: -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1
XTerm*faceName:

To apply these settings use xrdb(1) (don't forget to restart X programs after that):

$ xrdb .Xdefaults
$ echo 'Xft.dpi: 92' | xrdb -merge
$

Here is my .Xdefaults.

Lid

Define an action on laptop's lid closing. Do nothing (0), suspend (1), or hibernate (2):

# sysctl machdep.lidaction=0
machdep.lidaction: 2 -> 0
# sysctl machdep.lidaction=1
machdep.lidaction: 0 -> 1
# sysctl machdep.lidaction=2
machdep.lidaction: 1 -> 2
#

Prepare ThinkPad X1 Carbon Gen 5 for OpenBSD

Turn ThinkPad on and press F1 to enter Setup.

Select Security > I/O Ports, set Bluetooth and Fingerprint Reader to Disabled. These devices are not supported by OpenBSD. Disable other devices you don't use.

Select Security > Secure Boot, set Secure Boot to Disabled.

Select Startup > Boot, set Boot Priority Order to:
USB HDD, then NVMe0 ....

Select Startup, set UEFI/Legacy Boot to UEFI Only.

Press F10 to save changes and reboot.

Install OpenBSD.

Encrypt disk with bioctl(8) and CRYPTO

bioctl(8) is a RAID management interface with CRYPTO discipline for disk encryption.

Create an encrypted volume

Plug the drive in. Assuming it's sd3.

DANGER! All data on sd3 will be erased.

# dd if=/dev/urandom of=/dev/rsd3c bs=1m
# fdisk -iy -g -b 960 sd3
# printf 'a a


RAID
w
q
'|disklabel -E sd3
# bioctl -c C -l sd3a softraid0
New passphrase:
Re-type passphrase:
softraid0: CRYPTO volume attached as sd4
# dd if=/dev/zero of=/dev/rsd4c bs=1m count=1
# fdisk -iy sd4
# printf 'a i



w
q
'|disklabel -E sd4
# newfs sd4a
# mkdir /mnt/sd4a
# mount /dev/sd4a /mnt/sd4a
# ...
# umount /dev/sd4a
# bioctl -d sd4
#

It's safe to unplug sd3 drive now.

Mount and umount

Plug the drive in.

# bioctl -c C -l sd3a softraid0
Passphrase:
softraid0: CRYPTO volume attached as sd4
# mkdir /mnt/sd4a
# mount /dev/sd4a /mnt/sd4a
...
# umount /dev/sd4a
# bioctl -d sd4
#

Check out my helpers mnt_crypto and umnt_crypto and how to use them:

# bin/mnt_crypto  'XXXXXXXXXXXXXXXX.x' 'YYYYYYYYYYYYYYYY.y'
# bin/umnt_crypto 'XXXXXXXXXXXXXXXX.x'

Where XXXXXXXXXXXXXXXX.x is DUID and partition of a CRYPTO volume and YYYYYYYYYYYYYYYY.y—of a physical device.

You can find DUIDs by running this:

# disklabel /dev/sd3a | grep -E 'duid|RAID'
duid: XXXXXXXXXXXXXXXX
  a:          7716864                 0    RAID
# disklabel /dev/sd4a | grep -E 'duid|BSD'
duid: YYYYYYYYYYYYYYYY
  i:          7716864                64    4.2BSD   4096 32768 26062
#

Check file system consistency

A drive was accidentally disconnected (before you could unmount it properly). That happens. Run fsck(8):

# bioctl -c C -l sd3a softraid0
softraid0: sd4 was not shutdown properly
Passphrase:
softraid0: sd4 was not shutdown properly
softraid0: CRYPTO volume attached as sd4
# fsck /dev/sd4a
** /dev/rsd4a
** Last Mounted on /mnt/sd4a
** Phase 1 - Check Blocks and Sizes
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Check Cyl groups
38996 files, 58177423 used, 62950830 free
(10766 frags, 7867508 blocks, 0.0% fragmentation)

MARK FILE SYSTEM CLEAN? [Fyn?] y

***** FILE SYSTEM WAS MODIFIED *****
#

Change the passphrase

# bioctl -P sd4
Old passphrase:
New passphrase:
Re-type passphrase:
#

Configure newsboat(1) to read RSS feeds in terminal

Install newsboat(1). For example, on OpenBSD:

# pkg_add newsboat
...
newsboat-2.10.2: ok
#

Add the first feed to your .newsboat/urls, add .newsboat/config, run newsboat(1):

$ mkdir -p "$HOME/.newsboat"
$ echo 'https://www.romanzolotarev.com/rss.xml' \
"$HOME/.newsboat/urls"
$
$ cat > "$HOME/.newsboat/config" << EOF
browser         "firefox"
player          "mpv"
download-path   "~/downloads/%n"
save-path       "~/downloads"
reload-threads  20
cleanup-on-quit yes
text-width      74

bind-key - quit
bind-key G end
bind-key g home
bind-key j down
bind-key k up
EOF
$
$ newsboat

From a list of feeds select the first one and get the list of items:

newsboat 2.10.2 - Articles in feed 'Roman Zolotarev' (1 unread
   1 N  May 06   2.2K  Configure newsboat(1) to read RSS feeds
   2    May 01   1.4K  Configure minimalist login on OpenBSD
   3    May 01   1.8K  Set default applications on X Window Sy
   4    Apr 24   5.3K  My dear sponsor,
   5    Apr 13   5.6K  Enable HTTPS on OpenBSD with Let's Encr
   6    Apr 12   2.4K  Configure OpenBSD httpd(8) on your web
   7    Apr 11   2.4K  Deploy a VPS on Vultr
   8    Apr 07   9.6K  Static site generator with rsync and lo
   9    Apr 03   1.4K  Upgrade OpenBSD
  10    Mar 30   1.6K  Strong password generator
  11    Mar 16   710   Change time zone in OpenBSD
  12    Mar 02   1.6K  Backup with borg
  13    Mar 01   1.8K  Mount drives on OpenBSD
  14    Feb 27   713   Printing from the command line on macOS
  15    Nov 17  12.6K  OpenBSD on my fanless desktop computer
  16    Nov 15   3.8K  Why OpenBSD?
  17    Nov 02   2.1K  Enable full disk encryption on OpenBSD
  18    Oct 10   7.3K  Password manager powered by LibreSSL
  19    Sep 20   2.3K  Install OpenBSD on your desktop
  20    Sep 19   1.0K  Prepare a bootable OpenBSD drive on mac
  21    Sep 01   4.2K  Configure YubiKey for login and SSH on
-:Quit ENTER:Open s:Save r:Reload n:Next Unread A:Mark All Rea

Navigate with j, k, G, g, -.

Default key bindings:

Enter - open the feed or the article
n - jump to the next unread article
p - jump to the previous unread article
o - open an article in your browser
e - enqueue podcast for podboat
E - edit the list of your feeds in ~/.newsboat/urls
r - reload the feed
q - go up or quit

Check out my .newsboat/urls.

Set default programs with xdg-mime(1)

When you click on a downloaded PDF file in Firefox or when you run xdg-open(1), the file opens with ths default program for its mimetype.

Check the mimetype with xdg-mime(1):

$ xdg-mime query filetype example.pdf
application/pdf
$

Let's check the default application for application/pdf?

$ xdg-mime query default application/pdf
gimp.desktop
$

What? Why would you want to open your PDF files in Gimp? Weird. Let's fix this.

First off, install MuPDF, if you didn't yet.

# pkg_add mupdf
...
mupdf-1.11p2:glfw-3.2.1p0: ok
mupdf-1.11p2: ok
#

Then create mupdf.desktop in ~/.local/share/applications directory with just two lines.

[Desktop Entry]
Exec=/usr/local/bin/mupdf %u

Or use the full version:

[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
NoDisplay=true
Exec=/usr/local/bin/mupdf %u
Name=MuPDF
Comment=A lightweight PDF viewer

Set the new default application:

$ xdg-mime default mupdf.desktop application/pdf
$

Let's verify:

$ xdg-mime query default application/pdf
mupdf.desktop
$

P.S. Types for Word and Excel documents are not exactly what would you expect:

$ xdg-mime query filetype example.doc
application/octet-stream
$ xdg-mime query filetype example.xls
application/octet-stream
$ xdg-mime query filetype example.docx
application/zip
$ xdg-mime query filetype example.xlsx
application/zip
$

Set time zone on OpenBSD

Check your current time with date(1):

# date
Thu Apr  5 12:26:43 UTC 2018
#

The local timezone is UTC.

Check /etc/localtime with readlink(1):

# readlink /etc/localtime
/usr/share/zoneinfo/UTC
#

It's a symbolic link to UTC time zone file.

Find a file for the time zone you want to set with find(1):

# find /usr/share/zoneinfo -name 'Mos*'
/usr/share/zoneinfo/Europe/Moscow
...
#

Set timezone with zic(8).

# zic -l Europe/Moscow
#

Check the time zone:

# readlink /etc/localtime
/usr/share/zoneinfo/Europe/Moscow
# date
Thu Apr  5 15:26:51 MSK 2018
#

Generate passphrases with random(4)

diceware is a random passphrase generator. It uses random(4) as a source of entropy. Make sure your operating system provides good enough randomness.

Install

$ cd bin
$ ftp -V https://www.romanzolotarev.com/bin/diceware
diceware     100% |********************| 18711       00:00
$ chmod +x diceware

Roll dice

On every run it generates a random passphrase, 8-word long by default.

$ diceware
guerrilla agnostic backdoor glove jealous mummy myth sloth
$ diceware 20
khaki hemoglobin artichoke cyclist coverless dictionary
vegetable sardine datebook ruined purse cytoplasm
absorbing narrator snapshot smitten cuticle journal
fiscally neither
$

Pipe it to your favorite password manager:

$ diceware | pass import twitter
Enter pass phrase for /home/romanzolotarev/.pass/.key:
$

See also

random, pass

Thanks to Randall Munroe and Joseph Bonneau.

Tested on OpenBSD 6.3 and 6.4

Manage passwords with openssl(1) and oathtool(1)

pass is a password manager written in shell and powered by openssl(1) and oathtool(1).

Install

# pkg_add oath-toolkit
...
oath-toolkit-2.6.2p0: ok
#

Download and run pass. Assuming ./bin is in PATH.

$ cd bin
$ ftp https://www.romanzolotarev.com/bin/pass
$ chmod +x pass
$ pass
usage: export BASE_DIR=~/.pass
       export PRIVATE_KEY=~/.pass/.key
       export PUBLIC_KEY=~/.pass/.key.pub

       pass init
          | passphrase
          | add        id
          | import     id <pass>
          | show       id
          | export     id <pass>
          | ls        <id>

Initialization

Create a directory for your passwords and generate your key pair. Generate a strong pass phrase. For example, with diceware.

$ pass init
Generating public/private key pair.
New pass phrase:
Confirm:
Generating RSA private key, 2048 bit long modulus
..........................+++
..................+++
e is 65537 (0x10001)
writing RSA key
$ ls -1 ~/.pass
.key
.key.pub
$

As result you get two files in ~/.pass directory. These files are your keys and they are protected with your master pass phrase.

Important! Backup those files, you won't be able to recover any of your passwords without the private key. Also make sure you remember your pass phrase, there is no way to recover it either.

Change pass phrase

Change the master pass phrase for your private key.

$ pass passphrase
Changing /home/username/.pass/.key pass phrase.
Current pass phrase:
New pass phrase:
Confirm:
Pass phrase changed.
$

Add a password

Add the first password.

Run the following command and enter your master pass phrase, then type-in the password and hit Enter. In the second line type username and in the third line type url. Press Enter and CTRL-D to save the password.

$ pass add github
Pass phrase
Press Enter and CTRL-D to complete.
always mule boots jaguar agnostic singles dalmatian vixen
username: username
url: https://github.com
$

Import a password

Instead of typing your passwords manually you can pipe your favorite password generator right into pass.

$ diceware | pass import twitter
Enter pass phrase for /home/username/.pass/.key:
$

Edit the password

If you want to update your password run:

$ pass edit github
Enter pass phrase for /home/username/.pass/.key:

As soon as you enter the pass phrase pass opens vi with the content of your password file. Let's enable 2FA at GitHub paste the TOTP seed from GitHub into the password file. For example:

totp: fx33dwhsbw7esrda

When you're done press ZZ to save and exit vi.

Show the password

To show a password you can run:

$ pass show twitter
pelican mule satchel headband yo-yo lemon luscious older
$

But if a password file has a line staring with totp:, then pass shows one time password in the second line.

$ pass show github
Enter pass phrase for /home/username/.pass/.key:
always mule boots jaguar agnostic singles dalmatian vixen
122635
$

Export the password

If you want to see all lines of your password file, you can use export

$ pass export github
Enter pass phrase for /home/username/.pass/.key:
always mule boots jaguar agnostic singles dalmatian vixen
username: username
url: https://github.com
$

List all passwords

To list all your passwords run:

$ pass ls
github
twitter
$

Files

.pass
|-- .key           - RSA private key protected by pass phrase
|-- .key.pub       - RSA public key
|-- github         - tar archive of two files:
|   |-- github.key - AES key encrypted with RSA public key
|   `-- github.enc - text file encrypted with AES key
|-- github.sig     - signature of tar archive created with
|                    RSA private key
...

Every time you change your password file pass generates tar archive with a new AES key and a new signature. pass verifies the signature every time you show or export the password.

Environment variables

To change path to the working directory or your keys, define environment variables BASE_DIR, PRIVATE_KEY, PUBLIC_KEY. For example:

$ BASE_DIR=~/.pass \
PRIVATE_KEY=~/.pass/.key \
PUBLIC_KEY=~/.pass/.key.pub pass init
...

Completions in Korn shell

If you run pass on OpenBSD you may want to add completions in ksh(1)—its default shell. Add these functions to your ~/.profile:

update_complete_pass() {
  pass_list=$(pass ls)
  set -A complete_pass_edit -- $pass_list
  set -A complete_pass_export -- $pass_list
  set -A complete_pass_show -- $pass_list
}
update_complete_pass
pass_edit() { pass edit "$1"; }
pass_export() { pass export "$1" && update_complete_pass; }
pass_show() { pass show "$1" && update_complete_pass; }

Now open a terminal or source ~/.profile and try pass:

$ pass<Tab>
init  passphrase  add  import  show  export  ls
$ pass

Or most importantly try pass_show:

$ pass_show twit<Tab>
twitch  twitter
$ pass_show twit

See also

diceware, random

Generate SSH keys

Generate a strong passphrase to protect your private key. For example, with diceware.

Run ssh-keygen(1) to create a SSH key pair and enter that passphrase:

$ ssh-keygen -t ed25519 -a 100
Enter file in which to save the key
(/home/username/.ssh/id_ed25519):
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ~/.ssh/id_ed25519.
Your public key has been saved in ~/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx comment
The key's randomart image is:
+--[ED25519 256]--+
|       .o=@*=    |
|        oX = .=  |
|        * o +    |
|       = o =     |
|        S o +    |
|       * + o     |
|      = X.o.=    |
|       O =+o     |
|      . E++++    |
+----[SHA256]-----+
$

Option -t ed25519 specifies the type of the key.
Option -a 100 specifies the number of key derivation function rounds used (higher the number—better protection against brute-force cracking).

RSA fallback

If Ed25519 isn't yet supported by your operating systems, use long RSA keys as a fallback.

$ ssh-keygen -t rsa -b 4096 -o -a 100
Enter file in which to save the key
(/home/username/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ~/.ssh/id_rsa.
Your public key has been saved in ~/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx comment
The key's randomart image is:
+---[RSA 2048]----+
|  .ooo ...ooo    |
|  ..o.+  .o+  E  |
|.o.o.o = . o     |
|.Boo= + +        |
|+ Bo . =S        |
| o . ...+. o     |
|    . o  ++      |
|     o o .o      |
|      + ..*      |
+----[SHA256]-----+
$

Option -o enables the new OpenSSH format to increase resistance to brute-force cracking.

Do not share private keys

Don't copy or share your private key. Generate a new key pair for every user and every device. Use the same key pair for multiple destinations.

Use SSH configuration

Add all your frequently used hosts to ~/.ssh/config, like this:

Host remote_host
  User username_on_remote_host
  Hostname www.example.com
  IdentityFile /home/username/.ssh/id_ed25519

After adding this to your SSH configuration you can run:

# ssh www

instead of:

$ ssh -i ~/.ssh/id_ed25519 username_on_remote_host@www.example.com

Customize xenodm(1) login screen

Enable xenodm(1):

# rcctl enable xenodm
#

Edit /etc/X11/xenodm/Xresources:

xlogin.Login.echoPasswd:       true
xlogin.Login.fail:             fail
xlogin.Login.greeting:
xlogin.Login.namePrompt:        login 
xlogin.Login.passwdPrompt:     passwd 

xlogin.Login.height:           180
xlogin.Login.width:            280
xlogin.Login.y:                320
xlogin.Login.frameWidth:       0
xlogin.Login.innerFramesWidth: 0

xlogin.Login.background:       black
xlogin.Login.foreground:       #eeeeee
xlogin.Login.failColor:        white
xlogin.Login.inpColor:         black
xlogin.Login.promptColor:      #eeeeec

xlogin.Login.face:             fixed-13
xlogin.Login.failFace:         fixed-13
xlogin.Login.promptFace:       fixed-13
```

Edit /etc/X11/xenodm/Xsetup_0:

#!/bin/sh
xsetroot -solid black

Logout to check the login screen.

Use YubiKey for login and SSH.

Configure cwm(1)

cwm(1) is my favorite window manager for X11. It has a tiling mode, so I don't have to rearrange windows manually.

cwm(1) is in OpenBSD base.

$ echo 'exec cwm' >> ~/.xsession

Here is my .cwmrc. Quite often I keep just two windows open. On the left side: tmux in xterm(1). On the right side: Firefox.

Mount disk with... mount(1)

Only root can mount(8) file systems on OpenBSD, a regular user should run mount(8) via doas(1).

Plug in a USB drive and check system messages:

# dmesg
sd1 at scsibus2 targ 1 lun 0: <Vendor, Model, 1.26>
SCSI3 0/direct removable serial.12345678901234568789
sd1: 7633MB, 512 bytes/sector, 15633408 sectors
#

Check partitions:

# disklabel sd1
...
      size     offset  fstype [fsize bsize   cpg]
a:    736256       1024  4.2BSD   2048 16384 16142
c:  15633408          0  unused
i:       960         64   MSDOS
#

To mount a partition, for example, a:), use /dev/sd1a device.

Create a mount point directory, for example, /mnt/usb-drive, and mount the drive:

# mkdir -p /mnt/usb-drive
# mount /dev/sd1a /mnt/usb-drive
# ls /mnt/usb-drive
...
#

It's mounted.

Before disconnecting the drive from the USB port, unmount it. Leave mount point directory and then use it as an argument for unmount(8).

# cd
# umount /mnt/usb-drive
#

Or you can address your device directly:

# umount /dev/sd1a
#

Mount exFAT file system on OpenBSD

First, find your uid:

$ id -u
1000
$

Then as root install exfat-fuse and mount exFAT file system with your uid:

# pkg_add exfat-fuse
quirks-3.16 signed on 2018-10-12T15:26:25Z
exfat-fuse-1.2.8: ok
# mkdir -p /mnt/sd1i
# mount.exfat -o uid=1000 /dev/sd1i /mnt/sd1i
FUSE exfat 1.2.8
#

Use the file system as a regular user:

$ df /mnt/sd1i
Filesystem  512-blocks      Used     Avail Capacity  Mounted on
fusefs         7716800      1344   7710336     0%    /mnt/sd1i
$ touch /mnt/sd1i/test
$ ls -l /mnt/sd1i/test
-rwxrwxrwx  1 romanzolotarev  wheel  0 Nov  5 16:11 /mnt/sd1i/test
$

To unmount run as root:

# umount /mnt/sd1i
#

Mount file system via Media Transfer Protocol on OpenBSD

First, find your uid and gid:

$ id -u
1000
$ id -g
1000
$

Connect your phone, camera, or any other MTP compatible device to your computer. Set the device to MTP mode.

For example, on Android 8.0 it's called Transfer files.

Then as root install simple-mtpfs and mount a file system via MTP with your uid:

# pkg_add simple-mtpfs
quirks-3.16 signed on 2018-10-12T15:26:25Z
simple-mtpfs-0.3.0p0:libusb1-1.0.21p1: ok
simple-mtpfs-0.3.0p0:libmtp-1.1.15: ok
simple-mtpfs-0.3.0p0: ok
# mkdir -p /mnt/mtp
# simple-mtpfs --device 1 /mnt/mtp -o uid=1000 -o gid=1000 -o allow_other
#

Use the file system as a regular user:

#
$ df /mnt/mtp
Filesystem  512-blocks      Used     Avail Capacity  Mounted on
fusefs       291042488  42956896 248085592    15%    /mnt/mtp
$ touch /mnt/mtp/test
$ ls -l /mnt/mtp/test
-rw-r--r--  1 romanzolotarev  romanzolotarev  0 Nov  5 16:29 /mnt/mnt/test
$

To unmount run as root:

# umount /mnt/mtp
#

Configure login(1) and sshd(8) for YubiKey on OpenBSD

The login_yubikey(8) utility is called by login(1) and others to authenticate the user with YubiKey authentication.

Prepare YubiKey

Install and start YubiKey Personalization GUI:

# pkg_add yubikey-personalization-gui
...
yubikey-personalization-gui-3.1.25: ok
# yubikey-personalization-gui

Insert your YubiKey into USB port, select Yubico OTP > Quick, select Configuration Slot 1 or 2, click Write Configuration, save the log into /tmp/yubikey.csv, click Exit.

Extract uid and key from the log, verify /var/db/yubikey/* files, and remove yubikey.csv file.

# cd /var/db/yubikey
# touch romanzolotarev.{uid,key}
# chown root:auth *
# chmod 440 *
# grep Yubico /tmp/yubikey.csv | cut -f5 -d, > romanzolotarev.uid
# grep Yubico /tmp/yubikey.csv | cut -f6 -d, > romanzolotarev.key
# cat *
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxx
# rm /tmp/yubikey.csv
# ls -l
-r--r-----  1 root  auth  33 May  1 15:22 romanzolotarev.key
-r--r-----  1 root  auth  13 May  1 15:22 romanzolotarev.uid
#

You can uninstall yubikey-personalization-gui

# pkg_delete yubikey-personalization-gui
yubikey-personalization-gui-3.1.25: ok
Read shared items: ok
# pkg_delete -a
...
Read shared items: ok
#

Configure login(1) and sshd(8)

Back up login.conf(5) and sshd_config(5) to be able to revert changes.

# cp /etc/login.conf /etc/login.conf.bak
# cp /etc/ssh/sshd_config /etc/ssh/ssh_config.bak
#

Change auth-defaults in /etc/login.conf:

auth-defaults:auth=yubikey:

Add this line to etc/ssh/sshd_config:

AuthenticationMethods publickey,password

Restart sshd and verify: when ssh asks for a password—instead of entering your regular password—touch YubiKey, if you have used slot 1 (or touch and hold it for 2-3 seconds for slot 2)...

# rcctl restart sshd
# ssh root@localhost
root@localhost's password:
Last login: Wed May  2 17:11:06 2018 OpenBSD 6.3
(GENERIC.MP) #1: Sat Apr 21 14:26:25 CEST 2018

Welcome to OpenBSD: The proactively secure Unix-like
operating system.

Please use the sendbug(1) utility to report bugs in the system.
Before reporting a bug, please try to reproduce it with the
latest version of the code. With bug reports, please try to
ensure that enough information to reproduce the problem is
enclosed, and if a known fix for it exists, include that as well.
# exit

Host Git repositories on OpenBSD

Deploy a server and login into it.

On the remote host install git(1), add git user, add your public SSH key, change owner and group, then exit.

# pkg_add git
...
git-2.16.2: ok
The following new rcscripts were installed: /etc/rc.d/gitdaemon
See rcctl(8) for details.
Look in /usr/local/share/doc/pkg-readmes for extra documentation.
#
# mkdir /home/git
# user add git
# mkdir -m 700 /home/git/.ssh
# cp /root/.ssh/authorized_keys /home/git/.ssh/
# chown -R git:git /home/git
#

From your local host initialize a bare repository on the remote, add the remote and push a local copy to it.

$ ssh git@REMOTE git init --bare REPOSITORY.git
Initialized emtpy Git repository in /home/git/REPOSITORY.git/
$ cd REPOSITORY
$ git remote add REMOTE git@REMOTE_SERVER:REPOSITORY.git
$ git push REMOTE master
Counting objects: 1049, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1041/1041), done.
Writing objects: 100% (1049/1049), 3.80 MiB | 257.00 KiB/s, done.
Total 1049 (delta 676), reused 0 (delta 0)
remote: Resolving deltas: 100% (676/676), done.
To REMOTE_SERVER:REPOSITORY.git
 * [new branch]      master -> master
$

Publish Git repositories.

Publish Git repositories with stagit(1) on OpenBSD

stagit(1) generates HTML files from your git repository. The source of this website, for example: /src/.

Install

Set up git and httpd, then install stagit.

# pkg_add stagit
quirks-3.16 signed on 2018-10-12T15:26:25Z
stagit-0.8:libssh2-1.8.0p0: ok
stagit-0.8:libgit2-0.27.2: ok
stagit-0.8: ok
#

Update Git repository

Add owner and description to the Git repository:

$ cd REPOSITORY.git
$ echo 'OWNER_NAME' > owner
$ echo 'DESCRIPTION' > description
$

Add post-receive hook to REPOSITORY.git/hooks/:

#!/bin/sh
set -e
dst="/var/www/htdocs/$(basename "$(pwd)" '.git')"

mkdir -p "$dst/src"
(cd "$dst/src" && stagit "$src")
cp -f "$dst/src/log.html" "$dst/src/index.html"

Check out my files: post-receive hook and style.css.

Test

To test post-receive hook push from your local host to the server:

$ git push REMOTE master
...
$

Configure httpd(8) on OpenBSD

Install OpenBSD.

Edit /etc/httpd.conf. Add two server sections—one for www and another for naked domain (all requests are redirected to www).

server "www.example.com" {
  listen on * port 80
  root "/htdocs/www.example.com"
}

server "example.com" {
  listen on * port 80
  block return 301 "http://www.example.com$REQUEST_URI"
}

httpd(8) is chrooted to /var/www by default, so let's make a document root directory:

# mkdir -p /var/www/htdocs/www.example.com
#

Save and check the configuration. Enable httpd(8) and start it.

# httpd -n
configuration ok
# rcctl enable httpd
# rcctl start httpd
#

Publish your website

Copy your website content into /var/www/htdocs/www.example.com and then test it your web browser.

http://XXX.XXX.XXX.XXX/

Your web server should be up and running.

Update DNS records

If there is another HTTPS server using this domain, configure that server to redirect all HTTPS requests to HTTP.

Now as your new server is ready you can update DNS records accordingly.

    example.com. 300 IN     A XXX.XXX.XXX.XXX
www.example.com. 300 IN     A XXX.XXX.XXX.XXX

Examine your DNS is propagated.

$ dig example.com www.example.com
...
;; ANSWER SECTION:
example.com.         299     IN      A       XXX.XXX.XXX.XXX
...
;; ANSWER SECTION:
www.example.com.     299     IN      A       XXX.XXX.XXX.XXX
...
$

Check IP addresses in answer sections.

Open your website in a browser.

http://www.example.com/

Enable HTTPS on your server.

Enable HTTPS with acme-client(1) and Let's Encrypt on OpenBSD

Configure httpd(8).

To use Let's Encrypt as a certificate authority for TLS encryption add or update your CAA records for your domain.

    example.com. 300 IN   CAA   0 issue "letsencrypt.org"
www.example.com. 300 IN   CAA   0 issue "letsencrypt.org"

To configure acme-client(1), add these sections to /etc/acme-client.conf:

authority letsencrypt {
  api url "https://acme-v01.api.letsencrypt.org/directory"
  account key "/etc/acme/letsencrypt-privkey.pem"
}
authority letsencrypt-staging {
  api url "https://acme-staging.api.letsencrypt.org/directory"
  account key "/etc/acme/letsencrypt-staging-privkey.pem"
}
domain www.example.com {
  alternative names { example.com }
  domain key "/etc/ssl/private/www.example.com.key"
  domain certificate "/etc/ssl/www.example.com.crt"
  domain full chain certificate "/etc/ssl/www.example.com.pem"
  sign with letsencrypt
}

Create directories:

# mkdir -p -m 700 /etc/acme
# mkdir -p -m 700 /etc/ssl/acme/private
# mkdir -p -m 755 /var/www/acme
#

Update /etc/httpd.conf to handle verification requests from Let's Encrypt. It should look like this:

server "www.example.com" {
  listen on * port 80
  root "/htdocs/www.example.com"
  location "/.well-known/acme-challenge/*" {
    root "/acme"
    request strip 2
  }
}

server "example.com" {
  listen on * port 80
  block return 301 "http://www.example.com$REQUEST_URI"
}

Check this configuration and restart httpd:

# httpd -n
configuration ok
# rcctl restart httpd
httpd(ok)
httpd(ok)
#

Let's run acme-client to create new account and domain keys.

# acme-client -vAD www.example.com
...
acme-client: /etc/ssl/www.example.com.crt: created
acme-client: /etc/ssl/www.example.com.pem: created
#

To renew certificates automatically edit the current crontab:

# crontab -e

Append this line:

0 0 * * * acme-client www.example.com && rcctl reload httpd

Save and exit:

crontab: installing new crontab
#

Enable HTTPS and restart the daemon

Now we have the new certificate and domain key, so we can re-configure httpd to handle HTTPS requests. Add two server sections to /etc/httpd.conf for TLS. The result should look like this:

server "www.example.com" {
  listen on * tls port 443
  root "/htdocs/www.example.com"
  tls {
    certificate "/etc/ssl/www.example.com.pem"
    key "/etc/ssl/private/www.example.com.key"
  }
  location "/.well-known/acme-challenge/*" {
    root "/acme"
    request strip 2
  }
}

server "example.com" {
  listen on * tls port 443
  tls {
    certificate "/etc/ssl/www.example.com.pem"
    key "/etc/ssl/private/www.example.com.key"
  }
  block return 301 "https://www.example.com$REQUEST_URI"
}

server "www.example.com" {
  listen on * port 80
  root "/htdocs/www.example.com"
  location "/.well-known/acme-challenge/*" {
    root "/acme"
    request strip 2
  }
}

server "example.com" {
  listen on * port 80
  block return 301 "http://www.example.com$REQUEST_URI"
}

Test this configuration and restart httpd:

# httpd -n
configuration ok
# rcctl restart httpd
httpd (ok)
httpd (ok)
#

To verify your setup run SSL server test.

Congratulation! Your website and its visitors are now secured.

Add domains

Backup and remove the certificate

# mv /etc/ssl/www.example.com.crt /etc/ssl/www.example.com.crt.bak
#

Add a new alternative name to /etc/acme-client.conf:

...
alternative names { example.com new.example.com }
...

Add a new server section to /etc/httpd.conf. Use the same certificate and key.

...
server "new.example.com" {
  listen on * tls port 443
  root "/htdocs/new.example.com"
  tls {
    certificate "/etc/ssl/www.example.com.pem"
    key "/etc/ssl/private/www.example.com.key"
  }
  location "/.well-known/acme-challenge/*" {
    root "/acme"
    request strip 2
  }
}
...

Request a new certificate with the new alternative new in it. Verify httpd.conf and restart httpd(8):

# acme-client -vFAD www.example.com
...
acme-client: /etc/ssl/www.example.com.crt: created
acme-client: /etc/ssl/www.example.com.pem: created
# httpd -n
configuration ok
# rcctl restart httpd
httpd(ok)
httpd(ok)
#

Thanks to Tim Chase, Mischa Peters, and Ve Telko for reading drafts of this, to Reyk Floeter for httpd(8) and to Kristaps Dzonsons for acme-client(1).

Forward outgoing mail to a remote SMTP server

Replace smtpd.conf(5), add secrets, set permissions, test the configuration, and restart smtpd(8):

# cat > /etc/mail/smtpd.conf << EOF
table aliases file:/etc/mail/aliases
table secrets file:/etc/mail/secrets
listen on lo0
action "local" mbox alias <aliases>
action "relay" relay host smtp+tls://foo@server:port auth <secrets>
match for local action "local"
match for any action "relay"
EOF
#
# touch /etc/mail/secrets
# chmod 640 /etc/mail/secrets
# chown root:_smtpd /etc/mail/secrets
# echo "foo username:password" > /etc/mail/secrets
#
# smtpd -n
configuration OK
# rcctl restart smtpd
smtpd (ok)
smtpd (ok)
#

Configure nsd(8) on OpenBSD

Install two VMs in two different networks.
For example, OpenBSD.Amsterdam and Vultr.

Let's pick arbitrary names for them:

ns1.example.com
ns2.example.com

Edit nsd.conf(5) on ns1,
create a zone file for example.com,
copy nsd.conf and example.com.zone to ns2,
enable and start nsd(8) on both servers.

# cat > /var/nsd/etc/nsd.conf << EOF
server:
  database: ""

remote-control:
  control-enable: yes
  control-interface: /var/run/nsd.sock

zone:
  name: example.com
  zonefile: master/%s.zone
EOF
#
# cat > /var/nsd/zones/master/example.com.zone << EOF
$ORIGIN             example.com.
$TTL    300
@       3600  SOA   ns1.example.com. hostmaster.example.com. (
        2018121401  ; serial YYYYMMDDnn
        1440        ; refresh
        3600        ; retry
        604800      ; expire
        300 )       ; minimum TTL
@             NS    ns1.example.com.
@             NS    ns2.example.com.
ns1           A     46.23.88.178
ns2           A     140.82.28.210
@             MX    10 smtp.example.com.
@             MX    20 smtp.example.com.
@             A     46.23.88.178
www           A     46.23.88.178
EOF
#
# rcctl enable nsd
# rcctl start nsd
nsd (ok)
# dig +short example.com NS @127.0.0.1
ns1.example.com.
ns2.example.com.
#

Update nameservers ns1.example.com and their IP addreses (for glue records) at your domain registrar. Your mail server should accept mail for hostmaster@example.com.

Verify your setup with zonemaster.net.

Update zone

Edit the zone file and increment the serial on ns1, copy the zone file to ns2, reload nsd(8) on ns1 and ns2.

# rcctl reload nsd
nsd(ok)
#

Find and remove whitespaces with grep(1) and sed(1)

TL;DR: Checkout my fws, tws, and .gitconfig.

Find lines with trailing spaces in all non-binary files (recursively starting from the current directory).

$ grep -rIl '[[:space:]]$' .
file-with-trailing-spaces.txt
$

Find and remove those spaces.

$ grep -rIl '[[:space:]]$' . | xargs sed -i 's/[[:space:]]*$//'
$

A slightly faster version

Exclude *.git directories and use all CPU cores.

$ find . \
    \( -type d -name '*.git' -prune \) -o \
    \( -type f -print0 \) |
xargs -0 \
    -P "$(sysctl -n hw.ncpu)" \
    -r 2>/dev/null grep -Il '[[:space:]]$'
file-with-trailing-spaces.txt
$

Configure vi

Add to .exrc:

map gt mm:%s/[[:space:]]*$//^M`m

Where ^M is the actual CR character: press ^V, then <Enter>.

Configure git

Git can detect whitespaces.

$ git config --global core.whitespace \
    trailing-space,-space-before-tab,indent-with-non-tab,cr-at-eol
$

Add pre-commit hook to .git/hooks:

#!/bin/sh
exec git diff-index --check --cached HEAD --

If there are whitespace errors, it prints the file names and fails.

Thanks to Tim Chase for performance hints.

# Start a heading with one hash

## Start a subheading with two hashes

Paragraphs are separated by empty lines.
**Bold text** is wrapped in double asterisks,
_italic_ in underscores,
`monospace` in backticks.

[A link](https://www.romanzolotarev.com/).
![An image](/avatar.jpeg)

    # Indented code block
    hello() { echo 'Hello'; }

A list of items:

- Each item is on its line
- Lines start with `-`

An ordered list:

1. The first item
1. The second item can start with `1.` too
1. Markdown handles the numbering for you.

Convert Markdown to HTML with Jekyll, lowdown, pandoc, or with the original Markdown.pl.

Manage terminals with tmux(1)

tmux(1) is a terminal multiplexor.

Session

To create and attach to a new session run:

$ tmux

You've got a green status bar at the bottom of the window. That means now you're attached to a tmux session with name 0 (in the left bottom corner [0]) in the first and only window open number 0 and name ksh (0:ksh*).

To detach from tmux session press C-b d (Ctrl-b and then d) or you can just kill your terminal window. C-b is the default PREFIX key in tmux(1). The session stays intact.

To attach to existing session instead of tmux run:

$ tmux new -A -s 0

tmux(1) tries to attach (-A) to the existing session (-s 0) and if fails then it creates a new session.

Windows

To create a new window press PREFIX c. You've got another window created and selected (1:ksh*).

To select window 0 press PREFIX 0, to select 1 press PREFIX 1.

To close a window close program its running (to exit shell press C-d) or you can kill the window with PREFIX d. By default name of a window changes to its active program (for example, ksh).

To rename a window press PREFIX , then edit its name and hit Enter. Once a window is renamed its name will persist for the session.

Panes

With tmux(1) you can split a window into panes. PREFIX " to split horizontally and `PREFIX %' to split the window vertically.

To select another pane use PREFIX arrow, where arrow is up, down, left, or right.

To resize panes use PREFIX c-arrow.

Press PREFIX just once, then press arrow as many times as you need to select (or c-arrow to resize). But key press intervals should be under 500 ms (see repeat-time option), otherwise you need to press PREFIX again.

Workflow

Keep one session at a time and use one window per task. Each window may have multiple panes.

To start tmux(1) use this shell script, ~/bin/stmux:

#!/bin/sh
usage() { >&2 echo "usage: ${0##*/} window path command"; exit 1; }
[ -z "$1" ] && usage
[ -z "$2" ] && usage
[ -z "$3" ] && usage

tmux select-window -t "$1" 2>/dev/null ||
tmux new-window -n "$1" -c "$HOME/$2" "$3"

stmux requires three arguments: a window name, a path to the working directory, and an initial command.

Here is a shortcut:

m() { "$HOME/bin/stmux" m pub/music cmus; }

Run m from anywhere:

$ m

It tries to select the window named m and if it fails, it creates that window and runs cmus from pub/music directory.

See also

.tmux.conf, .profile, status, tmux wiki.

Edit text with vi(1)

On OpenBSD vi(1) is based on nvi 1.79, written by Keith Bostic.

You can't record macros in nvi, but you still can use them. Add a sequence of commands into a buffer (for example, "q...), then apply the macro as usual (with @q).

To edit multiple files: vi file1 file2, then :n[ext], :prev to switch, and :ar[gs] to list them all.

To open one more file :e[dit] file, then ^6 to alternate between two, or use :e# command.

To open in a split :E[dit] file, then ^W to switch between windows, and to set the window height to 20 lines :res[ize] 20.

To scroll current line to the top z<Enter>, to the center z., and to the bottom of screen z-. Scroll lines with ^Y and ^E as usual.

To search for the "expression" and place the next occurence of it to the center of screen: /expression/z..

Undo and redo: Press u to undo previous edit, then press . (dot) to undo, to redo press u again.

Increment a number: place cursor at the first digit and press #.

To redraw the screen press ^L.

If you miss Visual mode, try marks. For example, mark the line by pressing mm, move to another line, then delete from the current to the marked line with d'm. Or copy to the buffer with y'm.

Break lines at column 72 in Insert and Append modes.

:set wraplen=72

Format a paragraph with goal line length 72, allow indented paragraphs.

:?^$?,//!fmt -pw 72

Sort lines in a paragraph (in Command mode):

!}sort

To remove trailing spaces:

:%s/[[:space:]]\{1,\}/

To edit command-history:

:set cedit=\<TAB>

Where <TAB> is the actual tab character: press ^V, then <TAB>.

To read help:

:help

If you need Unicode, use nvi2:

# pkg_add nvi
...
nvi-2.1.3p1-iconv: ok
#

See also

.exrc, .profile, .tmux.conf, vi command help guide by Jeff W.

Make a static site with find(1), grep(1), and lowdown(1)

ssg is a static site generator written in shell. Optionally it converts Markdown files to HTML with lowdown(1).

Unless a page has <HTML> tag ssg4 extracts its title from <H1> tag, wraps the page with _header.html, _footer.html.

Then copies everything (excluding .*, CVS, and _*) from src to dst directory.

180 LoC. Enlarge, enhance, zoom!

Install

Download and chmod it:

$ mkdir -p bin
$ ftp -Vo bin/ssg4 https://www.romanzolotarev.com/bin/ssg4
ssg4       100% |*********************|    4916      00:00
$ chmod +x bin/ssg4
$ doas pkg_add lowdown
quirks-2.414 signed on 2018-03-28T14:24:37Z
lowdown-0.3.1: ok
$

lowdown(1) is optional. It's required only if there are any *.md files.

Usage

$ mkdir src dst
$ echo '# Hello, World!' > src/index.md
$ ftp -Vo src/_header.html https://www.romanzolotarev.com/raw/_header.html
_header.html 100% |**************************|  3362       00:00
$ ftp -Vo src/_footer.html https://www.romanzolotarev.com/raw/_footer.html
_header.html 100% |**************************|   727       00:00
$ ftp -Vo src/favicon.png https://www.romanzolotarev.com/raw/favicon.png
favicon.png  100% |**************************|   408       00:00
$ bin/ssg4 src dst 'Test' 'http://www'
./index.md
./favicon.png
[ssg] 2 files, 1 url
$ find dst
dst
dst/.files
dst/index.html
dst/favicon.png
dst/sitemap.xml
$ open dst/index.html

Markdown and HTML files

HTML files from src have greater priority than Markdown ones. ssg4 converts Markdown files from src to HTML in dst and then copies HTML files from src to dst. In the following example src/a.html wins:

src/a.md   -> dst/a.html
src/a.html -> dst/a.html

Favicon

Make sure you have /favicon.png in place.

Some browsers fetch /favicon.ico despite what you specified in the <LINK> tag, so you can use an empty one (180 bytes) as a placeholder.

Sitemap

ssg4 generates sitemap.xml with the list of all page. Don't forget to add absolute URL of the sitemap to your robot.txt.
For example:

user-agent: *
sitemap: https://www.romanzolotarev.com/sitemap.xml

RSS

To generate RSS feeds use rssg, then add their URLs to _header.html.
For example:

<link rel="alternate" type="application/atom+xml" href="/rss.xml">

Incremental updates

On every run ssg4 saves a list of files in dst/.files and updates only newer files. If no files were modified after that, ssg4 does nothing.

$ bin/ssg4 src dst 'Test' 'https://www'
[ssg] no files, 1 url
$

To force the update delete dst/.files and re-run ssg4.

$ rm dst/.files
$ bin/ssg4 src dst 'Test' 'https://www'
index.md
[ssg] 1 file, 1 url
$

Watch

Save this helper to ~/bin/sssg. It re-runs ssg4 with entr(1) on every file change.

$ cat $HOME/bin/sssg
#!/bin/sh
while :
do
    find . -type f ! -path '*/.*' |
    entr -d "$HOME/bin/ssg4" . "$1" "$(date)" '//www'
done
$

Install entr(1):

$ doas pkg_add entr
quirks-2.414 signed on 2018-03-28T14:24:37Z
entr-4.0: ok
$

Start the helper and keep it running:

$ ~/bin/s /var/www/htdocs/www
[ssg] 1 file, 1 url

Upgrade

Previous version of ssg has been retired.

Add <!DOCTYPE html>, <STYLE>...</STYLE> with your styles and an empty <TITLE></TITLE> tags to _header.html.

ssg4 captures page's title from the first <H1> tag of the page and inject it into <TITLE>, if it's present and empty.

Move _rss.html to _header.html, _styles.css to <STYLE> tag in _header.html, and _scripts.js to <SCRIPT> tag.

Dependencies

ssg4 depends on few programs from OpenBSD base:

$ for f in $(which cat cpio date sh awk find grep printf readlink sort tee)
do ldd "$f"
done | awk '/\//{print$7}' | grep '.' | sort -u
/bin/cat
/bin/cpio
/bin/date
/bin/sh
/usr/bin/awk
/usr/bin/find
/usr/bin/grep
/usr/bin/printf
/usr/bin/readlink
/usr/bin/sort
/usr/bin/tee
/usr/lib/libc.so.92.5
/usr/lib/libm.so.10.1
/usr/lib/libutil.so.13.0
/usr/lib/libz.so.5.0
/usr/libexec/ld.so

Users

blog.solobsd.org
bloguslibrus.fr
bsdjobs.com
cryogenix.net
dethronedemperor.com
grosu.nl
h3artbl33d.nl
high5.nl
matthewgraybosch.com
mvidal.net
openbsd.amsterdam
openbsd.space
romanzolotarev.com — obviously ;)
runbsd.info
stockersolutions.com

Thanks to Devin Teske for helping with awk(1), Kristaps Dzonsons for lowdown(1), and Eric Radman for entr(1).

Generate RSS feeds with grep(1), sed(1), and awk(1)

rssg is an RSS feed generator written in shell. It's a good companion for ssg.

It gets feed's description, URL, and the list of items from an index file.

Then for every item it extracts its title and treats the rest of the file as its description, replacing all relative URLs with absolute ones.

An index file can be in HTML or in Markdown format.

Finally, rssg outputs the feed in XML format.

148 LoC. grep and sed everything

Install

Download and chmod it:

$ ftp -Vo bin/rssg https://www.romanzolotarev.com/bin/rssg
rssg       100% |*********************|    4137      00:00
$ chmod +x bin/rssg
$ doas pkg_add lowdown
quirks-2.414 signed on 2018-03-28T14:24:37Z
lowdown-0.3.1: ok
$

Usage

$ rssg index.html 'title' > rss.xml
$

Here is an example of a minimal index.html file:

<h1>People who run BSD</h1>

<p>
Stories written by users of BSD operating systems.
Hosted by Roman Zolotarev.
</p>

<p>
Subscribe via <a href="https://bsdjobs.com/people/rss.xml">RSS</a>.
</p>

<ul>
<li><a href="mischapeters.html" title="2018-08-07">Mischa Peters</a></li>
<li><a href="h3artbl33d.html" title="2018-08-06">h3artbl33d</a></li>
</ul>

HTML parsing rules:

• <H1> and <A> tags should not contain line breaks.
• title is the first <H1> tag.
• description is the first <P> tag.
  All <H1> tags are excluded from description.
• url is HREF attribute of the first <A> tag with RSS content.
  
• items are lines with <A> tags and TITLE attribute.
• item file is HREF attribute of that line, item date is TITLE attribute, and item title is the content of <A> tag.

Thanks to Devin Teske for her awk(1) wizardry.

Archive with borg(1)

Borg is a deduplicating archiver with compression and encryption.

Install

# pkg_add borgbackup
...
borgbackup-1.1.4p0: ok
#

Initialize

$ borg init -e repokey -v ~/archives
Initializing repository at "archives"
Enter new passphrase:
Enter same passphrase again:
Do you want your passphrase to be displayed for verification? [yN]:
Remember your passphrase. Your data will be inaccessible without it.
Key in "<Repository /home/romanzolotarev/archives>" created.
Keep this key safe. Your data will be inaccessible without it.
Synchronizing chunks cache...
Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
Done.
$

Back up

$ borg create ~/archives::src-20180626-1304 src
Enter passphrase for key /home/romanzolotarev/archives:
$

Restore

$ cd /tmp
$ borg extract -v --list ~/archives::src-20180626-1304 src/www/borg.md
Enter passphrase for key /home/romanzolotarev/archives:
src/www/borg.md
$ sha256 /tmp/src/www/borg.md ~/src/www/borg.md
SHA256 (/tmp/src/www/borg.md) = 66d23...
SHA256 (/home/romanzolotarev/src/www/borg.md) = 66d23...
$

Set up a remote storage

To keep archives off-site set up your own server or sign up for Rsync.net ($10/year for 40 GB or $0.24/year/GB).

Automate

Create ~/bin/borgbackup script like this:

#!/bin/sh
export BORG_REPO='USERNAME@SERVER.rsync.net:REPO'
export BORG_RSH="ssh -i $HOME/.ssh/PUBLIC_KEY"
export BORG_REMOTE_PATH='/usr/local/bin/borg1/borg1'
export BORG_PASSPHRASE='PASSPHRASE'

archive=$(date +%Y%m%d-%H%M)
borg create -C lzma,9 -p \
    --exclude '*/.cache/*' \
    --exclude '*/Downloads/*' \
    "::$archive" "$HOME"

borg prune -v --list --stats \
    --keep-hourly 48 \
    --keep-daily 60 \
    --keep-monthly 12 \
    --keep-yearly 10 \
    '::'

$ chmod 0700 ~/bin/borgbackup
$ ~/bin/borgbackup
...
------------------------------------------------------------------------------
Keeping archive: 20180726-1352                        Thu, 2018-07-26 13:05:15
...
Keeping archive: 20180331-1505                        Sat, 2018-03-31 12:05:37
------------------------------------------------------------------------------
                       Original size      Compressed size    Deduplicated size
Deleted data:                    0 B                  0 B                  0 B
All archives:               66.93 GB             66.65 GB              7.38 GB

                       Unique chunks         Total chunks
Chunk index:                   34152               185692
------------------------------------------------------------------------------
Remote: Starting repository check
Remote: Starting repository index check
Remote: Completed repository check, no problems found.
Starting archive consistency check...
Analyzing archive 20180331-1505 (1/10)
...
Analyzing archive 20180726-1305 (10/10)
Archive consistency check complete, no problems found.
$

Use crontab(1) to run ~/bin/borgbackup by schedule.

Print with cups(1) on macOS

Add a printer:

# lpadmin -E \
-p Printer \
-v ipp://192.168.1.10/ipp/print \
-P Vendor-Model.ppd
#

-E enables accepting job
-p an arbitrary printer name
-v the device URI
-P a path to the PPD file

Check available printers:

$ lpstat -a
Printer accepting requests since Sat Mar 31 23:59:32 2018
$

Print a document:

$ lp -d Printer document.pdf
$

Delete the printer:

# lpadmin -x Printer
#

Prepare bootable USB drive with OpenBSD installer on macOS

Download the installer and verify its checksum:

$ cd /tmp
$ export URL=https://cloudflare.cdn.openbsd.org/pub/OpenBSD
$ curl -Os $URL/6.3/amd64/SHA256
$ curl -O  $URL/6.3/amd64/install63.fs
...
$ grep install63.fs SHA256|cut -f4 -d' '
df19266be16079ccd6114447f7bb13bdedb9c5cb66ecc1ea98544290fa4dc138
$ shasum -a 256 install63.fs|cut -f1 -d' '
df19266be16079ccd6114447f7bb13bdedb9c5cb66ecc1ea98544290fa4dc138
$

Plug in the USB drive. Its size should be at least 400 MB. Run diskutil list to find an identifier of the flash drive. Usually it's /dev/disk2.

Replace /dev/diskX with the identifier of the flash drive.
All data on /dev/diskX will be erased!

$ sudo diskutil unmount /dev/diskX
$ sudo dd if=install63.fs of=/dev/diskX bs=1m
...
$

Wait few minutes.

Install OpenBSD.

Edit text with Vim

Vim has everything you may need for text editing out-of-the-box: syntax highlighting, autocompletion, split screen, diff, spell checking, text formatting, text objects, persistent undo, automatic commands, macros, scripting, and many more.

Most of Vim features are kind of hidden and it makes sense, nothing stands on your way when you are working. Although, such minimalism makes learning curve a bit steeper.

On the other hand, everything in Vim is thoroughly documented and the documentation is always available via :help command.

Vim is keyboard-based

Usual Vim command is a sequence of keystrokes. You rarely use key chords in Vim and you don't need a mouse.

You can effortlessly make large edits with few keystrokes, because Vim has commands, movements, and can operate text objects: paragraphs, sentences, words, etc. Everything is mnemonic. For example, you can type dap in normal mode to "delete a paragraph", and ciw to "change in word", and so on.

Vim is extensible

Vim can do a lot without any customization or plugins, but you can tailor Vim for your needs. There are tons of plugins for Vim (you may need just few), you can install and update them with ease.

Vim is well integrated with command line tools (grep, git, head, tail, tee, find, cp, mv, rm, cut, uniq, sort, etc). With pipes and redirects you can compose programs to do any text manipulations you may need.

Vim is fast

Vim doesn't need a lot of resources to perform well. Its startup time is under six milliseconds:

$ vim -u NONE --startuptime vim.log +q
$ tail -n 1 vim.log | cut -f1 -d' '
005.287
$

To be fair, to start Vim with a dozen of plugins and to open a file takes about 60 ms. Still impressive.

Vim almost never lags and typing latency is very low. Typometer shows 4.8 ms for Vim in Terminal.app on macOS.

Even when you are editing files on a remote machine over SSH and the internet connection is slow, you still are in control, because in Vim you can do a lot with a single command: quick jumps inside a large file, switching among multiple files, searching and replacing across all files in a project, etc.

Yes, Vim works perfectly in a terminal over SSH. You can edit files remotely and be as productive as on your computer.

Vim is future-proof

Vim (or its predecessor vi) is pre-installed on all Unix-like machines (macOS, BSD, Linux). Vim has been ported to almost all operating systems, including Windows.

Vim is a free and open-source software. It's a time-tested software: vi released in 1976, Vim — in 1991. Vim will stay around for a long time. Once you learned Vim you may use it for decades. You workflow may change, programming languages come and go, but Vim always does its job well.

Still undecided? Try Vim for a few days.

Manage passwords with security(1) on macOS

Add a password to the default keychain:

$ security add-generic-password -a ${USER} -s NAME -w

Retrieve the password:

$ security find-generic-password -a ${USER} -s NAME -w

Delete the password:

$ security delete-generic-password -a ${USER} -s NAME

Host repositories on GitHub

Generate a new SSH key pair and copy public key to the clipboard.

$ xclip -selection clipboad ~/.ssh/id_ed25519.pub
$

Open your GitHub profile.

On Personal Settings > SSH and GPG keys page click New SSH key.

Type-in a Title, for example, a hostname of your computer.

Paste your public key into Key textarea.

Click Add SSH key.

Expect email A new public key was added to your account from GitHub.

$ ssh -T git@github.com
Hi romanzolotarev! You've successfully authenticated, but GitHub
does not provide shell access.
$

GitHub makes your public key available via HTTPS.

$ curl https://github.com/romanzolotarev.keys
ssh-ed25519 AAAAC3NzaC...
$

Make a static website with Jekyll

Jekyll is a static website generator. It converts your markdown files to web pages which you can publish with a single command or few clicks.

If you are on a Mac, both Ruby and Jekyll are pre-installed.

Create a new directory for your project and run Jekyll.

$ mkdir hello-world
$ cd hello-world
$ jekyll s
$

Create an index.md file:

---
---
# Hello, World!

Those dashes separate the Jekyll front matter from your Markdown content. Jekyll needs front matter even if it's empty.

Open http://127.0.0.1:4000 in a web browser.

Edit index.md. Jekyll detects changes and regenerates all files. To see changes, reload the web page.

Add more files if needed.

Publish

One of the simplest ways to publish is to push your project to GitHub. It will take care of running Jekyll to regenerate all files on push.

You can also publish your site on any web server. By default, Jekyll renders all files to the _site directory, so just copy those files and you're good to go. No dependencies, just static HTML files.

Layout (optional)

When you have multiple files and want to style your web pages, it makes sense to create a layout.

To add a new layout:

• Choose any layout name, say, default.
• Create a file default.html in the _layouts directory.
• Add any HTML you want and include the {% raw %}{{content}}{% endraw %} tag.

Live reload (advanced)

When I'm editing wordy pages or tweaking layouts I use the jekyll-livereload plugin. It triggers page reload every time I save a file.

jekyll-reload injects JavaScript code into <head>. So make sure you have a <head> tag in your layout.

Here's how to enable live reload:

Install Bundler:

$ gem install bundler

Add Gemfile:

source 'https://rubygems.org'
gem 'jekyll', group: :jekyll_plugins
group 'jekyll_plugins' do
  gem 'jekyll-livereload'
end

Install and run:

$ bundle install
$ bundle exec jekyll serve -L

See also

Jekyll Minimalist, GitHub Pages

Hi, my name is Roman, and I am addicted to tools.

Do you type for hours every day like I do? Then let me share a year-long journey to the holy grail ergonomic typing. Touch typing can change your life (in a good way). If you're looking for a new keyboard or considering learning an alternative layout, you should definitely keep reading.

Long story short

I "touch typed" with seven fingers for decades and managed to type at average speed with pretty poor accuracy. I tried so many times to learn proper technique, but I always gave up in a week. A year ago I decided it was now or never. I had only one goal: to type faster, like 100 WPM. Spoiler: I'm not there yet. Back then I was using QWERTY on an Apple Wireless keyboard.

This was my method: "Okay, roll up your sleeves, and just memorize every key for all ten fingers." It took two days. I memorized all the keys during that weekend. Typing speed plummeted to 10 WPM on the first day; I was "thinking" before pressing almost every key. I could type with 100% accuracy without looking, but it was very very slow.

Next phase: typing lessons every day for an hour. From time to time I typed with my seven (favorite) fingers when I needed to get work done, but in a few days I switched to the ten-finger method cold turkey. I continued practicing every day at Keybr and Keyhero and finally reached 40 WPM in two weeks.

Phew...

As soon as I returned to my original speed and accuracy, I decided to upgrade my keyboard to an ergonomic one. Two months later ErgoDox arrived. And of course, I wanted to try an alternative keyboard layout on it. After a quick analysis, I picked the Norman layout: it's easy to learn, and it significantly reduces distance traveled from the home row.

Relearning. My speed dropped to 10 WPM, and recovered to 40 WPM in three weeks. I switched to the ErgoDox full time and played with ErgoDox layers, ending up with a single-layer solution. I reached 50 WPM in 40 days and stopped all typing lessons.

Today I am a happy ErgoDox user. My average speed on Norman is 60 WPM, and it's increasing every month, slowly but steadily.

Lessons learned

Fast and accurate typing is a must-have skill for a programmer. I wish I'd switched to the right path earlier.

I am not the fastest typist, just a bit quicker than average. My achievements in terms of words per minute are very humble. Still, I can say the return on investment is overwhelmingly high.

Proper typing style

Better typing speed saves me a few hours every week on code documentation, notes, and emails. Fast typing enables blogging: you can find an hour for a draft, but it is harder to find two. So a difference of 20 WPM can affect your productivity quite significantly.

If you are an average typist, you should invest few minutes a day in typing lessons. Focus on accuracy and practice every day. Totally worth it.

Ergonomic keyboard

If you have a Mac, there's a good chance that your keyboard is excellent. Apple keyboards are robust, compact, and quiet.

ErgoDox is louder and bigger. The primary benefit of ErgoDox is ergonomics. (Surprise!) As with any split keyboard, you can sit (or stand) straight, so your posture is healthier, and it's simply more relaxing.

My initial goal was just to improve my typing speed. Of course, high speed is necessary, but when I started using ErgoDox, I realized that comfort is the primary reward: my hands, shoulders, and back are much happier now. Yes, ErgoDox costs three hundred dollars, but it's the best keyboard available today for that price, and the keyboard is the most important part of my workplace. If you're typing all day long, you can connect your awesome keyboard to any cheap computer and be productive in no time.

Alternative keyboard layout

I use Norman and like it better than QWERTY. I haven't tried any other layouts, and honestly, I'm not sure that learning alternative layouts is worth it. What I am 100% sure of is that I can learn any keyboard layout and be productive in two weeks. Layouts and keyboards do not limit my speed; my fingers can move faster than I can compose words in English.

Why not stick with QWERTY on all my keyboards? Switching to a different layout and keyboard helped me break my bad typing habits. It's easier to learn correct technique from scratch on an entirely new instrument than it is to to fix those bad habits deeply wired into your brain.

How did I choose Norman? Two sources. First, people who already who use multiple layouts for years: Gary Bernhardt, Aaron Patterson, a good review by Ted. Second, I compared Dvorak, Colemak, Workman, Norman, and even my custom layout with a keyboard layout analyzer (made by Patrick Gillespie). Norman performed slightly better than the others on my custom corpus of text.

One more reason I picked Norman: It's easy to switch to QWERTY and back to Norman in few minutes. (I use QWERTY when I travel.) Norman is just a fifteen-key difference from QWERTY.

I use Vim with both QWERTY and Norman, and I do not remap anything in Vim. In the beginning, I had one annoying issue: HJKL on Norman are in weird locations. I was hitting U instead of J. That was such a painful week. Now everything is just fine.

Looking back, I am not entirely sure if all these layouts made any difference in my case. I can learn any crazy layout and reach an average speed in few weeks, but it won't increase my speed beyond that level. Maybe I should try QWERTY on ErgoDox someday.

Level up

If you need to type at high speed for hours at a time, then you should probably follow Mirabai Knight and learn stenography. Beware: the learning curve for steno is steep and you need a steno machine (or for the first time you can use NKRO keyboard, e.g., ErgoDox).

Conclusion

Typing can be fun if you fix your bad typing habits. The earlier you start learning, the more rewarding it can be. Teach kids to touch type as soon as they start playing with the computer. This skill will stay relevant for at least one more generation.

If you want to take away only one thing from my story, it's this: Learn proper touch typing technique today.

Recipe

Take a typing test on Keyhero. Slower than 40 WPM? Practice 15 minutes every day for a month. If your accuracy is lower than 95%, slow down and try to type as accurately as possible.

If you type more than four hours every day, you should use an ergonomic keyboard.

See also

Typing with pleasure by Pavel Fating, Programming's dirtiest little secret by Steve Yegge, Norman layout by David Norman, My keyboard layout on GitHub

Looking for top-notch screencasts? You are on the right page.

I like watching screencasts better than reading books or documentation. Don't get me wrong, I love books and manual pages.

When it comes to learning a new programming language, to grasping complex abstractions, I prefer to start with screencasts. It's easier for me to learn from concrete examples narrated by an experienced programmer. Learning should not be mind-bending all the time.

Another thing I appreciate about screencasts is that they give me a chance to see industry leaders working with their tools. By looking at someone else's screen you can make accidental discoveries and learn about tools and techniques you never knew existed, one little thing at a time.

All the screencasts listed on this page are well made and cover everything you need to know as a professional programmer: from command line tools and text editors to advanced programming practices and lambda calculus.

Destroy All Software by Gary Bernhardt
computation, OOP, Unix, Rails, Python, TDD, Vim

Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf
JavaScript, FP

Building Web Apps with Elm by Mike and Nicole Clark
Elm

Developing With Elixir/OTP by Mike and Nicole Clark
Elixir

Vim Videos by Derek Wyatt
Vim

Vim Casts by Drew Neil
Vim, VimScript, Unix

Classroom Coding with Prof. Frisby by Brian Lonsdorf
JavaScript, FP

Hardcore Functional Programming in JavaScript by Brian Lonsdorf
JavaScript, FP

Elmseeds by Erik Person
Elm

DailyDrips by Josh Adams
Elixir, Elm, HTML, CSS, Ember, React Native, R

ElmLive by Aaron VonderHaar
Elm

KnowThen by James Moore
Elm, React, Go, RethinkDB

Learn Elixir by Daniel Berkompas
Elixir

Learn Phoenix by Daniel Berkompas
Elixir, Phoenix

Take off with Elixir by Rob Conery
Elixir, Phoenix

Lambda Island by Arne Brasseur
Clojure, Emacs

Hack Emacs by Rick Dillon
Emacs

React for Beginners by Wes Bos
React, Firebase

Redux by Dan Abramov
React, Redux

Peer to Peer by Drew Neil
Ruby, JavaScript, Haskell

Evented Mind by Chris Mather
JavaScript, React, Meteor, Node.js, git

Mijingo by Ryan Irelan
CMS, Git, HTML, CSS, Python, Jekyll

Jekyll Tips by CloudCannon
Jekyll, MacOS

Sysadmin Casts by Justin Weissig
AWS, Unix, Vagrant, Ansible, Puppet

CSS Tricks by Chris Coyier
CSS

Test-Driven JavaScript by James Shore
JavaScript

.Emacs Tutorials by Chris Forno
Emacs

Emacs Rocks by Magnar Sveen
Emacs

Parens of the dead by Magnar Sveen
Clojure

GoRails by Chris Oliver
Rails

RubyTapas by Avdi Grimm
Ruby

Talk Python Training by Michael Kennedy
Python, MongoDB, Pyramid, REST, SQL

NSScreencast by Ben Scheirman
iOS, Swift, Objective-C, Xcode

Level Up Tutorials by Scott Tolinski
Meteor, React, Angular, Drupal, WordPress, Magento, Sketch, Sass, Stylus, PostCSS, Java

Neckbeard Republic by Mahdi Yusuf
Python

EmberSchool by Jeffrey Biles
Ember

EmberScreencasts by Jeffrey Biles
Ember, JavaScript

Handmade Hero by Casey Muratori
C++, Win32

Brackeys by Asbjørn Thirslund
C#, JavaScript, Unity

Game Development Tutorials by Sebastian Lague
Unity, C#

Drifting Ruby by Dave Kimura
Rails, JavaScript

Schools and Stores

Egghead
Angular, React, Elm, JavaScript, RxJs, Node.js, D3

Upcase
Rails, Vim, JavaScript, Unix, Ruby, OOP/FP, Git

Frontend Masters

Pluralsights

Ray Wenderlich
Swift, iOS, Android, macOS, Apple Game Frameworks, Unity

Linux Academy
Linux, AWS, Azure, OpenStack, DevOps, BigData

Caster IO
Android, RxJava, Material Design, Espresso

Laracasts
PHP, Laravel, testing, JavaScript, tooling, HTML

Packt
Swift, Python, JavaScript, Java, and many more

See also Udemy, Udacity, Treehouse, Coursera, Envato Tuts+, and Codeacademy.

I recently worked on pagination for a web app. This simple problem is a good case study for comparing JavaScript and Elm.

Here's the use case:

We have a current page address, for example index, and a list of all the page addresses: index, vanilla, ramda, elm.

There are two links, Previous and Next. By clicking on those links you go to the previous or the next page accordingly.

When you're on the first page, the Previous link is disabled. When you're on the last page, Next is disabled.

              current page
                  |
                  |
[ Previous ]    index    vanilla    ramda    elm    [ Next ]
     |
     |
disabled link

Let's write two functions—one to prepare a data structure and another to generate HTML code based on it.

The paginate() function

This function takes a current page and a list of pages. It returns a tuple of previous, next. Both elements of the tuple can be empty.

The html() function

This function takes the result of paginate() and returns an HTML string containing links to the next and previous pages. It handles cases when a current page is not found, or either of the previous or next links is missing.

// List of pages
pages = ['index', 'vanilla', 'ramda', 'elm']

// There should be no Previous page
paginate('index', pages);
// => [undefined, 'vanilla']

html(paginate('index', pages));
// => 'No previous<a href="vanilla">Next</a>'

// Both links are available
html(paginate('vanilla', pages));
// => '<a href="index">Previous</a><a href="ramda">Next</a>'

// Non-existent page
html(paginate('pageX', pages));
// => 'Current not found'

To start with, let's implement this in vanilla JavaScript.

Vanilla JavaScript

We'll start with a plain JavaScript implementation; to be specific, ECMAScript 5. Then we'll see what we can improve.

How can we implement paginate() in JavaScript? First, get the index of the current page in the array of pages. If current is found, then get its neighbors and return an array of [previous, next]; otherwise, return nothing.

Implementing html() is pretty straightforward: get that array and render it to a string.

Naïve implementation in ECMAScript 5.

var pages = ['index', 'vanilla', 'ramda', 'elm'];
var current = 'vanilla';

var paginate = function(current, pages) {

  // Get index of current page
  // in array of pages
  var i = pages.indexOf(current);

  // If current page is found
  // (index is not -1)
  return i !== -1
    ? ([ pages[i - 1], // Previous page
        pages[i + 1]  // Next page
      ])
    // else return undefined
    : undefined;
}

var html = function(pagination) {
  if (pagination === undefined) return 'Current not found';

  var previous =
    pagination[0] === undefined
      ? 'No previous'
      : ('<a href="' + pagination[0] + '">Previous</a>');

  var next =
    pagination[1] === undefined
      ? 'No next'
      : ('<a href="' + pagination[1] + '">Next</a>');

  return (previous + next);
}

Now we can test our functions.

pages = ['index', 'vanilla', 'ramda', 'elm']
// => '["index", "vanilla", "ramda", "elm"]'

current = 'vanilla'
// => "vanilla"

paginate(current, pages)
// => ["index", "ramda"]

html(paginate(current, pages))
// => "<a href=\"index\">Previous</a><a href=\"ramda\">Next</a>"

How can we improve it?

First, those undefined values look suspicious. Just take a look at the edge case, when previous is undefined:

paginate('index', pages)
// => [undefined, "vanilla"]

We need some safer data types.

Second, those if and else statements are a problem. It is possible to forget something and accidentally miss a case.

We need a better way to branch our code.

Built with Ramda

Before we dive in into our implementation, let's get familiar with Ramda, a functional library for JavaScript.

If you haven't tried functional programming before, it may look unusual, but it's totally worth learning. It is consistently simple, backed by math, and fun to learn.

Ramda

Ramda helps us to write code in a purer functional style. It's a small library, has no dependencies, and works in all browsers as well as Node.

var numbers = [10, 20, 30, 40];
var inc = function (x) { return (x + 1); }

Compare the native map...

numbers.map(inc)
// => [11, 21, 31, 41]

... with Ramda's:

R.map(inc, numbers)
// => [11, 21, 31, 41]

It doesn't look that different at the beginning... but it's only the beginning.

How does map() work? It takes a function and a functor (e.g., array, string, or object), applies the function to each of the functor's values, and returns a functor of the same shape.

R.map(inc, {a: 100, b: 200})
// => {"a": 101, "b": 201}

R.map(inc, {a: 'a', b: 'b'})
// => {"a": "a1", "b": "b1"}

R.map(inc, 'abc')
// => ["a1", "b1", "c1"]

What happens when you pass fewer parameters than the function expects? Usually JavaScript functions are not happy:

numbers.map()
// => TypeError: Array.prototype.map callback must be a function

Now look at the Ramda function:

R.map()
// => function n(r,e){switch(arguments.length){case 0:return n;case 1:return b(r)?n:L(function(n){return t(r,n)});default:return b(r)&&b(e)?n:b(r)?L(function(n){return t(n,e)}):b(e)?L(function(n){return t(r,n)}):t(r,e)}}

That's right --- it returns a function. If there were no parameters passed, it returns itself. Just double checking:

R.map
// => function n(r,e){switch(arguments.length){case 0:return n;case 1:return b(r)?n:L(function(n){return t(r,n)});default:return b(r)&&b(e)?n:b(r)?L(function(n){return t(n,e)}):b(e)?L(function(n){return t(r,n)}):t(r,e)}}

What if you pass one parameter instead of two?

incAll = R.map(inc)
// => function n(r){return 0===arguments.length||b(r)?n:t.apply(this,arguments)}

It returns a partially applied function.

All Ramda functions are automatically curried and work this way. A curried function can take only a subset of its parameters and return a new function that takes the remaining parameters. If you call a curried function with all of its parameters, it just calls the function and returns a value.

So all of the following expressions return the same result:

incAll(numbers)
// => [11, 21, 31, 41]

R.map(inc, numbers)
// => [11, 21, 31, 41]

R.map(inc)(numbers)
// => [11, 21, 31, 41]

R.map()(inc)(numbers)
// => [11, 21, 31, 41]

Note that in most Ramda functions the data is supplied as the last parameter, to make it convenient for currying.

By the way, Ramda has R.inc() and R.dec() already.

R.map(R.dec)(numbers)
// => [9, 19, 29, 39]

Probably the simplest Ramda function is R.identity(). It does nothing but return the parameter supplied to it, so it's good as a placeholder function. We will use it in the example.

R.map(R.identity)(numbers)
// => [10, 20, 30, 40]

The next two function names speak for themselves: R.head() returns the first element of the array.

R.head(numbers)
// => 10

R.last() returns the last element of the array.

R.last(numbers)
// => 40

The last function you need to learn for now is R.concat().

R.concat(numbers, 50)
// => [10, 20, 30, 40, 50]

I am glad you got this far! Finally, we are at the point where we can get rid of undefined. There is a library for this. :)

Sanctuary

Sanctuary is a functional programming library. It depends on and works nicely with Ramda.

Let's compare what two indexOf functions return when the element is not found in the array:

R.indexOf(42, numbers)
// => -1

-1? Okay. Kind of weird, but familiar. Now look at Sanctuary's version:

S.indexOf(42, numbers)
// => Nothing()

It returns a value of Maybe type. Maybe is useful for composing functions that might not return a value.

Here's one more example of a function which returns Maybe.

S.at() takes an index and a list and returns Just the element of the list at the index, if the index is within the list's bounds...

S.at(1, numbers)
// => Just(20)

... and returns Nothing otherwise.

S.at(100, numbers)
// => Nothing()

Compare it with the native JavaScript alternative:

numbers[100]
// => undefined

Okay, sounds like we can get rid of undefined. But how should we handle Maybe values? To apply functions to Maybe values you can use old good map:

R.map(R.inc, S.Just(3))
// => Just(4)

R.map(R.inc, S.Nothing())
// => Nothing()

But what about branching code without using conditionals? In our case, we have two branches, left and right.

pagination[2] === undefined
  ? 'No next'                                     // Left
  : ('<a href="' + pagination[2] + '">Next</a>'); // Right

To handle it, we can convert Maybe to Either. What is Either? The Either type represents values with two possibilities, Left and Right.

S.maybeToEither('No next', S.Just(3))
// => Right(3)

S.maybeToEither('No next', S.Nothing())
// => Left("No next")

Now we can apply two different functions to Left and Right.

When the third parameter is Left, then R.identity() is applied to 'No next'. Let's hard-code the third parameter to test S.either.

S.either(R.identity, R.toString, S.Left('No next'))
// => "No next"

When the third parameter is Right, then R.toString() is applied to 3. The third parameter is hard-coded again.

S.either(R.identity, R.toString, S.Right(3))
// => "3"

Congratulations! Now you are ready to read the refactored solution. ;)

Implementation with Ramda and Sanctuary

// var R = require('ramda');
// var S = require('sanctuary');

var pages = ['index', 'vanilla', 'ramda', 'elm'];
var current = 'ramda';

var paginate = function(current, pages) {

  return R.map(
    function(index) {
      return [
        S.at(R.dec(index), pages),
        S.at(R.inc(index), pages)
      ]
    },
    // Gets index of the current page
    S.indexOf(current, pages)
  )
}

var html = function(pagination) {

  var previous =
    function(url) {
      return ('<a href="' + url + '">Previous</a>');
    }

  var next =
    function(url) {
      return ('<a href="' + url + '">Next</a>');
    }

  var buttons = function(x) {
    return R.concat(
      S.either(
        R.identity,
        previous,
        S.maybeToEither('No previous', R.head(x))
      ),
      S.either(
        R.identity,
        next,
        S.maybeToEither('No next', R.last(x))
      )
    )
  }

  return S.either(
    R.identity,
    buttons,
    S.maybeToEither('Current not found', pagination)
  )
}

Let's test it.

pages = ['index', 'vanilla', 'ramda', 'elm']
// => ["index", "vanilla", "ramda", "elm"]

current = 'ramda'
// => "ramda"

paginate('ramda', pages)
// => Just([Just("vanilla"), Just("elm")])

html(paginate('ramda', pages))
// => "<a href=\"vanilla\">Previous</a><a href=\"elm\">Next</a>"

What can we improve?

Syntax. It is getting pretty lengthy and noisy. ECMAScript 2015 solves this partially.

const paginate = (current, pages) => R.map(
  (i) => R.map(
    S.at(R.dec(i), pages),
    S.at(R.inc(i), pages)
  ), S.indexOf(current, pages)
)

By the way, here's our vanilla version in ECMAScript 2015.

const paginate = (current, pages) => {
  const i = pages.indexOf(current);
  return i !== -1
    ? [pages[i - 1], pages[i + 1]]
    : undefined;
}

Another problem with our solution is that html() returns a string. It would be good to have DOM elements instead. To manipulate the DOM we can use one of the Virtual DOM libraries or frameworks, like React, Angular, Ember, or Vue.

If we're looking for a lighter and purely functional solution, Elm is a better option.

Built with Elm

I have been playing with Elm for several months and find it fascinating: Helpful error messages. If it compiles, it works; no runtime errors; good performance; clean syntax; simple refactoring, and so on.

Writing in Elm

Create a file, say pagination.elm. If you are using any modules, you have to import them explicitly.

For this implementation in Elm I'm using the List type for the list of pages. To get value by index, we use getAt() and to get index by value, we use elemIndex(). Both functions are from the List.Extra module; let's import it.

List.Extra

List.Extra.getAt 3 pages
-- Just "elm"

We can use the exposing keyword to import particular functions of the module, and then call them without a qualifier.

import List.Extra exposing (getAt, elemIndex)

getAt 3 pages
-- Just "elm"

elemIndex "elm" pages
-- Just 3

As you can see, you don't need brackets in these function calls, just the function name and a list of its parameters.

To define a function you just type in a function name, then a list of its parameters, then the = sign, and finally its definition.

inc x = x + 1

inc 1
-- 2

You can define local functions inside a function with the let ... in keywords.

current = "ramda"

isCurrent page =
    let
        current = "elm"
    in
        page == current

isCurrent "elm"
-- True

To handle cases you can use the case ... of keywords, which is useful for pattern matching. The important difference with Elm is that its compiler won't let you forget to cover cases, and will make sure all branches return values of the same shape.

get index pages =
    case index of
        Just i ->
            "Index is " ++ i

        Nothing ->
            "No index"

You've probably noticed that for summing numbers in Elm we use +, but to concatenate strings we need ++.

Our function paginate() returns a tuple, which is a data type in Elm. Here's the syntax.

pagination = (Just "elm", Nothing)

Oh, the Maybe type is in the Elm core library, so you don't need to import it.

HTML elements are functions of the Html module. To create a link --- HTML element <A> --- you need to call the function Html.a with two parameters: list of attributes and list of children.

Html.a [ Html.Attributes.href "ramda" ] [ Html.text "Previous" ]

As you can guess, href is a function from the Html.Attributes module, and text is a function from the Html module.

That's it. You know enough Elm to read the code:

import Html exposing (div, text, a)
import Html.Attributes exposing (href)
import List.Extra exposing (getAt, elemIndex)


pages =
    [ "index", "vanilla", "ramda", "elm" ]


current =
    "elm"


paginate current pages =
    case (elemIndex current pages) of
        Just i ->
            ( (getAt (i - 1) pages), (getAt (i + 1) pages) )

        _ ->
            ( Nothing, Nothing )


html pagination =
    let
        next page =
            case page of
                Just url ->
                    a [ href url ] [ text "Next" ]

                Nothing ->
                    text "No next"

        previous page =
            case page of
                Just url ->
                    a [ href url ] [ text "Previous" ]

                Nothing ->
                    text "No previous"
    in
        case pagination of
            ( Nothing, Nothing ) ->
                text "Current not found"

            ( p, n ) ->
                div [] [ previous p, next n ]


main =
    html (paginate current pages)

Epilogue

You may ask, what's the point of adding lines of code and introducing new libraries and weird data types --- even a new language! Doesn't it complicate everything?

First, type safety helps you to avoid runtime errors and catch mistakes earlier. Second, pure functions are much simpler to understand, to maintain, and to refactor. Third, in most cases composability and point-free style make your code much cleaner.

If you're building a small web app and file size is critical, then nothing can beat vanilla JavaScript, of course. However, when your app grows, Ramda or Elm can save you from mistakes and make your developer experience much better.

You'd still better know JavaScript equality quirks, how to manipulate the DOM directly, how to manage scope, how to avoid mutable state, how to handle null, etc.

If JavaScript is so weird, why should we learn it? Because 3 billion people use web browsers and JavaScript is the only scripting language natively supported by most web browsers today. JavaScript is getting better, but it won't be changed dramatically anytime soon.

Bonus track

Thank you for reading this far! Here's another implementation with the Elm core library only. You can copy-paste it to Elm REPL and play with it.

import Html
import List

pages = [ "index", "vanilla", "ramda", "elm" ]
current = "elm"

paginate current pages =
  let
      cs = pages |> List.map Just
      ns = List.drop 1 cs ++ [ Nothing ]
      ps = Nothing :: List.take (List.length cs - 1) cs
      isCurrent (p, c, n) =
          case c == Just current of
              True -> Just (p, n)
              False -> Nothing
  in
    List.map3 (\p c n -> ( p, c, n )) ps cs ns
      |> List.filterMap isCurrent

main =
    paginate current pages
        |> toString
        |> Html.text
        -- Just (Just "ramda", Just "elm", Nothing)

See also

An Introduction to Elm by Evan Czaplicki,
Type Signatures by Scott Sauyet,
Functors, Applicatives, And Monads In Pictures by Aditya Bhargava,
Thinking in Ramda by Randy Coulman,
Professor Frisby's Mostly Adequate Guide to FP by Brian Lonsdorf,
Functional-Light JavaScript by Kyle Simpson,
Awesome FP JavaScript

Edit text with TextEdit.app

Usually I type my words into vi, but today I'm composing this page in TextEdit.app.

TextEdit.app is pre-installed on every Mac and supports plain text. To start using it for plain text files, set these defaults.

• First, open TextEdit.app,
• press ⌘, to open Preferences,
• switch Format to Plain text.

Note: You can also adjust the default font and size by clicking on Change beside Plain text font.

You can always adjust the font size in the current window with ⌘+ and ⌘-.

Optionally, go to Preferences > Open and Save. Check When Opening a File to Display HTML files as HTML code instead of formatted text.

Now you can close the TextEdit window and open a new one in plain text.

You can write some prose in TextEdit, but editing long texts, especially across multiple files, is inefficient. Frankly, I switched to Vim to edit this page as soon as the first draft was complete.

Plain text is awesome!

As soon as you figure out what and how to write, you need to publish what you have written. You have many options. Start with a standalone website.

You can post your writing on social media sites. Those sites have huge audiences, most of the people you want to reach are already there, you just sign in and start writing, and it is "free". But you give up all your rights at the moment of posting. You give up your content and your audience from the beginning. You have no control over page URLs, which makes it hard to transfer your content out of the platform. Your posts may be censored and your account can be banned. You cannot know which of your posts will appear in your followers' feeds. You do not decide how your pages look. You cannot remove ads, or change colors or fonts. When a platform dies, all your hard work disappears. You do not own your website.

A slightly better option is to use one of the blogging platforms: Medium, Svbtle, Tumblr, WordPress, etc. You have control over your page content. You can set up a custom domain and have some control over page URLs. But you are tied to a platform and its software --- it's painful to transfer your content out.

What does it mean to own your website? You need to fully control your domain, your content (rights, URLs, styles, markup, etc) the communication channels to your readers (emails and comments).

So if you're serious about publishing, should you make everything from scratch? Fortunately, you don't have to create the universe to make your own website.

Try GitHub Pages.

Keeping a website is time-consuming, your site may remain obscure, your pages will become outdated, and eventually you'll probably quit writing anyway. So why bother?

Because regular writing helps you to learn things deeper, helps you to spread your ideas, and helps your readers learn faster too—or at least have some fun.

There are many other means of communication nowadays, but writing is one of the most powerful, accessible, and scalable. Words are magical. You can write something today and people might read your words years later. Almost anyone can download your pages and read them. Even over a slow internet connection, on a slow computer, with a small screen: Nothing can stop your words. The number of your readers is unlimited, and the delivery cost is close to zero (less than one US dollar for a million page views).

You may say that writing is hard. Yes, it is hard, especially if you are writing in a foreign language, but with practice your writing will get better and the act of writing will become much more enjoyable.

What to write about?

Probably the first question you'll ask yourself is, what should I write about? You might say you definitely have nothing special to say, all your thoughts are obvious and all your stories are boring. But something that is obvious to you is not always obvious to other people, and something that is boring to you might be fascinating to someone from a different culture or who is new to the topic.

Tell a story about a project you are working on. It can be useful or entertaining, or both. It can be about a thing you made this week or a thing you learned today. You can write about how and what you are doing, and why you are doing it. What problems you are solving, how you pick and configure your tools, and so on.

In my case, today's story is about restarting this website and writing the first post. Way too meta? True.

If you want to make your website useful, make your pages actionable. Each of your posts can be a step-by-step instruction, a recipe. Start with small, simple pages and add depth gradually.

After choosing your topic, the next hard thing is to keep writing. To make your new hobby sustainable it is wise to build a writing habit—and most importantly, a publishing habit, or you may end up with hundreds of unpublished drafts. To fight your perfectionism set up a schedule: collect notes during the week (or better tweet as you go) and then on weekend repackage those notes into a structured page to publish it on Monday.

Just keep going.