@need 3200

@node Shared and Public Archives
@chapter Shared and Public Archives

In the earlier chapters, you learned how to create your first archive,
start a project, check in the initial sources and subsequent changes,
and retrieve past revisions.


In this chapter you'll learn how to make an archive available over a
network and begin to learn how multiple programmers can share a single
archive.

@need 3200

@section Registering for Network Access to Archives

As you should recall, an archive has both a logical name, and a
physical location:

@example
@group
        % larch archives
        lord@@emf.net--2003-example
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
          |     /usr/lord/@{archives@}/2003-example
          |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          |                     |
          |              archive location        
          |
        archive name
@end group
@group
@end group
@end example

(See @ref{Creating a New Archive}.)


Some archives can be accessed over a network, currently via any
of the protocols:

@example
@group
        FTP
        SFTP
        WebDAV
        plain HTTP
@end group
@group
@end group
@end example

Later in this chapter, you'll learn how to create such archives.


For now, you should know that to access such an archive, you register
it's name and physical location, using a URL for the physical
location.


For example, to access an HTTP or WebDAV archive:

@example
@group
    % larch register-archive lord@@emf.net--2003 \
            http://regexps.srparish.net/@{archives@}/lord@@emf.net--2003
@end group
@group
@end group
@end example

@noindent
or an FTP archive:

@example
@group
    % larch register-archive lord@@regexps.com--2002 \
            ftp://ftp.regexps.com/@{archives@}/lord@@regexps.com--2002
@end group
@group
@end group
@end example

You can see that these commands have taken effect:

@example
@group
    % larch archives
    lord@@emf.net--2003
            http://regexps.srparish.net/@{archives@}/lord@@emf.net--2003
    lord@@emf.net--2003-example
            /usr/lord/examples/@{archives@}/2003-example
    lord@@regexps.com--2002
            ftp://ftp.regexps.com/@{archives@}/lord@@regexps.com--2002
@end group
@group
@end group
@end example



@need 3200

@section Working with Several Archives at Once

After you've registered additional archives, how do you access them?


One trivial way is to make the archive you are interested in your
default:

@example
@group

@end group
@group
        % larch my-default-archive lord@@emf.net--2003
@end group
@group

@end group
@group
        % larch categories
        [...categories in the remote archive...]
@end group
@group

@end group
@end example

It can, of course, be inconvenient to keep changing your default
archive.  So for now, let's restore it to the archive we've been
using in the examples:

@example
@group
        % larch my-default-archive lord@@emf.net--2003-example
@end group
@group
@end group
@end example

There are two other ways to access a remote archive:

@need 3200

@subsection Selecting an Archive with -A

Every command that operates on archives accepts a @code{-A} option which
can be used to override the default:

@example
@group
        % larch my-default-archive
        lord@@emf.net--2003-example
@end group
@group

@end group
@group
        % larch categories -A lord@@emf.net--2003
        [... categories in lord@@emf.net--2003 ...]
@end group
@group

@end group
@end example

@strong{Usage Note:} A @code{-A} argument takes precedence over your default
archive but is overridden by fully qualified project names (see
below).




@need 3200

@subsection Fully Qualified Project Names

Commands that accept project names allow you to use @geindex fully qualified
project names
@dfn{fully qualified
project names}.   A fully qualified name is formed by prefixing an
archive name, followed by a slash, to the project name:

@example
@group
   category name:
   arch                     => lord@@emf.net--2003/arch
@end group
@group

@end group
@group
   branch name:
   arch--devo               => lord@@emf.net--2003/arch--devo
@end group
@group

@end group
@group
   version name:
   arch--devo--1.0          => lord@@emf.net--2003/arch--devo--1.0
@end group
@group

@end group
@group
   revision name:
   arch--devo--1.0--patch-1 => lord@@emf.net--2003/arch--devo--1.0--patch-1
@end group
@group

@end group
@end example

As in this example:

@example
@group
        % larch my-default-archive
        lord@@emf.net--2003-example
@end group
@group

@end group
@group
        % larch branches lord@@emf.net--2003/arch
        [... branches of arch in lord@@emf.net--2003 ...]
@end group
@group

@end group
@end example

@strong{Usage Note:} A fully qualified name takes precedence over both @code{-A}
arguments and your default archive.







@need 3200

@section Read-only Archives

Operating system and server access controls can be used to limit some
or all users to @emph{read-only} access.  For example, FTP is usually
configured in such a way that anonymous users can read, but not modify
the archive.




@need 3200

@section Read-only Archive Mirrors

@strong{Upcoming Change Warning:} The mechanism described in this section 
is going to change in future releases.  Mirrors will be more cleanly
supported.   Nevertheless, this mechanism is currently widely adopted
since it works @geindex well enough
@dfn{well enough} to get work done.


One popular way to use @code{arch} is to use a local (i.e. not network
accessible) archive for day-to-day work, but then to "publish" that
archive on the network by creating an @geindex archive mirror
@dfn{archive mirror}.


A mirror is created by:


@strong{1)} Creating an initially empty network-accessible archive.


@strong{2)} Storing a file called @code{=mirror} in the @code{=meta-data} directory
in the root of the remote archive.  That file should contain one line:
the name of the archive being mirrored.


@strong{3)} Using the command @code{larch push-mirror} to copy data from the 
local archive to the mirror:

@example
@group
    % larch push-mirror lord@@emf.net--2003 lord@@emf.net--2003-mirror
    [....]
@end group
@group
@end group
@end example

@strong{Usage Note:} Users do @emph{@strong{not}} generally run @code{push-mirror} by hand.
Instead, they create something called a @emph{notifier} that optimizes
@code{push-mirror} by keeping track of what parts of the archive have
previously been copied.  You'll learn more about notifiers in a later
chapter (see xref@geindex Driving Process Automation with arch Notifiers
@dfn{Driving Process Automation with arch Notifiers}).


@strong{Usage Note:} When you tell other people about your network accessible
mirror, tell them to register it under the name of your @emph{local}
archive.   As far as remote users are concerned, the mirror is the
same thing as your local archive.




@need 3200

@section Mixing Access Modes

There is nothing to prevent you from making a single archive available
via multiple access methods.   For example, you can register an FTP
accessible archive using a local-filesystem location on the machine
that contains the FTP directory, but ask other users to register it
with an @code{ftp:} URL.




@need 3200

@section Creating FTP Archives

An archive is made FTP accessible simply by putting its directory in 
a location where an FTP server can make it available.


@strong{Security Cautions:} When creating an FTP accessible archive, there are two
important security concerns: @emph{@strong{passwords in the clear}}, and @emph{@strong{FTP server
configuration}}.


@strong{Passwords in the Clear} As is well known, the FTP protocol sends
passwords across networks unencrypted.   In many situations, that is
considered an unacceptable security risk and you will therefore want
to consider using FTP access only for public data, and then only for
read-only access.


@strong{FTP Server Configuration} In general, securely configuring an FTP
server requires care, caution, and careful study of the relevant
documentation for the operating system and server implementation you
will be using.




@need 3200

@section Creating SFTP Archives

[This isn't documented yet.]




@need 3200

@section Creating WebDAV and HTTP Archives

[This isn't documented yet.]







