1 FreeBSD maintainer's guide to OpenSSH-portable 2 ============================================== 3 4 These instructions assume you have a clone of the FreeBSD git repo 5 main branch in src/freebsd/main, and will store vendor trees under 6 src/freebsd/vendor/. In addition, this assumes there is a "freebsd" 7 origin pointing to git(repo).freebsd.org/src.git. 8 901) Make sure your mail spool has plenty of free space. It'll fill up 10 pretty fast once you're done with this checklist. 11 1202) Download the latest OpenSSH-portable tarball and signature from 13 OpenBSD (https://ftp.openbsd.org/pub/OpenBSD/OpenSSH/portable/). 14 1503) Verify the signature: 16 17 $ gpg --verify openssh-X.YpZ.tar.gz.asc 18 1904) Unpack the tarball in a suitable directory: 20 21 $ tar xf openssh-X.YpZ.tar.gz 22 2305) Copy to a vendor branch: 24 25 $ cd src/freebsd/main 26 $ git worktree add ../vendor/openssh freebsd/vendor/openssh 27 $ cd ../vendor/openssh 28 $ rsync --archive --delete --exclude=.git /path/to/openssh-X.YpZ/ ./ 29 3006) Take care of added / deleted files: 31 32 $ git add -A 33 3407) Commit: 35 36 $ git commit -m "Vendor import of OpenSSH X.YpZ" 37 3808) Tag: 39 40 $ git tag -a -m "Tag OpenSSH X.YpZ" vendor/openssh/X.YpZ 41 42 At this point the vendor branch can be pushed to the FreeBSD repo via: 43 44 $ git push freebsd vendor/openssh 45 $ git push freebsd vendor/openssh/X.YpZ 46 47 Note the second "git push" command is used to push the tag, which is 48 not pushed by default. 49 50 It is also possible to push the branch and tag together, but use 51 --dry-run first to ensure that no undesired tags will be pushed: 52 53 $ git push --dry-run --follow-tags freebsd vendor/openssh 54 $ git push --follow-tags freebsd vendor/openssh 55 56 The update and tag could instead be pushed later, along with the merge 57 to main, but pushing now allows others to collaborate. 58 5909) Merge from the vendor branch: 60 61 $ git subtree merge -P crypto/openssh vendor/openssh 62 63 A number of files have been deleted from FreeBSD's copy of ssh, 64 including rendered man pages (which have a .0 extension). When 65 git prompts for these deleted files during the merge, choose 'd' 66 (leaving them deleted). 67 6810) Resolve conflicts. Remember to bump the version addendum in 69 version.h, and update the default value in sshd_config and 70 sshd_config.5. 71 7211) Diff against the vendor branch: 73 74 $ git diff --diff-filter=M vendor/openssh/X.YpZ HEAD:crypto/openssh 75 76 Review the diff for any unexpected changes. 77 7812) Run the configure script: 79 80 $ cd crypto/openssh 81 $ sh freebsd-configure.sh 82 8313) Review changes to config.h very carefully. 84 85 Note that libwrap should not be defined in config.h; as of 86 r311585 (233932cc2a60) it is conditional on MK_TCP_WRAPPERS. 87 8814) If source files have been added or removed, update the appropriate 89 makefiles to reflect changes in the vendor's Makefile.in. 90 9115) Update ssh_namespace.h: 92 93 $ cd crypto/openssh 94 $ sh freebsd-namespace.sh 95 9616) Build and install world, reboot, test. Pay particular attention 97 to pam_ssh(8), which gropes inside libssh and will break if 98 something significant changes or if ssh_namespace.h is out of 99 whack. 100 10117) Check for references to obsolete configuration options 102 (e.g., ChallengeResponseAuthentication in sshd_config) which 103 may exist in release/ scripts. 104 10518) Commit, and hunker down for the inevitable storm of complaints. 106 107 108 109 An overview of FreeBSD changes to OpenSSH-portable 110 ================================================== 111 1121) Modified server-side defaults 113 114 We've modified some configuration defaults in sshd: 115 116 - UsePAM defaults to "yes". 117 - PermitRootLogin defaults to "no". 118 - PasswordAuthentication defaults to "no". 119 - VersionAddendum defaults to "FreeBSD-YYYYMMDD". 120 - UseDNS defaults to "yes". 121 1222) Modified client-side defaults 123 124 We defaulted CheckHostIP to "no" in 2000 (a95c1225217b). Upstream has 125 now made the same change, and we no longer have any modified client-side 126 defaults. 127 1283) Canonic host names 129 130 We've added code to ssh.c to canonicize the target host name after 131 reading options but before trying to connect. This eliminates the 132 usual problem with duplicate known_hosts entries. 133 134 We added this support in 2002 (r99054 / bf2e2524a2ce). In 2014 135 upstream introduced CanonicalDomains and related options to serve a 136 similar purpose but they require environment-specific configuration. 137 1384) setusercontext() environment 139 140 Our setusercontext(3) can set environment variables, which we must 141 take care to transfer to the child's environment. 142 1435) TCP wrappers 144 145 Support for TCP wrappers was removed in upstream 6.7p1. We've 146 added it back by porting the 6.6p1 code forward. 147 148 TCP wrappers support in sshd will be disabled in HEAD and will 149 be removed from FreeBSD in the future. 150 1516) Agent client reference counting 152 153 We've added code to ssh-agent.c to implement client reference 154 counting; the agent will automatically exit when the last client 155 disconnects. 156 1577) Class-based login restrictions (27ceebbc2402) 158 159 We've added code to auth.c to enforce the host.allow, host.deny, 160 times.allow and times.deny login class capabilities, based on an 161 upstream submission from 162 https://github.com/openssh/openssh-portable/pull/262. 163 1648) Blocklist integration 165 166 We include blocklist (https://github.com/zoulasc/blocklist) in FreeBSD, 167 and ssh is patched to report login failures to it. 168 1699) Paths 170 171 A number of paths are changed to match FreeBSD's configuration (e.g., 172 using /usr/local/ instead of /uxr/X11R6/). 173 17410) Memory leaks 175 176 Coverity reported a memory leak for which we proposed a fix in 177 https://reviews.freebsd.org/D37253 and sent to the upstream mailing list at 178 https://lists.mindrot.org/pipermail/openssh-unix-dev/2022-November/040497.html 179 180 Upstream subsequently fixed only one of the related leaks, so we reverted 181 the partial fix and applied our change. 182 18311) Retired patches 184 185 We no longer have HPN patches (adaptive buffer size for increased 186 throughput on high-BxD links) or client-side VersionAddendum, but we 187 recognize and ignore the configuration options to avoid breaking 188 existing configurations. 189 190 191 192This port was brought to you by (in no particular order) DARPA, NAI 193Labs, ThinkSec, Nescafé, the Aberlour Glenlivet Distillery Co., 194Suzanne Vega, and a Sanford's #69 Deluxe Marker. 195 196 -- des@FreeBSD.org 197