From 3138ddab5f131d681e2fcff7f346717a0f323881 Mon Sep 17 00:00:00 2001 From: Boshi Lian Date: Fri, 11 Jan 2019 09:09:49 -0800 Subject: [PATCH] Update README.md --- README.md | 144 +++++++++++------------------------------------------- 1 file changed, 28 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index 1a7a406f..5ccea91c 100644 --- a/README.md +++ b/README.md @@ -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 + 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