[svnbook] r3801 committed - * src/en/book/ch02-basic-usage.xml,...
svnbook at googlecode.com
svnbook at googlecode.com
Fri Oct 15 10:47:59 CDT 2010
Revision: 3801
Author: cmpilato at gmail.com
Date: Fri Oct 15 08:47:24 2010
Log: * src/en/book/ch02-basic-usage.xml,
* src/en/book/ch03-advanced-topics.xml
Merge and expand some similar sections around authentication,
password caches, etc.
http://code.google.com/p/svnbook/source/detail?r=3801
Modified:
/trunk/src/en/book/ch02-basic-usage.xml
/trunk/src/en/book/ch03-advanced-topics.xml
=======================================
--- /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 14 19:16:22 2010
+++ /trunk/src/en/book/ch02-basic-usage.xml Fri Oct 15 08:47:24 2010
@@ -19,6 +19,16 @@
model of Subversion. For a complete reference of all commands,
see <xref linkend="svn.ref"/>.</para>
+ <para>Also, any Subversion operation that contacts the repository
+ over a network may potentially require that the user authenticate.
+ For the sake of simplicity, our examples throughout this chapter
+ avoid demonstrating and discussing authentication. Be aware that
+ if you hope to apply the knowledge herein to an existing,
+ real-world Subversion instance, you'll probably be forced to
+ provide at least a username and password to the server. See
+ <xref linkend="svn.serverconfig.netmodel.creds"/> for a detailed
+ description of Subversion's handling of authentication and client
+ credentials.</para>
<!-- =================================================================
-->
<!-- =================================================================
-->
@@ -59,8 +69,8 @@
</screen>
<para>As described in the previous output, you can ask for help on
- a particular subcommand by running <command>svn help
- <replaceable>SUBCOMMAND</replaceable></command>. Subversion
+ a particular subcommand by running <userinput>svn help
+ <replaceable>SUBCOMMAND</replaceable></userinput>. Subversion
will respond with the full usage message for that subcommand,
including its syntax, options, and behavior:</para>
@@ -436,84 +446,6 @@
exist, that's okay—<command>svn checkout</command> will
create it for you.</para>
- <sect2 id="svn.tour.initial.disabling-password-caching">
- <title>Disabling Password Caching</title>
-
- <para>When you perform a Subversion operation that requires you
- to authenticate, by default Subversion tries to cache your
- authentication credentials on disk in encrypted form. On some
- systems, Subversion may be unable to encrypt your
- authentication data. In those situations, Subversion will ask
- whether you want to cache your credentials to disk in
- plaintext:</para>
-
- <screen>
-$ svn checkout https://host.example.com:443/svn/private-repo
------------------------------------------------------------------------
-ATTENTION! Your password for authentication realm:
-
- <https://host.example.com:443> Subversion Repository
-
-can only be stored to disk unencrypted! You are advised to configure
-your system so that Subversion can store passwords encrypted, if
-possible. See the documentation for details.
-
-You can avoid future appearances of this warning by setting the value
-of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
-'/tmp/servers'.
------------------------------------------------------------------------
-Store password unencrypted (yes/no)?
-</screen>
-
- <para>If you want the convenience of not having to continually
- reenter your password for future operations, you can
- answer <literal>yes</literal> to this prompt. You'll want to
- consult any governing policies that are in place for your
- client computer—many companies have strict rules about
- the ways that their employees' authentication credentials
- should be stored. If you're concerned about caching your
- Subversion passwords in plaintext and do not want to be asked
- about it again and again, you can disable caching of plaintext
- passwords either permanently, or on a server-per-server
- basis.</para>
-
- <para>To permanently disable caching of passwords in plaintext,
- add the line <literal>store-plaintext-passwords = no</literal>
- to the <literal>[global]</literal> section in
- the <filename>servers</filename> configuration file on the
- local machine. To disable plaintext password caching for
- a particular server, use the same setting in the appropriate
- group section in the
- <filename>servers</filename> configuration file.
- See <xref linkend="svn.advanced.confarea.opts"/>
- in <xref linkend="svn.customization"/> for details.</para>
-
- <para>To disable password caching entirely for any single
- Subversion command-line operation, pass
- the <option>--no-auth-cache</option> option to that command
- line. To permanently disable caching entirely, add the
- line <literal>store-passwords = no</literal> to your local
- machine's Subversion configuration file. See
- <xref linkend="svn.serverconfig.netmodel.credcache"/> for
- details.</para>
-
- </sect2>
-
- <sect2 id="svn.tour.initial.different-user">
- <title>Authenticating As a Different User</title>
-
- <para>Since Subversion caches auth credentials by default (both
- username and password), it conveniently remembers who you were
- acting as the last time you modified your working copy. But
- sometimes that's not helpful—particularly if you're
- working in a shared working copy such as a system
- configuration directory or a web server document root. In this
- case, just pass the <option>--username</option> option on the
- command line, and Subversion will attempt to authenticate as
- that user, prompting you for a password if necessary.</para>
-
- </sect2>
-
</sect1>
<!-- =================================================================
-->
=======================================
--- /trunk/src/en/book/ch03-advanced-topics.xml Thu Oct 14 14:58:06 2010
+++ /trunk/src/en/book/ch03-advanced-topics.xml Fri Oct 15 08:47:24 2010
@@ -3969,9 +3969,9 @@
particular protocol is used to contact the server (see <xref
linkend="svn.advanced.reposurls"/>).</para>
- <tip><para>Run <userinput>svn --version</userinput> to see
- which URL schemes and protocols the client knows how to
- use.</para>
+ <tip>
+ <para>Run <userinput>svn --version</userinput> to see which
+ URL schemes and protocols the client knows how to use.</para>
</tip>
<para>When the server process receives a client request, it
@@ -4007,141 +4007,190 @@
</sect2>
<!-- ===============================================================
-->
- <sect2 id="svn.serverconfig.netmodel.credcache">
- <title>Client Credentials Caching</title>
-
- <para>Many servers are configured to require authentication on
- every request. This would be a big annoyance to users if
- they were forced to type their passwords over and over again.
- Fortunately, the Subversion client has a remedy for
- this—a built-in system for caching authentication
- credentials on disk. By default, whenever the command-line
- client successfully responds to a server's authentication
- challenge, credentials are cached on disk and keyed on a
- combination of the server's hostname, port, and authentication
- realm.</para>
-
- <para>When the client receives an authentication challenge, it
- first looks for the appropriate credentials in the user's disk
- cache. If seemingly suitable credentials are not present, or
- if the cached credentials ultimately fail to authenticate,
- the client will, by default, fall back to prompting the
- user for the necessary information.</para>
+ <sect2 id="svn.serverconfig.netmodel.creds">
+ <title>Client Credentials</title>
+
+ <para>Many Subversion servers are configured to required
+ authentication. Sometimes anonymous read operations are
+ allowed, while write operations must be authenticated. In
+ other cases, reads and writes alike require authentication.
+ Subversion's different server options understand different
+ authentication protocols, but from the user's point of view,
+ authentication typically boils down to usernames and
+ passwords. Subversion clients offer several different ways to
+ retrieve and store a user's authentication credentials, from
+ interactive prompting for usernames and passwords to encrypted
+ and non-encrypted on-disk data caches.</para>
<para>The security-conscious reader will suspect immediately
that there is reason for concern here. <quote>Caching
passwords on disk? That's terrible! You should never do
- that!</quote></para>
-
- <para>The Subversion developers recognize the legitimacy of such
- concerns, and so Subversion works with available mechanisms
- provided by the operating system and environment to try to
- minimize the risk of leaking this information. Here's a
- breakdown of what this means for users on the most common
- platforms:</para>
-
- <itemizedlist>
-
- <listitem>
- <para>On Windows, the Subversion client stores passwords
- in the <filename>%APPDATA%/Subversion/auth/</filename>
- directory. On Windows 2000 and later, the standard Windows
- cryptography services are used to encrypt the password
- on disk. Because the encryption key is managed
- by Windows and is tied to the user's own login
- credentials, only the user can decrypt the cached
- password. (Note that if the user's Windows account password
- is reset by an administrator, all of the cached passwords
- become undecipherable. The Subversion client will behave
- as though they don't exist, prompting for passwords when
- required.)</para>
- </listitem>
-
- <listitem>
- <para>Similarly, on Mac OS X, the Subversion client stores
- all repository passwords in the login keyring (managed by
- the Keychain service), which is protected by the user's
- account password. User preference settings can impose
- additional policies, such as requiring that the user's account
- password be entered each time the Subversion password is
- used.</para>
- </listitem>
-
- <listitem>
- <para>For other Unix-like operating systems, no standard
- <quote>keychain</quote> services exist. However, the
- Subversion client knows how to store password securely
- using the <quote>GNOME Keyring</quote> and
- <quote>KDE Wallet</quote> services.
- Also, before storing unencrypted passwords in the
- <filename>~/.subversion/auth/</filename> caching area,
- the Subversion client will ask the user for permission
- to do so. Note that the <filename>auth/</filename>
- caching area is still permission-protected so that only
- the user (owner) can read data from it, not the world at
- large. The operating system's own file permissions protect
- the passwords from other non-administrative users on the
- same system, provided they have no direct physical access
- to the storage media of the home directory, or backups
- thereof.</para>
- </listitem>
-
- </itemizedlist>
-
- <para>Of course, for the truly paranoid, none of these
- mechanisms meets the test of perfection. So for those folks
- willing to sacrifice convenience for the ultimate in security,
- Subversion provides various ways of disabling its credentials
- caching system altogether.</para>
-
- <para>To disable caching for a single command, pass the
- <option>--no-auth-cache</option> option:</para>
-
- <screen>
-$ svn commit -F log_msg.txt --no-auth-cache
-Authentication realm: <svn://host.example.com:3690> example realm
-Username: joe
-Password for 'joe':
-
-Adding newfile
-Transmitting file data .
-Committed revision 2324.
-
-# password was not cached, so a second commit still prompts us
-
-$ svn delete newfile
-$ svn commit -F new_msg.txt
-Authentication realm: <svn://host.example.com:3690> example realm
-Username: joe
-…
-</screen>
-
- <para>Or, if you want to disable credential caching permanently,
- you can edit the <filename>config</filename> file in your
- runtime configuration area and set the
- <literal>store-auth-creds</literal> option to
- <literal>no</literal>. This will prevent the storing of
- credentials used in any Subversion interactions you perform on
- the affected computer. This can be extended to cover all
- users on the computer, too, by modifying the system-wide
- runtime configuration area (described in <xref
- linkend="svn.advanced.confarea.layout" />).</para>
-
- <screen>
-[auth]
-store-auth-creds = no
+ that!</quote> Don't worry—it's not as bad as it sounds.
+ The following sections discuss the various types of credential
+ caches that Subversion uses, when it uses them, and how to
+ disable that functionality in whole or in part.</para>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.serverconfig.netmodel.credcache">
+ <title>Caching credentials</title>
+
+ <para>Subversion offers a remedy for the annoyance caused when
+ users are forced to type their usernames and passwords over
+ and over again. By default, whenever the command-line
+ client successfully responds to a server's authentication
+ challenge, credentials are cached on disk and keyed on a
+ combination of the server's hostname, port, and
+ authentication realm. This cache will then be automatically
+ consulted in the future, avoiding the need for the user to
+ re-type his or her authentication credentials. If seemingly
+ suitable credentials are not present in the cache, or if the
+ cached credentials ultimately fail to authenticate, the
+ client will, by default, fall back to prompting the user for
+ the necessary information.</para>
+
+ <para>The Subversion developers recognize that on-disk caches
+ of authentication credentials can be a security risk. To
+ offset this, Subversion works with available mechanisms
+ provided by the operating system and environment to try to
+ minimize the risk of leaking this information.</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>On Windows, the Subversion client stores passwords
+ in the <filename>%APPDATA%/Subversion/auth/</filename>
+ directory. On Windows 2000 and later, the standard
+ Windows cryptography services are used to encrypt the
+ password on disk. Because the encryption key is managed
+ by Windows and is tied to the user's own login
+ credentials, only the user can decrypt the cached
+ password. (Note that if the user's Windows account
+ password is reset by an administrator, all of the cached
+ passwords become undecipherable. The Subversion client
+ will behave as though they don't exist, prompting for
+ passwords when required.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Similarly, on Mac OS X, the Subversion client stores
+ all repository passwords in the login keyring (managed
+ by the Keychain service), which is protected by the
+ user's account password. User preference settings can
+ impose additional policies, such as requiring that the
+ user's account password be entered each time the
+ Subversion password is used.</para>
+ </listitem>
+
+ <listitem>
+ <para>For other Unix-like operating systems, no single
+ standard <quote>keychain</quote> service exists.
+ However, the Subversion client knows how to store
+ password securely using the <quote>GNOME Keyring</quote>
+ and <quote>KDE Wallet</quote> services. Also, before
+ storing unencrypted passwords in the
+ <filename>~/.subversion/auth/</filename> caching area,
+ the Subversion client will ask the user for permission
+ to do so. Note that the <filename>auth/</filename>
+ caching area is still permission-protected so that only
+ the user (owner) can read data from it, not the world at
+ large. The operating system's own file permissions protect
+ the passwords from other non-administrative users on the
+ same system, provided they have no direct physical access
+ to the storage media of the home directory, or backups
+ thereof.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Of course, for the truly paranoid, none of these
+ mechanisms meets the test of perfection. So for those folks
+ willing to sacrifice convenience for the ultimate in security,
+ Subversion provides various ways of disabling its credentials
+ caching system altogether.</para>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.tour.initial.disabling-password-caching">
+ <title>Disabling password caching</title>
+
+ <para>When you perform a Subversion operation that requires
+ you to authenticate, by default Subversion tries to cache
+ your authentication credentials on disk in encrypted form.
+ On some systems, Subversion may be unable to encrypt your
+ authentication data. In those situations, Subversion will
+ ask whether you want to cache your credentials to disk in
+ plaintext:</para>
+
+ <screen>
+$ svn checkout https://host.example.com:443/svn/private-repo
+-----------------------------------------------------------------------
+ATTENTION! Your password for authentication realm:
+
+ <https://host.example.com:443> Subversion Repository
+
+can only be stored to disk unencrypted! You are advised to configure
+your system so that Subversion can store passwords encrypted, if
+possible. See the documentation for details.
+
+You can avoid future appearances of this warning by setting the value
+of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
+'/tmp/servers'.
+-----------------------------------------------------------------------
+Store password unencrypted (yes/no)?
</screen>
- <para>Sometimes users will want to remove specific credentials
- from the disk cache. To do this, you need to navigate into
- the <filename>auth/</filename> area and manually delete the
- appropriate cache file. Credentials are cached in individual
- files; if you look inside each file, you will see keys and
- values. The <literal>svn:realmstring</literal> key describes
- the particular server realm that the file is associated
- with:</para>
-
- <screen>
+ <para>If you want the convenience of not having to continually
+ reenter your password for future operations, you can
+ answer <literal>yes</literal> to this prompt. If you're
+ concerned about caching your Subversion passwords in
+ plaintext and do not want to be asked about it again and
+ again, you can disable caching of plaintext passwords either
+ permanently, or on a server-per-server basis.</para>
+
+ <warning>
+ <para>When considering how to use Subversion's password
+ caching system, you'll want to consult any governing
+ policies that are in place for your client
+ computer—many companies have strict rules about the
+ ways that their employees' authentication credentials
+ should be stored.</para>
+ </warning>
+
+ <para>To permanently disable caching of passwords in
+ plaintext, add the line <literal>store-plaintext-passwords =
+ no</literal> to the <literal>[global]</literal> section in
+ the <filename>servers</filename> configuration file on the
+ local machine. To disable plaintext password caching for a
+ particular server, use the same setting in the appropriate
+ group section in the <filename>servers</filename>
+ configuration file. (See
+ <xref linkend="svn.advanced.confarea.opts"/> in
+ <xref linkend="svn.customization"/> for details.)</para>
+
+ <para>To disable password caching entirely for any single
+ Subversion command-line operation, pass
+ the <option>--no-auth-cache</option> option to that command
+ line. To permanently disable caching entirely, add the
+ line <literal>store-passwords = no</literal> to your local
+ machine's Subversion configuration file.</para>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.tour.initial.authn-cache-purge">
+ <title>Removing cached credentials</title>
+
+ <para>Sometimes users will want to remove specific credentials
+ from the disk cache. To do this, you need to navigate into
+ the <filename>auth/</filename> area and manually delete the
+ appropriate cache file. Credentials are cached in individual
+ files; if you look inside each file, you will see keys and
+ values. The <literal>svn:realmstring</literal> key describes
+ the particular server realm that the file is associated
+ with:</para>
+
+ <screen>
$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
@@ -4164,74 +4213,103 @@
END
</screen>
- <para>Once you have located the proper cache file, just delete
- it.</para>
-
- <para>One last word about <command>svn</command>'s
- authentication behavior, specifically regarding the
- <option>--username</option> and <option>--password</option>
- options. Many client subcommands accept these options, but it
- is important to understand that using these options does
- <emphasis>not</emphasis> automatically send credentials to the
- server. As discussed earlier, the server <quote>pulls</quote>
- credentials from the client when it deems necessary; the
- client cannot <quote>push</quote> them at will. If a username
- and/or password are passed as options, they will be
- presented to the server only if the server requests them. These
- options are typically used to authenticate as a different user
- than Subversion would have chosen by default (such as your
- system login name) or when trying to avoid interactive
- prompting (such as when calling <command>svn</command> from a
- script).</para>
-
- <note>
- <para>A common mistake is to misconfigure a server so
- that it never issues an authentication challenge. When
- users pass <option>--username</option> and
- <option>--password</option> options to the client, they're
- surprised to see that they're never used; that is, new
- revisions still appear to have been committed
- anonymously!</para>
- </note>
-
- <para>Here is a final summary that describes how a Subversion
- client behaves when it receives an authentication
- challenge.</para>
-
- <orderedlist>
- <listitem>
- <para>First, the client checks whether the user specified
- any credentials as command-line options
- (<option>--username</option> and/or
- <option>--password</option>). If so, the client will try
- to use those credentials to authenticate against the
- server.</para>
- </listitem>
- <listitem>
- <para>If no command-line credentials were provided, or the
- provided ones were invalid, the client looks up the server's
- hostname, port, and realm in the runtime configuration's
- <filename>auth/</filename> area, to see whether appropriate
- credentials are cached there. If so, it attempts to use
- those credentials to authenticate.</para>
- </listitem>
- <listitem>
- <para>Finally, if the previous mechanisms failed to
- successfully authenticate the user against the server, the
- client resorts to interactively prompting the user for
- valid credentials (unless instructed not to do so via the
- <option>--non-interactive</option> option or its
- client-specific equivalents).</para>
- </listitem>
- </orderedlist>
-
- <para>If the client successfully authenticates by any of these
- methods, it will attempt to cache the credentials on disk
- (unless the user has disabled this behavior, as mentioned
- earlier).</para>
-
- </sect2>
-
+ <para>Once you have located the proper cache file, just delete
+ it.</para>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.tour.initial.different-user">
+ <title>Command-line authentication</title>
+
+ <para>All Subversion command-line operations accept
+ the <option>--username</option>
+ and <option>--password</option> options, which allow you to
+ specify your username and password, respectively, so that
+ Subversion isn't forced to prompt you for that information.
+ This is especially handy if you need to invoke Subversion
+ from a script and cannot rely on Subversion being able to
+ locate valid cached credentials for you. These options are
+ also helpful when Subversion has already cached
+ authentication credentials for you, but you know they aren't
+ the ones you want it to use. Perhaps several system users
+ share a login to the system, but each have distinct
+ Subversion identities. You can omit
+ the <option>--password</option> option from this pair if
+ you wish Subversion to use only the provided username, but
+ still prompt you for that username's password.</para>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
+ <sect3 id="svn.tour.initial.authn-wrapup">
+ <title>Authentication wrap-up</title>
+
+ <para>One last word about <command>svn</command>'s
+ authentication behavior, specifically regarding the
+ <option>--username</option> and <option>--password</option>
+ options. Many client subcommands accept these options, but it
+ is important to understand that using these options does
+ <emphasis>not</emphasis> automatically send credentials to the
+ server. As discussed earlier, the server <quote>pulls</quote>
+ credentials from the client when it deems necessary; the
+ client cannot <quote>push</quote> them at will. If a username
+ and/or password are passed as options, they will be
+ presented to the server only if the server requests them. These
+ options are typically used to authenticate as a different user
+ than Subversion would have chosen by default (such as your
+ system login name) or when trying to avoid interactive
+ prompting (such as when calling <command>svn</command> from a
+ script).</para>
+
+ <note>
+ <para>A common mistake is to misconfigure a server so
+ that it never issues an authentication challenge. When
+ users pass <option>--username</option> and
+ <option>--password</option> options to the client, they're
+ surprised to see that they're never used; that is, new
+ revisions still appear to have been committed
+ anonymously!</para>
+ </note>
+
+ <para>Here is a final summary that describes how a Subversion
+ client behaves when it receives an authentication
+ challenge.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>First, the client checks whether the user specified
+ any credentials as command-line options
+ (<option>--username</option> and/or
+ <option>--password</option>). If so, the client will try
+ to use those credentials to authenticate against the
+ server.</para>
+ </listitem>
+ <listitem>
+ <para>If no command-line credentials were provided, or the
+ provided ones were invalid, the client looks up the server's
+ hostname, port, and realm in the runtime configuration's
+ <filename>auth/</filename> area, to see whether appropriate
+ credentials are cached there. If so, it attempts to use
+ those credentials to authenticate.</para>
+ </listitem>
+ <listitem>
+ <para>Finally, if the previous mechanisms failed to
+ successfully authenticate the user against the server, the
+ client resorts to interactively prompting the user for
+ valid credentials (unless instructed not to do so via the
+ <option>--non-interactive</option> option or its
+ client-specific equivalents).</para>
+ </listitem>
+ </orderedlist>
+
+ <para>If the client successfully authenticates by any of these
+ methods, it will attempt to cache the credentials on disk
+ (unless the user has disabled this behavior, as mentioned
+ earlier).</para>
+
+ </sect3>
+ </sect2>
</sect1>
<!-- =================================================================
-->
More information about the svnbook-dev
mailing list