2 rs-serve - A remotestorage server implementation
3 ================================================
11 2.3 authorization tools
17 3.4 Installing system-wide
19 3.6 Integrating authorization
24 remotestorage is an open specification for personal data storage. It is supposed to
25 replace the currently popular proprietary "cloud storage" protocols using an open
26 standard and thereby promoting the seperation of applications and their data on the
29 For more information, check out these links:
30 * http://remotestorage.io/ - Information about the remotestorage protocol and
31 current implementations.
32 * http://unhosted.org/ - Philosophy, hands-on Tutorials and App collection.
37 rs-serve brings three things:
38 * a HTTP endpoint implementing remotestorage: /storage/{user}
39 * a HTTP endpoint implementing webfinger: /.well-known/webfinger
40 * a collection of scripts to manage authorizations: add/remove/list token(s)
42 The user management is taken care of by the system. Each system user with an allowed
43 user id (default: >= 1000. Minimum defined by RS_MIN_UID in src/config.h) can access
44 their ~/storage/ directory (configurable via --dir option) using the remotestorage
47 rs-serve is entirely written in C, using mostly POSIX library functions. It relies
48 on a few portable libraries, see the list under "Dependencies" below.
49 It does however currently use the signalfd() system call, which is only available
50 on Linux. (this is a solvable problem though, if you want to be able to run on
51 another system, please open an issue to ask for help)
56 The currently implemented protocol version is "draft-dejong-remotestorage-01".
58 Currently the following features are supported:
59 * CORS support for all verbs
60 * GET, PUT, DELETE requests on files and folders
61 * Opaque version strings (in directory listings and "ETag" header)
62 * Conditional GET, PUT and DELETE requests ("If-Match", "If-None-Match" headers)
63 * Protection of all non-public paths via Bearer token authorization.
64 * Special handling of public paths (i.e. those starting with /public/), such that
65 requests on non-directory paths succeed without authorization.
66 * HEAD requests on files and folders with "Content-Length" header
67 (not part of remotestorage-01, only enabled when --experimental flag is given)
72 The webfinger implementation only serves information about remotestorage and is
73 currently not extensible.
74 The hostname part of user addresses is expected to be the hostname set for the
75 rs-serve instance. This currently defaults to "local.dev" and can be overridden
76 with the --hostname option.
77 Virtual hosting (== hosting storage for multiple domains from a single instance)
78 is currently not supported.
80 2.3) authorization tools
81 ------------------------
83 Authorization has to be handled elsewhere. remotestorage-00 requires the storage
84 provider to bring an OAuth 2 endpoint that can do implicit grant flow.
85 This endpoint is not part of rs-serve for vague reasons.
87 In order to run a fully functional remotestorage provider, you must cook one up
88 yourself (TODO: add link to un.ht customer backend) and hook it up to rs-serve.
90 See the section titled "Integrating authorization" for details.
95 The payload data of the remotestorage endpoint is stored on the local filesystem
96 within the respective user's home directory.
98 Thus a few restrictions apply:
100 * The remotestorage endpoint cannot be used to store both a directory and a file
101 under the same path (ignoring the trailing slash). That means you cannot store
102 /foo/bar/baz and /foo/bar, but only one of them. This is a natural restriction
103 of traditional filesystems, that is currently well adhered to by all apps using
104 remotestorage (as far as I know).
106 * MIME types may not be exact for files that were added "out-of-band", that is
107 not added via the remotestorage protocol, but by copying to the ~/storage/
108 directory by other means. rs-serve stores MIME type and character encoding
109 under the "user.mime_type" and "user.charset" extended attributes, given these
110 are supported by the underlying filesystem. When these attributes aren't set,
111 a MIME type is guessed using libmagic, which may not always yield desirable
112 results. (for example an empty file, created using "touch" will be transmitted
113 via remotestorage with a Content-Type header of "inode/x-empty; charset=binary")
114 If even libmagic fails to make sense of a file, the Content-Type is set to
115 "application/octet-stream; charset=binary".
120 These steps should enable you to install rs-serve.
126 - pkg-config (or tweak the Makefile)
133 On Debian based systems, this should give you all you need:
135 apt-get install build-essential libevent-dev libmagic-dev libattr1-dev
137 If you want to develop, you may also want debug symbols and valgrind (required by
138 leakcheck.sh script):
140 apt-get install libevent-dbg valgrind
142 3.2) Getting the code
143 ---------------------
145 Given you are reading this file, you probably have the code already, but just to
148 Currently the rs-serve code is hosted on github.
150 You can browse it online, at:
152 https://github.com/remotestorage/rs-serve
154 or close it using git:
156 git clone git://github.com/remotestorage/rs-serve.git
161 Given you have all dependencies installed, simply run
165 and you should be good to go.
167 3.4) Installing system-wide
168 ---------------------------
170 To install the rs-serve binary to /usr/bin, run
174 as a privileged user.
176 To install somewhere else, tweak the Makefile first.
178 This will also install an init script to /etc/init.d/rs-serve and a default
179 configuration to /etc/default/rs-serve.
181 On Debian based systems (i.e. when "update-rc.d" is present), "make install"
182 will also install the rs-serve init script into /etc/rc*.d/.
187 There are a variety of options
189 If you want to use the init script, you can set options in /etc/default/rs-serve,
190 otherwise just pass them on the command line.
196 to get a list of supported options.
198 3.6) Integrating authorization
199 ------------------------------
201 To integrate an authorization endpoint, you need to do two things:
203 * configure endpoint URI
205 Set the --auth-uri option to a printf style format string. "%s" will be
206 replaced with the username.
208 * configure your authorization endpoint to manage rs-serve tokens
210 rs-serve doesn't care where tokens come from, but it need to know them to
211 decide whether a given request is authorized or not. It maintains an internal
212 store for authorizations (i.e. structures of [user-name, token, scopes]),
213 which must be managed from the outside.
215 The tools to do this are:
219 Usage: rs-add-token <user> <token> <scope1> [<scope2> ... <scopeN>]
221 - <user> is the login name of the user (rs-serve must be able to resolve
222 it using getpwnam() in order to find the home directory)
223 - <token> is the token string authenticating future requests. For rs-serve
224 it is an opaque string.
225 - <scope1>..<scopeN> are scope strings in the same form as described in
226 draft-dejong-remotestorage-01, Section 9.
230 Usage: rs-remove-token <user> <token>
232 <user> and <token> must both be given.
233 If the token cannot be found, rs-remove-token terminates with non-zero status.
237 Lists all currently installed tokens and their respective scopes.
239 The output format is primarily meant for (human) debugging and subject to change.
244 * If you've found a bug, or have any questions, please open an issue on github:
245 https://github.com/remotestoage/rs-serve/issues
247 * If you want to contribute, fork the project on github and send pull requests.
249 * In any case, don't hesitate to talk with us on IRC:
250 #remotestorage and #unhosted, both on irc.freenode.org
253 - #unhosted: http://webchat.freenode.net/?channels=unhosted
254 - #remotestorage: http://webchat.freenode.net/?channels=remotestorage