The FTimes Project The HashDig Project The WebJob Project The PaD Project
Location: / Home / WebJob / Man Pages / xshar
Man Pages
WebJob
Home
                                                                                                                                                                                                       


NAME

xshar - Create an extended shell archive of one or more files.


SYNOPSIS

xshar [-u umask] file [file ...]


DESCRIPTION

This utility creates an extended shell archive from one or more input files. The archive is written to stdout as a sh(1) script. Only regular, text files may be placed in the archive. The resulting script will attempt to create intermediate directories on extraction.

Archives, when executed with no arguments, will print the following usage:

  <script> {-d|--deploy} [options] [-- command [options]]
           {-l|--lsshar} [options] [-- command [options]]
           {-r|--remove} [options] [-- command [options]]
           {-R|--revert} [options] [-- command [options]]

Details about the archive's various execution modes and options can be found in the following sections.


MODES OF OPERATION (SHELL ARCHIVE)

Each of the shell archive's execution modes is described below.

-d|--deploy

Deploy the contents of the archive (creating intermediate directories as needed), and conditionally execute a follow-up command.

-l|--lsshar

List the contents of the archive, and conditionally execute a follow-up command.

-r|--remove

Remove the contents of the archive (including empty directories), and conditionally execute a follow-up command.

-R|--revert

Revert the contents of the archive, and conditionally execute a follow-up command. Note that only files with a corresponding backup file (<file>.xsb) will be reverted.


OPTIONS (XSHAR)

-u umask

Specifies a umask value to embed (as a default value) in the shell archive. If not specified, a value of 022 is used.


OPTIONS (SHELL ARCHIVE)

Each of the shell archive's execution modes will accept the following options:

-C dir

Change to the specified directory before performing any work. If the directory does not exist, the script will abort.

-u umask

Set the run-time umask to the value specified.

Additionally, --deploy mode will accept the following option:

-b

Create backup files if the files being deployed already exist. Backup files will have an extension of '.xsb'.


FOLLOW-UP COMMAND (SHELL ARCHIVE)

The tokens described below may be used as place holders in the follow-up command. Before the command is executed, these tokens are expanded to their current values. The character '%' may be used to produce a literal token. For example, '%%1' would be expanded to '%1'.

%%

Escapes a single '%' character.

%1-%N

Expands to the name of a file or directory contained in the archive. The order that files are added to the archive determines their token value.

%contents

Expands to a list of all files and directories in the archive.

%cmd

Expands to the basename of the executing script.

%cwd

Expands to the current working directory. In general, this will differ from %owd when the -C option is used to change to directories.

%dirs

Expands to a list of all directories in the archive.

%files

Expands to a list of all files in the archive.

%owd

Expands to the original working directory.


EXAMPLES (SHELL ARCHIVE)

Example 1. List the contents of a shell archive

This example demonstrates how to list the contents of an archive called 'out.sh'.

  $ sh out.sh --lsshar

or (in short form)

  $ sh out.sh -l

Example 2. Deploy the contents of a shell archive

This example demonstrates how to deploy the contents of an archive called 'out.sh' to /usr/local/etc.

  $ sh out.sh --deploy -C /usr/local/etc

or (in short form)

  $ sh out.sh -d -C /usr/local/etc

Note: All files in an archive are relative. Therefore, if the -C option is not used, the files will be extracted to the current working directory.

Note: The specified directory must exist, or the script will abort.

Example 3. Remove the contents of a shell archive

This example demonstrates how to remove the contents of an archive called 'out.sh' from /usr/local/etc.

  $ sh out.sh --remove -C /usr/local/etc

or (in short form)

  $ sh out.sh -r -C /usr/local/etc

Note: All files in an archive are relative. Therefore, if the -C option is not used, the files will be removed from the current working directory.

Note: The script will attempt to remove any directories that it may have created. These operations will fail if the directories are not empty.

Example 4. Use tokens in a follow-up command

This example demonstrates how to use tokens in a follow-up command to perform inline editing of a file (upload.cfg) once it has been deployed. First, list the contents of the archive (out.sh):

  $ sh out.sh -l
  lsshar - config (%1)
  lsshar - config/import.cfg (%2)
  lsshar - config/upload.cfg (%3)

Note the token value (%3) that correspnds to the file upload.cfg.

Next, deploy the contents of the archive to the current working directory using a follow-up command that will remove any lines in upload.cfg that begin with the string 'Import='.

  $ sh out.sh -d -- 'perl -n -i -e "print unless (/^Import=/);" %3'
  deploy - config
  deploy - config/import.cfg
  deploy - config/upload.cfg
  runcmd - perl -n -i -e "print unless (/^Import=/);" config/upload.cfg
  status - 0

Example 5. Deploy a shell archive containing a uuencoded binary

This example demonstrates how to deploy a shell archive containing a uuencoded file and set the permissions on the resulting binary. Assume that the archive in question was built using Example 3 from the EXAMPLES (XSHAR) section.

  $ sh webjob.sh -d -- 'uudecode %1 && chmod 755 `basename %1 .uu`'

To remove the original uuencoded file when done, substitute the command shown above with the one given here:

  '{ uudecode %1 && chmod 755 `basename %1 .uu` ; rm -f %1 ; }'


EXAMPLES (XSHAR)

Example 1. Create a shell archive of several '.cfg' files

This example demonstrates how to create an archive of all '.cfg' files in the current directory:

  $ xshar *.cfg > out.sh

Example 2. Create a shell archive of a given directory

This example demonstrates how to create an archive of all files in a given directory:

  $ xshar `find <dir> -type f` > out.sh

Example 3. Create a shell archive containing a uuencoded binary

This example demonstrates how to create a shell archive containing a uuencoded binary.

  $ uuencode webjob > webjob.uu
  $ xshar webjob.uu > webjob.sh


AUTHOR

Klayton Monroe


HISTORY

This utility started out as a script that could create custom shell archives to hold WebJob config files. The shell archive format is a good fit for WebJob because it is executable and can hold multiple files. Therefore, clients needing to update their local configuration can do so in a single operation simply by running a job that downloads and deploys their personalized shell archive.

Over time, the custom bits that made this utility application-specific were refactored and generalized away. Also, the code was heavily influenced by PaD, which predates the use of shell archives within the project. In particular, xshar adopted PaD's delivery command capability -- being able to run delivery/follow-up commands has proven to be very useful in WebJob deployments.

This utility first appeared in WebJob 1.8.0.


SEE ALSO

sh(1), shar(1)


LICENSE

All documentation and code are distributed under same terms and conditions as WebJob.

Copyright 2000-2014 The WebJob Project, All Rights Reserved.
The FreeBSD Project SourceForge Logo KoreLogic, Inc.