README ¶
Share
Have you ever wanted to share some files with a buddy on your LAN, and had to go through all sorts of hassle to get that working? Or perhaps you wonder what it would be like to actually use git as a distributed version control system?
Share is a simple cli binary that will create a file server in the current directory so that you can share your files, and close down the server quickly.
Install
To install make sure you have go installed, then it's as easy as getting this library:
go get github.com/murphysean/share
I've only tested share on ubuntu linux 64. I'd be happy if any contributors would like to verify or expand this to other platforms.
Run
Sharing
Let's say you have some code you want to show your buddy in your workspace:
cd workspace/code
share
This will spin up a file server in that directory and tell you how your buddy can connect. For example:
Serving http on:
host Prometheus:43959
wlan0 192.168.1.14:43959
Notice that if you don't specify anything share
will use a system assigned port in the high
port range. Perhaps you'd like to use a specific port:
share -p 8080
Then there are times where you'd like to serve a particular directory on the same port every
time you fire it up. Share looks for a configuration file in the directory to be served, and
also in your home directory. If you create .share
in the directory with the following
contents:
SHARE_HTTP_PORT=8080
SHARE_USERNAME=user
SHARE_PASSWORD=password
Whenever you run share
in that directory share will run on port 8080 (if available) and
require authentication before serving content.
Share also comes with a 'smart' git server built in. So others can git clone, fetch, and pull
using the same http(s) address that they can use to browse. After you git init
your directory
others could clone your repository like so:
git clone http://host:port/
And finally you can change the directory you wish to share (default is the current directory)
share ../someotherdir
share /home/sean
Receiving
Sharing your files is only half the fun. Sometimes you'd really like your cohorts to contribute something back to your directory. With a 'smart' git server built in if they had previously cloned from you they can push there changes back with git. For example to push a branch back up to the server they could:
git push -u origin shinynewbranch
However sometimes you'd really just like to receive that handy little script from your mate.
Share has a built in web-page that allows someone to use an html form to upload files. Just
navigate to http(s)://yourip:port/upload.html
, select a file, and upload it.
Share also allows POST, PUT and DELETE verbs. So for the curl guys out there:
-
Form upload files (POST)
curl --form "file=@filename.txt" http(s)://host:port/
-
Upload file bytes (POST)
curl --data "file=@filename.txt" -H "Content-Type: text/plain" http(s)://host:port/
-
Put up a file (PUT)
curl -X PUT --data @filename.txt http(s)://host:port/filename.txt
-
Delete a file on the server (DELETE)
curl -X DELETE http(s)://host:port/filename.txt
The POST call will work on any directory path (Path ends with a /) even if the directory does not yet exist. The PUT verb will work on any file (Path doesn't end with a /) even if the path doesn't exist yet. Finally the DELETE verb will work on any file or directory as long as it isn't the root directory.
Authentication
Share allows you to protect your directory through http basic authorization. Since share allows clients to both pull (GET, HEAD), and push (POST, PUT, PATCH, DELETE), share allows you to control access for both of these operations. Setting the -username and -password flags will enable protection for both pulling and pushing clients. It will force them to use those credentials.
If you also set the -push-username and -push-password flags, the credentials for pulling clients will remain those set for -username and -password, but will require pushing clients to use the push credentials.
Finally if you only set the -push-* credentials, pulling clients will not be required to authenticate, but pushing clients will.
Examples:
share -username sean -password sean
will require both pushing and pulling clients to authenticate with sean:sean.share -username -password sean -push-username git -push-password git
will require pushing clients to use sean:sean, and pulling clients to use git:gitshare push-username git -push-password git
will allow anyone to download or fetch files from share, but will require pushing clients to authenticate with git:git
In curl you can enable basic authentication using the -u flag. For example:
curl -u sean:sean http(s)://host:port/filename.txt
. In wget you can enable basic authentication
by using the --username
and --password
flags. For example:
wget http(s)://host:port/filename.txt --user=sean --password=sean
.
TLS/SSL and enabling secure communication to share
If you want to enable https communication to share all you'll need is to get ahold of a certificate file and a key file. The easiest way is to create a rsa key, and a self signed cert:
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
You'll want to put these files somewhere that won't be shared through share, otherwise your private key used to secure traffic could be compromised.
The recommended option is to create a .share file in your home directory along with your cert.pem and your key.pem files. In the share file put the full path to the cert.pem and key.pem files as the attributes to the environment variable keys. It will look something like this:
SHARE_CERT_PATH=/home/sean/cert.pem
SHARE_KEY_PATH=/home/sean/key.pem
Finally you'll just want to start share up with the -https
command line flag, or the SHARE_HTTPS_PORT
environment variable set. You can specify the port as 0 to just have share nab a system assigned port.
If you are lucky enough to have a certificate signed by a trusted certificate authority and a valid signing chain then clients will trust you and you'll get the nice green lock in most browsers. However if you are just sharing over ip addresses or hostnames on a local network you'll run into problems with https validation in both browsers and clients.
The easiest solution to this problem is to just have those browsing your share to click the bypass
button in their browser and "proceed unsafely". You can also do the equivalent in curl using the -k
or --insecure
flag. In wget, there is the --no-check-certificate
flag.
Another solution is to have your buddy add your self signed cert to their certificate store, thus trusting any connections to your server from any client using the trust store. On ubuntu this link will detail how to do this. Just make sure you are setting the common name to the domain name, hostname or ip address of your box.
Configuration
Share looks for configuration in a number of places as it starts up:
- The command line flags
- Environment variables
- A .share file in the share directory
- A .share file in the users home directory
- A share.conf file at /etc/share/share.conf
Configuration settings found at the lower numbers will override those found at the higher numbers. Options [3-5] are basic .ini type configuration files. The keys match the environment variable keys, and all start with SHARE_*. Certificates, keys, usernames and passwords are all good options to keep in config that will not be available through the share directory itself.
Usage
Type share help
to get this information on the command line.
Usage of share v1.1.0:
share [-h] [-p|-http <http-port>] [-https <https-port>]
[-cert <path-to-pem>] [-key <path-to-pem>]
[-username <username>] [-password <password>]
[-push-username <username>] [-push-password <password>]
[directory path|'help']
-http="0": Specify the listening port for HTTP traffic. 0 = system assigned.
-p="0": Short version of http port
-https="": Specify the listening port for HTTPS traffic. 0 = system assigned.
-cert="cert.pem": Specify the path to the cert file
-key="key.pem": Specify the path to the key file
-username="": Set a required username for requesting clients
-password="": Set a required password for requesting clients
-push-username="": Set a required username for clients pushing or uploading
-push-password="": Set a required password for clients pushing or uploading
As an alternative to flags, use the environment variables
SHARE_HTTP_PORT
SHARE_HTTPS_PORT
SHARE_CERT_PATH
SHARE_KEY_PATH
SHARE_USERNAME
SHARE_PASSWORD
SHARE_PUSH_USERNAME
SHARE_PUSH_PASSWORD
You can also keep these environment variables in a file called
.share in your home directory, and/or the directory in which
you plan to run share to persist the configuration.
Want to serve via https? Create your certificate:
---
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
---
Put them in a directory other than the one you are sharing
Use the -key and -cert command line flags to tell share where they are
Start share and specify an https port using the options above
To Serve a git repository directory over http:
mv hooks/post-update.sample hooks/post-update
chmod a+x hooks/post-update
git update-server-info
Running
Share logs to both stdout and stderr. Here's a breakdown of where information goes:
- Errors -> stderr
- Information -> stderr
- Access Logs -> stdout
Start share and only show errors and startup information:
share > /dev/null
Start share and only show access logs (in apache format):
share 2> /dev/null
Start share and direct all output to a file logs.txt:
share > logs.txt 2>&1
You can also run share in the background:
share > logs.txt 2>&1 &
Or have the shell disown the process:
share > logs.txt 2>&1 & disown
Or run it as a daemon:
nohup share > logs.txt 2>&1 &
Documentation ¶
There is no documentation for this package.