1NAME
2 Net::SCP::Expect - Wrapper for scp that allows passwords via Expect.
3
4SYNOPSIS
5 Example 1 - uses login method, longhand scp:
6
7 my $scpe = Net::SCP::Expect->new;
8 $scpe->login('user name', 'password');
9 $scpe->scp('file','host:/some/dir');
10
11 Example 2 - uses constructor, shorthand scp:
12
13 my $scpe = Net::SCP::Expect->new(host=>'host', user=>'user', password=>'xxxx');
14 $scpe->scp('file','/some/dir'); # 'file' copied to 'host' at '/some/dir'
15
16 Example 3 - copying from remote machine to local host
17
18 my $scpe = Net::SCP::Expect->new(user=>'user',password=>'xxxx');
19 $scpe->scp('host:/some/dir/filename','newfilename');
20
21 See the scp() method for more information on valid syntax.
22
23PREREQUISITES
24 Expect 1.14. May work with earlier versions, but was tested with 1.14
25 (and now 1.15) only.
26
27 Term::ReadPassword 0.01 is required if you want to execute the
28 interactive test script.
29
30DESCRIPTION
31 This module is simply a wrapper around the scp call. The primary
32 difference between this module and *Net::SCP* is that you may send a
33 password programmatically, instead of being forced to deal with
34 interactive sessions.
35
36USAGE
37 Net::SCP::Expect->new(*option=>val*, ...)
38 Creates a new object and optionally takes a series of options (see
39 "OPTIONS" below). All "OBJECT METHODS" apply to this constructor.
40
41OBJECT METHODS
42 auto_yes
43 Set this to 1 if you want to automatically pass a 'yes' string to any
44 yes or no questions that you may encounter before actually being asked
45 for a password, e.g. "Are you sure you want to continue connecting
46 (yes/no)?" for first time connections, etc.
47
48 error_handler(*sub ref*)
49 This sets up an error handler to catch any problems with a call to
50 'scp()'. If you do not define an error handler, then a simple 'croak()'
51 call will occur, with the last line sent to the terminal added as part
52 of the error message.
53
54 The method will immediately return with a void value after your error
55 handler has been called.
56
57 host(*host*)
58 Sets the host for the current object
59
60 login(*login, password*)
61 If the login and password are not passed as options to the constructor,
62 they must be passed with this method (or set individually - see 'user'
63 and 'password' methods). If they were already set, this method will
64 overwrite them with the new values.
65
66 password(*password*)
67 Sets the password for the current user, or the passphrase for the
68 identify file if identity_file option is specified in the constructor
69
70 user(*user*)
71 Sets the user for the current object
72
73 scp()
74 Copies the file from source to destination. If no host is specified, you
75 will be using 'scp' as an expensive form of 'cp'.
76
77 There are several valid ways to use this method
78
79 Local to Remote
80 scp(*source, user@host:destination*);
81
82 scp(*source, host:destination*); # User already defined
83
84 scp(*source, :destination*); # User and host already defined
85
86 scp(*source, destination*); # Same as previous
87
88 Remote to Local
89 scp(*user@host:source, destination*);
90
91 scp(*host:source, destination*);
92
93 scp(*:source, destination*);
94
95OPTIONS
96 auto_quote - Auto-encapsulate all option values and scp from/to
97 arguments in single-quotes to insure that special characters, such as
98 spaces in file names, do not cause inadvertant shell exceptions. Default
99 is enabled. Note: Be aware that this feature may break backward
100 compatibility with scripts that manually quoted input arguments to work
101 around unquoted argument limitations in 0.12 or earlier of this module;
102 in such cases, try disabling it or update your script to take advantage
103 of the auto_quote feature.
104
105 auto_yes - Set this to 1 if you want to automatically pass a 'yes'
106 string to any yes or no questions that you may encounter before actually
107 being asked for a password, e.g. "Are you sure you want to continue
108 connecting (yes/no)?" for first time connections, etc.
109
110 cipher - Selects the cipher to use for encrypting the data transfer.
111
112 host - Specify the host name. This is now useful for both
113 local-to-remote and remote-to-local transfers.
114
115 identity_file - Specify the identify file to use.
116
117 no_check - Set this to 1 if you want to turn off error checking. Use
118 this if you're absolutely positive you won't encounter any errors and
119 you want to speed up your scp calls - up to 2 seconds per call (based on
120 the defaults).
121
122 option - Specify options from the config file. This is the equivalent of
123 -o.
124
125 password - The password for the given login. If not specified, then
126 identity_file must be specified or an error will occur on login. If both
127 identity_file and password are specified, the password will be treated
128 as the passphrase for the identity file.
129
130 port - Use the specified port.
131
132 preserve - Preserves modification times, access times, and modes from
133 the original file.
134
135 protocol - Specify the ssh protocol to use for scp. The default is
136 undef, which simply means scp will use whatever it normally would use.
137
138 recursive - Set to 1 if you want to recursively copy entire directories.
139
140 scp_path - The path for the scp binary to use, i.e.: /usr/bin/scp,
141 defaults to use the first scp on your $PATH variable.
142
143 subsystem - Specify a subsystem to invoke on the remote system. This
144 option is only valid with ssh2 and openssh afaik.
145
146 terminator - Set the string terminator that is attached to the end of
147 the password. The default is a newline.
148
149 timeout - Sets the timeout value for your scp operation. The default is
150 10 seconds.
151
152 timeout_auto - Sets the timeout for the 'auto_yes' option. I separated
153 this from the standard timeout because generally you won't need nearly
154 as much time as you would for a standard timeout, otherwise your script
155 will drag considerably. The default is 1 second (which should be
156 plenty).
157
158 timeout_err - Sets the timeout for the additional error checking that
159 the module does. Because errors come back almost instantaneously, I
160 thought it best to make this a separate option for the same reasons as
161 the 'timeout_auto' option above. The default is 'undef'.
162
163 Setting it to any integer value means that your program will exit after
164 that many seconds *whether or not the operation has completed*. Caveat
165 programmor.
166
167 user - The login name you wish to use.
168
169 verbose - Set to 1 if you want verbose output sent to STDOUT. Note that
170 this disables some error checking (ala no_check) because the verbose
171 output could otherwise be picked up by expect itself.
172
173NOTES
174 The -q option (disable progress meter) is automatically passed to scp.
175
176 The -B option may NOT be set. If you don't plan to send passwords or use
177 identity files (with passphrases), consider using *Net::SCP* instead.
178
179 In the event a new version of *Net::SSH::Perl* is released that supports
180 scp, I recommend using that instead. Why? First, it should be a more
181 secure way to perform scp. Second, this module is not the fastest, even
182 with error checking turned off. Both reasons have to do with TTY
183 interaction.
184
185 Also, please see the Net::SFTP module from Dave Rolsky. If this suits
186 your needs, use it instead.
187
188FUTURE PLANS
189 There are a few options I haven't implemented. If you *really* want to
190 see them added, let me know and I'll see what I can do.
191
192 Add exception handling tests to the interactive test suite.
193
194KNOWN ISSUES
195 At least one user has reported warnings related to POD parsing with Perl
196 5.00503. These can be safely ignored. They do not appear in Perl 5.6 or
197 later.
198
199 Probably not thread safe. See RT bug #7567 from Adam Ruck.
200
201THANKS
202 Thanks to Roland Giersig (and Austin Schutz) for the Expect module. Very
203 handy.
204
205 Thanks also go out to all those who have submitted bug reports and/or
206 patches. See the CHANGES file for specifics.
207
208LICENSE
209 Net::SCP::Expect is licensed under the same terms as Perl itself.
210
211COPYRIGHT
212 2005-2008 Eric Rybski <rybskej@yahoo.com>, 2003-2004 Daniel J. Berger.
213
214CURRENT AUTHOR AND MAINTAINER
215 Eric Rybski <rybskej@yahoo.com>. Please send all module inquries to me.
216
217ORIGINAL AUTHOR
218 Daniel Berger
219
220 djberg96 at yahoo dot com
221
222 imperator on IRC
223
224SEE ALSO
225 Net::SCP, Net::SFTP, Net::SSH::Perl, Net::SSH2
226
227