From 5de397a876b587ba05a9169237deffdc71f273b0 Mon Sep 17 00:00:00 2001 From: Damien Miller Date: Fri, 5 Apr 2019 11:29:51 -0700 Subject: [PATCH] second thoughts: leave README in place A number of contrib/* files refer to the existing README so let's leave it in place for release and add the new markdown version in parallel. I'll get rid of README after release. --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 000000000..4e2624161 --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +# Portable OpenSSH + +OpenSSH is a complete implementation of the SSH protocol (version 2) for secure remote login, command execution and file transfer. It includes a client ``ssh`` and server ``sshd``, file transfer utilities ``scp`` and ``sftp`` as well as tools for key generation (``ssh-keygen``), run-time key storage (``ssh-agent``) and a number of supporting programs. + +This is a port of OpenBSD's [OpenSSH](https://openssh.com) to most Unix-like operating systems, including Linux, OS X and Cygwin. Portable OpenSSH polyfills OpenBSD APIs that are not available elsewhere, adds sshd sandboxing for more operating systems and includes support for OS-native authentication and auditing (e.g. using PAM). + +## Documentation + +The official documentation for OpenSSH are the man pages for each tool: + +* [ssh(1)](https://man.openbsd.org/ssh.1) +* [sshd(8)](https://man.openbsd.org/sshd.8) +* [ssh-keygen(1)](https://man.openbsd.org/ssh-keygen.1) +* [ssh-agent(1)](https://man.openbsd.org/ssh-agent.1) +* [scp(1)](https://man.openbsd.org/scp.1) +* [sftp(1)](https://man.openbsd.org/sftp.1) +* [ssh-keyscan(8)](https://man.openbsd.org/ssh-keyscan.8) +* [sftp-server(8)](https://man.openbsd.org/sftp-server.8) + +## Stable Releases + +Stable release tarballs are available from a number of [download mirrors](https://www.openssh.com/portable.html#downloads). We recommend the use of a stable release for most users. Please read the [release notes](https://www.openssh.com/releasenotes.html) for details of recent changes and potential incompatibilities. + +## Building Portable OpenSSH + +### Dependencies + +Portable OpenSSH is built using autoconf and make. It requires a working C compiler, standard library and headers, as well as [zlib](https://www.zlib.net/) and ``libcrypto`` from either [LibreSSL](https://www.libressl.org/) or [OpenSSL](https://www.openssl.org) to build. Certain platforms and build-time options may require additional dependencies. + +### Building a release + +Releases include a pre-built copy of the ``configure`` script and may be built using: + +``` +tar zxvf openssh-X.Y.tar.gz +cd openssh +./configure # [options] +make && make tests +``` + +See the [Build-time Customisation](#build-time-customisation) section below for configure options. If you plan on installing OpenSSH to your system, then you will usually want to specify destination paths. + +### Building from git + +If building from git, you'll need [autoconf](https://www.gnu.org/software/autoconf/) installed to build the ``configure`` script. The following commands will check out and build portable OpenSSH from git: + +``` +git clone https://github.com/openssh/openssh-portable # or https://anongit.mindrot.org/openssh.git +cd openssh-portable +autoreconf +./configure +make && make tests +``` + +### Build-time Customisation + +There are many build-time customisation options available. All Autoconf destination path flags (e.g. ``--prefix``) are supported (and are usually required if you want to install OpenSSH). + +For a full list of available flags, run ``configure --help`` but a few of the more frequently-used ones are described below. Some of these flags will require additional libraries and/or headers be installed. + +Flag | Meaning +--- | --- +``--with-pam`` | Enable [PAM](https://en.wikipedia.org/wiki/Pluggable_authentication_module) support. [OpenPAM](https://www.openpam.org/), [Linux PAM](http://www.linux-pam.org/) and Solaris PAM are supported. +``--with-libedit`` | Enable [libedit](https://www.thrysoee.dk/editline/) support for sftp. +``--with-kerberos5`` | Enable Kerberos/GSSAPI support. Both [Heimdal](https://www.h5l.org/) and [MIT](https://web.mit.edu/kerberos/) Kerberos implementations are supported. +``--with-selinux`` | Enable [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) support. + +## Development + +Portable OpenSSH development is discussed on the [openssh-unix-dev mailing list](https://lists.mindrot.org/mailman/listinfo/openssh-unix-dev) ([archive mirror](https://marc.info/?l=openssh-unix-dev)). Bugs and feature requests are tracked on our [Bugzilla](https://bugzilla.mindrot.org/). + +## Reporting bugs + +_Non-security_ bugs may be reported to the developers via [Bugzilla](https://bugzilla.mindrot.org/) or via the mailing list above. Security bugs should be reported to [openssh@openssh.com](mailto:openssh.openssh.com).