xref: /freebsd/crypto/openssh/FREEBSD-upgrade (revision 9faa27f263d1b68cc1beb5a58e9ff2a80fa1e20e)
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