Changeset 8dbc612 in rtems for doc


Ignore:
Timestamp:
11/18/14 14:33:33 (9 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
4.11, 5, master
Children:
6b4a22e3
Parents:
3fe5d01
git-author:
Sebastian Huber <sebastian.huber@…> (11/18/14 14:33:33)
git-committer:
Sebastian Huber <sebastian.huber@…> (11/20/14 09:30:26)
Message:

shell: Documentation

Location:
doc/shell
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/shell/Makefile.am

    r3fe5d01 r8dbc612  
    2525
    2626general.texi: general.t
    27         $(BMENU2) -p "Configuration and Initialization rtems_shell_init - initialize the shell" \
     27        $(BMENU2) -p "Configuration and Initialization rtems_shell_login_check - Default login check handler" \
    2828            -u "Top" \
    2929            -n "File and Directory Commands" < $< > $@
  • doc/shell/confinit.t

    r3fe5d01 r8dbc612  
    99
    1010This chapter provides information on how the application
    11 configures and intializes the RTEMS shell.
     11configures and initializes the RTEMS shell.
    1212
    1313@c
     
    214214TBD
    215215
     216@c
     217@c
     218@c
     219@section Access Control
     220
     221@subsection Login Checks
     222
     223Login checks are optional for the RTEMS shell and can be configured via a login
     224check handler passed to @code{rtems_shell_init()}.  One login check handler is
     225@code{rtems_shell_login_check()}.
     226
     227@subsection Configuration Files
     228
     229The following files are used by the login check handler
     230@code{rtems_shell_login_check()} to validate a passphrase for a user and to set
     231up the user environment for the shell command execution.
     232
     233@table @file
     234
     235@item /etc/passwd
     236The format for each line is
     237
     238@example
     239user_name:password:UID:GID:GECOS:directory:shell
     240@end example
     241
     242with colon separated
     243fields.  For more information refer to the Linux PASSWD(5) man page.  Use a
     244@code{password} of @code{*} to disable the login of the user.  An empty
     245password allows login without a password for this user.  In contrast to
     246standard UNIX systems, this file is only readable and writeable for the user
     247with an UID of zero by default.  The @code{directory} is used to perform a
     248filesystem change root operation in @code{rtems_shell_login_check()} in
     249contrast to a normal usage as the HOME directory of the user.  The
     250@strong{default} content is
     251
     252@example
     253root::0:0::::
     254@end example
     255
     256so there is @strong{no password required} for the @code{root} user.
     257
     258@item /etc/group
     259The format for each line is
     260
     261@example
     262group_name:password:GID:user_list
     263@end example
     264
     265with colon separated fields.  The @code{user_list} is comma separated.  For
     266more information refer to the Linux GROUP(5) man page.  In contrast to standard
     267UNIX systems, this file is only readable and writeable for the user with an UID
     268of zero by default.  The default content is
     269
     270@example
     271root::0:
     272@end example
     273
     274@end table
     275
     276@subsection Command Visibility and Execution Permission
     277
     278Each command has
     279
     280@itemize @bullet
     281@item an owner,
     282@item a group, and
     283@item a read permission flag for the owner, the group and all other users, and
     284@item an execution permission flag for the owner, the group and all other
     285users.
     286@end itemize
     287
     288The read and write permission flags are stored in the command mode.  The read
     289permission flags determine the visibility of the command for the current user.
     290The execution permission flags determine the ability to execute a command for
     291the current user.  These command properties can be displayed and changed with
     292the
     293
     294@itemize @bullet
     295@item @code{cmdls},
     296@item @code{cmdchown}, and
     297@item @code{cmdchmod}
     298@end itemize
     299
     300commands.  The access is determined by the effective UID, the effective GID and
     301the supplementary group IDs of the current user and follows the standard
     302filesystem access procedure.
     303
     304@subsection Add CRYPT(3) Formats
     305
     306By default the @code{crypt_r()} function used by
     307@code{rtems_shell_login_check()} supports only plain text passphrases.  Use
     308@code{crypt_add_format()} to add more formats.  The following formats are
     309available out of the box
     310
     311@itemize @bullet
     312@item @code{crypt_md5_format},
     313@item @code{crypt_sha256_format}, and
     314@item @code{crypt_sha512_format}.
     315@end itemize
     316
     317An example follows.
     318
     319@findex crypt_add_format
     320@example
     321#include <crypt.h>
     322
     323void add_formats( void )
     324@{
     325  crypt_add_format( &crypt_md5_format );
     326  crypt_add_format( &crypt_sha512_format );
     327@}
     328@end example
     329
    216330@section Functions
    217331
     
    220334
    221335@page
    222 @subsection rtems_shell_init - initialize the shell
     336@subsection rtems_shell_init - Initialize the shell
    223337
    224338@cindex initialization
     
    256370key value pair per instance. You should make sure that your RTEMS configuration
    257371accounts for these resources.
     372
     373@page
     374@subsection rtems_shell_login_check - Default login check handler
     375
     376@cindex initialization
     377
     378@subheading CALLING SEQUENCE:
     379
     380@findex rtems_shell_login_check
     381@example
     382bool rtems_shell_login_check(
     383  const char *user,
     384  const char *passphrase
     385);
     386@end example
     387
     388@subheading DIRECTIVE STATUS CODES:
     389@code{true} - login is allowed, and@*
     390@code{false} - otherwise.
     391
     392@subheading DESCRIPTION:
     393
     394This function checks if the specified passphrase is valid for the specified user.
     395
     396@subheading NOTES:
     397
     398As a side-effect if the specified passphrase is valid for the specified user,
     399this function
     400
     401@itemize @bullet
     402@item performs a filesystem change root operation to the directory of the
     403specified user if the directory path is non-empty,
     404@item changes the owner of the current shell device to the UID of the specified
     405user,
     406@item sets the real and effective UID of the current user environment to the
     407UID of the specified user,
     408@item sets the real and effective GID of the current user environment to the
     409GID of the specified user, and
     410@item sets the supplementary group IDs of the current user environment to the
     411supplementary group IDs of the specified user.
     412@end itemize
     413
     414In case the filesystem change root operation fails, then the environment setup
     415is aborted and @code{false} is returned.
Note: See TracChangeset for help on using the changeset viewer.