source: rtems-docs/shell/configuration_and_init.rst @ 8ca13ed

4.115
Last change on this file since 8ca13ed was 8ca13ed, checked in by Amar Takhar <verm@…>, on 01/16/16 at 20:32:09

Split document.

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