Provided by: libsvn-notify-mirror-perl_0.04000-2_all bug

NAME

       SVN::Notify::Mirror::SSH - Mirror a repository path via SSH

SYNOPSIS

       Use svnnotify in post-commit:

         svnnotify --repos-path "$1" --revision "$2" \
          --handler Mirror::SSH --to "/path/to/www/htdocs" \
          [--svn-binary /full/path/to/svn] \
          [[--ssh-host remote_host] [--ssh-user remote_user] \
          [--ssh-tunnel 10.0.0.2] \
          [--ssh-identity /home/user/.ssh/id_rsa]]

       or better yet, use SVN::Notify::Config for a more sophisticated setup:

         #!/usr/bin/perl -MSVN::Notify::Config=$0
         --- #YAML:1.0
         '':
           PATH: "/usr/bin:/usr/local/bin"
         'path/in/repository':
           handler: Mirror
           to: "/path/to/www/htdocs"
         'some/other/path/in/repository':
           handler: Mirror::SSH
           to: "/path/to/remote/www/htdocs"
           ssh-host: "remote_host"
           ssh-user: "remote_user"
           ssh-tunnel: "10.0.0.2"
           ssh-identity: "/home/user/.ssh/id_rsa"

DESCRIPTION

       Keep a directory in sync with a portion of a Subversion repository.  Typically used to
       keep a development web server in sync with the changes made to the repository.  This
       directory can either be on the same box as the repository itself, or it can be remote (via
       SSH connection).

USAGE

       Depending on whether the target is a "Local Mirror" or a Remote Mirror, there are
       different options available.  All options are available either as a commandline option to
       svnnotify or as a hash key in SVN::Notify::Config (see their respective documentation for
       more details).

   Working Copy on Mirror
       Because 'svn export' is not able to be consistently updated, the sync'd directory must be
       a full working copy, and if you are running Apache, you should add lines like the
       following to your Apache configuration file:

         # Disallow browsing of Subversion working copy
         # administrative directories.
         <DirectoryMatch "^/.*/\.svn/">
          Order deny,allow
          Deny from all
         </DirectoryMatch>

       The files in the working copy must be writeable (preferrably owned) by the user identity
       executing the hook script (this is the user identity that is running Apache or svnserve
       respectively).

Local Mirror

       Please see SVN::Notify::Mirror for details.

   Remote Mirror
       Used for directories not located on the same machine as the repository itself.  Typically,
       this might be a production web server located in a DMZ, so special consideration must be
       paid to security concerns.  In particular, the remote mirror server may not be able to
       directly access the repository box.

       NOTE: be sure and consult "Remote Mirror Pre-requisites" before configuring your post-
       commit hook.

       ·   ssh-host

           This value is required and must be the hostname or IP address of the remote host
           (where the mirror directories reside).

       ·   ssh-user

           This value is optional and specifies the remote username that owns the working copy
           mirror.

       ·   ssh-identity

           This value may be optional and should be the full path to the local identity file
           being used to authenticate with the remote host. If you are setting the ssh-user to be
           something other than the local user name, you will typically also have to set the ssh-
           identity.

       ·   ssh-tunnel

           If the remote server does not have direct access to the repository server, it is
           possible to use the tunneling capabilities of SSH to provide temporary access to the
           repository.  This works even if repository is located internally, and the remote
           server is located outside of a firewall or on a DMZ.

           The value passed for ssh-tunnel should be the IP address to which the local repository
           service is bound (when using svnserve).  This will tunnel port 3690 from the
           repository box to localhost:3690 on the remote box.  This must also be the way that
           the original working copy was checked out (see below).

           To tunnel some other port, for example when using Apache/mod_dav, ssh-tunnel should be
           the entire mapping expression, as described in the OpenSSH documentation under the
           "-R" option (remote port forwarding).  For most sites, passing "8080:10.0.0.2:80" will
           work (which will tunnel port 80 from the repository to port 8080 on the remote
           client).  If you are using SSL with Apache, you can use e.g. "80443:10.0.0.2:443".

           For example, see "Remote Mirror Pre-requisites" and after step #6, perform the
           following additional steps (when using svnserve):

             # su - localuser
             $ ssh -i .ssh/id_rsa remote_user@remote_host -R3690:10.0.0.2:3690
             $ cd /path/to/mirror/working/copy
             $ svn co svn://127.0.0.1/repos/path/to/files .

           where 10.0.0.2 is the IP address hosting the repository service.  For the same
           configuration when using Apache/mod_dav, do this instead:

             # su - localuser
             $ ssh -i .ssh/id_rsa remote_user@remote_host -R8080:10.0.0.2:80
             $ cd /path/to/mirror/working/copy
             $ svn co http://127.0.0.1:8080/repos/path/to/files .

       ·   ssh-options

           If you have any other options that you would like to pass to the ssh client (for
           example to change the default SSH port), you can pass extra options using this
           parameter.  Be sure that you pass it a string that has ssh long option/value pairs
           separated by a space, or short options without any space at all.  Internally,
           parameter is split on spaces and passed in the @Net::SSH::options array.

   Remote Mirror Pre-requisites
       Before you can configure a remote mirror, you need to produce an SSH identity file to use:

       1. Log in as repository user
           Give the user identity being used to execute the hook scripts (the user running Apache
           or svnserve) a shell and log in as that user, e.g. "su - svn";

       2. Create SSH identity files on repository machine
           Run "ssh-keygen" and create an identity file (without a password).

       3. Log in as remote user
           Perform the same steps as #1, but this time on the remote machine.  This username
           doesn't have to be the same as in step #1, but it must be a user with full write
           access to the mirror working copy.

       4. Create SSH identity files on remote machine
           It is usually more efficient to go ahead and use "ssh-keygen" to create the .ssh
           folder in the home directory of the remote user.

       5. Copy the public key from local to remote
           Copy the .ssh/id_dsa.pub (or id_rsa.pub if you created an RSA key) to the remote
           server and add it to the .ssh/authorized_keys for the remote user.  See the SSH
           documentation for instructions on how to configure

       6. Confirm configuration
           As the repository user, confirm that you can successfully connect to the remote
           account, e.g.:

             # su - local_user
             $ ssh -i .ssh/id_rsa remote_user@remote_host

           This is actually a good time to either check out the working copy or to confirm that
           the remote account has rights to update the working copy mirror.  If the remote server
           does not have direct network access to the repository server, you can use the tunnel
           facility of SSH (see ssh-tunnel above) to provide access (e.g.  through a firewall).

       Once you have set up the various accounts, you are ready to set your options.

AUTHOR

       John Peacock <jpeacock@cpan.org>

COPYRIGHT

       Copyright (c) 2005-2008 John Peacock

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

       SVN::Notify, SVN::Notify::Config, SVN::Notify::Mirror