# swcopy(8)

### Contents

- NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- TARGET COPYING RULES
  - Rules
  - Examples
- IMPLEMENTATION EXTENSIONS
  - RPM Translation
- EXTENDED OPTIONS
  - Posix
  - Swbis Implementation
- RETURN VALUE
- NOTES
- REQUISITE UTILITIES
- FILES
- APPLICABLE STANDARDS
- SEE ALSO
- IDENTIFICATION
- BUGS

### 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), that is
           if a directory is being copied, it will never be a  different  name  on
           the target.  A single source file is specified for one or more targets.
           The syntax does not support multiple source files.  A portable  charac-
           ter  string  in  the  target 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 directory from one host to another

                         Copy directory yy into directory cc if cc exists,
                         otherwise create cc and copy yy into it. If cc
                         is 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
           complies 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.481
            Date: 2006-02-15
            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 ]