These installation instructions can be followed when installing from source:
0.0.0 should be replaced with the version of AScopy that has been
tar xvzf ascopy-0.0.0.tar.gz
Make sure that you have sufficient rights for
./configure && make && make
./configure --helpto view the possibilities.
ascopybinary is in your
PATHand that the man page can be found through your
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.
ascopy - web site maintenance utility
ascopy [OPTIONS]... [ACTION] SITENAME
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.
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.
The program returns 0 if everything went well, 1 otherwise.
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.
.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).
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
Copyright (C) 2006 Niels Heirbaut <email@example.com>.
There are some annoyances and probably also some bugs. Please report them to <firstname.lastname@example.org>.
ascopy 1.0.0 December 2006 ASCOPY(1)