engineering/sshpiper
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README.md

Browse source
This commit is contained in:
Boshi Lian 2019-01-11 09:09:49 -08:00 • committed by GitHub
parent 9a328f567e
commit 3138ddab5f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

144
README.md
View file

@ -49,7 +49,7 @@ go get -u -tags pam github.com/tg123/sshpiper/sshpiperd
docker run farmer1992/sshpiperd
```
Run [:question: what is WORKING_DIR](#files-inside-working-dir)
Run with [Workding Dir upstream driver](sshpiperd/upstream/workingdir/README.md)
```
docker run -d -p 2222:2222 \
@ -57,6 +57,7 @@ docker run -d -p 2222:2222 \
-v /YOUR_WORKING_DIR:/var/sshpiper \
farmer1992/sshpiperd
```
Run with [Additional Challenge](#additional-challenge---challenger-driver)
use env `SSHPIPERD_CHALLENGER` to specify which challenger to use
@ -94,6 +95,9 @@ _NOTE:_
## Quick start
Just run `showme.sh` in [sshpiperd example directory](sshpiperd/example)
or
Copy paste command below to run
```
go get github.com/tg123/sshpiper/sshpiperd && `go env GOPATH`/src/github.com/tg123/sshpiper/sshpiperd/example/showme.sh
```
@ -123,113 +127,23 @@ Permission denied (publickey).
## Configuration
```
./sshpiperd daemon -h
sshpiperd:
-l, --listen= Listening Address (default: 0.0.0.0) [$SSHPIPERD_LISTENADDR]
-p, --port= Listening Port (default: 2222) [$SSHPIPERD_PORT]
-i, --server-key= Server key file for SSH Piper (default: /etc/ssh/ssh_host_rsa_key) [$SSHPIPERD_SERVER_KEY]
-u, --upstream-driver= Upstream provider driver (default: workingdir) [$SSHPIPERD_UPSTREAM_DRIVER]
-c, --challenger-driver= Additional challenger name, e.g. pam, empty for no additional challenge [$SSHPIPERD_CHALLENGER]
--auditor-driver= Auditor for ssh connections piped by SSH Piper [$SSHPIPERD_AUDITOR]
--log= LogFile path. Leave empty or any error occurs will fall back to stdout [$SSHPIPERD_LOG_PATH]
--log-flags= Flags for logger see https://godoc.org/log, default LstdFlags (default: 3) [$SSHPIPERD_LOG_FLAGS]
upstream.mysql:
--upstream-mysql-host= mysql host for driver (default: 127.0.0.1) [$SSHPIPERD_UPSTREAM_MYSQL_HOST]
--upstream-mysql-user= mysql user for driver (default: root) [$SSHPIPERD_UPSTREAM_MYSQL_USER]
--upstream-mysql-password= mysql password for driver [$SSHPIPERD_UPSTREAM_MYSQL_PASSWORD]
--upstream-mysql-port= mysql port for driver (default: 3306) [$SSHPIPERD_UPSTREAM_MYSQL_PORT]
--upstream-mysql-dbname= mysql dbname for driver (default: sshpiper) [$SSHPIPERD_UPSTREAM_MYSQL_DBNAME]
upstream.postgres:
--upstream-postgres-host= postgres host for driver (default: 127.0.0.1) [$SSHPIPERD_UPSTREAM_POSTGRES_HOST]
--upstream-postgres-user= postgres user for driver (default: postgres) [$SSHPIPERD_UPSTREAM_POSTGRES_USER]
--upstream-postgres-password= postgres password for driver [$SSHPIPERD_UPSTREAM_POSTGRES_PASSWORD]
--upstream-postgres-port= postgres port for driver (default: 5432) [$SSHPIPERD_UPSTREAM_POSTGRES_PORT]
--upstream-postgres-dbname= postgres dbname for driver (default: sshpiper) [$SSHPIPERD_UPSTREAM_POSTGRES_DBNAME]
--upstream-postgres-sslmode= postgres sslmode for driver (default: require) [$SSHPIPERD_UPSTREAM_POSTGRES_SSLMODE]
--upstream-postgres-sslcert= postgres sslcert for driver [$SSHPIPERD_UPSTREAM_POSTGRES_SSLCERT]
--upstream-postgres-sslkey= postgres sslkey for driver [$SSHPIPERD_UPSTREAM_POSTGRES_SSLKEY]
--upstream-postgres-sslrootcert= postgres sslrootcert for driver [$SSHPIPERD_UPSTREAM_POSTGRES_SSLROOTCERT]
upstream.sqlite:
--upstream-sqlite-dbfile= databasefile for sqlite (default: file:sshpiper.sqlite) [$SSHPIPERD_UPSTREAM_SQLITE_FILE]
upstream.workingdir:
--upstream-workingdir= Path to workingdir (default: /var/sshpiper) [$SSHPIPERD_UPSTREAM_WORKINGDIR]
--upstream-workingdir-allowbadusername Disable username check while search the working dir [$SSHPIPERD_UPSTREAM_WORKINGDIR_ALLOWBADUSERNAME]
--upstream-workingdir-nocheckperm Disable 0400 checking when using files in the working dir [$SSHPIPERD_UPSTREAM_WORKINGDIR_NOCHECKPERM]
--upstream-workingdir-fallbackusername= Fallback to a user when user does not exists in directory [$SSHPIPERD_UPSTREAM_WORKINGDIR_FALLBACKUSERNAME]
--upstream-workingdir-stricthostkey upstream host public key must in known_hosts file, otherwise drop the connection [$SSHPIPERD_UPSTREAM_WORKINGDIR_STRICTHOSTKEY]
challenger.welcometext:
--challenger-welcometext= Show a welcome text when connect to sshpiper server [$SSHPIPERD_CHALLENGER_WELCOMETEXT]
auditor.typescript-logger:
--auditor-typescriptlogger-outputdir= Place where logged typescript files were saved (default: /var/sshpiper) [$SSHPIPERD_AUDITOR_TYPESCRIPTLOGGER_OUTPUTDIR]
```
### Files inside `Working Dir`
`Working Dir` is a `/home`-like directory.
SSHPiperd read files from `workingdir/[username]/` to know upstream's configuration.
e.g.
```
workingdir tree
.
├── github
│   └── sshpiper_upstream
└── linode
└── sshpiper_upstream
```
when `ssh sshpiper_host -l github`,
sshpiper reads `workingdir/github/sshpiper_upstream` and the connect to the upstream.
#### User files
*These file MUST NOT be accessible to group or other. (chmod og-rwx filename)*
* sshpiper_upstream
* line starts with `#` are treated as comment
* only the first not comment line will be parsed
* if no port was given, 22 will be used as default
* if `user@` was defined, username to upstream will be the mapped one
```
# comment
[user@]upstream[:22]
```
```
e.g.
git@github.com
google.com:12345
```
* authorized_keys
OpenSSH format `authorized_keys` (see `~/.ssh/authorized_keys`). Used for `publickey sign again(see below)`.
* id_rsa
sshpiper provides 3 pluginable components to highly customize your piper
RSA key for `publickey sign again(see below)`.
* known_hosts
when `upstream-workingdir-stricthostkey` is set, upstream server's public key must present in known_hosts
* [Upstream Driver](#upstream-Driver---upstream-driver=))
* [Additional Challenge](#additional-challenge---challenger-driver)
* [Auditor](#auditor-for-pipes---auditor-driver)
### Upstream Driver (`--upstream-driver=`)
#### Publickey sign again
Upstream driver helps sshpiper to find which upstream host to connect and how to connect.
For example, you can change the username when connecting to upstream sshd by config upstream driver
#### [Workding Directory](sshpiperd/upstream/workingdir/README.md)
#### [Database Driver](sshpiperd/upstream/database/README.md)
#### How to do public key authentication when using sshpiper
During SSH publickey auth, [RFC 4252 Section 7](http://tools.ietf.org/html/rfc4252#section-7),
ssh client sign `session_id` and some other data using private key into a signature `sig`.
@ -282,12 +196,11 @@ now `ssh test@sshpiper -i -i PK_X`, sshpiper will send `PK_Y` to server instead
### Additional Challenge (`--challenger-driver=`)
ssh piper allows you run your own challenge before dialing to the upstream.
sshpiper allows you to add your own challenge before dialing to the upstream.
if a client failed in this challenge, connection will be closed.
however, the client has to pass the upstream server's auth in order to establish the whole connection.
`Additional Challenge` is required, but not enough.
This is useful when you want use publickey and something like [google-authenticator](https://github.com/google/google-authenticator) together. OpenSSH do not support use publickey and other auth together.
@ -306,10 +219,17 @@ This is useful when you want use publickey and something like [google-authentica
support azure ad device grant, more info
<https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code>
sshpier will ask user to login using webpage
```
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ****** to authenticate.
```
### SSH Session logging (`--auditor-driver=typescript-logger`)
### Auditor for pipes (`--auditor-driver=`)
#### SSH Session logging (`--auditor-driver=typescript-logger`)
When `record_typescript` is allowed, each piped connection would be recorded into [typescript](https://en.wikipedia.org/wiki/Script_(Unix)) in working_dir.
@ -331,11 +251,3 @@ This is useful when you want use publickey and something like [google-authentica
$ scriptreplay -t 1472847798.timing 1472847798.typescript # will replay the ssh session
```
## TODO List
* live upgrade
* hostbased auth support
* ssh-copy-id support or tools
* challenger: menu challenger
* sshpiperd: user@subhost@host support