shell2http.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "SHELL2HTTP" "" "April 2024" "" ""
HTTP\-server designed to execute shell commands\. It is suitable for development, prototyping or remote control, facilitates rapid iteration and testing of shell\-based functionalities\. Easy to set up using just two command\-line arguments: URL\-path and shell command\. Next, when an HTTP request is made for the specified path, the stdout of the shell script will be returned, that\'s all\.
.
.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
    \-form\-check       : regexp for check form fields (pass only vars that match the regexp)
    \-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)
    \-500              : return 500 error if shell exit code != 0
    \-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
With \fB\-form\-check\fR option you can specify the regular expression for checking the form fields\. For example, if you want to allow only variables that contain the only digits, you can specify the following option: \fB\-form\-check=\'^[0\-9]+$\'\fR\. Then only requests like \fBhttp://localhost:8080/path?NNN=123\fR will be produce variable \fB$v_NNN\fR\.
.
.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 install msoap/tools/shell2http
# update:
brew upgrade shell2http
.
.fi
.
.IP "" 0
.
.P
Download binaries from: releases \fIhttps://github\.com/msoap/shell2http/releases/latest\fR (MacOS/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
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
\fINotice\fR: 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 and commands may not work as expected or not work at all\.
.
.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
.
.P
Compile for MIPS CPU (for example, for some WiFi routers like Asus):
.
.IP "" 4
.
.nf

GOOS=linux GOARCH=mipsle GOMIPS=softfloat go build \-trimpath \-ldflags="\-w \-s" \-o 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