Skip to content

Commit d509bb0

Browse files
fclairambfclairamb
authored
chore(config): Documentation update (#812)
Adding JSON Schema + Doc
1 parent 875b1e5 commit d509bb0

File tree

3 files changed

+365
-0
lines changed

3 files changed

+365
-0
lines changed

‎config-schema.json‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://raw.githubusercontent.com/fclairamb/ftpserver/main/config-schema.json",
4+
"type": "object",
5+
"default": {},
6+
"title": "https://github.com/fclairamb/ftpserver config format",
7+
"additionalProperties": false,
8+
"required": [
9+
"accesses"
10+
],
11+
"properties": {
12+
"$schema": {
13+
"$id": "/properties/$schema",
14+
"type": "string",
15+
"title": "This schema",
16+
"description": "Allow to declare the schema",
17+
"default": "https://raw.githubusercontent.com/fclairamb/ftpserver/main/config-schema.json",
18+
"examples": [
19+
"https://raw.githubusercontent.com/fclairamb/ftpserver/main/config-schema.json"
20+
]
21+
},
22+
"version": {
23+
"type": "integer",
24+
"default": 1,
25+
"title": "The version of the config file",
26+
"examples": [
27+
1
28+
]
29+
},
30+
"listen_address": {
31+
"type": "string",
32+
"default": "",
33+
"title": "The listening address",
34+
"examples": [
35+
":21"
36+
]
37+
},
38+
"public_host": {
39+
"type": "string",
40+
"default": "",
41+
"title": "The public listening address (when behing a NAT gateway)",
42+
"examples": [
43+
"1.2.3.4"
44+
]
45+
},
46+
"max_clients": {
47+
"type": "integer",
48+
"default": 0,
49+
"title": "The maximum number of concurrent clients to accept",
50+
"examples": [
51+
200
52+
]
53+
},
54+
"passive_transfer_port_range": {
55+
"type": "object",
56+
"default": {},
57+
"title": "The allowed passive transfer ports",
58+
"required": [
59+
"start",
60+
"end"
61+
],
62+
"properties": {
63+
"start": {
64+
"type": "integer",
65+
"default": 0,
66+
"title": "First allowed port",
67+
"examples": [
68+
2122
69+
]
70+
},
71+
"end": {
72+
"type": "integer",
73+
"default": 0,
74+
"title": "Last allowed port",
75+
"examples": [
76+
2130
77+
]
78+
}
79+
},
80+
"examples": [{
81+
"start": 2122,
82+
"end": 2130
83+
}]
84+
},
85+
"logging": {
86+
"type": "object",
87+
"default": {},
88+
"title": "The logging options",
89+
"required": [
90+
"ftp_exchanges",
91+
"file_accesses"
92+
],
93+
"properties": {
94+
"ftp_exchanges": {
95+
"type": "boolean",
96+
"default": false,
97+
"title": "Log all FTP exchanges",
98+
"examples": [
99+
true
100+
]
101+
},
102+
"file_accesses": {
103+
"type": "boolean",
104+
"default": false,
105+
"title": "Log all file accesses",
106+
"examples": [
107+
true
108+
]
109+
}
110+
},
111+
"examples": [{
112+
"ftp_exchanges": true,
113+
"file_accesses": true
114+
}]
115+
},
116+
"tls": {
117+
"type": "object",
118+
"default": {},
119+
"title": "TLS parameters",
120+
"required": [
121+
"server_cert"
122+
],
123+
"properties": {
124+
"server_cert": {
125+
"type": "object",
126+
"default": {},
127+
"title": "Server certificate",
128+
"required": [
129+
"cert",
130+
"key"
131+
],
132+
"properties": {
133+
"cert": {
134+
"type": "string",
135+
"default": "",
136+
"title": "Public key",
137+
"examples": [
138+
"cert.pem"
139+
]
140+
},
141+
"key": {
142+
"type": "string",
143+
"default": "",
144+
"title": "Private key",
145+
"examples": [
146+
"key.pem"
147+
]
148+
}
149+
},
150+
"examples": [{
151+
"cert": "cert.pem",
152+
"key": "key.pem"
153+
}]
154+
}
155+
},
156+
"examples": [{
157+
"server_cert": {
158+
"cert": "cert.pem",
159+
"key": "key.pem"
160+
}
161+
}]
162+
},
163+
"accesses": {
164+
"type": "array",
165+
"default": [],
166+
"title": "The accesses",
167+
"items": {
168+
"type": "object",
169+
"title": "A Schema",
170+
"required": [
171+
"user",
172+
"pass",
173+
"fs",
174+
"params"
175+
],
176+
"properties": {
177+
"user": {
178+
"type": "string",
179+
"title": "The FTP user",
180+
"examples": [
181+
"test",
182+
"dropbox",
183+
"gdrive",
184+
"s3",
185+
"sftp"
186+
]
187+
},
188+
"pass": {
189+
"type": "string",
190+
"title": "The FTP password",
191+
"examples": [
192+
"test",
193+
"dropbox",
194+
"gdrive",
195+
"s3",
196+
"sftp"
197+
]
198+
},
199+
"fs": {
200+
"type": "string",
201+
"title": "The backend file system to use",
202+
"examples": [
203+
"os",
204+
"dropbox",
205+
"gdrive",
206+
"s3",
207+
"sftp"
208+
]
209+
},
210+
"params": {
211+
"type": "object",
212+
"title": "The parameter of each file system"
213+
},
214+
"shared": {
215+
"type": "boolean",
216+
"default": false,
217+
"title": "If the backend shall be shared between session",
218+
"examples": [
219+
true
220+
]
221+
},
222+
"read_only": {
223+
"type": "boolean",
224+
"default": false,
225+
"title": "If the backend shall be read only",
226+
"examples": [
227+
true
228+
]
229+
},
230+
"sync_and_delete": {
231+
"type": "object",
232+
"default": {},
233+
"title": "If we should use the sync & delete mechanism",
234+
"required": [
235+
"enable",
236+
"directory"
237+
],
238+
"properties": {
239+
"enable": {
240+
"type": "boolean",
241+
"default": false,
242+
"title": "The enable Schema",
243+
"examples": [
244+
true
245+
]
246+
},
247+
"directory": {
248+
"type": "string",
249+
"default": "",
250+
"title": "The directory Schema",
251+
"examples": [
252+
"/tmp/snd"
253+
]
254+
}
255+
},
256+
"examples": [{
257+
"enable": true,
258+
"directory": "/tmp/snd"
259+
}]
260+
}
261+
},
262+
"examples": [{
263+
"user": "test",
264+
"pass": "test",
265+
"fs": "os",
266+
"params": {
267+
"basePath": "/tmp"
268+
}
269+
},
270+
{
271+
"user": "test",
272+
"pass": "test",
273+
"fs": "os",
274+
"params": {
275+
"basePath": "/tmp"
276+
}
277+
},
278+
{
279+
"user": "dropbox",
280+
"pass": "dropbox",
281+
"fs": "dropbox",
282+
"params": {
283+
"token": "..."
284+
}
285+
},
286+
{
287+
"user": "gdrive",
288+
"pass": "gdrive",
289+
"fs": "gdrive",
290+
"params": {
291+
"google_client_id": "***.apps.googleusercontent.com",
292+
"google_client_secret": "****",
293+
"base_path": "ftp"
294+
}
295+
},
296+
{
297+
"user": "s3",
298+
"pass": "s3",
299+
"fs": "s3",
300+
"params": {
301+
"endpoint": "https://s3.amazonaws.com",
302+
"region": "eu-west-1",
303+
"bucket": "my-bucket",
304+
"access_key_id": "AKIA....",
305+
"secret_access_key": "IDxd....",
306+
"disable_ssl": "false",
307+
"path_style": "false"
308+
}
309+
},
310+
{
311+
"user": "sftp",
312+
"pass": "sftp",
313+
"fs": "sftp",
314+
"shared": true,
315+
"read_only": true,
316+
"sync_and_delete": {
317+
"enable": true,
318+
"directory": "/tmp/snd"
319+
},
320+
"params": {
321+
"username": "user",
322+
"password": "password",
323+
"hostname": "192.168.168.11:22"
324+
}
325+
}]
326+
}
327+
}
328+
},
329+
"examples": []
330+
}

‎config/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Sample config files
2+
3+
## FTP Server behind a NAT gateway
4+
```json
5+
{
6+
"$schema": "https://raw.githubusercontent.com/fclairamb/ftpserver/main/config-schema.json",
7+
"listen_address": ":2121",
8+
"public_host": "1.2.3.4",
9+
"accesses": [
10+
{
11+
"user": "test",
12+
"pass": "test",
13+
"fs": "os",
14+
"params": {
15+
"basePath": "/tmp"
16+
}
17+
}
18+
]
19+
}
20+
```

‎config/confpar/samples/behind_nat.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/fclairamb/ftpserver/main/config-schema.json",
3+
"listen_address": ":2121",
4+
"public_host": "1.2.3.4",
5+
"accesses": [
6+
{
7+
"user": "test",
8+
"pass": "test",
9+
"fs": "os",
10+
"params": {
11+
"basePath": "/tmp"
12+
}
13+
}
14+
]
15+
}

0 commit comments

Comments
 (0)