Installation
These installation instructions can be followed when installing from source:
-
Download the latest release from the download page.
-
Go to the directory where the archive has been downloaded and
unpack it using the following command:
0.0.0 should be replaced with the version of AScopy that has been downloaded.tar xvzf ascopy-0.0.0.tar.gz
-
Go to the newly created directory and type:
Make sure that you have sufficient rights for the installation../configure && make && make install
The configure script provides some optional settings. Type./configure --helpto view the possibilities.
-
Make sure that the
ascopybinary is in yourPATHand that the man page can be found through yourMANPATHenvironment variable.
- AScopy is now ready for use. Please refer to the user's manual below for more information.
User's manual
The documentation below is the user's manual as it is included with the distribution of AScopy. It is always a copy of the documentation included in the latest stable release.
NAME
ascopy - web site maintenance utility
SYNOPSIS
ascopy [OPTIONS]... [ACTION] SITENAME
DESCRIPTION
Synchronize files, directories and their permissions between the remote
location for a web site and its location on a local machine. Only
files and directories that have changed will be transferred. The trans-
portation is done using an external SFTP client.
Ascopy recognizes files that have been moved or copied to a new loca-
tion and does not attempt to send these files to the remote site. It
just copies them directly on the remote site.
OPTIONS
The options for ascopy can be split into two groups: one option indi-
cating the action the program has to take and other options that change
the behavior during operation. The possible actions and options are
listed below:
Actions
-l, --list
List changes between remote and local sites (default).
-v, --view
Display a list of the site definitions. By default it shows the
definitions as stored in $HOME/.ascopyrc unless another configu-
ration file has been specified (see Optional Settings).
-i, --init, --initialize
Mark all files and directories as not updated. This removes the
local stored information for the remote site and makes ascopy
think that there are no files on the remote server. The default
location for the file that will be removed is:
$HOME/.ascopy/<sitename>. See FILES.
-f, --fetch
Find out what files are on the remote site. This will overwrite
the locally stored information on for the remote site. The
default location for this data is: $HOME/.ascopy/<sitename>. See
FILES.
-e, --verify
Verify stored state of site matches real remote state. If both
the local and the remote site are the same ascopy will exit with
a return value of 0, otherwise it will return with a value of 1.
-c, --catchup
Mark all files and directories as updated. This will take the
state of the local site and write it to the file containing the
state for the site. Default location: $HOME/.ascopy/<sitename>.
See FILES.
-s, --synch, --synchronize
Update the local site from the remote site. This makes the local
copy of the site equal to the remote copy. Local files may be
deleted or changed.
-u, --up, --update
Update the remote site from the local site.
-h, --help
Display this help message.
-V, --version
Display version information.
Optional settings
-r FILE, --rcfile=FILE
Use alternate run control file. See FILES for more information
on the format of this file.
-p PATH, --storepath=PATH
Use alternate site storage directory. See FILES.
-y, --prompting
Request confirmation before making each update.
-q, --quiet
Be quiet while performing the operation. If confirmation is
needed or requested (see the -p or --prompting optional setting)
it will not be suppressed.
-n, --dry-run
Display what will be done but do not carry out the operation.
RETURN VALUES
The program returns 0 if everything went well, 1 otherwise.
ENVIRONMENT
ascopy's behavior is affected by the following environment variables:
ASCOPY_SITEDATA_DIR
This variable holds the path where the data for each site will
be stored. Its default value is $HOME/.ascopy and can also be
set using the -p or --storepath option.
ASCOPY_CONF_FILE
Defines the name of the file that holds the configuration data
of the remote sites. Its default value is $HOME/.ascopyrc and
can also be set using the -r or --rcfile option. See the FILES
section for information about the content.
FILES
.ascopyrc
Default run configuration file that contains the site settings. Other
files can be set using ASCOPY_CONF_FILE (see ENVIRONMENT) or the
--rcfile command line switch (see OPTIONS).
The configuration file is a text file that holds the settings as key-
value pairs where the key and value are separated by whitespace. The
following keys have to be defined:
site sitename
Sets the name of the definition for a site. It MUST be the first
entry for each definition as aScopy will consider all following
entries to belong to this definition.
server servername
The name of the remote server for the site.
username username
The username with which to log in to the remote server.
local dir
The directory where the local copy of the site will be stored.
remote dir
The directory on the remote system where the site will be
stored.
exclude pattern
Files or directories that can be excluded when building the
actual file list from the local machine or the remote system.
Beware the files that were once correctly but that are now
excluded, will be deleted from the remote server when an update
is done. The exclude option can take three forms:
To exclude files in any directory that conform to a certain pat-
tern, the pattern following exclude is just the general file
pattern. The first example excludes all files that end with the
'bak' extension, the second example excludes all files start
with a '.' and end with the 'swp' extension (vi temporary
files):
exclude *.bak
exclude .*.swp
To exclude files in a specific directory, prefix the pattern
with a slash '/'. The example below will exclude all files with
a 'txt' extension in the given directory. The directory is rela-
tive to the directories specified with local or remote.
exclude /personal/*.txt
It is even possible to exclude entire directories using the syn-
tax shown before. The following example will exclude all files
and sub-directories in the personal directory:
exclude /personal
Example configuration file:
site www.yoursite.com
username hutch
server your.uploadserver.com
local /home/hutch/htdocs/www.yoursite.com/
remote /home/who/htdocs/
exclude *.bak
exclude .*.swp
As stated the configuration file can contain more than one site
definition. Whitespace is ignored so it can be used to make the
file a bit more readable.
Data files.
For each site definition in the configuration file a file will be cre-
ated that holds the state of that site. The location of these files is
by default in the directory $HOME/.ascopy but can be changed by setting
ASCOPY_SITEDATA_DIR (see ENVIRONMENT) or using the --storepath switch
(see OPTIONS).
EXAMPLES
Starting from scratch
ascopy needs a run control file where the definitions for the sites
will be stored and a working directory. Both have to be created manu-
ally. Use the following command to create the working directory:
mkdir -m 700 $HOME/.ascopy
To create an empty run file execute the following commands:
touch $HOME/.ascopyrc
chmod 600 $HOME/.ascopyrc
After this has been done the run file can be edited and the site
details can be entered in there. See the FILES section for details.
Since ascopy uses SSH and SFTP the user will be asked for a username
and a password. This can be a bit cumbersome and SSH allows
authentication to be automated using a key pair. The ssh(1) documenta-
tion contains information on this.
Starting with an existing remote web site
It is assumed that the site configuration already has been set (see
FILES). First get the information on the remote site:
ascopy --fetch sitename
Then make the local site equal to the remote site:
ascopy --synchronize sitename
Beware that might alter and/or destroy files on your local machine. It
might be wise to make a backup first.
Starting with an existing local web site
Make sure that the root directory of the remote site has been created
by either you or the administrator. The issue the following command:
ascopy --initialize sitename
Uploading changes
To upload the changes made to a local site use the following command:
ascopy --update sitename
SEE ALSO
ssh(1), sftp(1)
AUTHOR
Copyright (C) 2006 Niels Heirbaut <niels@heirbaut.nl>.
BUGS
There are some annoyances and probably also some bugs. Please report
them to <nheirbaut@users.sourceforge.net>.
ascopy 1.0.0 December 2006 ASCOPY(1)