200 lines
6.3 KiB
Plaintext
200 lines
6.3 KiB
Plaintext
FreeBSD maintainer's guide to OpenSSH-portable
|
||
==============================================
|
||
|
||
These instructions assume you have a clone of the FreeBSD git repo
|
||
main branch in src/freebsd/main, and will store vendor trees under
|
||
src/freebsd/vendor/. In addition, this assumes there is a "freebsd"
|
||
origin pointing to git(repo).freebsd.org/src.git.
|
||
|
||
00) Make sure your mail spool has plenty of free space. It'll fill up
|
||
pretty fast once you're done with this checklist.
|
||
|
||
01) Download the latest OpenSSH-portable tarball and signature from
|
||
OpenBSD (https://ftp.openbsd.org/pub/OpenBSD/OpenSSH/portable/).
|
||
|
||
02) Verify the signature:
|
||
|
||
$ gpg --verify openssh-X.YpZ.tar.gz.asc
|
||
|
||
03) Unpack the tarball in a suitable directory:
|
||
|
||
$ tar xf openssh-X.YpZ.tar.gz
|
||
|
||
04) Copy to a vendor branch:
|
||
|
||
$ cd src/freebsd/main
|
||
$ git worktree add ../vendor/openssh freebsd/vendor/openssh
|
||
$ cd ../vendor/openssh
|
||
$ rsync --archive --delete --exclude=.git /path/to/openssh-X.YpZ/ ./
|
||
|
||
05) Take care of added / deleted files:
|
||
|
||
$ git add -A
|
||
|
||
06) Commit:
|
||
|
||
$ git commit -m "Vendor import of OpenSSH X.YpZ"
|
||
|
||
07) Tag:
|
||
|
||
$ git tag -a -m "Tag OpenSSH X.YpZ" vendor/openssh/X.YpZ
|
||
|
||
At this point the vendor branch can be pushed to the FreeBSD repo via:
|
||
|
||
$ git push freebsd vendor/openssh
|
||
|
||
(It could also be pushed later on, along with the merge to main, but
|
||
pushing now allows others to collaborate.)
|
||
|
||
08) Check out head and run the pre-merge script, which strips our RCS
|
||
tags from files that have them:
|
||
|
||
$ cd src/freebsd/main/crypto/openssh
|
||
$ sh freebsd-pre-merge.sh
|
||
|
||
09) Merge from the vendor branch:
|
||
|
||
$ git subtree merge -P crypto/openssh vendor/openssh
|
||
|
||
A number of files have been deleted from FreeBSD's copy of ssh,
|
||
including rendered man pages (which have a .0 extension). When
|
||
git prompts for these deleted files during the merge, choose 'd'
|
||
(leaving them deleted).
|
||
|
||
0A) Resolve conflicts. Remember to bump the version addendum in
|
||
version.h, and update the default value in ssh{,d}_config and
|
||
ssh{,d}_config.5.
|
||
|
||
0B) Diff against the vendor branch:
|
||
|
||
$ git diff --diff-filter=M vendor/openssh/X.YpZ HEAD:crypto/openssh
|
||
|
||
Files that have modifications relative to the vendor code, and
|
||
only those files, must have the svn:keywords property set to
|
||
FreeBSD=%H and be listed in the 'keywords' file created by the
|
||
pre-merge script.
|
||
|
||
0C) Run the post-merge script, which re-adds RCS tags to files that
|
||
need them:
|
||
|
||
$ sh freebsd-post-merge.sh
|
||
|
||
These tags are not used with git, but we will leave them in place as
|
||
long as svn-based FreeBSD 11.x and 12.x are supported.
|
||
|
||
0D) Run the configure script:
|
||
|
||
$ sh freebsd-configure.sh
|
||
|
||
0E) Review changes to config.h very carefully.
|
||
|
||
Note that libwrap should not be defined in config.h; as of
|
||
r311585 (233932cc2a60) it is conditional on MK_TCP_WRAPPERS.
|
||
|
||
0F) If source files have been added or removed, update the appropriate
|
||
makefiles to reflect changes in the vendor's Makefile.in.
|
||
|
||
10) Update ssh_namespace.h:
|
||
|
||
$ sh freebsd-namespace.sh
|
||
|
||
11) Build and install world, reboot, test. Pay particular attention
|
||
to pam_ssh(8), which gropes inside libssh and will break if
|
||
something significant changes or if ssh_namespace.h is out of
|
||
whack.
|
||
|
||
12) Commit, and hunker down for the inevitable storm of complaints.
|
||
|
||
|
||
|
||
An overview of FreeBSD changes to OpenSSH-portable
|
||
==================================================
|
||
|
||
* don't free string returned by login_getcapstr(3)
|
||
|
||
Committed upstream as f060c2bc85d59d111fa18a12eb3872ee4b9f7e97
|
||
|
||
* Use login_getpwclass() instead of login_getclass()
|
||
|
||
Committed upstream as 3d05e5881ceb2e48e1948ba14292216b56ed792e
|
||
|
||
0) VersionAddendum
|
||
|
||
The SSH protocol allows for a human-readable version string of up
|
||
to 40 characters to be appended to the protocol version string.
|
||
FreeBSD takes advantage of this to include a date indicating the
|
||
"patch level", so people can easily determine whether their system
|
||
is vulnerable when an OpenSSH advisory goes out. Some people,
|
||
however, dislike advertising their patch level in the protocol
|
||
handshake, so we've added a VersionAddendum configuration variable
|
||
to allow them to change or disable it. Upstream added support for
|
||
VersionAddendum on the server side, but we also support it on the
|
||
client side.
|
||
|
||
1) Modified server-side defaults
|
||
|
||
We've modified some configuration defaults in sshd:
|
||
|
||
- UsePAM defaults to "yes".
|
||
- PermitRootLogin defaults to "no".
|
||
- X11Forwarding defaults to "yes".
|
||
- PasswordAuthentication defaults to "no".
|
||
- VersionAddendum defaults to "FreeBSD-YYYYMMDD".
|
||
- PrivilegeSeparation defaults to "sandbox".
|
||
- UseDNS defaults to "yes".
|
||
|
||
2) Modified client-side defaults
|
||
|
||
We've modified some configuration defaults in ssh:
|
||
|
||
- CheckHostIP defaults to "no".
|
||
- VerifyHostKeyDNS defaults to "yes" if built with LDNS.
|
||
- VersionAddendum defaults to "FreeBSD-YYYYMMDD".
|
||
|
||
3) Canonic host names
|
||
|
||
We've added code to ssh.c to canonicize the target host name after
|
||
reading options but before trying to connect. This eliminates the
|
||
usual problem with duplicate known_hosts entries.
|
||
|
||
4) setusercontext() environment
|
||
|
||
Our setusercontext(3) can set environment variables, which we must
|
||
take care to transfer to the child's environment.
|
||
|
||
5) TCP wrappers
|
||
|
||
Support for TCP wrappers was removed in upstream 6.7p1. We've
|
||
added it back by porting the 6.6p1 code forward.
|
||
|
||
TCP wrappers support in sshd will be disabled in HEAD and will
|
||
be removed from FreeBSD in the future.
|
||
|
||
6) Agent client reference counting
|
||
|
||
We've added code to ssh-agent.c to implement client reference
|
||
counting; the agent will automatically exit when the last client
|
||
disconnects.
|
||
|
||
7) Class-based login restrictions
|
||
|
||
We've added code to auth2.c to enforce the host.allow, host.deny,
|
||
times.allow and times.deny login class capabilities.
|
||
|
||
8) HPN
|
||
|
||
We no longer have the HPN patches (adaptive buffer size for
|
||
increased throughput on high-BxD links), but we recognize and
|
||
ignore HPN-related configuration options to avoid breaking existing
|
||
configurations.
|
||
|
||
|
||
|
||
This port was brought to you by (in no particular order) DARPA, NAI
|
||
Labs, ThinkSec, Nescafé, the Aberlour Glenlivet Distillery Co.,
|
||
Suzanne Vega, and a Sanford's #69 Deluxe Marker.
|
||
|
||
-- des@FreeBSD.org
|
||
|
||
$FreeBSD$
|