1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
4 | |
---|
5 | Configuration and Initialization |
---|
6 | ******************************** |
---|
7 | |
---|
8 | Introduction |
---|
9 | ============ |
---|
10 | |
---|
11 | This chapter provides information on how the application configures and |
---|
12 | initializes the RTEMS shell. |
---|
13 | |
---|
14 | Configuration |
---|
15 | ============= |
---|
16 | |
---|
17 | The command set available to the application is user configurable. It is |
---|
18 | configured using a mechanism similar to the ``confdefs.h`` mechanism used to |
---|
19 | specify application configuration. |
---|
20 | |
---|
21 | In the simplest case, if the user wishes to configure a command set with all |
---|
22 | commands available that are neither filesystem management (e.g. mounting, |
---|
23 | formating, etc.) or network related, then the following is all that is |
---|
24 | required: |
---|
25 | |
---|
26 | .. code-block:: c |
---|
27 | |
---|
28 | #define CONFIGURE_SHELL_COMMANDS_INIT |
---|
29 | #define CONFIGURE_SHELL_COMMANDS_ALL |
---|
30 | #include <rtems/shellconfig.h> |
---|
31 | |
---|
32 | In a slightly more complex example, if the user wishes to include all |
---|
33 | networking commands as well as support for mounting MS-DOS and NFS filesystems, |
---|
34 | then the following is all that is required: |
---|
35 | |
---|
36 | .. code-block:: c |
---|
37 | |
---|
38 | #define CONFIGURE_SHELL_COMMANDS_INIT |
---|
39 | #define CONFIGURE_SHELL_COMMANDS_ALL |
---|
40 | #define CONFIGURE_SHELL_MOUNT_MSDOS |
---|
41 | #define CONFIGURE_SHELL_MOUNT_NFS |
---|
42 | #include <rtems/shellconfig.h> |
---|
43 | |
---|
44 | The shell uses a POSIX key to reference the shell's per thread environment. A |
---|
45 | user's application needs to account for this key. If the application has a |
---|
46 | configuration for POSIX keys add one extra for the shell. If there is no |
---|
47 | entry add to the configuration: |
---|
48 | |
---|
49 | .. code-block:: c |
---|
50 | |
---|
51 | #define CONFIGURE_MAXIMUM_POSIX_KEYS (5) |
---|
52 | |
---|
53 | Customizing the Command Set |
---|
54 | --------------------------- |
---|
55 | |
---|
56 | The user can configure specific command sets by either building up the set from |
---|
57 | individual commands or starting with a complete set and disabling individual |
---|
58 | commands. Each command has two configuration macros associated with it. |
---|
59 | |
---|
60 | *CONFIGURE_SHELL_COMMAND_XXX* |
---|
61 | Each command has a constant of this form which is defined when |
---|
62 | building a command set by individually enabling specific |
---|
63 | commands. |
---|
64 | |
---|
65 | *CONFIGURE_SHELL_NO_COMMAND_XXX* |
---|
66 | In contrast, each command has a similar command which is |
---|
67 | defined when the application is configuring a command set |
---|
68 | by disabling specific commands in the set. |
---|
69 | |
---|
70 | Adding Custom Commands |
---|
71 | ---------------------- |
---|
72 | |
---|
73 | One of the design goals of the RTEMS Shell was to make it easy for a user to |
---|
74 | add custom commands specific to their application. We believe this design goal |
---|
75 | was accomplished. In order to add a custom command, the user is required to do |
---|
76 | the following: |
---|
77 | |
---|
78 | - Provide a *main-style* function which implements the command. If that |
---|
79 | command function uses a ``getopt`` related function to parse arguments, it |
---|
80 | *MUST* use the reentrant form. |
---|
81 | |
---|
82 | - Provide a command definition structure of type ``rtems_shell_cmd_t``. |
---|
83 | |
---|
84 | - Configure that command using the ``CONFIGURE_SHELL_USER_COMMANDS`` macro. |
---|
85 | |
---|
86 | Custom aliases are configured similarly but the user only provides an alias |
---|
87 | definition structure of type ``rtems_shell_alias_t`` and configures the alias |
---|
88 | via the ``CONFIGURE_SHELL_USER_ALIASES`` macro. |
---|
89 | |
---|
90 | In the following example, we have implemented a custom command named |
---|
91 | ``usercmd`` which simply prints the arguments it was passed. We have also |
---|
92 | provided an alias for ``usercmd`` named ``userecho``. |
---|
93 | |
---|
94 | .. code-block:: c |
---|
95 | |
---|
96 | #include <rtems/shell.h> |
---|
97 | int main_usercmd(int argc, char **argv) |
---|
98 | { |
---|
99 | int i; |
---|
100 | printf( "UserCommand: argc=%d\n", argc ); |
---|
101 | for (i=0 ; i<argc ; i++ ) |
---|
102 | printf( "argv[%d]= %s\n", i, argv[i] ); |
---|
103 | return 0; |
---|
104 | } |
---|
105 | rtems_shell_cmd_t Shell_USERCMD_Command = { |
---|
106 | "usercmd", /* name */ |
---|
107 | "usercmd n1 \[n2 \[n3...]]", /* usage */ |
---|
108 | "user", /* topic */ |
---|
109 | main_usercmd, /* command */ |
---|
110 | NULL, /* alias */ |
---|
111 | NULL /* next */ |
---|
112 | }; |
---|
113 | rtems_shell_alias_t Shell_USERECHO_Alias = { |
---|
114 | "usercmd", /* command */ |
---|
115 | "userecho" /* alias */ |
---|
116 | }; |
---|
117 | #define CONFIGURE_SHELL_USER_COMMANDS &Shell_USERCMD_Command |
---|
118 | #define CONFIGURE_SHELL_USER_ALIASES &Shell_USERECHO_Alias |
---|
119 | #define CONFIGURE_SHELL_COMMANDS_INIT |
---|
120 | #define CONFIGURE_SHELL_COMMANDS_ALL |
---|
121 | #define CONFIGURE_SHELL_MOUNT_MSDOS |
---|
122 | #include <rtems/shellconfig.h> |
---|
123 | |
---|
124 | Notice in the above example, that the user wrote the *main* for their command |
---|
125 | (e.g. ``main_usercmd``) which looks much like any other ``main()``. They then |
---|
126 | defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which |
---|
127 | describes that command. This command definition structure is registered into |
---|
128 | the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS`` |
---|
129 | to ``&Shell_USERCMD_Command``. |
---|
130 | |
---|
131 | Similarly, to add the ``userecho`` alias, the user provides the alias |
---|
132 | definition structure named ``Shell_USERECHO_Alias`` and defines |
---|
133 | ``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias. |
---|
134 | |
---|
135 | The user can configure any number of commands and aliases in this manner. |
---|
136 | |
---|
137 | Initialization |
---|
138 | ============== |
---|
139 | |
---|
140 | The shell may be easily attached to a serial port or to the ``telnetd`` server. |
---|
141 | This section describes how that is accomplished. |
---|
142 | |
---|
143 | Attached to a Serial Port |
---|
144 | ------------------------- |
---|
145 | |
---|
146 | Starting the shell attached to the console or a serial port is very simple. The |
---|
147 | user invokes ``rtems_shell_init`` with parameters to indicate the |
---|
148 | characteristics of the task that will be executing the shell including name, |
---|
149 | stack size, and priority. The user also specifies the device that the shell is |
---|
150 | to be attached to. |
---|
151 | |
---|
152 | This example is taken from the ``fileio`` sample test. This shell portion of |
---|
153 | this test can be run on any target which provides a console with input and |
---|
154 | output capabilities. It does not include any commands which cannot be |
---|
155 | supported on all BSPs. The source code for this test is in |
---|
156 | ``testsuites/samples/fileio`` with the shell configuration in the ``init.c`` |
---|
157 | file. |
---|
158 | |
---|
159 | .. code-block:: c |
---|
160 | |
---|
161 | #include <rtems/shell.h> |
---|
162 | void start_shell(void) |
---|
163 | { |
---|
164 | printf(" =========================\n"); |
---|
165 | printf(" starting shell\n"); |
---|
166 | printf(" =========================\n"); |
---|
167 | rtems_shell_init( |
---|
168 | "SHLL", /* task name */ |
---|
169 | RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */ |
---|
170 | 100, /* task priority */ |
---|
171 | "/dev/console", /* device name */ |
---|
172 | false, /* run forever */ |
---|
173 | true, /* wait for shell to terminate */ |
---|
174 | rtems_shell_login_check /* login check function, |
---|
175 | use NULL to disable a login check */ |
---|
176 | ); |
---|
177 | } |
---|
178 | |
---|
179 | In the above example, the call to ``rtems_shell_init`` spawns a task to run the |
---|
180 | RTEMS Shell attached to ``/dev/console`` and executing at priority 100. The |
---|
181 | caller suspends itself and lets the shell take over the console device. When |
---|
182 | the shell is exited by the user, then control returns to the caller. |
---|
183 | |
---|
184 | Attached to a Socket |
---|
185 | -------------------- |
---|
186 | |
---|
187 | TBD |
---|
188 | |
---|
189 | Access Control |
---|
190 | ============== |
---|
191 | |
---|
192 | Login Checks |
---|
193 | ------------ |
---|
194 | |
---|
195 | Login checks are optional for the RTEMS shell and can be configured via a login |
---|
196 | check handler passed to ``rtems_shell_init()``. One login check handler |
---|
197 | is ``rtems_shell_login_check()``. |
---|
198 | |
---|
199 | Configuration Files |
---|
200 | ------------------- |
---|
201 | |
---|
202 | The following files are used by the login check handler |
---|
203 | ``rtems_shell_login_check()`` to validate a passphrase for a user and to set up |
---|
204 | the user environment for the shell command execution. |
---|
205 | |
---|
206 | :file:`/etc/passwd` |
---|
207 | The format for each line is |
---|
208 | |
---|
209 | .. code:: c |
---|
210 | |
---|
211 | user_name:password:UID:GID:GECOS:directory:shell |
---|
212 | |
---|
213 | with colon separated fields. For more information refer to the Linux |
---|
214 | PASSWD(5) man page. Use a ``password`` of ``*`` to disable the login of the |
---|
215 | user. An empty password allows login without a password for this user. In |
---|
216 | contrast to standard UNIX systems, this file is only readable and writeable |
---|
217 | for the user with an UID of zero by default. The ``directory`` is used to |
---|
218 | perform a filesystem change root operation in ``rtems_shell_login_check()`` |
---|
219 | in contrast to a normal usage as the HOME directory of the user. |
---|
220 | The *default* content is: |
---|
221 | |
---|
222 | .. code:: c |
---|
223 | |
---|
224 | root::0:0:::: |
---|
225 | |
---|
226 | so there is *no password required* for the ``root`` user. |
---|
227 | |
---|
228 | :file:`/etc/group` |
---|
229 | The format for each line is: |
---|
230 | |
---|
231 | .. code:: c |
---|
232 | |
---|
233 | group_name:password:GID:user_list |
---|
234 | |
---|
235 | with colon separated fields. The ``user_list`` is comma separated. For |
---|
236 | more information refer to the Linux GROUP(5) man page. In contrast to |
---|
237 | standard UNIX systems, this file is only readable and writeable for the |
---|
238 | user with an UID of zero by default. The default content is |
---|
239 | |
---|
240 | .. code:: c |
---|
241 | |
---|
242 | root::0: |
---|
243 | |
---|
244 | Command Visibility and Execution Permission |
---|
245 | ------------------------------------------- |
---|
246 | |
---|
247 | Each command has: |
---|
248 | |
---|
249 | - an owner, |
---|
250 | |
---|
251 | - a group, and |
---|
252 | |
---|
253 | - a read permission flag for the owner, the group and all other users, and |
---|
254 | |
---|
255 | - an execution permission flag for the owner, the group and all other |
---|
256 | users. |
---|
257 | |
---|
258 | The read and write permission flags are stored in the command mode. The read |
---|
259 | permission flags determine the visibility of the command for the current user. |
---|
260 | The execution permission flags determine the ability to execute a command for |
---|
261 | the current user. These command properties can be displayed and changed with |
---|
262 | the: |
---|
263 | |
---|
264 | - ``cmdls``, |
---|
265 | |
---|
266 | - ``cmdchown``, and |
---|
267 | |
---|
268 | - ``cmdchmod`` |
---|
269 | |
---|
270 | commands. The access is determined by the effective UID, the effective GID and |
---|
271 | the supplementary group IDs of the current user and follows the standard |
---|
272 | filesystem access procedure. |
---|
273 | |
---|
274 | Add CRYPT(3) Formats |
---|
275 | -------------------- |
---|
276 | |
---|
277 | By default the ``crypt_r()`` function used by ``rtems_shell_login_check()`` |
---|
278 | supports only plain text passphrases. Use ``crypt_add_format()`` to add more |
---|
279 | formats. The following formats are available out of the box: |
---|
280 | |
---|
281 | - ``crypt_md5_format``, |
---|
282 | |
---|
283 | - ``crypt_sha256_format``, and |
---|
284 | |
---|
285 | - ``crypt_sha512_format``. |
---|
286 | |
---|
287 | An example follows: |
---|
288 | |
---|
289 | .. index:: crypt_add_format |
---|
290 | |
---|
291 | .. code:: c |
---|
292 | |
---|
293 | #include <crypt.h> |
---|
294 | void add_formats( void ) |
---|
295 | { |
---|
296 | crypt_add_format( &crypt_md5_format ); |
---|
297 | crypt_add_format( &crypt_sha512_format ); |
---|
298 | } |
---|
299 | |
---|
300 | Functions |
---|
301 | ========= |
---|
302 | |
---|
303 | This section describes the Shell related C functions which are publicly |
---|
304 | available related to initialization and configuration. |
---|
305 | |
---|
306 | .. raw:: latex |
---|
307 | |
---|
308 | \clearpage |
---|
309 | |
---|
310 | rtems_shell_init - Initialize the shell |
---|
311 | --------------------------------------- |
---|
312 | .. index:: initialization |
---|
313 | .. index:: rtems_shell_init |
---|
314 | |
---|
315 | CALLING SEQUENCE: |
---|
316 | .. code-block:: c |
---|
317 | |
---|
318 | rtems_status_code rtems_shell_init( |
---|
319 | const char *task_name, |
---|
320 | size_t task_stacksize, |
---|
321 | rtems_task_priority task_priority, |
---|
322 | const char *devname, |
---|
323 | bool forever, |
---|
324 | bool wait, |
---|
325 | rtems_login_check login_check |
---|
326 | ); |
---|
327 | |
---|
328 | DIRECTIVE STATUS CODES: |
---|
329 | ``RTEMS_SUCCESSFUL`` - Shell task spawned successfully |
---|
330 | *others* - to indicate a failure condition |
---|
331 | |
---|
332 | DESCRIPTION: |
---|
333 | This service creates a task with the specified characteristics to run the RTEMS |
---|
334 | Shell attached to the specified ``devname``. |
---|
335 | |
---|
336 | NOTES: |
---|
337 | This method invokes the ``rtems_task_create`` and ``rtems_task_start`` |
---|
338 | directives and as such may return any status code that those directives may |
---|
339 | return. |
---|
340 | |
---|
341 | There is one POSIX key necessary for all shell instances together and one |
---|
342 | POSIX key value pair per instance. You should make sure that your RTEMS |
---|
343 | configuration accounts for these resources. |
---|
344 | |
---|
345 | .. raw:: latex |
---|
346 | |
---|
347 | \clearpage |
---|
348 | |
---|
349 | rtems_shell_login_check - Default login check handler |
---|
350 | ----------------------------------------------------- |
---|
351 | .. index:: initialization |
---|
352 | .. index:: rtems_shell_login_check |
---|
353 | |
---|
354 | CALLING SEQUENCE: |
---|
355 | .. code:: c |
---|
356 | |
---|
357 | bool rtems_shell_login_check( |
---|
358 | const char *user, |
---|
359 | const char *passphrase |
---|
360 | ); |
---|
361 | |
---|
362 | DIRECTIVE STATUS CODES: |
---|
363 | ``true`` - login is allowed, and |
---|
364 | ``false`` - otherwise. |
---|
365 | |
---|
366 | DESCRIPTION: |
---|
367 | This function checks if the specified passphrase is valid for the specified |
---|
368 | user. |
---|
369 | |
---|
370 | NOTES: |
---|
371 | As a side-effect if the specified passphrase is valid for the specified |
---|
372 | user, this function: |
---|
373 | |
---|
374 | - performs a filesystem change root operation to the directory of the |
---|
375 | specified user if the directory path is non-empty, |
---|
376 | |
---|
377 | - changes the owner of the current shell device to the UID of the specified |
---|
378 | user, |
---|
379 | |
---|
380 | - sets the real and effective UID of the current user environment to the |
---|
381 | UID of the specified user, |
---|
382 | |
---|
383 | - sets the real and effective GID of the current user environment to the |
---|
384 | GID of the specified user, and |
---|
385 | |
---|
386 | - sets the supplementary group IDs of the current user environment to the |
---|
387 | supplementary group IDs of the specified user. |
---|
388 | |
---|
389 | In case the filesystem change root operation fails, then the environment |
---|
390 | setup is aborted and ``false`` is returned. |
---|