NAME

App::Smbxfer - A "modulino" (module/program hybrid) for file transfer between Samba shares and the local filesystem.

MODULINO: MOTIVATION AND DESCRIPTION

This software provides a subset of the features of smbclient. The main motivation for its existence was a limitation in smbclient causing a timeout that precluded transfer of large files.

An especially useful way to apply this modulino is to invoke it as a non-interactive command-line tool. This can be an effective way to create cron jobs for backup of data TO Samba shares.

As a module, it provides functions to conduct file transfers, get information on Samba filesystem objects, and to perform validations on "SMB path specs," Samba location identifiers of the form:

smb://server/share/path/to/something

VERSION

This documentation refers to App::Smbxfer version 0.01.

MODULE: FUNCTIONS

Functions in App::Smbxfer are used to aid with transferring files between Samba shares and the local filesysem. This is the context in which the following functions are provided.

usage

Prints command-line usage information.

options

Prints command-line options.

run

"main() method" for running module as a command-line program.

credentials

my ($username, $password, $domain) = credentials( $credentials_file );

Load SMB access credentials from the specified filename, which should be formatted as expected by the smb* suite of tools (smbclient, etc.)

validated_paths

my ($local_path, $remote_smb_path_spec) = validated_paths(
    SMB => $smb,
    SOURCE => $source,
    DEST => $dest,
    SOURCE_IS_LOCAL => $whether_or_not_source_is_local_path
);

Given source, destination paths as expected by modulino's run() function, performs validations and returns normalized forms of both paths in order (source, dest).

do_smb_transfer

do_smb_transfer(
    SMB_OBJECT =>        $smb,
    LOCAL_PATH =>        $local_path,
    SMB_PATH_SPEC =>     $remote_smb_path_spec,
    SOURCE_IS_LOCAL =>   $whether_or_not_source_is_local_path,
    RECURSIVE =>         1,
    CREATE_PARENTS =>    1
);

Handles setup for upload/download, then delegates responsibility for file transfer to the appropriate handler.

parse_smb_spec

my ($smb_parent_path, $smb_path, $smb_share_spec) =
    ( parse_smb_spec( $smb_path_spec ) )[2,3,4];

Given a Samba location identifier with optional leading 'smb:', returns a number of potentially useful pieces of the path (server, share, path name, basename, etc.).

The following are returned (in order):

0

Server

1

Share

2

Parent path

3

Path

4

Share spec

5

Path spec

6

Parent path spec

7

Basename

create_smb_dir_path

create_smb_dir_path( $smb, $smb_path_spec_prefix, $path_to_create );

Creates directories on the Samba share leading up to and including the given directory path. The path created is rooted at the specified SMB path spec prefix, which should represent an existing directory node in the Samba share filesystem.

create_local_dir_path

create_local_dir_path( $local_prefix, $path_to_create );

Creates directories on the local filesystem leading up to and including the given directory path. The path created is rooted at the specified prefix path, which should represent an existing directory node in the local filesystem.

smb_element_type

my $remote_element_type = smb_element_type( $smb, $smb_path_spec );

Find the 'type' (file, dir, etc.) of an SMB element given its path spec. If the element itself does not exist, an undefined value is returned.

smb_download

smb_download(
    SMB_OBJ => $smb,
    SMB_PATH_SPEC => $smb_path_spec,
    LOCAL_DEST_NAME => $local_path,
    RECURSIVE => 0
);

Download a file from a Samba network share to the local filesystem.

smb_upload

smb_upload(
    SMB_OBJ => $smb,
    SOURCE => $local_path,
    SMB_PATH_SPEC => $smb_path_spec,
    RECURSIVE => 1
);

Upload a file from the local filesystem to a Samba network share.

PROGRAM: USAGE

USAGE
  Smbxfer <options> //<server>/<share>[/<path>[/<filename>]] <local-name>
  Smbxfer <options> <local-name> //<server>/<share>[/<path>/<filename>]


OPTIONS
  Usage information:
  --usage|help

  Command-line options:
  --options

  Name of file containing credentials (standard smb credentials file):
  --cred <credentials-filename>
  
  Transfer directory <local-name>:
  --recursive

  Create parent directories:
  --parents

PROGRAM: REQUIRED ARGUMENTS

As in the 'cp' command, two arguments are required: the source and the destination, in that order.

PROGRAM: OPTIONS

This program can be given an option, '--cred', that specifies the path to a filename containing Samba access credentials, explained in the CONFIGURATION AND ENVIRONMENT section.

For recursive transfers, the '--recursive' flag is supported. The '--parents' flag causes the entire directory structure from the source path argument to be replicated at the destination. If the source path argument is a relative path, only the dirs in the path as specified will be created at the destination. For the entire path from root to be created, specify an absolute path for the source path.

For usage and options information, try ('--usage' or '--help') and '--options', respectively.

PROGRAM: DIAGNOSTICS

Invalid options!

Command-line options were not recognized. --usage and --options provide succinct information to resolve.

cannot open credentials file: ...

The specified Samba access credentials file could not be opened.

Error: SMB specification smb path spec not found

Could not connect to the indicated Samba server/share/path.

source OR destination must be in "SMB path spec" format

Exactly one of the source and destination must be formatted in "SMB path specification" format: '//<server>/<share>[/<path>]'

Error: local source source is not a file or a directory

Only files or directories may be uploaded to a Samba server.

Error: SMB source source is not a file or a directory

Only files or directories may be downloaded from a Samba server.

Error: when transferring a directory source, any existing destination must also be a directory

An directory was specified as the source for a transfer and a file was specified as the destination.

Error: destination must be a directory with --parents option.

When using --parents to replicate parent directory structures, the destination must be a directory, not some existing file (since replication of directory structures implies restrictions on the location of the target file).

Omitting directory $src_smb_path in non-recursive mode.

The --recursive option must be used for directory transfers.

path is not a directory or a file...ignoring.

Only files or directories can be uploaded or downloaded using smb_upload() or smb_download().

cannot open file: ...

Local OS error while trying to open a file.

cannot mkdir path : ...

Local OS error while trying to create a directory.

SMB error: cannot create file: ...

Remote Samba error while trying to create a file.

SMB error: cannot mkdir path : ...

Remote Samba error while trying to create a directory.

SMB error: cannot opendir: ...

Remote Samba error while trying to open a directory.

SMB error: cannot unlink: ...

Remote Samba error while trying to delete a file.

PROGRAM: CONFIGURATION AND ENVIRONMENT

The credentials file that can be used via the '--cred' option should be in the same format used by smbclient. This file looks as follows:

   username = <username>
   password = <password>
   domain = <domain>

PROGRAM: NON-TRIVIAL DEPENDENCIES

Filesys::SmbClient

IO::Prompt

PROGRAM: INCOMPATIBILITIES

No known incompatibilities.

BUGS AND LIMITATIONS

No known bugs. Please report problems to Karl Erisman (kerisman@cpan.org). Patches are welcome.

AUTHOR

Karl Erisman (kerisman@cpan.org)

LICENSE AND COPYRIGHT

Copyright (c) 2007 Karl Erisman (kerisman@cpan.org). All rights reserved.

This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SCRIPT CATEGORIES

Networking

UNIX/System_Administration

Win32

cpanm App::Smbxfer

perl -MCPAN -e shell
install App::Smbxfer