1lshell(1) General Commands Manual lshell(1)
2
6 lshell - Limited Shell
7
10 lshell [OPTIONS]
11
14 lshell provides a limited shell configured per user. The configuration
15 is done quite simply using a configuration file. Coupled with ssh's
16 authorized_keys or with /etc/shells and /etc/passwd , it becomes very
17 easy to restrict user's access to a limited set of command.
18
21 --config <FILE>
22 Specify config file
23 --log <DIR>
25 Specify the log directory
26 --<param> <value>
28 where <param> is *any* config file parameter
29 -h, --help
31 Show help message
32 --version
34 Show version
35
38 You can configure lshell through its configuration file:
39 On Linux -> /etc/lshell.conf
41 On *BSD -> /usr/{pkg,local}/etc/lshell.conf
42 The configuration is dynamically reloaded. Which means that you can
44 edit the configuration, and all the connected users will automatically
45 load it. In case you are using multiple configuration files (see
46 include_dir), you will need to refresh the main configuration's time‐
47 stamp, in order to reload the configuration:
48 touch /path/to/lshell.conf
50 lshell configuration has 4 types of sections:
52 [global] -> lshell system configuration (only 1)
54 [default] -> lshell default user configuration (only 1)
55 [foo] -> UNIX username "foo" specific configuration
56 [grp:bar] -> UNIX groupname "bar" specific configuration
57 Order of priority when loading preferences is the following:
59 1- User configuration
61 2- Group configuration
62 3- Default configuration
63 [global]
65 logpath
66 config path (default is /var/log/lshell/)
67 loglevel
69 0, 1, 2, 3 or 4 (0: no logs -> 4: logs everything)
70 logfilename
72 - set to syslog in order to log to syslog
73 - set log file name, e.g. %u-%y%m%d (i.e foo-20091009.log):
74 %u -> username
75 %d -> day [1..31]
76 %m -> month [1..12]
77 %y -> year [00..99]
78 %h -> time [00:00..23:59]
79 syslogname
81 in case you are using syslog, set your logname (default: lshell)
82 include_dir
84 include a directory containing multiple configuration files.
85 These files can only contain default/user/group configuration.
86 The global configuration will only be loaded from the default
87 configuration file. This variable will be expanded (e.g.
88 /path/*.conf).
89 path_noexec
91 set path to sudo noexec library. This path is usually autode‐
92 tected, only set this variable to use alternate path. If set and
93 the shared object is not found, lshell will exit immediately.
94 Otherwise, please check your logs to verify that a standard path
95 is detected.
96 [default] and/or [username] and/or [grp:groupname]
98 aliases
99 command aliases list (similar to bash's alias directive)
100 allowed
102 a list of the allowed commands or set to 'all' to allow
103 all commands in user's PATH
104 if sudo(8) is installed and sudo_noexec.so is available,
106 it will be loaded before running every command, prevent‐
107 ing it from running further commands itself. If not
108 available, beware of commands like vim/find/more/etc.
109 that will allow users to execute code (e.g. /bin/sh) from
110 within the application, thus easily escaping lshell. See
111 variable 'path_noexec' to use an alternative path to
112 library.
113 allowed_shell_escape
115 a list of the allowed commands that are permitted to exe‐
116 cute other programs (e.g. shell scripts with exec(3)).
117 Setting this variable to 'all' is NOT allowed. Warning:
118 do not put here any command that can execute arbitrary
119 commands (e.g. find, vim, xargs).
120 important: commands defined in 'allowed_shell_escape'
122 override their definition in the ´allowed´ variable.
123 allowed_cmd_path
125 a list of path; all executable files inside these path
126 will be allowed
127 env_path
129 update the environment variable $PATH of the user
130 (optional)
131 env_vars
133 set environment variables (optional)
134 forbidden
136 a list of forbidden characters or commands
137 history_file
139 set the history filename. A wildcard can be used:
140 %u -> username (e.g. '/home/%u/.lhistory')
141 history_size
143 set the maximum size (in lines) of the history file
144 home_path (deprecated)
146 set the home folder of your user. If not specified, the
147 home directory is set to the $HOME environment variable.
148 This variable will be removed in the next version of
149 lshell, please use your system's tools to set a user's
150 home directory. A wildcard can be used:
151 %u -> username (e.g. '/home/%u')
152 intro set the introduction to print at login
154 login_script
156 define the script to run at user login
157 passwd password of specific user (default is empty)
159 path list of path to restrict the user geographically. It is
161 possible to use wildcards (e.g. '/var/log/ap*').
162 prompt set the user's prompt format (default: username)
164 %u -> username
165 %h -> hostname
166 prompt_short
168 set prompt style for current directory - 0, 1 or 2.
169 Default is 0.
170 0 -> will show the current directory as compared to
171 home directory ~/current/dir
172 1 -> will only show the current directory name
173 2 -> will show the complete path to the current
174 directory
175 overssh
177 list of command allowed to execute over ssh (e.g. rsync,
178 rdiff-backup, scp, etc.)
179 scp allow or forbid the use of scp connection - set to 1 or 0
181 scpforce
183 force files sent through scp to a specific directory
184 scp_download
186 set to 0 to forbid scp downloads (default is 1)
187 scp_upload
189 set to 0 to forbid scp uploads (default is 1)
190 sftp allow or forbid the use of sftp connection - set to 1 or
192 0.
193 WARNING: This option will not work if you are using
195 OpenSSH's internal-sftp service (e.g. when configured in
196 chroot)
197 sudo_commands
199 a list of the allowed commands that can be used with
200 sudo(8). If set to ´all', all the 'allowed' commands will
201 be accessible through sudo(8).
202 It is possible to use the -u sudo flag in order to run a
204 command as a different user than the default root.
205 timer a value in seconds for the session timer
207 strict logging strictness. If set to 1, any unknown command is
209 considered as forbidden, and user's warning counter is
210 decreased. If set to 0, command is considered as unknown,
211 and user is only warned (i.e. *** unknown synthax)
212 warning_counter
214 number of warnings when user enters a forbidden value
215 before getting exited from lshell. Set to -1 to disable
216 the counter, and just warn the user.
217 winscp enable support for WinSCP with scp mode (NOT sftp)
219 When enabled, the following parameters will be overrid‐
221 den:
222 scp_upload: 1 (uses scp(1) from within session)
223 scp_download: 1 (uses scp(1) from within session)
224 scpforce: ignored (uses scp(1) from within session)
225 forbidden: -[';']
226 allowed: +['scp', 'env', 'pwd', 'groups', 'unset',
227 'unalias']
228
231 Here is the set of commands that are always available with
232 lshell:
233 clear clears the terminal
235 export name of exported shell variable. Disabled by default,
237 enable it by adding it to allowed commands.
238 help, ?
240 print the list of allowed commands
241 history
243 print the commands history
244 lpath lists all allowed and forbidden path
246 lsudo lists all sudo allowed commands
248
251 $ lshell
252 Tries to run lshell using default ${PRE‐
253 FIX}/etc/lshell.conf as configuration file. If it fails a
254 warning is printed and lshell is interrupted. lshell
255 options are loaded from the configuration file
256 $ lshell --config /path/to/myconf.file --log /path/to/mylog.log
258 This will override the default options specified for con‐
259 figuration and/or log file
260
263 The primary goal of lshell, was to be able to create shell
264 accounts with ssh access and restrict their environment to a
265 couple a needed commands. In this example, User 'foo' and user
266 'bar' both belong to the 'users' UNIX group:
267 User foo:
269 - must be able to access /usr and /var but not
270 /usr/local
271 - user all command in his PATH but 'su'
272 - has a warning counter set to 5
273 - has his home path set to '/home/users'
274 User bar:
276 - must be able to access /etc and /usr but not
277 /usr/local
278 - is allowed default commands plus 'ping' minus 'ls'
279 - strictness is set to 1 (meaning he is not allowed to
280 type an unknown command)
281 In this case, my configuration file will look something like
283 this:
284 # CONFIURATION START
286 [global]
287 logpath : /var/log/lshell/
288 loglevel : 2
289 [default]
291 allowed : ['ls','pwd']
292 forbidden : [';', '&', '|']
293 warning_counter : 2
294 timer : 0
295 path : ['/etc', '/usr']
296 env_path : ':/sbin:/usr/bin/'
297 scp : 1 # or 0
298 sftp : 1 # or 0
299 overssh : ['rsync','ls']
300 aliases : {'ls':'ls --color=auto','ll':'ls -l'}
301 [grp:users]
303 warning_counter : 5
304 overssh : - ['ls']
305 [foo]
307 allowed : 'all' - ['su']
308 path : ['/var', '/usr'] - ['/usr/local']
309 home_path : '/home/users'
310 [bar]
312 allowed : + ['ping'] - ['ls']
313 path : - ['/usr/local']
314 strict : 1
315 scpforce : '/home/bar/uploads/'
316 # CONFIURATION END
317
319 In order to log a user's warnings into the logging directory
320 (default /var/log/lshell/) , you must firt create the folder (if
321 it doesn't exist yet) and chown it to lshell group:
322 # addgroup --system lshell
324 # mkdir /var/log/lshell
325 # chown :lshell /var/log/lshell
326 # chmod 770 /var/log/lshell
327 then add the user to the lshell group:
329 # usermod -aG lshell user_name
331 In order to set lshell as default shell for a user:
333 On Linux:
335 # chsh -s /usr/bin/lshell user_name
336 On *BSD:
338 # chsh -s /usr/{pkg,local}/bin/lshell user_name
339
341 Currently maintained by Ignace Mouzannar (ghantoos)
342
345 Feel free to send me your recommendations at <ghantoos@ghan‐
346 toos.org>
347v0.9.18 July, 2015 lshell(1)