source: rtems-docs/shell/configuration_and_init.rst @ 9aafb39

4.115
Last change on this file since 9aafb39 was 489740f, checked in by Chris Johns <chrisj@…>, on 05/20/16 at 02:47:09

Set SPDX License Identifier in each source file.

  • Property mode set to 100644
File size: 12.2 KB
Line 
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
7Configuration and Initialization
8################################
9
10Introduction
11============
12
13This chapter provides information on how the application configures and
14initializes the RTEMS shell.
15
16Configuration
17=============
18
19The command set available to the application is user configurable.  It is
20configured using a mechanism similar to the ``confdefs.h`` mechanism used to
21specify application configuration.
22
23In the simplest case, if the user wishes to configure a command set with all
24commands available that are neither filesystem management (e.g. mounting,
25formating, etc.) or network related, then the following is all that is
26required:
27
28.. code-block:: c
29
30    #define CONFIGURE_SHELL_COMMANDS_INIT
31    #define CONFIGURE_SHELL_COMMANDS_ALL
32    #include <rtems/shellconfig.h>
33
34In a slightly more complex example, if the user wishes to include all
35networking commands as well as support for mounting MS-DOS and NFS filesystems,
36then 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
46Customizing the Command Set
47---------------------------
48
49The user can configure specific command sets by either building up the set from
50individual commands or starting with a complete set and disabling individual
51commands.  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
63Adding Custom Commands
64----------------------
65
66One of the design goals of the RTEMS Shell was to make it easy for a user to
67add custom commands specific to their application.  We believe this design goal
68was accomplished.  In order to add a custom command, the user is required to do
69the 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
79Custom aliases are configured similarly but the user only provides an alias
80definition structure of type ``rtems_shell_alias_t`` and configures the alias
81via the ``CONFIGURE_SHELL_USER_ALIASES`` macro.
82
83In the following example, we have implemented a custom command named
84``usercmd`` which simply prints the arguments it was passed. We have also
85provided 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
117Notice 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
119defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which
120describes that command.  This command definition structure is registered into
121the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS``
122to ``&Shell_USERCMD_Command``.
123
124Similarly, to add the ``userecho`` alias, the user provides the alias
125definition structure named ``Shell_USERECHO_Alias`` and defines
126``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias.
127
128The user can configure any number of commands and aliases in this manner.
129
130Initialization
131==============
132
133The shell may be easily attached to a serial port or to the ``telnetd`` server.
134This section describes how that is accomplished.
135
136Attached to a Serial Port
137-------------------------
138
139Starting the shell attached to the console or a serial port is very simple. The
140user invokes ``rtems_shell_init`` with parameters to indicate the
141characteristics of the task that will be executing the shell including name,
142stack size, and priority.  The user also specifies the device that the shell is
143to be attached to.
144
145This example is taken from the ``fileio`` sample test.  This shell portion of
146this test can be run on any target which provides a console with input and
147output capabilities.  It does not include any commands which cannot be
148supported on all BSPs.  The source code for this test is in
149``testsuites/samples/fileio`` with the shell configuration in the ``init.c``
150file.
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
172In the above example, the call to ``rtems_shell_init`` spawns a task to run the
173RTEMS Shell attached to ``/dev/console`` and executing at priority 100.  The
174caller suspends itself and lets the shell take over the console device.  When
175the shell is exited by the user, then control returns to the caller.
176
177Attached to a Socket
178--------------------
179
180TBD
181
182Access Control
183==============
184
185Login Checks
186------------
187
188Login checks are optional for the RTEMS shell and can be configured via a login
189check handler passed to ``rtems_shell_init()``.  One login check handler
190is ``rtems_shell_login_check()``.
191
192Configuration Files
193-------------------
194
195The 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
197the 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
237Command Visibility and Execution Permission
238-------------------------------------------
239
240Each 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
251The read and write permission flags are stored in the command mode.  The read
252permission flags determine the visibility of the command for the current user.
253The execution permission flags determine the ability to execute a command for
254the current user.  These command properties can be displayed and changed with
255the:
256
257- ``cmdls``,
258
259- ``cmdchown``, and
260
261- ``cmdchmod``
262
263commands.  The access is determined by the effective UID, the effective GID and
264the supplementary group IDs of the current user and follows the standard
265filesystem access procedure.
266
267Add CRYPT(3) Formats
268--------------------
269
270By default the ``crypt_r()`` function used by ``rtems_shell_login_check()``
271supports only plain text passphrases.  Use ``crypt_add_format()`` to add more
272formats.  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
280An 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
293Functions
294=========
295
296This section describes the Shell related C functions which are publicly
297available related to initialization and configuration.
298
299rtems_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
323others - to indicate a failure condition
324
325**DESCRIPTION:**
326
327This service creates a task with the specified characteristics to run the RTEMS
328Shell attached to the specified ``devname``.
329
330**NOTES:**
331
332This method invokes the ``rtems_task_create`` and ``rtems_task_start``
333directives and as such may return any status code that those directives may
334return.
335
336There is one POSIX key necessary for all shell instances together and one POSIX
337key value pair per instance. You should make sure that your RTEMS configuration
338accounts for these resources.
339
340rtems_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
362This function checks if the specified passphrase is valid for the specified
363user.
364
365**NOTES:**
366
367As a side-effect if the specified passphrase is valid for the specified user,
368this 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
385In case the filesystem change root operation fails, then the environment setup
386is aborted and ``false`` is returned.
Note: See TracBrowser for help on using the repository browser.