diff options
-rw-r--r-- | README | 37 |
1 files changed, 37 insertions, 0 deletions
@@ -0,0 +1,37 @@ +Fshare is a simple Python-based HTTP server for personal ad-hoc file sharing. You upload files in the form of HTTP PUT +or POST requests and it returns a URL through which the file contents can be retrieved. + +Fshare has two modes of operation: private (the default) and public. In the private mode, the generated URLs are +a HMAC computed from server's private key (which it generates on the first run) and the file contents. They should thus +be unguessable as long as the server's key remains secret, and so can be used for sharing confidential information - +only someone in possession of the URL can access the data. + +In the public mode (activated by the -P switch), the generated URLs are short and easy to remember - and therefore also +easy to guess. This mode is useful for sharing non-sensitive data. + +Fshare works only with plain HTTP and does no limiting or authentication - anyone can upload data as they wish. In a +typical setup it should be deployed behind a gateway such as Nginx, that will handle TLS, authentication, request size +limits, etc. + +Fshare should be run as an executable Python script. It takes two mandatory arguments - the state dir and the data dir. +The state dir contains server runtime data (such as the abovementioned private key), the data dir will contain the +actual uploaded files. + +The data from a PUT/POST request is stored exactly as it was received. E.g. using curl one can upload files with + $ curl --data-binary '@<filename>' https://<server location>/pic.jpg +The server will reply with a URL like + https://<server location>/081c5e45316f0c65e945edc4622a8173451d4a808648f5e310ced8a7e079ffdf/pic.jpg +in the private mode or + https://<server location>/f2.jpg +in the public mode. The data can be retrieved with a HTTP GET request for this URL. + +In GET requests, fshare only looks at the basename (i.e. stripping the extension, if any) of the first path component of +the request location. You can thus add/change the extenion, add further arbitrary path components, or otherwise modify +it as you wish. As long as the first component is unchanged, the same data will be returned. + +In PUT/POST requests, the request location is appended to the generated URL (in the public mode, only the extension of +the last path component is used). As per the previous paragraph, this is done for convenience only and may be changed at +will. Requests with an empty location will work as well, then the returned URL will be just the HMAC in the private mode +and have no extension in the public mode. + +Fshare is distributed under the GNU AGPL licence. |