shell2http.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "SHELL2HTTP" "" "October 2021" "" ""
HTTP\-server to execute shell commands\. Designed for development, prototyping or remote control\. Settings through two command line arguments, path and shell command\. By default bind to :8080\.
.
.SH "Usage"
.
.nf

shell2http [options] /path "shell command" /path2 "shell command2" \.\.\.
options:
    \-host="host"      : host IP for http server (default bind to all interfaces)
    \-port=NNNN        : port for http server, 0 \- to receive a random port (default 8080)
    \-form             : parse query into environment vars, handle uploaded files
    \-cgi              : run scripts in CGI\-mode:
                        \- set environment variables with HTTP\-request information
                        \- write POST|PUT|PATCH\-data to script STDIN (if is not set \-form)
                        \- parse headers from script (eg: "Location: URL\en\en")
    \-export\-vars=var  : export environment vars ("VAR1,VAR2,\.\.\.")
                        by default export PATH, HOME, LANG, USER, TMPDIR
    \-export\-all\-vars  : export all current environment vars
    \-no\-index         : don\'t generate index page
    \-add\-exit         : add /exit command
    \-log=filename     : log filename, default \- STDOUT
    \-shell="shell"    : shell for execute command, "" \- without shell (default "sh")
    \-cache=N          : caching command out for N seconds
    \-one\-thread       : run each shell command in one thread
    \-show\-errors      : show the standard output even if the command exits with a non\-zero exit code
    \-include\-stderr   : include stderr to output (default is stdout only)
    \-cert=cert\.pem    : SSL certificate path (if specified \-cert/\-key options \- run https server)
    \-key=key\.pem      : SSL private key path
    \-basic\-auth=""    : setup HTTP Basic Authentication ("user_name:password"), can be used several times
    \-timeout=N        : set timeout for execute shell command (in seconds)
    \-no\-log\-timestamp : log output without timestamps
    \-version
    \-help
.
.fi
.
.P
In the \fB\-form\fR mode, variables are available for shell scripts:
.
.IP "\(bu" 4
$v_NNN \-\- data from query parameter with name "NNN" (example: \fBhttp://localhost:8080/path?NNN=123\fR)
.
.IP "\(bu" 4
$filepath_ID \-\- uploaded file path, ID \- id from \fB<input type=file name=ID>\fR, temporary uploaded file will be automatically deleted
.
.IP "\(bu" 4
$filename_ID \-\- uploaded file name from browser
.
.IP "" 0
.
.P
To setup multiple auth users, you can specify the \fB\-basic\-auth\fR option multiple times\. The credentials for basic authentication may also be provided via the \fBSH_BASIC_AUTH\fR environment variable\. You can specify the preferred HTTP\-method (via \fBMETHOD:\fR prefix for path): \fBshell2http GET:/date date\fR
.
.SH "Install"
MacOS:
.
.IP "" 4
.
.nf

brew tap msoap/tools
brew install shell2http
# update:
brew upgrade shell2http
.
.fi
.
.IP "" 0
.
.P
Using snap (Ubuntu or any Linux distribution with snap):
.
.IP "" 4
.
.nf

# install stable version:
sudo snap install shell2http

# install the latest version:
sudo snap install \-\-edge shell2http

# update
sudo snap refresh shell2http
.
.fi
.
.IP "" 0
.
.P
Notice: the snap\-package has its own sandbox with the \fB/bin\fR, \fB/usr/bin\fR directories which are not equal to system\-wide \fBPATH\fR directories\.
.
.P
Download binaries from: releases \fIhttps://github\.com/msoap/shell2http/releases/latest\fR (OS X/Linux/Windows/RaspberryPi)
.
.P
For Docker users, availeble tags see in Docker Hub \fIhttps://hub\.docker\.com/r/msoap/shell2http\fR:
.
.IP "" 4
.
.nf

docker pull msoap/shell2http
.
.fi
.
.IP "" 0
.
.P
Build from source (minimum Go version is 1\.12):
.
.IP "" 4
.
.nf

go install github\.com/msoap/shell2http@latest
# set link to your PATH if needed:
ln \-s $(go env GOPATH)/bin/shell2http ~/bin/shell2http
.
.fi
.
.IP "" 0
.
.SH "Examples"
.
.nf

shell2http /top "top \-l 1 | head \-10"
shell2http /date date /ps "ps aux"
shell2http \-export\-all\-vars /env \'printenv | sort\' /env/path \'echo $PATH\' /env/gopath \'echo $GOPATH\'
shell2http \-export\-all\-vars /shell_vars_json \'perl \-MJSON \-E "say to_json(\e%ENV)"\'
shell2http \-export\-vars=GOPATH /get \'echo $GOPATH\'
.
.fi
.
.SS "HTML calendar for current year"
.
.nf

shell2http /cal_html \'echo "<html><body><h1>Calendar</h1>Date: <b>$(date)</b><br><pre>$(cal $(date +%Y))</pre></body></html>"\'
.
.fi
.
.P
.
.SS "Get URL parameters (http://localhost:8080/form?from=10&to=100)"
.
.nf

shell2http \-form /form \'echo $v_from, $v_to\'
.
.fi
.
.P
.
.SS "CGI scripts"
.
.nf

shell2http \-cgi /user_agent \'echo $HTTP_USER_AGENT\'
shell2http \-cgi /set \'touch file; echo "Location: /another_path\en"\' # redirect
shell2http \-cgi /404 \'echo "Status: 404"; echo; echo "404 page"\' # custom HTTP code
.
.fi
.
.P
.
.SS "Upload file"
.
.nf

shell2http \-form \e
    GET:/form \'echo "<html><body><form method=POST action=/file enctype=multipart/form\-data><input type=file name=uplfile><input type=submit></form>"\' \e
    POST:/file \'cat $filepath_uplfile > uploaded_file\.dat; echo Ok\'
.
.fi
.
.P
Testing upload file with curl:
.
.IP "" 4
.
.nf

curl \-i \-F uplfile=@some/file/path \'http://localhost:8080/file\'
.
.fi
.
.IP "" 0
.
.P
.
.SS "Simple http\-proxy server (for logging all URLs)"
Setup proxy as "http://localhost:8080/"
.
.IP "" 4
.
.nf

shell2http \-log=/dev/null \-cgi / \'echo $REQUEST_URI 1>&2; [ "$REQUEST_METHOD" == "POST" ] && post_param="\-d@\-"; curl \-sL $post_param "$REQUEST_URI" \-A "$HTTP_USER_AGENT"\'
.
.fi
.
.IP "" 0
.
.P
.
.SS "Test slow connection (http://localhost:8080/slow?duration=10)"
.
.nf

shell2http \-form /slow \'sleep ${v_duration:\-1}; echo "sleep ${v_duration:\-1} seconds"\'
.
.fi
.
.P
.
.SS "Proxy with cache in files (for debug with production API with rate limit)"
get \fBhttp://api\.url/\fR as \fBhttp://localhost:8080/get?url=http://api\.url/\fR
.
.IP "" 4
.
.nf

shell2http \-form \e
    /form \'echo "<html><form action=/get>URL: <input name=url><input type=submit>"\' \e
    /get \'MD5=$(printf "%s" $v_url | md5); cat cache_$MD5 || (curl \-sL $v_url | tee cache_$MD5)\'
.
.fi
.
.IP "" 0
.
.P
.
.SS "Remote sound volume control (Mac OS)"
.
.nf

shell2http /get  \'osascript \-e "output volume of (get volume settings)"\' \e
           /up   \'osascript \-e "set volume output volume (($(osascript \-e "output volume of (get volume settings)")+10))"\' \e
           /down \'osascript \-e "set volume output volume (($(osascript \-e "output volume of (get volume settings)")\-10))"\'
.
.fi
.
.P
.
.SS "Remote control for Vox\.app player (Mac OS)"
.
.nf

shell2http /play_pause \'osascript \-e "tell application \e"Vox\e" to playpause" && echo ok\' \e
           /get_info \'osascript \-e "tell application \e"Vox\e"" \-e "\e"Artist: \e" & artist & \e"\en\e" & \e"Album: \e" & album & \e"\en\e" & \e"Track: \e" & track" \-e "end tell"\'
.
.fi
.
.P
.
.SS "Get four random OS X wallpapers"
.
.nf

shell2http /img \'cat "$(ls "/Library/Desktop Pictures/"*\.jpg | ruby \-e "puts STDIN\.readlines\.shuffle[0]")"\' \e
           /wallpapers \'echo "<html><h3>OS X Wallpapers</h3>"; seq 4 | xargs \-I@ echo "<img src=/img?@ width=500>"\'
.
.fi
.
.P
.
.SS "Mock service with JSON API"
.
.nf

curl "http://some\-service/v1/call1" > 1\.json
shell2http \-cgi /call1 \'cat 1\.json\' /call2 \'echo "Content\-Type: application/json\en"; echo "{\e"error\e": \e"ok\e"}"\'
.
.fi
.
.P
.
.SS "Windows example"
Returns value of \fBvar\fR for run in Windows \fBcmd\fR (\fBhttp://localhost:8080/test?var=value123\fR)
.
.IP "" 4
.
.nf

shell2http\.exe \-form /test "echo %v_var%"
.
.fi
.
.IP "" 0
.
.P
.
.SS "With HTTP headers"
Send custom HTTP headers:
.
.IP "" 4
.
.nf

shell2http \-cgi / \'echo "Content\-Type: application/javascript\en"; echo "{\e"error\e": \e"ok\e"}"\'
.
.fi
.
.IP "" 0
.
.P
On Windows:
.
.IP "" 4
.
.nf

shell2http\.exe \-cgi / "echo Content\-Type: application/javascript& echo\.& echo body"
.
.fi
.
.IP "" 0
.
.P
.
.SH "Run from Docker\-container"
Example of \fBtest\.Dockerfile\fR for server for get current date:
.
.IP "" 4
.
.nf

FROM msoap/shell2http
# may be install some alpine packages:
# RUN apk add \-\-no\-cache \.\.\.
CMD ["/date", "date"]
.
.fi
.
.IP "" 0
.
.P
Build and run container:
.
.IP "" 4
.
.nf

docker build \-f test\.Dockerfile \-t date\-server \.
docker run \-\-rm \-p 8080:8080 date\-server
.
.fi
.
.IP "" 0
.
.SH "SSL"
Run https server:
.
.IP "" 4
.
.nf

shell2http \-cert=\./cert\.pem \-key=\./key\.pem \.\.\.
.
.fi
.
.IP "" 0
.
.P
Generate self\-signed certificate:
.
.IP "" 4
.
.nf

go run $(go env GOROOT)/src/crypto/tls/generate_cert\.go \-host localhost
.
.fi
.
.IP "" 0
.
.SH "See also"
.
.IP "\(bu" 4
Create Telegram bot from command\-line \- shell2telegram \fIhttps://github\.com/msoap/shell2telegram\fR
.
.IP "\(bu" 4
A http daemon for local development \- devd \fIhttps://github\.com/cortesi/devd\fR
.
.IP "\(bu" 4
Turn any program that uses STDIN/STDOUT into a WebSocket server \- websocketd \fIhttps://github\.com/joewalnes/websocketd\fR
.
.IP "\(bu" 4
The same tool configurable via JSON \- webhook \fIhttps://github\.com/adnanh/webhook\fR
.
.IP "" 0