swcopy(8)

Contents

NAME

       swcopy -- Copy POSIX and RPM packages.

SYNOPSIS

       swcopy [-p] [-s source_file] [-f file] [-t targetfile] \
       [-x option=value] [-X options_file] [-W option] \
       [software_selections] [@target [target1...]]

DESCRIPTION

       swcopy  copies  a POSIX distribution from a source archive or directory
       to a target archive directory.  Neither swcopy  nor  any  component  of
       swbis  is  required  on  the target host, however, the target host must
       look like a Unix system at the shell and  command-line  utility  level.
       Remote network connections are made by ssh.  Ssh is the default but rsh
       can be selected by a command line option.

       Before and during data transfer to  the  target,  the  distribution  is
       audited.   Package  auditing  includes parsing the INDEX and INFO meta-
       data files.  The package pathnames are checked for consistency  with  a
       valid  layout.   swcopy  can  be  made  to operate on arbitrary data or
       archives not in POSIX  format  by  using  the  --no-audit  option.   By
       default  and  with no external influences (i.e. swdefaults file) swcopy
       will read a archive on stdin and write an audited  archive  on  stdout.
       The  uncompressed  audited  output file will be identical to the uncom-
       pressed input file unless an error occurs.   Compressed  archives  that
       are  audited  will  be  re-compressed  in the same format, however, the
       resulting file may not be identical to the input file (i.e. date, file-
       name,  and  other  stored data in the compressed format will be differ-
       ent).

       swcopy operates on serial archives (e.g. compressed tar archives) or on
       file system directories.  It will attempt to preserve the form (archive
       or directory) and compression state of the source object.  An exception
       is "." as a target (See Implementation Extensions below).

OPTIONS

       -f FILE

              Reads software_selections from FILE. (Not implemented).

       -p

              Preview  the  operation.  Information is written to stdout.  The
              target is not written and no remote connections are established.


       -s SOURCE

              Specify the source file SOURCE, "-" is standard input.  The syn-
              tax is the same as for a target.  SOURCE may be a  directory  or
              archive file.

       -t targetfile

              Specify a file containing a list of targets (one per line).

       -x option=value

              Specify  the extended option overriding the defaults file value.

       -X FILE

              Specify the extended options  filename,  FILE,   overriding  the
              default  filenames.  This option may be given more then once. If
              the resulting specified value is an empty string then reading of
              any options file is disabled.

       -v

              Given one time it is identical to -x verbose=2.  This option can
              be given multiple times with increasing effect.  (Implementation
              extension option).
              -v  is level 2, -vv is level 3,... etc.
                  level 0: silent on stdout and stderr.
                  level 1: fatal and warning messages to stderr.
              -v  level 2: level 1 plus a progress bar.
              -vv level 3: level 2 plus script stderr.
              -vvv level 4: level 3 plus events.
              -vvvv level 5: level 4 plus events.
              -vvvvv level 6: level 5 plus set shell -vx option.
              -vvvvvv level 7 and higher: level 6 plus debugging messages.
               The  progress meter is suppressed if swcopy is using stdout for
              data.

       -b SIZE

              Set block size, same as --block-size=N (Implementation extension
              option).

       --version, -V

              Show version (Implementation extension)

       --help

              Show help (Implementation extension)

       -W option[,option,...]

              Specify the implementation extension option.
              Syntax: -W option[=option_argument[,option...]
              Options  may be separated by a comma.  The implementation exten-
              sion options may also be given individually using  the  '--long-
              option[=option_arg]' syntax.

       -W no-audit

              Defaults File Option: swbis_no_audit
              Do not audit the transferred file.  This allows copying of arbi-
              trary data.

       -W audit

              Do audit the transferred file.  Useful for  overriding  swbisde-
              faults file.

       -W block-size=SIZE

              SIZE is number of octets.

       -W login

              Establishes  a  interactive  shell  on the (remote) target host.
              Intended for debugging/verifying ssh operation.

       -W gzip

              Compress output using gzip.

       -W bzip

              Compress output using bzip2.

       -W extract

              Install the source using the archive reading utility at the tar-
              get.

       -W pty

              Do  use  pseudo-tty.   The  system  Ptys  are  only used for the
              --login feature.  A warning is emitted to stderr which says that
              the usage may be insecure.

       -W no-pty

              Do not use pseudo-tty.  The system Ptys are only used by default
              for the --login feature, otherwise they are not  used  and  this
              option  would  have  no  effect.   If ptys are used a warning is
              emitted to stderr which says that the usage may be insecure.

       -W uncompress

              Write output archive that is uncompressed.

       -W remote-shell=SHELL

              Defaults File Option: swbis_remote_shell_client
              Supported shells are "ssh" and "rsh", ssh is the default.

       -W quiet-progress

              Defaults File Option: swbis_quiet_progress_bar
              Disable progress bar, which is active for verbose levels  2  and
              higher (i.e. -v).

       -W show-progress

              Enables progress bar.(i.e. -v).

       -W show-options-files
              Show the complete list of options files and if they are found.

       -W show-options
              Show the options after reading the files and parsing the command
              line options.

       -W pax-command={tar|pax|star|gtar}
              Set the  portable  archive  command  for  all  operations.   The
              default is "pax".

       -W pax-read-command={tar|pax|star|gtar}
              Set the read command for local and remote hosts.

       -W remote-pax-read-command={tar|pax|star|gtar}
              Defaults File Option: swbis_remote_pax_read_command
              Set the read command for remote hosts.  This is the command that
              runs on the target (e.g. pax -r, tar xpf  -).   The  default  is
              "pax".

       -W local-pax-read-command={tar|pax|star|gtar}
              Defaults File Option: swbis_local_pax_read_command
              Set  the read command for local hosts.  This is the command that
              runs on the target (e.g. pax -r, tar xpf  -).   The  default  is
              "pax".

       -W pax-write-command={tar|pax|star|gtar|swbistar}
              Set  the  write command for local and remote hosts.  This is the
              command that runs on the target (e.g. pax -w, tar cf -).

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
              Defaults File Option: swbis_remote_pax_write_command
              Set the write command for remote hosts.

       -W local-pax-write-command={tar|pax|star|gtar|swbistar}
              Defaults File Option: swbis_local_pax_write_command
              Set the portable archive write command  for  local  host  opera-
              tions.   This  is  the command that runs on the source (e.g. pax
              -w, tar cf -).  The default is "pax".

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
              Defaults File Option: swbis_remote_pax_write_command
              Set the portable archive write command for  remote  host  opera-
              tions.   This  is  the command that runs on the source (e.g. pax
              -w, tar cf -).  The default is "pax".

       -W no-defaults
              Do not read any defaults files.

       -W no-remote-kill
              Defaults File Option: swbis_no_remote_kill
              Disables the use of a second remote connection to tear down  the
              first  in  the  event of SIGINT or SIGTERM or SIGPIPE.  Only has
              effect if the number of ssh hops is greater than  1.   A  single
              host  remote connection (ssh hop = 1) never uses a second remote
              connection.

       -W no-getconf
              Defaults File Option: swbis_no_getconf
              Makes the remote command be '/bin/sh -s' instead of the default

       -W shell-command=NAME
              Defaults File Option: swbis_shell_command
              NAME may be one of "bash", "sh" or  "posix"  and  specifies  the
              remote  command run by the remote shell.  "posix" is 'PATH=`get-
              conf PATH` sh -s', "bash" is "/bin/bash -s",  "sh"  is  "/bin/sh
              -s", and "ksh" is "ksh -s".  The default is "posix".

       -W use-getconf
              Opposite of --no-getconf.

       -W allow-rpm
              Defaults File Option: swbis_allow_rpm
              Allows detection and translation of RPMs.  (--audit must also be
              set.)

       -W unrpm
              Turns on options --allow-rpm and --audit.

       software_selections

              Refer to the software objects (products, filesets) on  which  to
              be  operated.  (Not  implemented).   The  implementation defined
              behavior for no selections is to operate on the entire distribu-
              tion.


       target

              Refers  to the software_collection where the software selections
              are to be applied.  Allows specification of  host  and  pathname
              where  the  software  collection is located.  A target that con-
              tains only one part is assumed  to  be  a  hostname.   To  force
              interpretation  as  a  path,  use a absolute path or prefix with
              ':'.


       Source and Target Specification and Logic

            Synopsis:
                 Posix:
                      host[:path]
                      host
                      host:
                      /path  # Absolute path

                 Swbis Extension:
                      [user@]host[:path]
                      :path

                 Swbis Multi-hop Target Extension:
                      # '@@' is the target delimiter
                      target@@target[@@targetN...]
                      [user@]host[@@[user@]host[@@...]][:path]

            A more formal description:

            target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
                   | HOST_CHARACTER_STRING ':'
                   | HOST_CHARACTER_STRING
                   | PATHNAME_CHARACTER_STRING
                   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
                   ;

              PATHNAME_CHARACTER_STRING must be an absolute path unless
                              a HOST_CHARACTER_STRING is given.  Allowing
                              a relative path is a feature of the swbis
                              implementation.

                       NOTE: A '.' as a target is an implementation
                             extension and means extract in current
                             directory.

                       NOTE: A '-' indicating stdout/stdin is an
                             implementation extension.

                       NOTE: A ':' in the first character indicates a filename.
                             This is an implementation extension.

              HOST_CHARACTER_STRING is an IP or hostname.

           Examples:
              Copy the  distribution /var/tmp/foo.tar.gz at 192.168.1.10
                     swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root


       Implementation Extension Syntax (multi ssh-hop) :
           Syntax:
           %start   wtarget    # the Implementation Extension Target
           wtarget   : wtarget DELIM sshtarget
                     | sshtarget
                     ;
           sshtarget : user '@' target # Note: only the last target
                     | target          # may have a PATHNAME
                     ;
           target   : HOST_CHARACTER_STRING
                    | HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
                    ;
           user     : PORTABLE_CHARACTER_STRING  # The user name

           DELIM    : '@@'   # The multi-hop delimiter.
                    ;


TARGET COPYING RULES

       Currently, file permissions and ownerships are not copied. 'swcopy'  is
       not  intended to be used in the way of cp or scp, although it can be if
       forced.  Non-existing directories in a target are  created.   A  source
       directory cannot be renamed (although a regular file can be).  A single
       source file is specified for one or more targets.  The syntax does  not
       support multiple source files.  A portable character string in the tar-
       get spec is assumed to be a hostname unless it begins with a slash  '/'
       or a colon ':'.

   Rules
       If  a  target  directory  on the host does not exist it will be created
       using mkdir -p using the file creation mask of the  originating  swcopy
       process.   A  trailing slash in the target spec signifies that the last
       path component should be a directory.  A source spec that is  a  direc-
       tory will be created on the target as a directory with the same name in
       the target directory.  If the source spec is stdin then  the  existence
       of  directories  in  the target spec and a trailing slash in the target
       spec path determines whether the created file will be a regular file or
       directory, that is, stdin will be copied as a file unless the last tar-
       get path component is a directory or ends  in  a  slash  '/'.   If  the
       source  spec is a regular file, the source basename will be used as the
       basename in the target if the last target path component is a directory
       or ends in a slash '/', otherwise, the target basename is the last path
       component of the target  spec.   The  implementation  option  --extract
       biases  these  rules to install using the archive reading command (e.g.
       pax -r).

   Examples
                  Install a tarball in the current directory:
                    Note: Must use stdin as source and "." as the target.

                          swcopy --no-audit -s - @. < foo.tar.gz

                   Copy thru a firewall:

                          swcopy -s /var/tmp/foo.tar.gz \
                               @root@host1@@root@host2:/var/tmp

                   Copy Stdin to a remote host:

                     Unpack the archive on stdin in the directory
                     /a/b/c if 'c' is a directory, otherwise copy
                     the archive file to a file named 'c' in
                     directory /a/b creating it if possible and
                     overwriting if required.
                         swcopy -s - @host1:/a/b/c

                   Copy Stdin to a remote host:

                     Unpack the serial archive on stdin in the
                     directory /a/b/c if 'c' is a directory,
                     otherwise make the directory 'c' but fail if
                     directory 'c' cannot be created.
                         swcopy -s - @host1:/a/b/c/
                                   # Note trailing slash.

                   Copy a regular file:

                     Copy file yy to directory /aa/bb/cc/ on the
                     remote host, creating it if required and possible.
                     If cc is a regular file then fail.
                         swcopy -s /xx/yy @host1:/aa/bb/cc/

                   Copy a regular file thru intermediate host 'fw':

                     Copy file yy to home directory of user1 on host1
                     thru a an intermediate host fw,
                         swcopy -s /xx/yy @fw@@user1@host1:.

                   Copy a regular file:

                     Copy yy into directory cc if it exists, otherwise
                     copy into bb renaming as cc, otherwise create cc
                     and copy as yy.
                         swcopy -s /xx/yy @host1:/aa/bb/cc

IMPLEMENTATION EXTENSIONS

   Software Specification Targets
       A dash '-' is supported and means stdout  or  stdin.   Operations  with
       stdout and stdin on a remote host is not supported.

       A  decimal  '.'  is supported and means the current directory.  This is
       supported for remote and non-remote targets.  If the source is standard
       input, the distribution will be unpacked (e.g. pax -r) in the directory
       '.'.  If the source is a regular file then a regular file in  '.'  will
       be created with the same name.

       Thus,

                  # swcopy -s `pwd`/myarchive.tgz @.  # Do NOT do this even
                                                      # though in most cases
                                                      # swcopy is a coward.

        will destroy the source file myarchive.tgz, whereas

                  # swcopy -s - @. <`pwd`/myarchive.tgz

        will install it with the configured archive reading utility.



   RPM Translation
       RPM (RedHat Package Manager) format packages are copied by first trans-
       lating to an equivalent ISO/IEEE file layout in POSIX  tar  format  and
       then  copying  as  a  POSIX package.  The RPM detection and translation
       occurs if the ''--allow-rpm'' option is on (either by the command  line
       args  or  defaults  file)  and  the  ''--audit''  option is on.  If the
       ''--allow-rpm'' option is not set an error occurs.  If the  ''--audit''
       is  not  set,  the RPM is copied as arbitrary data and translation does
       not occur.

       Since translation is done on the local (management) host,  RPM  is  not
       reqired on the remote (target) host.

       The translation is (internally) equivalent to :

          cat your-poor-poor-0.0.bin.rpm |
          /usr/lib/swbis/lxpsf --psf-form2 -H ustar |
          swpackage -Wsource=- -s@PSF

EXTENDED OPTIONS

       Extended  options  can  be  specified  on the command line using the -x
       option or from the defaults file, swdefaults.  Shown below is an actual
       portion of a defaults file which show default values.

   Posix
       These  options are set in the /usr/lib/swbis/swdefaults or the ~/.swde-
       faults


          autoselect_dependencies     = false      # Not Implemented
          compress_files              = false      # Not Implemented
          compression_type            = none       # Not Implemented
          distribution_source_directory   = -
          distribution_target_directory   = -
          enforce_dependencies        = false       # Not Implemented
          enforce_dsa                 = false       # Not Implemented
          logfile                     = /var/lib/sw/swcopy.log #Not Implemented
          loglevel                    = 1          # Not Implemented
          recopy                      = false      # Not Implemented
          select_local         = false      # Not Implemented
          uncompress_files             = false     # Not Implemented
          verbose                      = 1


   Swbis Implementation
       These options  are  set  in  the  /usr/lib/swbis/swbisdefaults  or  the
       ~/.swbis/swbisdefaults file.


         swcopy.swbis_no_getconf = false # true or false
         swcopy.swbis_shell_command = posix # {sh|bash|posix|ksh}
         swcopy.swbis_no_remote_kill = false # true or false
         swcopy.swbis_no_audit = false # true or false
         swcopy.swbis_quiet_progress_bar = false # true or false
         swcopy.swbis_local_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
         swcopy.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
         swcopy.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
         swcopy.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
         swcopy.swbis_allow_rpm = false  # true or false
         swcopy.swbis_remote_shell_client=ssh

RETURN VALUE

       0  if all targets succeeded, 1 if all targets failed, 2 if some targets
       failed and some succeeded.

NOTES

        Multiple ssh-hops is an implementation extension.

REQUISITE UTILITIES

       Swcopy requires a Posix shell accessible by the remote  shell  command.
       This  is  the  remote  command  run by ssh (or rsh) for all operations.
       This command can be controlled by the  --shell-command  option  or  the
       swbis_shell_command  defaults file option.  Permitted values are "bash"
       (/bin/bash -s), "sh" (/bin/sh  -s),  "ksh"  (/bin/ksh  -s)  or  "posix"
       ('PATH=`getconf  PATH`  sh  -s').   The  default  is  "posix".   swcopy
       requires the POSIX capability of reading commands on stdin according to
       the  specification  described  in IEEE Std 1003.1, 2003 Ed.; sh -shell,
       Section STDIN.  This requirement accommodates reading of shell  program
       code  and  data  on  STDIN.  This capability may not be present in some
       /bin/sh shells.  The "/bin/sh" on FreeBSD-5.1 is broken in this regard,
       hence  ''--shell-command=bash'' should be used for BSD hosts.  The pub-
       lic domain Korn shell (pdksh-5.2.14) seems to work OK, that is, it com-
       plies  by  luck or intent with the POSIX capability of reading data and
       code on stdin.

       If the  --no-getconf  option  is  set  or  the  swcopy.swbis_no_getconf
       defaults option is "true" then the remote command is '/bin/sh -s'.  Use
       of the no-getconf option is needed for communication with user accounts
       on  remote  machines whose login shell is not a Bourne shell (e.g. csh)
       such as root on some default BSD installations.  Other *nix systems may
       require  use  of  getconf  because their /bin/sh is broken or not Posix
       enough (e.g. Sun platforms).  Still other systems may not have getconf.

       Other utilities required to be in $PATH on the remote host are: dd, pax
       (or tar|star|gtar), mkdir, echo, test, sleep, read (if not builtin).

FILES

       /usr/lib/swbis/swdefaults
       /usr/lib/swbis/swbisdefaults
       $HOME/.swbis/swdefaults
       $HOME/.swbis/swbisdefaults


APPLICABLE STANDARDS

       ISO/IEC 15068-2:1999, Open Group CAE C701

SEE ALSO

       info swbis

       sw(5), swbisparse(1), swign(1), swverify(8)

IDENTIFICATION

        swcopy(8): The archive copying utility of the swbis project.
        Author: Jim Lowe   Email: jhlowe at acm.org
        Version: 0.473
        Date: 2005-11-04
        Copying: GNU Free Documentation License

BUGS

       Swcopy is subject to breakage if a user's account  on  an  intermediate
       (or  terminal)  host in a target spec is not configured to use a Bourne
       compatible shell. (This breakage may be eliminated by use of the  --no-
       getconf option as explained above.)

       A  multiple  ssh  hop source spec  (more than 1 remote host involved in
       the source transfer) upon a SIGINT may result in sshd and ssh processes
       being  left  on  on  the  intermediate  host(s), this despite, swcopy's
       action of sending a SIGTERM to the remote script's parent process.

       Swcopy does not currently implement Software Selections nor the  events
       of the Selection and Analysis Phases nor dependency copying nor fileset
       state transitions.  The Execution (copying) phase is done on the entire
       distribution  by  the  utility  selected  in .../swbisdefaults which is
       pax(1) by default.  Pax is not found on all GNU/Linux  systems.   Also,
       the pax version shipped with some (older) GNU/Linux systems mangles the
       pathname of files whose pathname is exactly 100 octets  long.   Despite
       this  pax  is  the  the  builtin  default.   GNU tar is widely used and
       trusted but creates non-standard archives for long pathnames.   Perhaps
       the  best  compromise is to use star (with -H ustar header option)  for
       archive creation and (GNU) tar for archive reading.  If  your  environ-
       ment is 100% GNU/Linux using GNU tar is safe (GNU tar 1.13.25 is recom-
       mended).  Swcopy does not support using  the  cpio  utility  since  its
       archive  writing interface is unlike pax and tar, although, future sup-
       port is possible for archive reading.



                                                                     swcopy(8)

[ Index ] [ Back ]