GRID-MAPFILE-ADD-ENTRY(8)
=========================
:doctype:      manpage
:man source:   Grid Community Toolkit
:man version:  6
:man manual:   Grid Community Toolkit Manual
:man software: Grid Community Toolkit

NAME
----
grid-mapfile-add-entry - Add an entry to a gridmap file

SYNOPSIS
--------
*grid-mapfile-add-entry* [ -h | -help | -usage | -version | -versions ]

*grid-mapfile-add-entry* -dn 'DISTINGUISHED-NAME' -ln 'LOCAL-NAME'...  [-d | -dryrun] [ -f 'MAPFILE' | -mapfile 'MAPFILE' ] [ -n ] [ -c ]

DESCRIPTION
-----------
The *grid-mapfile-add-entry* program adds a new mapping from an X.509
distinguished name to a local POSIX user name to a gridmap file. Gridmap files
are used as a simple authorization method for services such as GRAM5 or
GridFTP.

The *grid-mapfile-add-entry* program verifies that the 'LOCAL-NAME' is a valid
user name on the system on which it was run, and that the mapping between
'DISTINGUISHED-NAME' and 'LOCAL-NAME' does not already exist in the gridmap
file.

By default, *grid-mapfile-add-entry* will modify the gridmap file named by the
+GRIDMAP+ environment variable if present, or the file
+/etc/grid-security/grid-mapfile+ if not. This can be changed by the use of the
'-mapfile' or '-f' command-line options.


If the gridmap file does not exist, *grid-mapfile-add-entry* will create it. If
it already exists, *grid-mapfile-add-entry* will save the current contents of
the file to a new file with the string +.old+ appended to the
file name.

The full set of command-line options to *grid-mapfile-add-entry* are:

*-help, -usage*::
    Display the command-line options to *grid-mapfile-add-entry*.

*-version, -versions*::
    Display the version number of the *grid-mapfile-add-entry* command. The
    second form includes more details.

*-dn 'DISTINGUISHED-NAME'*::
    The X.509 distinguished name to add a mapping for. The name should be in
    OpenSSL's +oneline+ format.

*-ln 'LOCAL-NAME'...*::
    The POSIX user name to map the distinguished name to. This name must be a
    valid username. Add multiple 'LOCAL-NAME' strings after the '-ln'
    command-line option. If any of the local names are invalid, no changes will
    be made to the gridmap file. 

*-d, -dryrun*::
    Verify local names and display diagnostics about what would be added to the
    gridmap file, but don't actually modify the file.

*-mapfile 'MAPFILE', -f 'MAPFILE'*::
    Modify the gridmap file named by 'MAPFILE' instead of the default.

*-n*::
    Don't copy the original file to 'MAPFILE'.old.

*-c*::
    Don't check for changes to the gridmap during program execution.

EXAMPLES
--------
Add a mapping between the current user's certificate to the current user id to
a gridmap file in +$HOME/.gridmap+:

==============================================================================
    % grid-mapfile-add-entry -f $HOME/.gridmap -dn "`grid-cert-info -subject`" -ln "`id -un`"
    Modifying /home/juser/.gridmap ...
    /home/juser/.gridmap does not exist... Attempting to create /home/juser/.gridmap
    New entry:
    "/DC=org/DC=example/DC=grid/CN=Joe User" juser
    (1) entry added
==============================================================================

Add a mapping between the a distinguished name and multiple local
names:

==============================================================================
    % grid-mapfile-add-entry -dn "/DC=org/DC=example/DC=grid/CN=Joe User" juser" local1 local2
    Modifying /home/juser/.gridmap ...
    /home/juser/.gridmap does not exist... Attempting to create /home/juser/.gridmap
    New entry:
    "/DC=org/DC=example/DC=grid/CN=Joe User" local1,local2
    (1) entry added
==============================================================================

ENVIRONMENT
-----------
The following environment variables affect the execution of *grid-mapfile-add-entry*:

+GRIDMAP+::
    Path to the default gridmap to modify

FILES
-----
The following files affect the execution of *grid-mapfile-add-entry*:

+/etc/grid-security/grid-mapfile+::
    Path to the default gridmap to modify if +GRIDMAP+ environment variable is
    not set.

SEE ALSO
--------
grid-mapfile-check-consistency(8), grid-mapfile-delete-entry(8)

AUTHOR
------
Copyright (C) 1999-2016 University of Chicago
