diff options
author | Amar Takhar <verm@darkbeer.org> | 2016-01-16 15:32:09 -0500 |
---|---|---|
committer | Amar Takhar <verm@darkbeer.org> | 2016-05-02 20:51:22 -0400 |
commit | 8ca13ed19f5b90bc53a7b2db26fb736d45e6007b (patch) | |
tree | 52bd4d9cb5def7d75cbc4e5d67f9642985b7458f /shell/configuration_and_init.rst | |
parent | Clean up the alias command. (diff) | |
download | rtems-docs-8ca13ed19f5b90bc53a7b2db26fb736d45e6007b.tar.bz2 |
Split document.
Diffstat (limited to 'shell/configuration_and_init.rst')
-rw-r--r-- | shell/configuration_and_init.rst | 381 |
1 files changed, 381 insertions, 0 deletions
diff --git a/shell/configuration_and_init.rst b/shell/configuration_and_init.rst new file mode 100644 index 0000000..ab66c92 --- /dev/null +++ b/shell/configuration_and_init.rst @@ -0,0 +1,381 @@ +Configuration and Initialization +################################ + +Introduction +============ + +This chapter provides information on how the application configures and +initializes the RTEMS shell. + +Configuration +============= + +The command set available to the application is user configurable. It is +configured using a mechanism similar to the ``confdefs.h`` mechanism used to +specify application configuration. + +In the simplest case, if the user wishes to configure a command set with all +commands available that are neither filesystem management (e.g. mounting, +formating, etc.) or network related, then the following is all that is +required: + +.. code-block:: c + + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #include <rtems/shellconfig.h> + +In a slightly more complex example, if the user wishes to include all +networking commands as well as support for mounting MS-DOS and NFS filesystems, +then the following is all that is required: + +.. code-block:: c + + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #define CONFIGURE_SHELL_MOUNT_MSDOS + #define CONFIGURE_SHELL_MOUNT_NFS + #include <rtems/shellconfig.h> + +Customizing the Command Set +--------------------------- + +The user can configure specific command sets by either building up the set from +individual commands or starting with a complete set and disabling individual +commands. Each command has two configuration macros associated with it. + +*CONFIGURE_SHELL_COMMAND_XXX* + Each command has a constant of this form which is defined when + building a command set by individually enabling specific + commands. + +*CONFIGURE_SHELL_NO_COMMAND_XXX* + In contrast, each command has a similar command which is + defined when the application is configuring a command set + by disabling specific commands in the set. + +Adding Custom Commands +---------------------- + +One of the design goals of the RTEMS Shell was to make it easy for a user to +add custom commands specific to their application. We believe this design goal +was accomplished. In order to add a custom command, the user is required to do +the following: + +- Provide a *main-style* function which implements the command. If that + command function uses a ``getopt`` related function to parse arguments, it + *MUST* use the reentrant form. + +- Provide a command definition structure of type ``rtems_shell_cmd_t``. + +- Configure that command using the ``CONFIGURE_SHELL_USER_COMMANDS`` macro. + +Custom aliases are configured similarly but the user only provides an alias +definition structure of type ``rtems_shell_alias_t`` and configures the alias +via the ``CONFIGURE_SHELL_USER_ALIASES`` macro. + +In the following example, we have implemented a custom command named +``usercmd`` which simply prints the arguments it was passed. We have also +provided an alias for ``usercmd`` named ``userecho``. + +.. code-block:: c + + #include <rtems/shell.h> + int main_usercmd(int argc, char **argv) + { + int i; + printf( "UserCommand: argc=%d\n", argc ); + for (i=0 ; i<argc ; i++ ) + printf( "argv[%d]= %s\n", i, argv[i] ); + return 0; + } + rtems_shell_cmd_t Shell_USERCMD_Command = { + "usercmd", /* name */ + "usercmd n1 \[n2 \[n3...]]", /* usage */ + "user", /* topic */ + main_usercmd, /* command */ + NULL, /* alias */ + NULL /* next */ + }; + rtems_shell_alias_t Shell_USERECHO_Alias = { + "usercmd", /* command */ + "userecho" /* alias */ + }; + #define CONFIGURE_SHELL_USER_COMMANDS &Shell_USERCMD_Command + #define CONFIGURE_SHELL_USER_ALIASES &Shell_USERECHO_Alias + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #define CONFIGURE_SHELL_MOUNT_MSDOS + #include <rtems/shellconfig.h> + +Notice in the above example, that the user wrote the*main* for their command +(e.g. ``main_usercmd``) which looks much like any other ``main()``. They then +defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which +describes that command. This command definition structure is registered into +the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS`` +to ``&Shell_USERCMD_Command``. + +Similarly, to add the ``userecho`` alias, the user provides the alias +definition structure named ``Shell_USERECHO_Alias`` and defines +``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias. + +The user can configure any number of commands and aliases in this manner. + +Initialization +============== + +The shell may be easily attached to a serial port or to the ``telnetd`` server. +This section describes how that is accomplished. + +Attached to a Serial Port +------------------------- + +Starting the shell attached to the console or a serial port is very simple. The +user invokes ``rtems_shell_init`` with parameters to indicate the +characteristics of the task that will be executing the shell including name, +stack size, and priority. The user also specifies the device that the shell is +to be attached to. + +This example is taken from the ``fileio`` sample test. This shell portion of +this test can be run on any target which provides a console with input and +output capabilities. It does not include any commands which cannot be +supported on all BSPs. The source code for this test is in +``testsuites/samples/fileio`` with the shell configuration in the ``init.c`` +file. + +.. code-block:: c + + #include <rtems/shell.h> + void start_shell(void) + { + printf(" =========================\n"); + printf(" starting shell\n"); + printf(" =========================\n"); + rtems_shell_init( + "SHLL", /* task name */ + RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */ + 100, /* task priority */ + "/dev/console", /* device name */ + false, /* run forever */ + true, /* wait for shell to terminate */ + rtems_shell_login_check /* login check function, + use NULL to disable a login check */ + ); + } + +In the above example, the call to ``rtems_shell_init`` spawns a task to run the +RTEMS Shell attached to ``/dev/console`` and executing at priority 100. The +caller suspends itself and lets the shell take over the console device. When +the shell is exited by the user, then control returns to the caller. + +Attached to a Socket +-------------------- + +TBD + +Access Control +============== + +Login Checks +------------ + +Login checks are optional for the RTEMS shell and can be configured via a login +check handler passed to ``rtems_shell_init()``. One login check handler +is ``rtems_shell_login_check()``. + +Configuration Files +------------------- + +The following files are used by the login check handler +``rtems_shell_login_check()`` to validate a passphrase for a user and to set up +the user environment for the shell command execution. + +:file:`/etc/passwd` + The format for each line is + + .. code:: c + + user_name:password:UID:GID:GECOS:directory:shell + + with colon separated fields. For more information refer to the Linux + PASSWD(5) man page. Use a ``password`` of ``*`` to disable the login of the + user. An empty password allows login without a password for this user. In + contrast to standard UNIX systems, this file is only readable and writeable + for the user with an UID of zero by default. The ``directory`` is used to + perform a filesystem change root operation in ``rtems_shell_login_check()`` + in contrast to a normal usage as the HOME directory of the user. + The *default* content is: + + .. code:: c + + root::0:0:::: + + so there is *no password required* for the ``root`` user. + +:file:`/etc/group` + The format for each line is: + + .. code:: c + + group_name:password:GID:user_list + + with colon separated fields. The ``user_list`` is comma separated. For + more information refer to the Linux GROUP(5) man page. In contrast to + standard UNIX systems, this file is only readable and writeable for the + user with an UID of zero by default. The default content is + + .. code:: c + + root::0: + +Command Visibility and Execution Permission +------------------------------------------- + +Each command has: + +- an owner, + +- a group, and + +- a read permission flag for the owner, the group and all other users, and + +- an execution permission flag for the owner, the group and all other + users. + +The read and write permission flags are stored in the command mode. The read +permission flags determine the visibility of the command for the current user. +The execution permission flags determine the ability to execute a command for +the current user. These command properties can be displayed and changed with +the: + +- ``cmdls``, + +- ``cmdchown``, and + +- ``cmdchmod`` + +commands. The access is determined by the effective UID, the effective GID and +the supplementary group IDs of the current user and follows the standard +filesystem access procedure. + +Add CRYPT(3) Formats +-------------------- + +By default the ``crypt_r()`` function used by ``rtems_shell_login_check()`` +supports only plain text passphrases. Use ``crypt_add_format()`` to add more +formats. The following formats are available out of the box: + +- ``crypt_md5_format``, + +- ``crypt_sha256_format``, and + +- ``crypt_sha512_format``. + +An example follows: + +.. index:: crypt_add_format + +.. code:: c + + #include <crypt.h> + void add_formats( void ) + { + crypt_add_format( &crypt_md5_format ); + crypt_add_format( &crypt_sha512_format ); + } + +Functions +========= + +This section describes the Shell related C functions which are publicly +available related to initialization and configuration. + +rtems_shell_init - Initialize the shell +--------------------------------------- +.. index:: initialization + +**CALLING SEQUENCE:** + +.. index:: rtems_shell_init + +.. code-block:: c + + rtems_status_code rtems_shell_init( + const char *task_name, + size_t task_stacksize, + rtems_task_priority task_priority, + const char *devname, + bool forever, + bool wait, + rtems_login_check login_check + ); + +**DIRECTIVE STATUS CODES:** + +``RTEMS_SUCCESSFUL`` - Shell task spawned successfully + +others - to indicate a failure condition + +**DESCRIPTION:** + +This service creates a task with the specified characteristics to run the RTEMS +Shell attached to the specified ``devname``. + +.. note:: + + This method invokes the ``rtems_task_create`` and ``rtems_task_start`` + directives and as such may return any status code that those directives may + return. + + There is one POSIX key necessary for all shell instances together and one + POSIX key value pair per instance. You should make sure that your RTEMS + configuration accounts for these resources. + +rtems_shell_login_check - Default login check handler +----------------------------------------------------- +.. index:: initialization + +**CALLING SEQUENCE:** + +.. index:: rtems_shell_login_check + +.. code:: c + + bool rtems_shell_login_check( + const char \*user, + const char \*passphrase + ); + +**DIRECTIVE STATUS CODES:** + +``true`` - login is allowed, and +``false`` - otherwise. + +**DESCRIPTION:** + +This function checks if the specified passphrase is valid for the specified +user. + +.. note:: + + As a side-effect if the specified passphrase is valid for the specified + user, this function: + + - performs a filesystem change root operation to the directory of the + specified user if the directory path is non-empty, + + - changes the owner of the current shell device to the UID of the specified + user, + + - sets the real and effective UID of the current user environment to the + UID of the specified user, + + - sets the real and effective GID of the current user environment to the + GID of the specified user, and + + - sets the supplementary group IDs of the current user environment to the + supplementary group IDs of the specified user. + + In case the filesystem change root operation fails, then the environment + setup is aborted and ``false`` is returned. + |