'\" t
.\"     Title: voms-proxy-init
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 09/26/2013
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "VOMS\-PROXY\-INIT" "1" "09/26/2013" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
voms-proxy-init \- creates a proxy certificate with VOMS extensions
.SH "SYNOPSIS"
.sp
\fBvoms\-proxy\-init\fR [options]
.SH "DESCRIPTION"
.sp
The voms\-proxy\-init command generates a proxy with the VOMS information included in an X\&.509 non critical extension\&.
.sp
The VOMS attributes are obtained from a known VOMS server\&. The list of known VOMS servers is configured using a \fBvomses\fR configuration file, whose syntax is documented in the \fBvomses\fR man page\&. A custom vomses location can be specified using the \fB\-\-vomses\fR option\&.
.sp
VOMS attributes are requested only if the \fB\-voms\fR option is passed on the command line, specifying for which Virtual Organizations (VOs) attributes are requested\&.
.sp
VOMS attributes are signed by the VOMS server that issues them\&. The signature is verified on the client side leveraging local trust information, which is typically maintained in \fB/etc/grid\-security/vomsdir\fR\&. The vomsdir structure is documented in the \fBvomsdir\fR man page\&. A custom vomsdir can be specified using the \fB\-\-vomsdir\fR option\&.
.sp
The default location of the proxy generated by voms\-proxy\-init is
.sp
.if n \{\
.RS 4
.\}
.nf
 /tmp/x509up_u<user_id>
.fi
.if n \{\
.RE
.\}
.sp
where user_id is the effective user id of the user running the command\&. A non\-standard location for the proxy can be specified using the \fB\-out\fR option\&.
.SS "Requesting VOMS attributes"
.sp
Attributes can be requested using the \fB\-voms\fR option\&. A basic usage is given in the following example:
.sp
.if n \{\
.RS 4
.\}
.nf
voms\-proxy\-init \-voms <voname>
.fi
.if n \{\
.RE
.\}
.sp
where voname is the name of one of the configured VOs\&. The above command will create a proxy containing a VOMS extension which holds all group attributes beloging to the user\&.
.sp
VOMS roles are conditional attributes which are included in a VOMS attribute certificate only when explicitly requested\&. Roles can be requested using a command like the following one:
.sp
.if n \{\
.RS 4
.\}
.nf
voms\-proxy\-init \-voms atlas:/atlas/Role=pilot
.fi
.if n \{\
.RE
.\}
.SS "Ordering requested attributes"
.sp
Typically VOMS attributes are returned in the order on which they are requested on the command line\&. For instance, the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
voms\-proxy\-init \-voms infngrid:/infngrid/group1 \-voms infngrid:/infngrid/Role=pilot
.fi
.if n \{\
.RE
.\}
.sp
will produce an Attribute Certificate which has as the primary attribute /infngrid/group1, followed by /infngrid/Role=pilot, and then by the other attributes belonging to the user\&. The \fB\-order\fR can also be used to express order requirements\&.
.SS "Setting the validity period of the generated proxy and attribute certificate"
.sp
By default, voms\-proxy\-init will generate a proxy valid for 12 hours including a VOMS extension valid for the same time (if requested)\&. These time periods can be changed using the \fB\-valid\fR option, which will set the validity of both the proxy and the AC\&. Note that the validity of the AC can only be "proposed" by voms\-proxy\-init, as the AC validity is set by the VOMS server and its maximum value is limited by local VOMS server configuration (typically the maximum value is 24 hours)\&.
.SS "Setting the type of proxy generated by voms\-proxy\-init"
.sp
By default, voms\-proxy\-init generates a legacy proxy compatible with Globus Toolkit version 2\&. This behaviour can be changed using the \fB\-rfc\fR option, which will produce an RFC3820 compliant proxy\&. In order to generate a Globus Toolkit version 3 proxy, i\&.e\&. a draft compliant proxy, use the \fB\-proxyver 3\fR option\&.
.SH "CONFIGURATION"
.sp
Local configuration for trusted VOs is needed for \fIvoms\-proxy\-init\fR to work properly\&. See the \fIvomses(5)\fR and \fIvomsdir(5)\fR man pages for more details\&.
.SH "OPTIONS"
.sp
Options may be specified using either a "\-" or "\-\-" prefix\&.
.sp
\fB\-b,\-\-bits <num\-bits>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Number of bits in key {512|1024|2048|4096}
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-cert <certfile>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Nonstandard location of user certificate
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-certdir <certdir>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Nonstandard location of trusted cert dir
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-conf <file>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Read options from <file>
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-debug\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Enables extra debug output
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-dont_verify_ac\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Skips AC verification
.fi
.if n \{\
.RE
.\}
.sp
\fB\-f,\-\-failonwarn\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Treat warnings as errors
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-help\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Displays helps and exits
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-hours <hours>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Sets the generated proxy validity to H hours (default:12)\&.
Note that this option only sets the lifetime of the generated proxy\&.
Use \-valid to set lifetime for both the proxy and the AC\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-ignorewarn\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Ignore warnings
.fi
.if n \{\
.RE
.\}
.sp
\fB\-k,\-\-key <keyfile>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Non standard location of user key
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-limited\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Creates a limited proxy
.fi
.if n \{\
.RE
.\}
.sp
\fB\-n,\-\-noregen\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Use an existing proxy certificate to obtain VOMS attributes and to sign the new generated proxy
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-old\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Creates a legacy, GT2 compliant proxy (synonymous with \*(Aq\-proxyver 2\*(Aq)
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-order <fqan>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
The fqan specified with this option is set as the primary FQAN if present in the list of  attributes returned by the server\&.
Use this option more than once if you want to set the  order for more than one FQAN\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-out <proxyfile>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Non standard location of the generated proxy certificate
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-path_length <L>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Allow a chain of at most L proxies to be generated and signed from the proxy created by voms\-proxy\-init\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-proxyver <2|3|4>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Sets the type of proxy generated by VOMS proxy init\&. 2 stands for legacy proxy,3 for draft proxy, 4 for rfc proxy\&.
Use \-old or \-rfc instead of this option\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-pwstdin\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Reads private key passphrase from standard input\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-q,\-\-quiet\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Quiet mode, minimal output
.fi
.if n \{\
.RE
.\}
.sp
\fB\-r,\-\-rfc\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Creates an RFC 3820 compliant proxy (synonymous with \*(Aq\-proxyver 4\*(Aq)
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-target <hostname>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Targets the AC against a specific hostname\&. Multiple targets can be expressed using this option multiple times\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-usage\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Displays helps and exits
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-valid <h:m>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Sets generated proxy and AC validity to h hours and m minutes (defaults to 12:00)\&.
Note that the VOMS server could shorten the validity of the issued AC depending on the server configuration\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-verify\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Verifies the validity of the user certificate\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-version\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Displays version
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-voms <voms<:fqan>>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Specifies the VO for which the AC is requested\&. <:fqan> is optional,and is used to ask for
specific attributes (e\&.g:  \-\-voms atlas:/atlas/Role=pilot)\&.
This option can be used multiple times to request multiple FQANs for different VOs\&.
The order in which the option appears on the command line influence the order of the issued attributes\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-vomsdir <DIR>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Sets the path where lsc files and other local VOMS trust anchors will be looked for\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-vomses <vomses file>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Specifies the name of a VOMSES file from which VOMS server contact information is parsed\&.
.fi
.if n \{\
.RE
.\}
.sp
\fB\-\-vomslife <h:m>\fR
.sp
.if n \{\
.RS 4
.\}
.nf
Sets the validity of the requested VOMS attribute certificate to h hours and m minutes (defaults to the value of the \*(Aq\-valid\*(Aq option)
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.sp
To report bugs or ask for support, use GGUS: https://ggus\&.eu/pages/home\&.php
.SH "AUTHORS"
.sp
Andrea Ceccanti <andrea\&.ceccanti@cnaf\&.infn\&.it>
.sp
Daniele Andreotti <daniele\&.andreotti@cnaf\&.infn\&.it>
.sp
Valerio Venturi <valerio\&.venturi@cnaf\&.infn\&.it>
.SH "SEE ALSO"
.sp
voms\-proxy\-destroy(1), voms\-proxy\-info(1), vomses(5), vomsdir(5)
.SH "COPYING"
.sp
Copyright 2012 Istituto Nazionale di Fisica Nucleare
.sp
Licensed under the Apache License, Version 2\&.0 (the "License"); you may not use this file except in compliance with the License\&. You may obtain a copy of the License at
.sp
.if n \{\
.RS 4
.\}
.nf
http://www\&.apache\&.org/licenses/LICENSE\-2\&.0
.fi
.if n \{\
.RE
.\}
.sp
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\&. See the License for the specific language governing permissions and limitations under the License\&.