GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XSHAR (1)

.ds Aq ’

NAME

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

CONTENTS

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.
Search for    or go to Top of page |  Section 1 |  Main Index


perl v5.20.3 XSHAR (1) 2016-03-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.