@samitouri / QOSami-HFS-2 / commits / f32f234b

updated docs

Massimo Melina committed Apr 28, 2022 at 11:48 UTC f32f234b6cdf67f4d2264449765aac6135c8dfaf

4 files changed +269 -265

README.md

+18 -265

@@ -1,5 +1,7 @@

1 # HFS: HTTP File Server

3 +## Introduction

4 +

5 HFS is a file server offering a virtual file system (vfs).

6 You can easily share a single file instead of the whole folder,

7 or you can rename it, but without touching the real file, just virtually.

@@ -12,6 +14,7 @@ This is a full rewrite of [the Delphi version](https://github.com/rejetto/hfs2).

14 You won't find all previous features here (yet), but still we got:

16 ## Features

17 +

18 - https

19 - unicode

20 - virtual file system

@@ -25,25 +28,10 @@ You won't find all previous features here (yet), but still we got:

28 - log file

29 - speed throttler

30 - admin web interface

31 +- virtual hosting (plug-in)

32 +- anti-brute-force (plug-in)

29 -### Why you should upgrade from HFS 2.x to 3

30 -

31 -As you can see from the list above, we already have some goods that you can't find in HFS 2

32 -

33 -- https

34 -- fully supports unicode

35 -- more robust

36 -- plugins system

37 -- ZIP format for archives instead of TAR

38 -- more flexible permissions

39 -

40 -### Why you should still stay with HFS 2.x (so far)

41 -

42 -- smaller

43 -- more tested

44 -- easier to configure (not sure about this anymore)

45 -

46 -# Installation

34 +## Installation

36 1. go to https://github.com/rejetto/hfs/releases

37 2. click on `Assets`

@@ -57,7 +45,7 @@ If your system is not covered, you can try this alternative version:

45 3. chmod +x run

46 4. launch `./run`

60 -# Plug-ins

48 +## Plug-ins

50 To install a plugin you just copy its folder inside `plugins` folder.

@@ -65,256 +53,21 @@ Delete it to uninstall.

54 HFS will ignore all folders with `-disabled` at the end of the name.

68 -# Developers section

69 -

70 -## Building instructions

71 -

72 -0. Install [Node.js](https://nodejs.org/) 16+

73 -1. Install Typescript: launch `npm -g i typescript`

74 -3. Launch `npm run build-all` in the root

75 -

76 -You'll see some warnings about vulnerabilities. Fear not, for those are in the dev tools we are using.

77 -If you want to be assured, run `npm audit --production` that will exclude dev stuff, and you should see something

78 -more reassuring, like "found 0 vulnerabilities", hopefully.

79 -

80 -## Dev environment

81 -

82 -One way of working on sources here is to `npm run watch-server`.

83 -This will give you auto-restarting of the server on back-end changes.

84 -Set an env `DEV=1` to let the code know we are in a dev environment.

85 -

86 -If you want to work on the frontend and admin too, you should *first*

87 -1. set an env `FRONTEND_PROXY=3005`

88 -2. `npm run start-frontend`

89 -1. set an env `ADMIN_PROXY=3006`

90 -2. `npm run start-admin`

91 -

92 -Having this env-s will make the server get all related stuff from the other dev servers.

93 -Otherwise, you should be sure that frontend and admin have been built, and its files are ready to be used in `dist` folder.

94 -In this latter case, the `DEV=1` you set before will make the server get the files from inside the `dist` folder.

95 -

96 -## For plug-in makers

97 -

98 -A plug-in is a folder with a `plugin.js` file in it.

99 -

100 -Plug-ins can be hot-swapped, and at some extent can be edited without restarting the server.

101 -

102 -Each plug-in has access to the same set of features.

103 -Normally you'll have a plug-in that's a theme, and another that's a firewall,

104 -but nothing is preventing a single plug-in from doing both tasks.

105 -

106 -`plugin.js` is a javascript module that exports an `init` function like this:

107 -```js

108 -exports.init = api => ({

109 - frontend_css: 'mystyle.css'

110 -})

111 -```

112 -

113 -The init function is called when the module is loaded and should return an object with things to customize.

114 -In the example above we are asking a css file to be loaded in the frontend.

115 -The parameter `api` object contains some useful things we'll see later.

116 -You can decide to return things in the `init` function, or directly in the `exports`.

117 -If you need to access the api you must use `init`, otherwise you can go directly with `exports`.

118 -

119 -Let's first look at the things you can return:

120 -

121 -### Things a plugin can return or export

122 -

123 -- `description: string` try to explain what this plugin is for. This must go in `exports` and use "double quotes".

124 -- `version: number` use progressive numbers to distinguish each release. This must go in `exports`.

125 -- `frontend_css: string | string[]` path to one or more css files that you want the frontend to load. These are to be placed in the `public` folder (refer below).

126 -- `frontend_js: string | string[]` path to one or more js files that you want the frontend to load. These are to be placed in the `public` folder (refer below).

127 -- `middleware: (Context) => void | true | function` a function that will be used as a middleware: it can interfere with http activity.

128 -

129 - To know what the Context object contains please refer to [Koa's documentation](https://github.com/koajs/koa/blob/master/docs/api/context.md).

130 - You don't get the `next` parameter as in standard Koa's middlewares because this is different, but we are now explaining how to achieve the same results.

131 - To interrupt other middlewares on this http request, return `true`.

132 - If you want to execute something in the "upstream" of middlewares, return a function.

133 -

134 -- `unload: function` called when unloading a plugin. This is a good place for example to clearInterval().

135 -- `onDirEntry: ({ entry: DirEntry, listPath: string }) => void | false` by providing this callback you can manipulate the record

136 - that is sent to the frontend (`entry`), or you can return false to exclude this entry from the results.

137 -- `config: { [key]: FieldDescriptor }` declare a set of admin-configurable values owned by the plugin that will be displayed inside Admin panel for change.

138 - Each property is identified by its key, and the descriptor is another object with options about the field.

139 - A simple empty object `{}` is a text field.

140 -

141 - Eg: you want a `message` text. You add this to your `plugin.js`:

142 - ```js

143 - exports.config = { message: {} }

144 - ```

56 +## Why you should upgrade from HFS 2.x to 3

146 - Once the admin has chosen a value for it, the value will be saved in the main config file, under the `plugins_config` property.

147 - ```yaml

148 - plugins_config:

149 - name_of_the_plugin:

150 - message: Hi there!

151 - ```

152 - When necessary your plugin will read its value using `api.getConfig('message')`.

58 +As you can see from the list of features, we already have some goods that you cannot find in HFS 2.

59 +Other than that, you can also consider:

154 -#### FieldDescriptor

155 -

156 -Currently, these properties are supported:

157 -- `type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect'` . Default is `string`.

158 -- `label: string` what name to display next to the field. Default is based on `key`.

159 -- `helperText: string` extra text printed next to the field.

160 -

161 -Based on `type`, other properties are supported:

162 -- `string`

163 - - `multiline: boolean`. Default is `false`.

164 -- `number`

165 - - `min: number`

166 - - `max: number`

167 -- `select`

168 - - `options: { [label]: AnyJsonValue }`

169 -- `multiselect` it's like `select` but its result is an array of values.

170 -

171 -### api object

172 -

173 -The `api` object you get as parameter of the `init` contains the following:

174 -

175 - - `require: function` use this instead of standard `require` function to access modules already loaded by HFS.

176 -

177 - - `getConfig(key: string): any` get config's value set up by using `exports.config`.

178 -

179 - - `const: object` all constants of the `const.ts` file are exposed here. E.g. BUILD_TIMESTAMP, API_VERSION, etc.

180 -

181 - - `getConnections: Connections[]` retrieve current list of active connections.

182 -

183 - - `events: EventEmitter` this is the main events emitter used by HFS.

184 -

185 - - `srcDir: string` this can be useful if you need to import some extra function not available in `api`.

186 - ```js

187 - exports.init = api => {

188 - const { watchLoad } = api.require(api.srcDir + '/watchLoad')

189 - }

190 - ```

191 - You *should* try to keep this kind of behavior at its minimum, as name of sources and of elements in them are subject to change.

192 - If you need something for your plugin that's not covered by `api`, you can test it with this method,

193 - but you should then discuss it on the forum because an addition to `api` is your best option for making a future-proof plugin.

194 -

195 -Each plug-in can have a `public` folder, and its files will be accessible at `/~/plugins/PLUGIN_NAME/FILENAME`.

196 -

197 -### Front-end specific

198 -

199 -The following information applies to the default front-end, and may not apply to a custom one.

200 -

201 -#### Javascript

202 -Once your script is loaded into the frontend (via `frontend_js`), you will have access to the `HFS` object in the global scope.

203 -There you'll find `HFS.onEvent` function that is the base of communication.

204 -

205 -`onEvent(eventName:string, callback: (object) => any)` your callback will be called on the specified event.

206 -Depending on the event you'll have an object with parameters in it, and may return some output. Refer to the specific event for further information.

207 -

208 -This is a list of available frontend events, with respective parameters and output.

209 -

210 -- `additionalEntryProps`

211 - - you receive each entry of the list, and optionally produce HTML code that will be added in the `entry-props` container.

212 - - parameters `{ entry: Entry }`

213 -

214 - The `Entry` type is an object with the following properties:

215 - - `n: string` name of the entry, including relative path in some cases.

216 - - `s?: number` size of the entry, in bytes. It may be missing, for example for folders.

217 - - `t?: Date` generic timestamp, combination of creation-time and modified-time.

218 - - `c?: Date` creation-time.

219 - - `m?: Date` modified-time.

220 - - output `string | void`

221 -

222 -# File formats

223 -

224 -General configuration is read by default from file `config.yaml`.

225 -When not specified, default values will be used.

226 -Supported entries are:

227 -- `port` where to accept http connections. Default is 80.

228 -- `vfs` the files and folders you want to expose. For details see the dedicated following section.

229 -- `log` path of the log file. Default is `access.log`.

230 -- `log_rotation` frequency of log rotation. Accepted values are `daily`, `weekly`, `monthly`, or empty string to disable. Default is `weekly`.

231 -- `error_log` path of the log file for errors. Default is `error.log`.

232 -- `errors_in_main_log` if you want to use a single file for both kind of entries. Default is false.

233 -- `accounts` path of the accounts file. Default is `accounts.yaml`.

234 -- `mime` command what mime-type to be returned with some files.

235 - E.g.: `"*.jpg": image/jpeg`

236 - You can specify multiple entries, or separate multiple file masks with a p|pe.

237 - You can use the special value `auto` to attempt automatic detection.

238 -- `max_kbps` throttle output speed. Default is Infinity.

239 -- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.

240 -- `zip_calculate_size_for_seconds` how long should we wait before the zip archive starts streaming, trying to understand its finale size. Default is 1.

241 -- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.

242 -- `https_port` listen on a specific port. Default is 443.

243 -- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.

244 -- `private_key` use this file for https private key. Default is none.

245 -- `allowed_referer` you can decide what domains can link to your files. Wildcards supported. Default is any.

246 -- `block` a list of rules that will block connections. E.g.:

247 - ```

248 - block:

249 - - ip: 192.168.0.90

250 - ```

251 - Syntax supports, other than simple address, `*` as wildcard and CIDR format.

252 -- `plugins_config` this is a generic place where you can find/put configuration for each plugin, at least those that need configuration.

253 -- `enable_plugins` if a plugin is not present here, it won't run. Defaults is `[ antibrute ]`.

254 -- `custom_header` provide HTML code to be put at the top of your Frontend. Default is none.

255 -- `localhost_admin` should Admin be accessed without credentials when on localhost. Default is true.

256 -- `proxies` number of proxies between server and clients to be trusted about providing clients' IP addresses. Default is 0.

257 -

258 -## Virtual File System (VFS)

259 -

260 -The virtual file system is a tree of files and folders, collectively called *nodes*.

261 -By default, a node is a folder, unless you provide for it a source that's a file.

262 -Valid keys in a node are:

263 -- `name`: this is the name we'll use to display this file/folder. If not provided, HFS will infer it from the source. At least `name` or `source` must be provided.

264 -- `source`: absolute or relative path of where to get the content

265 -- `children`: just for folders, specify its virtual children.

266 - Value is a list and its entries are nodes.

267 -- `rename`: similar to name, but it's from the parent node point.

268 - Use this to change the name of entries that are read from the source, not listed in the VFS.

269 - Value is a dictionary, where the key is the original name.

270 -- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.

271 -- `default`: to be used with a folder where you want to serve a default html. E.g.: "index.html". Using this will make `mime` default to "auto".

272 -- `can_read`: specify who can download this entry. Value is a `WhoCan` descriptor, which is one of these values

273 - - `true`: anyone can, even people who didn't log in. This is normally the default value.

274 - - `false`: no one can.

275 - - `"*"`: any account can, i.e. anyone who logged in.

276 - - `[ frank, peter ]`: the list of accounts who can.

277 -- `can_see`: specify who can see this entry. Even if a user can download you can still make the file not appear in the list.

278 - Remember that to see in the list you must also be able to download, or else you won't see it anyway. Value is a `WhoCan` descriptor, refer above.

279 -- `masks`: maps a file mask to a set of properties as the one documented in this section. E.g.

280 - ```

281 - masks:

282 - "**/*.mp3":

283 - can_read: false

284 - "*.jpg|*.png":

285 - mime: auto

286 - ```

287 -

288 -# Accounts

289 -

290 -Accounts are kept in `accounts.yaml` if any, or you can decide another file by passing parameter `--accounts`.

291 -Inside the file, all accounts should go under `accounts:` key, as a dictionary where the key is the username.

292 -E.g.

293 -```

294 -accounts:

295 - admin:

296 - password: hello123

297 - belongs: group1

298 - guest:

299 - password: guest

300 - group1:

301 -```

302 -

303 -As soon as the file is read HFS will encrypt passwords in a non-reversible way. It means that `password` property is replaced with an encrypted property: `srp`.

304 -For this reason HFS needs that your accounts file is writable.

305 -

306 -As you can see in the example, `group1` has no password. This implies that you cannot log in as `group1`, but still `group1` exists and its purpose is to

307 -gather multiple accounts and refer to them collectively as `group1`, so you can quickly share powers among several accounts.

308 -

309 -## Account options

61 +- it's more robust: it was designed to be an always-running server, while HFS 1-2 was designed for occasional usage (transfer and quit)

62 +- passwords are never really stored, just a non-reversible hash is

63 +- more flexible permissions

311 -Other options you can define as properties of an account:

65 +But you may still want to stay with HFS 2.x (so far) for the following reasons

313 -- `ignore_limits` to ignore speed limits. Default is `false`.

314 -- `redirect` provide a URL if you want the user to be redirected upon login. Default is none.

315 -- `admin` set `true` if you want to let this account log in to the Admin interface.

316 -- `belongs` an array of usernames of other accounts from which to inherit their permissions.

67 +- smaller

68 +- more tested

69 +- classic window interface (can be easier for some people)

71 ## License

320 -[GPLv3](https://github.com/rejetto/hfs/blob/master/LICENSE.txt).

73 +[GPLv3](https://github.com/rejetto/hfs/blob/master/LICENSE.txt)

dev-plugins.md new

+126

@@ -0,0 +1,126 @@

1 +# For plug-in makers

2 +

3 +A plug-in is a folder with a `plugin.js` file in it.

4 +

5 +Plug-ins can be hot-swapped, and at some extent can be edited without restarting the server.

6 +

7 +Each plug-in has access to the same set of features.

8 +Normally you'll have a plug-in that's a theme, and another that's a firewall,

9 +but nothing is preventing a single plug-in from doing both tasks.

10 +

11 +`plugin.js` is a javascript module that exports an `init` function like this:

12 +```js

13 +exports.init = api => ({

14 + frontend_css: 'mystyle.css'

15 +})

16 +```

17 +

18 +The init function is called when the module is loaded and should return an object with things to customize.

19 +In the example above we are asking a css file to be loaded in the frontend.

20 +The parameter `api` object contains some useful things we'll see later.

21 +You can decide to return things in the `init` function, or directly in the `exports`.

22 +If you need to access the api you must use `init`, otherwise you can go directly with `exports`.

23 +

24 +Let's first look at the things you can return:

25 +

26 +## Things a plugin can return or export

27 +

28 +- `description: string` try to explain what this plugin is for. This must go in `exports` and use "double quotes".

29 +- `version: number` use progressive numbers to distinguish each release. This must go in `exports`.

30 +- `frontend_css: string | string[]` path to one or more css files that you want the frontend to load. These are to be placed in the `public` folder (refer below).

31 +- `frontend_js: string | string[]` path to one or more js files that you want the frontend to load. These are to be placed in the `public` folder (refer below).

32 +- `middleware: (Context) => void | true | function` a function that will be used as a middleware: it can interfere with http activity.

33 +

34 + To know what the Context object contains please refer to [Koa's documentation](https://github.com/koajs/koa/blob/master/docs/api/context.md).

35 + You don't get the `next` parameter as in standard Koa's middlewares because this is different, but we are now explaining how to achieve the same results.

36 + To interrupt other middlewares on this http request, return `true`.

37 + If you want to execute something in the "upstream" of middlewares, return a function.

38 +

39 +- `unload: function` called when unloading a plugin. This is a good place for example to clearInterval().

40 +- `onDirEntry: ({ entry: DirEntry, listPath: string }) => void | false` by providing this callback you can manipulate the record

41 + that is sent to the frontend (`entry`), or you can return false to exclude this entry from the results.

42 +- `config: { [key]: FieldDescriptor }` declare a set of admin-configurable values owned by the plugin that will be displayed inside Admin panel for change.

43 + Each property is identified by its key, and the descriptor is another object with options about the field.

44 + A simple empty object `{}` is a text field.

45 +

46 + Eg: you want a `message` text. You add this to your `plugin.js`:

47 + ```js

48 + exports.config = { message: {} }

49 + ```

50 +

51 + Once the admin has chosen a value for it, the value will be saved in the main config file, under the `plugins_config` property.

52 + ```yaml

53 + plugins_config:

54 + name_of_the_plugin:

55 + message: Hi there!

56 + ```

57 + When necessary your plugin will read its value using `api.getConfig('message')`.

58 +

59 +### FieldDescriptor

60 +

61 +Currently, these properties are supported:

62 +- `type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect'` . Default is `string`.

63 +- `label: string` what name to display next to the field. Default is based on `key`.

64 +- `helperText: string` extra text printed next to the field.

65 +

66 +Based on `type`, other properties are supported:

67 +- `string`

68 + - `multiline: boolean`. Default is `false`.

69 +- `number`

70 + - `min: number`

71 + - `max: number`

72 +- `select`

73 + - `options: { [label]: AnyJsonValue }`

74 +- `multiselect` it's like `select` but its result is an array of values.

75 +

76 +## api object

77 +

78 +The `api` object you get as parameter of the `init` contains the following:

79 +

80 +- `require: function` use this instead of standard `require` function to access modules already loaded by HFS.

81 +

82 +- `getConfig(key: string): any` get config's value set up by using `exports.config`.

83 +

84 +- `const: object` all constants of the `const.ts` file are exposed here. E.g. BUILD_TIMESTAMP, API_VERSION, etc.

85 +

86 +- `getConnections: Connections[]` retrieve current list of active connections.

87 +

88 +- `events: EventEmitter` this is the main events emitter used by HFS.

89 +

90 +- `srcDir: string` this can be useful if you need to import some extra function not available in `api`.

91 + ```js

92 + exports.init = api => {

93 + const { watchLoad } = api.require(api.srcDir + '/watchLoad')

94 + }

95 + ```

96 + You *should* try to keep this kind of behavior at its minimum, as name of sources and of elements in them are subject to change.

97 + If you need something for your plugin that's not covered by `api`, you can test it with this method,

98 + but you should then discuss it on the forum because an addition to `api` is your best option for making a future-proof plugin.

99 +

100 +Each plug-in can have a `public` folder, and its files will be accessible at `/~/plugins/PLUGIN_NAME/FILENAME`.

101 +

102 +## Front-end specific

103 +

104 +The following information applies to the default front-end, and may not apply to a custom one.

105 +

106 +### Javascript

107 +Once your script is loaded into the frontend (via `frontend_js`), you will have access to the `HFS` object in the global scope.

108 +There you'll find `HFS.onEvent` function that is the base of communication.

109 +

110 +`onEvent(eventName:string, callback: (object) => any)` your callback will be called on the specified event.

111 +Depending on the event you'll have an object with parameters in it, and may return some output. Refer to the specific event for further information.

112 +

113 +This is a list of available frontend events, with respective parameters and output.

114 +

115 +- `additionalEntryProps`

116 + - you receive each entry of the list, and optionally produce HTML code that will be added in the `entry-props` container.

117 + - parameters `{ entry: Entry }`

118 +

119 + The `Entry` type is an object with the following properties:

120 + - `n: string` name of the entry, including relative path in some cases.

121 + - `s?: number` size of the entry, in bytes. It may be missing, for example for folders.

122 + - `t?: Date` generic timestamp, combination of creation-time and modified-time.

123 + - `c?: Date` creation-time.

124 + - `m?: Date` modified-time.

125 + - output `string | void`

126 +

dev.md new

+123

@@ -0,0 +1,123 @@

1 +# For developers

2 +

3 +## Building instructions

4 +

5 +0. Install [Node.js](https://nodejs.org/) 16+

6 +1. Install Typescript: launch `npm -g i typescript`

7 +3. Launch `npm run build-all` in the root

8 +

9 +You'll see some warnings about vulnerabilities. Fear not, for those are in the dev tools we are using.

10 +If you want to be assured, run `npm audit --production` that will exclude dev stuff, and you should see something

11 +more reassuring, like "found 0 vulnerabilities", hopefully.

12 +

13 +## Dev environment

14 +

15 +First `npm install`.

16 +

17 +One way of working on sources here is to `npm run watch-server`.

18 +This will give you auto-restarting of the server on back-end changes.

19 +Set an env `DEV=1` to let the code know we are in a dev environment.

20 +

21 +If you want to work on the frontend and admin too, you should *first*

22 +1. set an env `FRONTEND_PROXY=3005`

23 +2. `npm run start-frontend`

24 +1. set an env `ADMIN_PROXY=3006`

25 +2. `npm run start-admin`

26 +

27 +Having this env-s will make the server get all related stuff from the other dev servers.

28 +Otherwise, you should be sure that frontend and admin have been built, and its files are ready to be used in `dist` folder.

29 +In this latter case, the `DEV=1` you set before will make the server get the files from inside the `dist` folder.

30 +

31 +## File formats

32 +

33 +General configuration is read by default from file `config.yaml`.

34 +When not specified, default values will be used.

35 +Supported entries are:

36 +- `port` where to accept http connections. Default is 80.

37 +- `vfs` the files and folders you want to expose. For details see the dedicated following section.

38 +- `log` path of the log file. Default is `access.log`.

39 +- `log_rotation` frequency of log rotation. Accepted values are `daily`, `weekly`, `monthly`, or empty string to disable. Default is `weekly`.

40 +- `error_log` path of the log file for errors. Default is `error.log`.

41 +- `errors_in_main_log` if you want to use a single file for both kind of entries. Default is false.

42 +- `accounts` path of the accounts file. Default is `accounts.yaml`.

43 +- `mime` command what mime-type to be returned with some files.

44 + E.g.: `"*.jpg": image/jpeg`

45 + You can specify multiple entries, or separate multiple file masks with a p|pe.

46 + You can use the special value `auto` to attempt automatic detection.

47 +- `max_kbps` throttle output speed. Default is Infinity.

48 +- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.

49 +- `zip_calculate_size_for_seconds` how long should we wait before the zip archive starts streaming, trying to understand its finale size. Default is 1.

50 +- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.

51 +- `https_port` listen on a specific port. Default is 443.

52 +- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.

53 +- `private_key` use this file for https private key. Default is none.

54 +- `allowed_referer` you can decide what domains can link to your files. Wildcards supported. Default is any.

55 +- `block` a list of rules that will block connections. E.g.:

56 + ```

57 + block:

58 + - ip: 192.168.0.90

59 + ```

60 + Syntax supports, other than simple address, `*` as wildcard and CIDR format.

61 +- `plugins_config` this is a generic place where you can find/put configuration for each plugin, at least those that need configuration.

62 +- `enable_plugins` if a plugin is not present here, it won't run. Defaults is `[ antibrute ]`.

63 +- `custom_header` provide HTML code to be put at the top of your Frontend. Default is none.

64 +- `localhost_admin` should Admin be accessed without credentials when on localhost. Default is true.

65 +- `proxies` number of proxies between server and clients to be trusted about providing clients' IP addresses. Default is 0.

66 +

67 +### Virtual File System (VFS)

68 +

69 +The virtual file system is a tree of files and folders, collectively called *nodes*.

70 +By default, a node is a folder, unless you provide for it a source that's a file.

71 +Valid keys in a node are:

72 +- `name`: this is the name we'll use to display this file/folder. If not provided, HFS will infer it from the source. At least `name` or `source` must be provided.

73 +- `source`: absolute or relative path of where to get the content

74 +- `children`: just for folders, specify its virtual children.

75 + Value is a list and its entries are nodes.

76 +- `rename`: similar to name, but it's from the parent node point.

77 + Use this to change the name of entries that are read from the source, not listed in the VFS.

78 + Value is a dictionary, where the key is the original name.

79 +- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.

80 +- `default`: to be used with a folder where you want to serve a default html. E.g.: "index.html". Using this will make `mime` default to "auto".

81 +- `can_read`: specify who can download this entry. Value is a `WhoCan` descriptor, which is one of these values

82 + - `true`: anyone can, even people who didn't log in. This is normally the default value.

83 + - `false`: no one can.

84 + - `"*"`: any account can, i.e. anyone who logged in.

85 + - `[ frank, peter ]`: the list of accounts who can.

86 +- `can_see`: specify who can see this entry. Even if a user can download you can still make the file not appear in the list.

87 + Remember that to see in the list you must also be able to download, or else you won't see it anyway. Value is a `WhoCan` descriptor, refer above.

88 +- `masks`: maps a file mask to a set of properties as the one documented in this section. E.g.

89 + ```

90 + masks:

91 + "**/*.mp3":

92 + can_read: false

93 + "*.jpg|*.png":

94 + mime: auto

95 + ```

96 +

97 +## Accounts

98 +

99 +All accounts go under `accounts:` key, as a dictionary where the key is the username.

100 +E.g.

101 +```

102 +accounts:

103 + admin:

104 + password: hello123

105 + belongs: group1

106 + guest:

107 + password: guest

108 + group1:

109 +```

110 +

111 +As soon as the config is read HFS will encrypt passwords (if necessary) in a non-reversible way. It means that `password` property is replaced with an encrypted property: `srp`.

112 +

113 +As you can see in the example, `group1` has no password. This implies that you cannot log in as `group1`, but still `group1` exists and its purpose is to

114 +gather multiple accounts and refer to them collectively as `group1`, so you can quickly share powers among several accounts.

115 +

116 +## Account options

117 +

118 +Other options you can define as properties of an account:

119 +

120 +- `ignore_limits` to ignore speed limits. Default is `false`.

121 +- `redirect` provide a URL if you want the user to be redirected upon login. Default is none.

122 +- `admin` set `true` if you want to let this account log in to the Admin interface.

123 +- `belongs` an array of usernames of other accounts from which to inherit their permissions.

todo.md

@@ -43,3 +43,5 @@

43 - log: ip2name

44 - apis in separated log file with parameters?

45 - search operators (size, type?)

46 +- ability to install as service in Windows

47 + - an application to control the service as tray icon