1ba11afccSDag-Erling Smørgrav FreeBSD maintainer's guide to OpenSSH-portable 2ba11afccSDag-Erling Smørgrav ============================================== 3ba11afccSDag-Erling Smørgrav 474c59ab7SEd Maste These instructions assume you have a clone of the FreeBSD git repo 574c59ab7SEd Maste main branch in src/freebsd/main, and will store vendor trees under 674c59ab7SEd Maste src/freebsd/vendor/. In addition, this assumes there is a "freebsd" 774c59ab7SEd Maste origin pointing to git(repo).freebsd.org/src.git. 874c59ab7SEd Maste 9fca7ac55SEd Maste01) Make sure your mail spool has plenty of free space. It'll fill up 10ba11afccSDag-Erling Smørgrav pretty fast once you're done with this checklist. 11ba11afccSDag-Erling Smørgrav 12fca7ac55SEd Maste02) Download the latest OpenSSH-portable tarball and signature from 139fcda2f4SEd Maste OpenBSD (https://ftp.openbsd.org/pub/OpenBSD/OpenSSH/portable/). 14ba11afccSDag-Erling Smørgrav 15fca7ac55SEd Maste03) Verify the signature: 16ba11afccSDag-Erling Smørgrav 17cf783db1SDag-Erling Smørgrav $ gpg --verify openssh-X.YpZ.tar.gz.asc 181c71974bSDag-Erling Smørgrav 19fca7ac55SEd Maste04) Unpack the tarball in a suitable directory: 20ba11afccSDag-Erling Smørgrav 21cf783db1SDag-Erling Smørgrav $ tar xf openssh-X.YpZ.tar.gz 22e2fb0b2aSDag-Erling Smørgrav 23fca7ac55SEd Maste05) Copy to a vendor branch: 24ba11afccSDag-Erling Smørgrav 2574c59ab7SEd Maste $ cd src/freebsd/main 2674c59ab7SEd Maste $ git worktree add ../vendor/openssh freebsd/vendor/openssh 2774c59ab7SEd Maste $ cd ../vendor/openssh 2874c59ab7SEd Maste $ rsync --archive --delete --exclude=.git /path/to/openssh-X.YpZ/ ./ 29ba11afccSDag-Erling Smørgrav 30fca7ac55SEd Maste06) Take care of added / deleted files: 31ba11afccSDag-Erling Smørgrav 3274c59ab7SEd Maste $ git add -A 33ba11afccSDag-Erling Smørgrav 34fca7ac55SEd Maste07) Commit: 35ba11afccSDag-Erling Smørgrav 3674c59ab7SEd Maste $ git commit -m "Vendor import of OpenSSH X.YpZ" 37ba11afccSDag-Erling Smørgrav 38fca7ac55SEd Maste08) Tag: 39ba11afccSDag-Erling Smørgrav 4074c59ab7SEd Maste $ git tag -a -m "Tag OpenSSH X.YpZ" vendor/openssh/X.YpZ 41ba11afccSDag-Erling Smørgrav 42576b477bSEd Maste At this point the vendor branch can be pushed to the FreeBSD repo via: 43576b477bSEd Maste 44576b477bSEd Maste $ git push freebsd vendor/openssh 45ab7d0959SEd Maste $ git push freebsd vendor/openssh/X.YpZ 46576b477bSEd Maste 47ab7d0959SEd Maste Note the second "git push" command is used to push the tag, which is 48ab7d0959SEd Maste not pushed by default. 49ab7d0959SEd Maste 50ab7d0959SEd Maste It is also possible to push the branch and tag together, but use 51ab7d0959SEd Maste --dry-run first to ensure that no undesired tags will be pushed: 52ab7d0959SEd Maste 53ab7d0959SEd Maste $ git push --dry-run --follow-tags freebsd vendor/openssh 54ab7d0959SEd Maste $ git push --follow-tags freebsd vendor/openssh 55ab7d0959SEd Maste 56ab7d0959SEd Maste The update and tag could instead be pushed later, along with the merge 57ab7d0959SEd Maste to main, but pushing now allows others to collaborate. 58576b477bSEd Maste 59cf783db1SDag-Erling Smørgrav09) Merge from the vendor branch: 60ba11afccSDag-Erling Smørgrav 6174c59ab7SEd Maste $ git subtree merge -P crypto/openssh vendor/openssh 62cf783db1SDag-Erling Smørgrav 6399b201c3SEd Maste A number of files have been deleted from FreeBSD's copy of ssh, 6499b201c3SEd Maste including rendered man pages (which have a .0 extension). When 6574c59ab7SEd Maste git prompts for these deleted files during the merge, choose 'd' 6699b201c3SEd Maste (leaving them deleted). 6799b201c3SEd Maste 68fca7ac55SEd Maste10) Resolve conflicts. Remember to bump the version addendum in 69c755a7ccSEd Maste version.h, and update the default value in sshd_config and 70c755a7ccSEd Maste sshd_config.5. 71cf783db1SDag-Erling Smørgrav 72fca7ac55SEd Maste11) Diff against the vendor branch: 73cf783db1SDag-Erling Smørgrav 7474c59ab7SEd Maste $ git diff --diff-filter=M vendor/openssh/X.YpZ HEAD:crypto/openssh 75cf783db1SDag-Erling Smørgrav 769b7eddfeSEd Maste Review the diff for any unexpected changes. 77cf783db1SDag-Erling Smørgrav 78fca7ac55SEd Maste12) Run the configure script: 79cf783db1SDag-Erling Smørgrav 806834ca8aSEd Maste $ cd crypto/openssh 81cf783db1SDag-Erling Smørgrav $ sh freebsd-configure.sh 82cf783db1SDag-Erling Smørgrav 83fca7ac55SEd Maste13) Review changes to config.h very carefully. 84cf783db1SDag-Erling Smørgrav 854c3ccd96SEd Maste Note that libwrap should not be defined in config.h; as of 8674c59ab7SEd Maste r311585 (233932cc2a60) it is conditional on MK_TCP_WRAPPERS. 874c3ccd96SEd Maste 88fca7ac55SEd Maste14) If source files have been added or removed, update the appropriate 89e66498cdSDag-Erling Smørgrav makefiles to reflect changes in the vendor's Makefile.in. 90ba11afccSDag-Erling Smørgrav 91fca7ac55SEd Maste15) Update ssh_namespace.h: 92ba11afccSDag-Erling Smørgrav 936834ca8aSEd Maste $ cd crypto/openssh 944f52dfbbSDag-Erling Smørgrav $ sh freebsd-namespace.sh 95e66498cdSDag-Erling Smørgrav 96fca7ac55SEd Maste16) Build and install world, reboot, test. Pay particular attention 97cf783db1SDag-Erling Smørgrav to pam_ssh(8), which gropes inside libssh and will break if 98cf783db1SDag-Erling Smørgrav something significant changes or if ssh_namespace.h is out of 99cf783db1SDag-Erling Smørgrav whack. 100cf783db1SDag-Erling Smørgrav 101fca7ac55SEd Maste17) Check for references to obsolete configuration options 1029340d69eSMark Johnston (e.g., ChallengeResponseAuthentication in sshd_config) which 1039340d69eSMark Johnston may exist in release/ scripts. 1049340d69eSMark Johnston 105fca7ac55SEd Maste18) Commit, and hunker down for the inevitable storm of complaints. 106ba11afccSDag-Erling Smørgrav 107ba11afccSDag-Erling Smørgrav 108ba11afccSDag-Erling Smørgrav 109ba11afccSDag-Erling Smørgrav An overview of FreeBSD changes to OpenSSH-portable 110ba11afccSDag-Erling Smørgrav ================================================== 111ba11afccSDag-Erling Smørgrav 112ba11afccSDag-Erling Smørgrav1) Modified server-side defaults 113ba11afccSDag-Erling Smørgrav 114ba11afccSDag-Erling Smørgrav We've modified some configuration defaults in sshd: 115ba11afccSDag-Erling Smørgrav 1160591b689SDag-Erling Smørgrav - UsePAM defaults to "yes". 117ba11afccSDag-Erling Smørgrav - PermitRootLogin defaults to "no". 1180591b689SDag-Erling Smørgrav - PasswordAuthentication defaults to "no". 1190591b689SDag-Erling Smørgrav - VersionAddendum defaults to "FreeBSD-YYYYMMDD". 120c4cd1fa4SDag-Erling Smørgrav - UseDNS defaults to "yes". 121ba11afccSDag-Erling Smørgrav 122ba11afccSDag-Erling Smørgrav2) Modified client-side defaults 123ba11afccSDag-Erling Smørgrav 124*9faa27f2SEd Maste We defaulted CheckHostIP to "no" in 2000 (a95c1225217b). Upstream has 125*9faa27f2SEd Maste now made the same change, and we no longer have any modified client-side 126*9faa27f2SEd Maste defaults. 127ba11afccSDag-Erling Smørgrav 128ba11afccSDag-Erling Smørgrav3) Canonic host names 129ba11afccSDag-Erling Smørgrav 130ba11afccSDag-Erling Smørgrav We've added code to ssh.c to canonicize the target host name after 131ba11afccSDag-Erling Smørgrav reading options but before trying to connect. This eliminates the 132ba11afccSDag-Erling Smørgrav usual problem with duplicate known_hosts entries. 133ba11afccSDag-Erling Smørgrav 134232b4f33SEd Maste We added this support in 2002 (r99054 / bf2e2524a2ce). In 2014 135232b4f33SEd Maste upstream introduced CanonicalDomains and related options to serve a 136232b4f33SEd Maste similar purpose but they require environment-specific configuration. 137232b4f33SEd Maste 138cb7b8027SDag-Erling Smørgrav4) setusercontext() environment 139ba11afccSDag-Erling Smørgrav 140ba11afccSDag-Erling Smørgrav Our setusercontext(3) can set environment variables, which we must 141ba11afccSDag-Erling Smørgrav take care to transfer to the child's environment. 142ba11afccSDag-Erling Smørgrav 1430591b689SDag-Erling Smørgrav5) TCP wrappers 1440591b689SDag-Erling Smørgrav 1450591b689SDag-Erling Smørgrav Support for TCP wrappers was removed in upstream 6.7p1. We've 1460591b689SDag-Erling Smørgrav added it back by porting the 6.6p1 code forward. 1470591b689SDag-Erling Smørgrav 148e491358cSEd Maste TCP wrappers support in sshd will be disabled in HEAD and will 149e491358cSEd Maste be removed from FreeBSD in the future. 150e491358cSEd Maste 1519ded3306SDag-Erling Smørgrav6) Agent client reference counting 1520591b689SDag-Erling Smørgrav 1530591b689SDag-Erling Smørgrav We've added code to ssh-agent.c to implement client reference 1540591b689SDag-Erling Smørgrav counting; the agent will automatically exit when the last client 1550591b689SDag-Erling Smørgrav disconnects. 1560591b689SDag-Erling Smørgrav 157f3fd8850SEd Maste7) Class-based login restrictions (27ceebbc2402) 1580591b689SDag-Erling Smørgrav 159f3fd8850SEd Maste We've added code to auth.c to enforce the host.allow, host.deny, 160f3fd8850SEd Maste times.allow and times.deny login class capabilities, based on an 161f3fd8850SEd Maste upstream submission from 162f3fd8850SEd Maste https://github.com/openssh/openssh-portable/pull/262. 16335a03425SEd Maste 1648974fa45SEd Maste8) Blocklist integration 1658974fa45SEd Maste 1668974fa45SEd Maste We include blocklist (https://github.com/zoulasc/blocklist) in FreeBSD, 1678974fa45SEd Maste and ssh is patched to report login failures to it. 1688974fa45SEd Maste 1698974fa45SEd Maste9) Paths 1708974fa45SEd Maste 1718974fa45SEd Maste A number of paths are changed to match FreeBSD's configuration (e.g., 1728974fa45SEd Maste using /usr/local/ instead of /uxr/X11R6/). 1738974fa45SEd Maste 174c888b3b2SEd Maste10) Memory leaks 175c888b3b2SEd Maste 176c888b3b2SEd Maste Coverity reported a memory leak for which we proposed a fix in 177c888b3b2SEd Maste https://reviews.freebsd.org/D37253 and sent to the upstream mailing list at 178c888b3b2SEd Maste https://lists.mindrot.org/pipermail/openssh-unix-dev/2022-November/040497.html 179c888b3b2SEd Maste 180c888b3b2SEd Maste Upstream subsequently fixed only one of the related leaks, so we reverted 181c888b3b2SEd Maste the partial fix and applied our change. 182c888b3b2SEd Maste 183c888b3b2SEd Maste11) Retired patches 1840591b689SDag-Erling Smørgrav 1856f7bc8e7SEd Maste We no longer have HPN patches (adaptive buffer size for increased 1866f7bc8e7SEd Maste throughput on high-BxD links) or client-side VersionAddendum, but we 1876f7bc8e7SEd Maste recognize and ignore the configuration options to avoid breaking 1886f7bc8e7SEd Maste existing configurations. 1890591b689SDag-Erling Smørgrav 190ba11afccSDag-Erling Smørgrav 191ba11afccSDag-Erling Smørgrav 192ba11afccSDag-Erling SmørgravThis port was brought to you by (in no particular order) DARPA, NAI 1930085282bSDag-Erling SmørgravLabs, ThinkSec, Nescafé, the Aberlour Glenlivet Distillery Co., 194ba11afccSDag-Erling SmørgravSuzanne Vega, and a Sanford's #69 Deluxe Marker. 195ba11afccSDag-Erling Smørgrav 196ba11afccSDag-Erling Smørgrav -- des@FreeBSD.org 197