merge my stuff into the man file

svn path=/trunk/mono/; revision=51655

1 files changed, 115 insertions, 8 deletions

diff --git a/man/mozroots.1 b/man/mozroots.1
index b3f2f729824..2b2cc1d1128 100644
--- a/man/mozroots.1
+++ b/man/mozroots.1
@@ -1,14 +1,15 @@
 .\" 
 .\" mozroots man page
 .\" (C) 2005 Novell, Inc. 
-.\" Author:
+.\" Authors:
 .\"   Miguel de Icaza (miguel@gnu.org)
+.\"   Sebastien Pouliot  <sebastien@ximian.com>
 .\"
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
 ..
-.TH Mono "Mono 1.0"
+.TH Mono "MozRoots"
 .SH NAME
 mozroots \- Download and import trusted root certificates from Mozilla's LXR into Mono's certificate store
 .SH SYNOPSIS
@@ -28,12 +29,24 @@ Import the certificates into the trust store.
 .TP
 .I "--sync"
 Synchronize (add/remove) the trust store with the certificates.
+Synchronize is useful for new Mono installations (no roots) and for
+automated updates (no user confirmation for addition or removal).
 .TP
 .I "--ask"
 Always confirm before adding or removing trusted certificates.
+.B Note:
+The initial import will likely add about 100 new trusted root
+certificates into your store. You'll have to answer
+.B yes
+to every one of them if this option is specified.
 .TP
 .I "--ask-add"
 Always confirm before adding a new trusted certificate.
+.B Note:
+The initial import will likely add about 100 new trusted root
+certificates into your store. You'll have to answer
+.B yes
+to every one of them if this option is specified.
 .TP
 .I "--ask-remove"
 Always confirm before removing an existing trusted certificate.
@@ -41,30 +54,124 @@ Always confirm before removing an existing trusted certificate.
 .TP
 .I "--url url"
 Specify an alternative URL for downloading the trusted certificates
-(LXR source format).
+(LXR source format). This should only be useful for testing or if 
+the Mozilla's LXR web site address is changed. It can also be used
+to cache a local copy of the LXR file into your local intranet.
 .TP
 .I "--file name"
-Do not download but use the specified file.
+Do not download from LXR but use the specified file. This is useful
+if many computers have to download the same file from the Internet.
+This way you can keep a local copy on a file server (and minimize
+network traffic).
 .TP
 .I "--pkcs7 name"
-Export the certificates into a PKCS#7 file.
+Export the certificates into a PKCS#7 file. This is useful for 
+debugging purpose or for re-importing the same list into other 
+software.
 .TP
 .I "--machine"
 Import the certificate in the machine trust store. The default is to
-import into the user store.
+import all trusted root certificates into the current user store.
 .TP
 .I "--quiet"
-Limit console output to errors and confirmations messages.
+Limit console output to errors and confirmations messages. This is
+useful when scripting.
+.SH EXAMPLES
+.PP
+After the initial Mono installation you'll have no trusted roots 
+certificates pre-installed. 
+Neither will you have some root test certificates installed (your own
+or the ones provided by using 
+.B setreg
+). In this case the simplest thing to do, if you want to trust all 
+those certificates, is to import and synchronize.
+.nf
+	$ mozroots --import --sync
+	Mozilla Roots Importer - version 1.1.9.0
+	Download and import trusted root certificates from Mozilla's LXR.
+	Copyright 2002, 2003 Motus Technologies. Copyright 2004-2005 Novell. BSD licensed.
+ 
+	Downloading from 'http://lxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt'...
+	Importing certificates into user store...
+	93 new root certificates were added to your trust store.
+	Import process completed.
+.fi
+.PP
+If you created some test certificates (e.g. for using SSL/TLS with XSP)
+and/or if your enterprise requires some additional root certificates
+(e.g. intranet) then you may want to skip the removal part of the 
+process. You can do this by asking for a removal confirmation 
+(--ask-remove option) and answer no when prompted.
+.nf
+	$ mozroots --import --ask-remove
+	Mozilla Roots Importer - version 1.1.9.0
+	Download and import trusted root certificates from Mozilla's LXR.
+	Copyright 2002, 2003 Motus Technologies. Copyright 2004-2005 Novell. BSD licensed.
+ 
+	Downloading from 'http://lxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt'...
+	Importing certificates into user store...
+	93 new root certificates were added to your trust store.
+	2 previously trusted certificates were not part of the update.
+
+	Issuer: CN=Mono Test Root Agency
+	Serial number: 69-B0-E1-4F-88-6E-C7-85-48-0E-74-91-38-76-F4-28
+	Valid from 9/1/2003 11:55:48 AM to 12/31/2039 1:59:59 PM
+	Thumbprint SHA-1: EF-26-C2-28-11-3F-79-ED-9D-EC-3F-3B-D5-7A-26-F2-7C-9F-FA-63
+	Thumbprint MD5:   AE-19-3E-64-36-21-F2-A4-8B-69-38-CA-64-4B-2E-62
+	Are you sure you want to remove this certificate ? no
+.PP
+You can still use the synchronize option (--sync) if you have activated
+the default test roots certificate on your system. They will be removed
+at the end of the synchronization process but you can quickly add them 
+back with the
+.B setreg
+tool.
+.nf
+	$ setreg 1 true
+.fi
+.PP
+Another option to ease updates is to synchronize your machine trust store
+(using the --machine option) and keep your customized (test) certificates
+in your personal store (or vice versa). Note that every user on this 
+computer will be trusting all the newly imported certificates.
+.nf
+	$ mozroots --import --machine --sync
+	Mozilla Roots Importer - version 1.1.9.0
+	Download and import trusted root certificates from Mozilla's LXR.
+	Copyright 2002, 2003 Motus Technologies. Copyright 2004-2005 Novell. BSD licensed.
+ 
+	Downloading from 'http://lxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt'...
+	Importing certificates into user store...
+	94 new root certificates were added to your trust store.
+	Import process completed.
+.fi
+.PP
+Once the initial import is complete the number of changes (additions or 
+removals) is generally very low. In this case it makes sense to know 
+about any changes (i.e. ask for confirmation). No confirmation will be
+required if no changes are made to your trust store.
+.nf
+	$ mozroots --import --ask
+	Mozilla Roots Importer - version 1.1.9.0
+	Download and import trusted root certificates from Mozilla's LXR.
+	Copyright 2002, 2003 Motus Technologies. Copyright 2004-2005 Novell. BSD licensed.
+ 
+	Downloading from 'http://lxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt'...
+	Importing certificates into user store...
+	Import process completed.
+.fi
 .SH FILES
 .PP
 ~/.config/.mono/certs, /usr/share/.mono/certs
 .PP
 Contains Mono certificate stores for users / machine. See the certmgr(1) 
 manual page for more information on managing certificate stores.
+.SH COPYRIGHT
+Copyright (C) 2005 Novell. 
 .SH MAILING LISTS
 Mailing lists are listed at the
 http://www.mono-project.com/Mailing_Lists
 .SH WEB SITE
 http://www.mono-project.com
 .SH SEE ALSO
-.BR mono(1), certmgr(1).
+.BR mono(1), certmgr(1). setreg(1)