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