-
Notifications
You must be signed in to change notification settings - Fork 112
/
lshell.1
460 lines (435 loc) · 10.6 KB
/
lshell.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
.\"
.\" Man page for the Limited Shell (lshell) project.
.\"
.TH lshell 1 "July, 2015" "v0.9.18"
.SH NAME
lshell \- Limited Shell
.SH SYNOPSIS
.B lshell
[\fIOPTIONS\fR]
.SH DESCRIPTION
\fBlshell\fR provides a limited shell configured per user.
The configuration is done quite simply using a configuration file.
Coupled with ssh's
.I authorized_keys
or with
.I /etc/shells
and
.I /etc/passwd
, it becomes very easy to restrict user's access to a limited set of command.
.SH OPTIONS
.TP
.B \--config \fI<FILE>\fR
Specify config file
.TP
.B \--log \fI<DIR>\fR
Specify the log directory
.TP
.B \--<param> \fI<value>\fR
where <param> is *any* config file parameter
.TP
.B \-h, --help
Show help message
.TP
.B \--version
Show version
.SH CONFIGURATION
You can configure lshell through its configuration file:
.RS
.ft 3
.nf
.sp
On Linux \-> /etc/lshell.conf
On *BSD \-> /usr/{pkg,local}/etc/lshell.conf
.ft
.LP
.RE
.fi
The configuration is dynamically reloaded. Which means that you can edit
the configuration, and all the connected users will automatically load it. In
case you are using multiple configuration files (see include_dir), you will
need to refresh the main configuration's timestamp, in order to reload the
configuration:
.RS
.ft 3
.nf
.sp
touch /path/to/lshell.conf
.ft
.LP
.RE
.fi
\fBlshell\fR configuration has 4 types of sections:
.RS
.ft 3
.nf
.sp
[global] -> lshell system configuration (only 1)
[default] -> lshell default user configuration (only 1)
[foo] -> UNIX username "foo" specific configuration
[grp:bar] -> UNIX groupname "bar" specific configuration
.ft
.LP
.RE
.fi
Order of priority when loading preferences is the following:
.RS
.ft 3
.nf
.sp
1- User configuration
2- Group configuration
3- Default configuration
.ft
.LP
.RE
.fi
.SS [global]
.TP
.I logpath
config path (default is /var/log/lshell/)
.TP
.I loglevel
0, 1, 2, 3 or 4 (0: no logs -> 4: logs everything)
.TP
.I logfilename
\- set to \fBsyslog\fR in order to log to syslog
.RS
\- set log file name, e.g. %u-%y%m%d (i.e foo-20091009.log):
.BR \ \ \ \ %u
-> username
.RE
.RS
.BR \ \ \ \ %d
-> day [1..31]
.RE
.RS
.BR \ \ \ \ %m
-> month [1..12]
.RE
.RS
.BR \ \ \ \ %y
-> year [00..99]
.RE
.RS
.BR \ \ \ \ %h
-> time [00:00..23:59]
.RE
.TP
.I syslogname
in case you are using syslog, set your logname (default: lshell)
.TP
.I include_dir
include a directory containing multiple configuration files.
These files can only contain default/user/group configuration. The
global configuration will only be loaded from the default configuration
file. This variable will be expanded (e.g. /path/*.conf).
.TP
.I path_noexec
set path to sudo noexec library. This path is usually autodetected, only set
this variable to use alternate path. If set and the shared object is not found,
lshell will exit immediately. Otherwise, please check your logs to verify that
a standard path is detected.
while this should not be a common practice, setting this variable to an empty
string will disable LD_PRELOAD prepend of the commands. This is done at your
own risk, as lshell becomes easily breached using some commands like find(1)
using the -exec flag.
.RS
.SS [default] and/or [username] and/or [grp:groupname]
.TP
.TP
.I aliases
command aliases list (similar to bash's alias directive)
.TP
.I allowed
a list of the allowed commands or set to 'all' to allow all commands in user's \
PATH
if sudo(8) is installed and sudo_noexec.so is available, it will be loaded
before running every command, preventing it from running further commands
itself. If not available, beware of commands like vim/find/more/etc. that will
allow users to execute code (e.g. /bin/sh) from within the application,
thus easily escaping lshell. See variable 'path_noexec' to use an alternative
path to library.
.TP
.I allowed_shell_escape
a list of the allowed commands that are permitted to execute other programs
(e.g. shell scripts with exec(3)). Setting this variable to 'all' is NOT
allowed. Warning: do not put here any command that can execute arbitrary
commands (e.g. find, vim, xargs).
important: commands defined in 'allowed_shell_escape' override their definition
in the \'allowed\' variable.
.TP
.I allowed_cmd_path
a list of path; all executable files inside these path will be allowed
.TP
.I disable_exit
disable user exit, this could be useful when lshell is spawned from another
none-restricted shell (e.g. bash)
.TP
.I env_path
update the environment variable $PATH of the user (optional)
.TP
.I env_vars
set environment variables (optional)
.TP
.I forbidden
a list of forbidden characters or commands
.TP
.I history_file
set the history filename. A wildcard can be used:
.RS
.BR \ \ \ \ %u
-> username (e.g. '/home/%u/.lhistory')
.RE
.TP
.I history_size
set the maximum size (in lines) of the history file
.TP
.I home_path (deprecated)
set the home folder of your user. If not specified, the home directory is set \
to the $HOME environment variable. This variable will be removed in the next \
version of lshell, please use your system's tools to set a user's home \
directory. A wildcard can be used:
.RS
.BR \ \ \ \ %u
-> username (e.g. '/home/%u')
.RE
.TP
.I intro
set the introduction to print at login
.TP
.I login_script
define the script to run at user login
.TP
.I passwd
password of specific user (default is empty)
.TP
.I path
list of path to restrict the user geographically. It is possible to use \
wildcards (e.g. '/var/log/ap*').
.TP
.I prompt
set the user's prompt format (default: username)
.RS
.BR \ \ \ \ %u
-> username
.RE
.RS
.BR \ \ \ \ %h
-> hostname
.RE
.TP
.I prompt_short
set prompt style for current directory - 0, 1 or 2. Default is 0.
.RS
.BR \ \ \ \ 0
-> will show the current directory as compared to home directory ~/current/dir
.RE
.RS
.BR \ \ \ \ 1
-> will only show the current directory name
.RE
.RS
.BR \ \ \ \ 2
-> will show the complete path to the current directory
.RE
.TP
.I overssh
list of command allowed to execute over ssh (e.g. rsync, rdiff-backup, scp, \
etc.)
.TP
.I scp
allow or forbid the use of scp connection - set to 1 or 0
.TP
.I scpforce
force files sent through scp to a specific directory
.TP
.I scp_download
set to 0 to forbid scp downloads (default is 1)
.TP
.I scp_upload
set to 0 to forbid scp uploads (default is 1)
.TP
.I sftp
allow or forbid the use of sftp connection - set to 1 or 0.
WARNING: This option will not work if you are using OpenSSH's \
internal-sftp service (e.g. when configured in chroot)
.TP
.I sudo_commands
a list of the allowed commands that can be used with sudo(8). If set to \
\'all', all the 'allowed' commands will be accessible through sudo(8).
It is possible to use the -u sudo flag in order to run a command as a \
different user than the default root.
.TP
.I timer
a value in seconds for the session timer
.TP
.I strict
logging strictness. If set to 1, any unknown command is considered as \
forbidden, and user's warning counter is decreased. If set to 0, command is \
considered as unknown, and user is only warned (i.e. *** unknown synthax)
.TP
.I warning_counter
number of warnings when user enters a forbidden value before getting exited \
from lshell. Set to \fB\-1\fR to disable the counter, and just warn the user.
.TP
.I winscp
enable support for WinSCP with scp mode (NOT sftp)
When enabled, the following parameters will be overridden:
.RS
.BR \ \ \ \ scp_upload :
1 (uses scp(1) from within session)
.RE
.RS
.BR \ \ \ \ scp_download:
1 (uses scp(1) from within session)
.RE
.RS
.BR \ \ \ \ scpforce :
ignored (uses scp(1) from within session)
.RE
.RS
.BR \ \ \ \ forbidden :
-[';']
.RE
.RS
.BR \ \ \ \ allowed :
+['scp', 'env', 'pwd', 'groups', 'unset', 'unalias']
.RE
.SH SHELL BUILTIN COMMANDS
Here is the set of commands that are always available with lshell:
.TP
.I clear
clears the terminal
.TP
.I export
name of exported shell variable. Disabled by default, enable it by adding it \
to allowed commands.
.TP
.I help, ?
print the list of allowed commands
.TP
. I history
print the commands history
.TP
. I lpath
lists all allowed and forbidden path
.TP
. I lsudo
lists all sudo allowed commands
.SH EXAMPLES
.TP
.B $ lshell
.RS
Tries to run lshell using default ${PREFIX}/etc/lshell.conf as configuration \
file. If it fails a warning is printed and lshell is interrupted.
lshell options are loaded from the configuration file
.RE
.TP
.B $ lshell --config /path/to/myconf.file --log /path/to/mylog.log
.RS
This will override the default options specified for configuration and/or log \
file
.RE
.SH USE CASE
The primary goal of lshell, was to be able to create shell accounts \
with ssh access and restrict their environment to a couple a needed \
commands.
In this example, User 'foo' and user 'bar' both belong to the 'users' UNIX \
group:
.TP
.B User foo:
.RS
- must be able to access /usr and /var but not /usr/local
- user all command in his PATH but 'su'
- has a warning counter set to 5
- has his home path set to '/home/users'
.RE
.TP
.B User bar:
.RS
- must be able to access /etc and /usr but not /usr/local
- is allowed default commands plus 'ping' minus 'ls'
- strictness is set to 1 (meaning he is not allowed to type an unknown command)
.RE
In this case, my configuration file will look something like this:
.RS
.ft 3
.nf
.sp
# CONFIURATION START
[global]
logpath : /var/log/lshell/
loglevel : 2
[default]
allowed : ['ls','pwd']
forbidden : [';', '&', '|']
warning_counter : 2
timer : 0
path : ['/etc', '/usr']
env_path : ':/sbin:/usr/bin/'
scp : 1 # or 0
sftp : 1 # or 0
overssh : ['rsync','ls']
aliases : {'ls':'ls \-\-color=auto','ll':'ls \-l'}
[grp:users]
warning_counter : 5
overssh : - ['ls']
[foo]
allowed : 'all' - ['su']
path : ['/var', '/usr'] - ['/usr/local']
home_path : '/home/users'
[bar]
allowed : + ['ping'] - ['ls']
path : - ['/usr/local']
strict : 1
scpforce : '/home/bar/uploads/'
# CONFIURATION END
.ft
.LP
.RE
.fi
.SH NOTES
.TP
In order to log a user's warnings into the logging directory (default \
\fI/var/log/lshell/\fR) , you must firt create the folder (if it doesn't \
exist yet) and chown it to lshell group:
.RS
.ft 3
.nf
.sp
# addgroup \-\-system lshell
# mkdir /var/log/lshell
# chown :lshell /var/log/lshell
# chmod 770 /var/log/lshell
.ft
.LP
.RE
.fi
then add the user to the \fIlshell\fR group:
.RS
.ft 3
.nf
.sp
# usermod \-aG lshell user_name
.ft
.LP
.RE
.fi
In order to set lshell as default shell for a user:
.RS
.ft 3
.nf
.sp
On Linux:
# chsh \-s /usr/bin/lshell user_name
On *BSD:
# chsh \-s /usr/{pkg,local}/bin/lshell user_name
.ft
.LP
.RE
.fi
.SH AUTHOR
Currently maintained by Ignace Mouzannar (ghantoos)
.SH EMAIL
Feel free to send me your recommendations at <ghantoos@ghantoos.org>