moved config format out of readme
Massimo Melina committed
Mar 16, 2023 at 10:50 UTC
5023038c3364f98408a2f69c8d2d49933e9856a0
2 files changed
+95
-92
README.md
+1
-92
@@ -139,98 +139,7 @@ kind of distribution on Windows, or `USER_FOLDER/.hfs` on other systems.
139
You can decide a different file and location by passing `--config SOME_FILE` at command line, or inside
140
an *env* called `HFS_CONFIG`. Any relative path provided is relative to the *cwd*.
141
142
-### Configuration properties
143
-- `port` where to accept http connections. Default is 80.
144
-- `vfs` the files and folders you want to expose. For details see the dedicated following section.
145
-- `log` path of the log file. Default is `access.log`.
146
-- `log_rotation` frequency of log rotation. Accepted values are `daily`, `weekly`, `monthly`, or empty string to disable. Default is `weekly`.
147
-- `error_log` path of the log file for errors. Default is `error.log`.
148
-- `errors_in_main_log` if you want to use a single file for both kind of entries. Default is false.
149
-- `accounts` list of accounts. For details see the dedicated following section.
150
-- `mime` command what mime-type to be returned with some files.
151
- E.g.: `"*.jpg": image/jpeg`
152
- You can specify multiple entries, or separate multiple file masks with a p|pe.
153
- You can use the special value `auto` to attempt automatic detection.
154
-- `max_kbps` throttle output speed. Default is Infinity.
155
-- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.
156
-- `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.
157
-- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.
158
-- `https_port` listen on a specific port. Default is 443.
159
-- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.
160
-- `private_key` use this file for https private key. Default is none.
161
-- `allowed_referer` you can decide what domains can link to your files. Wildcards supported. Default is empty, meaning any.
162
-- `block` a list of rules that will block connections. E.g.:
163
- ```
164
- block:
165
- - ip: 192.168.0.90
166
- ```
167
- Syntax supports, other than simple address, `*` as wildcard and CIDR format.
168
-- `plugins_config` this is a generic place where you can find/put configuration for each plugin, at least those that need configuration.
169
-- `enable_plugins` if a plugin is not present here, it won't run. Defaults is `[ antibrute ]`.
170
-- `localhost_admin` should Admin be accessed without credentials when on localhost. Default is true.
171
-- `proxies` number of proxies between server and clients to be trusted about providing clients' IP addresses. Default is 0.
172
-- `keep_unfinished_uploads` should unfinished uploads be deleted immediately when interrupted. Default is true.
173
-- `favicon` path to file to be used as favicon. Default is none.
174
-
175
-#### Virtual File System (VFS)
176
-
177
-The virtual file system is a tree of files and folders, collectively called *nodes*.
178
-By default, a node is a folder, unless you provide for it a source that's a file.
179
-Valid keys in a node are:
180
-- `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.
181
-- `source`: absolute or relative path of where to get the content
182
-- `children`: just for folders, specify its virtual children.
183
- Value is a list and its entries are nodes.
184
-- `rename`: similar to name, but it's from the parent node point.
185
- Use this to change the name of entries that are read from the source, not listed in the VFS.
186
- Value is a dictionary, where the key is the original name.
187
-- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.
188
-- `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".
189
-- `can_read`: specify who can download this entry. Value is a `WhoCan` descriptor, which is one of these values
190
- - `true`: anyone can, even people who didn't log in. This is normally the default value.
191
- - `false`: no one can.
192
- - `"*"`: any account can, i.e. anyone who logged in.
193
- - `[ frank, peter ]`: the list of accounts who can.
194
-- `can_see`: specify who can see this element. Even if a user can download you can still make the file not appear in the list.
195
- Value is a `WhoCan` descriptor, refer above.
196
-- `can_upload` specify who can upload. Applies to folders with a source. Default is none.
197
-- `can_delete` specify who can delete. Applies to folders with a source. Default is none.
198
-- `masks`: maps a file mask to a set of properties as the one documented in this section. E.g.
199
- ```
200
- "**/*.mp3":
201
- can_read: false
202
- "*.jpg|*.png":
203
- mime: auto
204
- ```
205
-
206
-Permissions set on an inner element will override inherited permissions. This means that you can restrict access to folder1,
207
-and yet decide to give free access to folder1/subfolder2.
208
-
209
-#### Accounts
210
-
211
-All accounts go under `accounts:` property, as a dictionary where the key is the username.
212
-E.g.
213
-```
214
-accounts:
215
- admin:
216
- password: hello123
217
- belongs: group1
218
- guest:
219
- password: guest
220
- group1:
221
-```
222
-
223
-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`.
224
-
225
-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
226
-gather multiple accounts and refer to them collectively as `group1`, so you can quickly share powers among several accounts.
227
-
228
-For each account entries, this is the list of properties you can have:
229
-
230
-- `ignore_limits` to ignore speed limits. Default is `false`.
231
-- `redirect` provide a URL if you want the user to be redirected upon login. Default is none.
232
-- `admin` set `true` if you want to let this account log in to the Admin-panel. Default is `false`.
233
-- `belongs` an array of usernames of other accounts from which to inherit their permissions. Default is none.
142
+[Check details about config file format](https://github.com/rejetto/hfs/blob/main/config.md).
143
144
## Reverse proxy
145
config.md
new
+94
@@ -0,0 +1,94 @@
1
+This file contains details the configuration files.
2
+
3
+### Configuration properties
4
+- `port` where to accept http connections. Default is 80.
5
+- `vfs` the files and folders you want to expose. For details see the dedicated following section.
6
+- `log` path of the log file. Default is `access.log`.
7
+- `log_rotation` frequency of log rotation. Accepted values are `daily`, `weekly`, `monthly`, or empty string to disable. Default is `weekly`.
8
+- `error_log` path of the log file for errors. Default is `error.log`.
9
+- `errors_in_main_log` if you want to use a single file for both kind of entries. Default is false.
10
+- `accounts` list of accounts. For details see the dedicated following section.
11
+- `mime` command what mime-type to be returned with some files.
12
+ E.g.: `"*.jpg": image/jpeg`
13
+ You can specify multiple entries, or separate multiple file masks with a p|pe.
14
+ You can use the special value `auto` to attempt automatic detection.
15
+- `max_kbps` throttle output speed. Default is Infinity.
16
+- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.
17
+- `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.
18
+- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.
19
+- `https_port` listen on a specific port. Default is 443.
20
+- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.
21
+- `private_key` use this file for https private key. Default is none.
22
+- `allowed_referer` you can decide what domains can link to your files. Wildcards supported. Default is empty, meaning any.
23
+- `block` a list of rules that will block connections. E.g.:
24
+ ```
25
+ block:
26
+ - ip: 192.168.0.90
27
+ ```
28
+ Syntax supports, other than simple address, `*` as wildcard and CIDR format.
29
+- `plugins_config` this is a generic place where you can find/put configuration for each plugin, at least those that need configuration.
30
+- `enable_plugins` if a plugin is not present here, it won't run. Defaults is `[ antibrute ]`.
31
+- `localhost_admin` should Admin be accessed without credentials when on localhost. Default is true.
32
+- `proxies` number of proxies between server and clients to be trusted about providing clients' IP addresses. Default is 0.
33
+- `keep_unfinished_uploads` should unfinished uploads be deleted immediately when interrupted. Default is true.
34
+- `favicon` path to file to be used as favicon. Default is none.
35
+
36
+#### Virtual File System (VFS)
37
+
38
+The virtual file system is a tree of files and folders, collectively called *nodes*.
39
+By default, a node is a folder, unless you provide for it a source that's a file.
40
+Valid keys in a node are:
41
+- `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.
42
+- `source`: absolute or relative path of where to get the content
43
+- `children`: just for folders, specify its virtual children.
44
+ Value is a list and its entries are nodes.
45
+- `rename`: similar to name, but it's from the parent node point.
46
+ Use this to change the name of entries that are read from the source, not listed in the VFS.
47
+ Value is a dictionary, where the key is the original name.
48
+- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.
49
+- `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".
50
+- `can_read`: specify who can download this entry. Value is a `WhoCan` descriptor, which is one of these values
51
+ - `true`: anyone can, even people who didn't log in. This is normally the default value.
52
+ - `false`: no one can.
53
+ - `"*"`: any account can, i.e. anyone who logged in.
54
+ - `[ frank, peter ]`: the list of accounts who can.
55
+- `can_see`: specify who can see this element. Even if a user can download you can still make the file not appear in the list.
56
+ Value is a `WhoCan` descriptor, refer above.
57
+- `can_upload` specify who can upload. Applies to folders with a source. Default is none.
58
+- `can_delete` specify who can delete. Applies to folders with a source. Default is none.
59
+- `masks`: maps a file mask to a set of properties as the one documented in this section. E.g.
60
+ ```
61
+ "**/*.mp3":
62
+ can_read: false
63
+ "*.jpg|*.png":
64
+ mime: auto
65
+ ```
66
+
67
+Permissions set on an inner element will override inherited permissions. This means that you can restrict access to folder1,
68
+and yet decide to give free access to folder1/subfolder2.
69
+
70
+#### Accounts
71
+
72
+All accounts go under `accounts:` property, as a dictionary where the key is the username.
73
+E.g.
74
+```
75
+accounts:
76
+ admin:
77
+ password: hello123
78
+ belongs: group1
79
+ guest:
80
+ password: guest
81
+ group1:
82
+```
83
+
84
+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`.
85
+
86
+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
87
+gather multiple accounts and refer to them collectively as `group1`, so you can quickly share powers among several accounts.
88
+
89
+For each account entries, this is the list of properties you can have:
90
+
91
+- `ignore_limits` to ignore speed limits. Default is `false`.
92
+- `redirect` provide a URL if you want the user to be redirected upon login. Default is none.
93
+- `admin` set `true` if you want to let this account log in to the Admin-panel. Default is `false`.
94
+- `belongs` an array of usernames of other accounts from which to inherit their permissions. Default is none.