[e52906b] | 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
[489740f] | 2 | |
---|
[4886d60] | 3 | .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
[e5afcaa] | 4 | |
---|
[8ca13ed] | 5 | Configuration and Initialization |
---|
[f15d607] | 6 | ******************************** |
---|
[8ca13ed] | 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 | |
---|
[cf0c79a] | 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 | |
---|
[8ca13ed] | 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 | |
---|
[62d03a1] | 124 | Notice in the above example, that the user wrote the *main* for their command |
---|
[8ca13ed] | 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 | |
---|
[bf61a8b] | 306 | .. raw:: latex |
---|
| 307 | |
---|
| 308 | \clearpage |
---|
| 309 | |
---|
[8ca13ed] | 310 | rtems_shell_init - Initialize the shell |
---|
| 311 | --------------------------------------- |
---|
| 312 | .. index:: initialization |
---|
| 313 | .. index:: rtems_shell_init |
---|
| 314 | |
---|
[bf61a8b] | 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 | ); |
---|
[8ca13ed] | 327 | |
---|
[bf61a8b] | 328 | DIRECTIVE STATUS CODES: |
---|
| 329 | ``RTEMS_SUCCESSFUL`` - Shell task spawned successfully |
---|
| 330 | *others* - to indicate a failure condition |
---|
[8ca13ed] | 331 | |
---|
[bf61a8b] | 332 | DESCRIPTION: |
---|
| 333 | This service creates a task with the specified characteristics to run the RTEMS |
---|
| 334 | Shell attached to the specified ``devname``. |
---|
[8ca13ed] | 335 | |
---|
[bf61a8b] | 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. |
---|
[8ca13ed] | 340 | |
---|
[bf61a8b] | 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. |
---|
[8ca13ed] | 344 | |
---|
[bf61a8b] | 345 | .. raw:: latex |
---|
[8ca13ed] | 346 | |
---|
[bf61a8b] | 347 | \clearpage |
---|
[8ca13ed] | 348 | |
---|
| 349 | rtems_shell_login_check - Default login check handler |
---|
| 350 | ----------------------------------------------------- |
---|
| 351 | .. index:: initialization |
---|
| 352 | .. index:: rtems_shell_login_check |
---|
| 353 | |
---|
[bf61a8b] | 354 | CALLING SEQUENCE: |
---|
| 355 | .. code:: c |
---|
[8ca13ed] | 356 | |
---|
[bf61a8b] | 357 | bool rtems_shell_login_check( |
---|
| 358 | const char *user, |
---|
| 359 | const char *passphrase |
---|
| 360 | ); |
---|
[8ca13ed] | 361 | |
---|
[bf61a8b] | 362 | DIRECTIVE STATUS CODES: |
---|
| 363 | ``true`` - login is allowed, and |
---|
| 364 | ``false`` - otherwise. |
---|
[8ca13ed] | 365 | |
---|
[bf61a8b] | 366 | DESCRIPTION: |
---|
| 367 | This function checks if the specified passphrase is valid for the specified |
---|
| 368 | user. |
---|
[8ca13ed] | 369 | |
---|
[bf61a8b] | 370 | NOTES: |
---|
| 371 | As a side-effect if the specified passphrase is valid for the specified |
---|
| 372 | user, this function: |
---|
[8ca13ed] | 373 | |
---|
[bf61a8b] | 374 | - performs a filesystem change root operation to the directory of the |
---|
| 375 | specified user if the directory path is non-empty, |
---|
[8ca13ed] | 376 | |
---|
[bf61a8b] | 377 | - changes the owner of the current shell device to the UID of the specified |
---|
| 378 | user, |
---|
[8ca13ed] | 379 | |
---|
[bf61a8b] | 380 | - sets the real and effective UID of the current user environment to the |
---|
| 381 | UID of the specified user, |
---|
[8ca13ed] | 382 | |
---|
[bf61a8b] | 383 | - sets the real and effective GID of the current user environment to the |
---|
| 384 | GID of the specified user, and |
---|
[8ca13ed] | 385 | |
---|
[bf61a8b] | 386 | - sets the supplementary group IDs of the current user environment to the |
---|
| 387 | supplementary group IDs of the specified user. |
---|
[8ca13ed] | 388 | |
---|
[bf61a8b] | 389 | In case the filesystem change root operation fails, then the environment |
---|
| 390 | setup is aborted and ``false`` is returned. |
---|