<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Network Model</title>
<link rel="stylesheet" type="text/css" href="styles.css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1" />
<style type="text/css">
body { background-image: url('images/draft.png');
background-repeat: no-repeat;
background-position: top left;
/* The following properties make the watermark "fixed" on the page. */
/* I think that's just a bit too distracting for the reader... */
/* background-attachment: fixed; */
/* background-position: center center; */
}</style>
<link rel="home" href="index.html" title="Version Control with Subversion [DRAFT]" />
<link rel="up" href="svn.advanced.html" title="Chapter 3. Advanced Topics" />
<link rel="prev" href="svn.advanced.changelists.html" title="Changelists" />
<link rel="next" href="svn.advanced.working-without-a-wc.html" title="Working Without a Working Copy" />
</head>
<body>
<div xmlns="" id="vcws-version-notice">
<p>This text is a work in progress—highly subject to
change—and may not accurately describe any released
version of the Apache™ Subversion® software.
Bookmarking or otherwise referring others to this page is
probably not such a smart idea. Please visit
<a href="http://www.svnbook.com/">http://www.svnbook.com/</a>
for stable versions of this book.</p>
</div>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Network Model</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="svn.advanced.changelists.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. Advanced Topics</th>
<td width="20%" align="right"> <a accesskey="n" href="svn.advanced.working-without-a-wc.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" title="Network Model">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="svn.serverconfig.netmodel"></a>Network Model</h2>
</div>
</div>
</div>
<p>At some point, you're going to need to understand how your
Subversion client communicates with its server. Subversion's
networking layer is abstracted, meaning that Subversion clients
exhibit the same general behaviors no matter what sort of server
they are operating against. Whether speaking the HTTP protocol
(<code class="literal">http://</code>) with the Apache HTTP Server or
speaking the custom Subversion protocol
(<code class="literal">svn://</code>) with <span class="command"><strong>svnserve</strong></span>,
the basic network model is the same. In this section, we'll
explain the basics of that network model, including how
Subversion manages authentication and authorization
matters.</p>
<div class="sect2" title="Requests and Responses">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.netmodel.reqresp"></a>Requests and Responses</h3>
</div>
</div>
</div>
<p>The Subversion client spends most of its time managing
working copies. When it needs information from a remote
repository, however, it makes a network request, and the
server responds with an appropriate answer. The details of
the network protocol are hidden from the user—the client
attempts to access a URL, and depending on the URL scheme, a
particular protocol is used to contact the server (see <a class="xref" href="svn.basic.in-action.html#svn.advanced.reposurls" title="Addressing the Repository">the section called “Addressing the Repository”</a>).</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Tip]" src="images/tip.png" />
</td>
<th align="left">Tip</th>
</tr>
<tr>
<td align="left" valign="top">
<p>Run <strong class="userinput"><code>svn --version</code></strong> to see which
URL schemes and protocols the client knows how to use.</p>
</td>
</tr>
</table>
</div>
<p>
<a id="idp10447216" class="indexterm"></a>When the server process receives a client request, it
often demands that the client identify itself. It issues
an authentication challenge to the client, and the client
responds by providing <em class="firstterm">credentials</em> back
to the server. Once authentication is complete, the server
responds with the original information that the client asked for.
Notice that this system is different from systems such as CVS,
where the client preemptively offers credentials (<span class="quote">“<span class="quote">logs
in</span>”</span>) to the server before ever making a request. In
Subversion, the server <span class="quote">“<span class="quote">pulls</span>”</span> credentials by
challenging the client at the appropriate moment, rather than
the client <span class="quote">“<span class="quote">pushing</span>”</span> them. This makes certain
operations more elegant. For example, if a server is
configured to allow anyone in the world to read a repository,
the server will never issue an authentication challenge
when a client attempts to <span class="command"><strong>svn checkout</strong></span>.</p>
<p>If the particular network requests issued by the client
result in a new revision being created in the repository
(e.g., <span class="command"><strong>svn commit</strong></span>), Subversion uses the
authenticated username associated with those requests as the
author of the revision. That is, the authenticated user's
name is stored as the value of the
<code class="literal">svn:author</code> property on the new revision
(see <a class="xref" href="svn.advanced.props.html#svn.advanced.props.ref" title="Subversion's Reserved Properties">the section called “Subversion's Reserved Properties”</a>). If the
client was not authenticated (i.e., if the server never issued
an authentication challenge), the revision's
<code class="literal">svn:author</code> property is empty.</p>
</div>
<div class="sect2" title="Client Credentials">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.netmodel.creds"></a>Client Credentials</h3>
</div>
</div>
</div>
<p>Many Subversion servers are configured to require
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.</p>
<p>The security-conscious reader will suspect immediately
that there is reason for concern here. <span class="quote">“<span class="quote">Caching
passwords on disk? That's terrible! You should never do
that!</span>”</span> 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.</p>
<div class="sect3" title="Caching credentials">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.netmodel.credcache"></a>Caching credentials</h4>
</div>
</div>
</div>
<p>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.</p>
<p>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.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>On Windows, the Subversion client stores passwords
in the <code class="filename">%APPDATA%/Subversion/auth/</code>
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.)</p>
</li>
<li class="listitem">
<p>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.</p>
</li>
<li class="listitem">
<p>For other Unix-like operating systems, no single
standard <span class="quote">“<span class="quote">keychain</span>”</span> service exists.
However, the Subversion client knows how to store
passwords securely using the <span class="quote">“<span class="quote">GNOME Keyring</span>”</span>
and <span class="quote">“<span class="quote">KDE Wallet</span>”</span> services. Also, before
storing unencrypted passwords in the
<code class="filename">~/.subversion/auth/</code> caching area,
the Subversion client will ask the user for permission
to do so. Note that the <code class="filename">auth/</code>
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.</p>
</li>
</ul>
</div>
<p>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.</p>
</div>
<div class="sect3" title="Disabling password caching">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.tour.initial.disabling-password-caching"></a>Disabling password caching</h4>
</div>
</div>
</div>
<p>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:</p>
<div class="informalexample">
<pre class="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)?
</pre>
</div>
<p>If you want the convenience of not having to continually
reenter your password for future operations, you can
answer <code class="literal">yes</code> 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-by-server basis.</p>
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Warning]" src="images/warning.png" />
</td>
<th align="left">Warning</th>
</tr>
<tr>
<td align="left" valign="top">
<p>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.</p>
</td>
</tr>
</table>
</div>
<p>To permanently disable caching of passwords in
plaintext, add the line <code class="literal">store-plaintext-passwords =
no</code> to the <code class="literal">[global]</code> section in
the <code class="filename">servers</code> 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 <code class="filename">servers</code>
configuration file. (See
<a class="xref" href="svn.advanced.confarea.html#svn.advanced.confarea.opts" title="Runtime Configuration Options">the section called “Runtime Configuration Options”</a> in
<a class="xref" href="svn.customization.html" title="Chapter 7. Customizing Your Subversion Experience">Chapter 7, <em>Customizing Your Subversion Experience</em></a> for details.)</p>
<p>To disable password caching entirely for any single
Subversion command-line operation, pass
the <code class="option">--no-auth-cache</code> option to that command
line. To permanently disable caching entirely, add the
line <code class="literal">store-passwords = no</code> to your local
machine's Subversion configuration file.</p>
</div>
<div class="sect3" title="Removing cached credentials">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.tour.initial.authn-cache-purge"></a>Removing cached credentials</h4>
</div>
</div>
</div>
<p>Sometimes users will want to remove specific credentials
from the disk cache. To do this, you need to navigate into
the <code class="filename">auth/</code> 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 <code class="literal">svn:realmstring</code> key describes
the particular server realm that the file is associated
with:</p>
<div class="informalexample">
<pre class="screen">
$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
5c3c22968347b390f349ff340196ed39
$ cat ~/.subversion/auth/svn.simple/5671adf2865e267db74f09ba6f872c28
K 8
username
V 3
joe
K 8
password
V 4
blah
K 15
svn:realmstring
V 45
<https://svn.domain.com:443> Joe's repository
END
</pre>
</div>
<p>Once you have located the proper cache file, just delete
it.</p>
</div>
<div class="sect3" title="Command-line authentication">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.tour.initial.different-user"></a>Command-line authentication</h4>
</div>
</div>
</div>
<p>All Subversion command-line operations accept
the <code class="option">--username</code>
and <code class="option">--password</code> 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 <code class="option">--password</code> option from this pair if
you wish Subversion to use only the provided username, but
still prompt you for that username's password.</p>
</div>
<div class="sect3" title="Authentication wrap-up">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.tour.initial.authn-wrapup"></a>Authentication wrap-up</h4>
</div>
</div>
</div>
<p>One last word about <span class="command"><strong>svn</strong></span>'s
authentication behavior, specifically regarding the
<code class="option">--username</code> and <code class="option">--password</code>
options. Many client subcommands accept these options, but it
is important to understand that using these options does
<span class="emphasis"><em>not</em></span> automatically send credentials to the
server. As discussed earlier, the server <span class="quote">“<span class="quote">pulls</span>”</span>
credentials from the client when it deems necessary; the
client cannot <span class="quote">“<span class="quote">push</span>”</span> 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 <span class="command"><strong>svn</strong></span> from a
script).</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>A common mistake is to misconfigure a server so
that it never issues an authentication challenge. When
users pass <code class="option">--username</code> and
<code class="option">--password</code> 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!</p>
</td>
</tr>
</table>
</div>
<p>Here is a final summary that describes how a Subversion
client behaves when it receives an authentication
challenge.</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>First, the client checks whether the user specified
any credentials as command-line options
(<code class="option">--username</code> and/or
<code class="option">--password</code>). If so, the client will try
to use those credentials to authenticate against the
server.</p>
</li>
<li class="listitem">
<p>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
<code class="filename">auth/</code> area, to see whether appropriate
credentials are cached there. If so, it attempts to use
those credentials to authenticate.</p>
</li>
<li class="listitem">
<p>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
<code class="option">--non-interactive</code> option or its
client-specific equivalents).</p>
</li>
</ol>
</div>
<p>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).</p>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="svn.advanced.changelists.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="svn.advanced.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="svn.advanced.working-without-a-wc.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Changelists </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Working Without a Working Copy</td>
</tr>
</table>
</div>
<div xmlns="" id="vcws-footer">
<hr />
<img src="images/cc-by.png" style="float: right;" />
<p>You are reading <em>Version Control with Subversion</em> (for
Subversion 1.8), by Ben Collins-Sussman, Brian W. Fitzpatrick,
and C. Michael Pilato.</p>
<p>This work is licensed under
the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.</p>
<p>To submit comments, corrections, or other contributions to the
text, please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a>.</p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
i586
>
media
>
core-updates
>
by-pkgid
>
d32d95698a59acd37b394f83dfc217c6
>
files
>
211
