App::Smbxfer - A "modulino" (module/program hybrid) for file transfer between Samba shares and the local filesystem.
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
This documentation refers to App::Smbxfer version 0.01.
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.
Prints command-line usage information.
Prints command-line options.
"main() method" for running module as a command-line program.
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.)
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( 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.
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):
Server
Share
Parent path
Path
Share spec
Path spec
Parent path spec
Basename
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( $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.
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_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_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.
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
As in the 'cp' command, two arguments are required: the source and the destination, in that order.
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.
Invalid options!
Command-line options were not recognized. --usage and --options provide succinct information to resolve.
--usage
--options
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.
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>
Filesys::SmbClient
IO::Prompt
No known incompatibilities.
No known bugs. Please report problems to Karl Erisman (kerisman@cpan.org). Patches are welcome.
Karl Erisman (kerisman@cpan.org)
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.
Networking
UNIX/System_Administration
Win32
7 POD Errors
The following errors were encountered while parsing the POD:
Expected text after =item, not a number
To install App::Smbxfer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Smbxfer
CPAN shell
perl -MCPAN -e shell install App::Smbxfer
For more information on module installation, please visit the detailed CPAN module installation guide.