|Sebastian Kippe 7c170384a4 Add git to list of dependencies in README||4 years ago|
|auth||5 years ago|
|lib||5 years ago|
|scripts||5 years ago|
|src||5 years ago|
|test||5 years ago|
|tools||5 years ago|
|.gitignore||5 years ago|
|.gitmodules||5 years ago|
|CHANGELOG||5 years ago|
|COPYING||5 years ago|
|LICENSE||5 years ago|
|Makefile||5 years ago|
|README.md||4 years ago|
|TODO||5 years ago|
|init-script-defaults||5 years ago|
|init-script.sh||5 years ago|
|package.json||5 years ago|
A remoteStorage server implementation for POSIX systems.
remoteStorage is an open specification for personal data storage. It is supposed to replace the currently popular proprietary "cloud storage" protocols using an open standard and thereby promoting the seperation of applications and their data on the web.
For more information, check out these links:
rs-serve brings 3 things:
The user management is taken care of by the system. Each system user with an
allowed user id (default: >= 1000. Minimum defined by
src/config.h) can access their
~/storage/ directory (configurable via
--dir option) using the remoteStorage endpoint.
rs-serve is written entirely in C, using mostly POSIX library functions. It relies on a few portable libraries (see the list under "Dependencies" below).
It does however currently use the
signalfd() system call, which is only
available on Linux. (this is a solvable problem though, if you want to
be able to run on another system, please open an issue to ask for help.)
The currently implemented protocol version is "draft-dejong-remotestorage-01".
Currently the following features are supported:
/public/), such that requests on non-directory paths succeed without authorization.
Content-Lengthheader (not part of remotestorage-01, only enabled when
--experimentalflag is given)
The Webfinger implementation only serves information about remoteStorage and is currently not extensible.
The hostname part of user addresses is expected to be the hostname set for
the rs-serve instance. This currently defaults to
local.dev and can be
overridden with the
Virtual hosting (== hosting storage for multiple domains from a single instance) is currently not supported.
rs-serve now comes with an authorization backend and frontend, supporting the implicit bearer flow as described by OAuth 2. Authentication happens through PAM, so you can use any authentication backend supported by PAM (such as passwd/shadow files, LDAP, SQL...).
You can do this by running:
To start the server run
It runs on port 8888 by default, you can change this by tweaking the auth/backend/server.js file. Note that you also need to configure the backend URL in auth/frontend/app.js.
The frontend part is an unhosted web app (i.e. completely client side), so you can use any webserver to serve it. However, for simplicity the backend server will also automatically serve all files from auth/frontend/.
Once you got that all running, set the
--auth-uri option of rs-serve to point
to where you're serving the frontend, e.g.
Note that while the remotestorage server itself needs to run on port 80, the authorization frontend and backend can run on any port you like.
The payload data of the remotestorage endpoint is stored on the local filesystem within the respective user's home directory.
Thus a few restrictions apply:
The remotestorage endpoint cannot be used to store both a directory and a file
under the same path (ignoring the trailing slash). That means you cannot store
/foo/bar, but only one of them. This is a natural restriction
of traditional filesystems, that is currently well adhered to by all apps using
remotestorage (as far as I know).
MIME types may not be exact for files that were added "out-of-band", that is
not added via the remoteStorage protocol, but by copying to the
directory by other means. rs-serve stores MIME type and character encoding
user.charset extended attributes, given these
are supported by the underlying filesystem. When these attributes aren't set,
a MIME type is guessed using libmagic, which may not always yield desirable
results. (for example an empty file, created using
touch will be transmitted
via remoteStorage with a Content-Type header of
If even libmagic fails to make sense of a file, the
Content-Type is set to
These steps should enable you to install rs-serve.
On Debian based systems, this should give you all you need:
apt-get install build-essential cmake libevent-dev libmagic-dev libattr1-dev libssl-dev libdb-dev pkg-config git
If you want to develop, you may also want debug symbols and valgrind (required by leakcheck.sh script):
apt-get install libevent-dbg valgrind
Given you are reading this file, you probably have the code already, but just to be sure:
Currently the rs-serve code is hosted on GitHub.
You can browse it online at https://github.com/remotestorage/rs-serve or clone it using git:
git clone git://github.com/remotestorage/rs-serve.git
Given you have all dependencies installed, simply run
and you should be good to go.
To install the rs-serve binary to
as a privileged user.
To install somewhere else, tweak the Makefile first.
This will also install an init script to
/etc/init.d/rs-serve and a default
On Debian based systems (i.e. when
update-rc.d is present),
will also install the rs-serve init script into
There are a variety of options.
If you want to use the init script, you can set options in
otherwise just pass them on the command line.
to get a list of supported options.
To integrate an authorization endpoint, you need to do two things:
--auth-uri option to a printf style format string.
%s will be
replaced with the username.
rs-serve doesn't care where tokens come from, but it need to know them to decide whether a given request is authorized or not. It maintains an internal store for authorizations (i.e. structures of [user-name, token, scopes]), which must be managed from the outside.
The tools to do this are:
Usage: rs-add-token <user> <token> <scope1> [<scope2> ... <scopeN>]
<user>is the login name of the user (rs-serve must be able to resolve it using getpwnam() in order to find the home directory)
<token>is the token string authenticating future requests. For rs-serve it is an opaque string.
<scope1>..<scopeN>are scope strings in the same form as described in draft-dejong-remotestorage-01, Section 9.
Usage: rs-remove-token <user> <token>
<token> must both be given. If the token cannot be found,
rs-remove-token terminates with non-zero status.
Lists all currently installed tokens and their respective scopes.
The output format is primarily meant for (human) debugging and subject to change.
If you've found a bug, or have any questions, please open an issue on GitHub: https://github.com/remotestoage/rs-serve/issues
If you want to contribute, fork the project on GitHub and send pull requests.
In any case, don't hesitate to talk with us on IRC: #remotestorage and #unhosted, both on irc.freenode.org