This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Net/SNMP/Interfaces, Next: Net/SNMP/Interfaces/Details, Prev: Net/SNMP, Up: Module List provide simple methods to gain interface data via ************************************************* NAME ==== Net::SNMP::Interfaces - provide simple methods to gain interface data via SNMP SYNOPSIS ======== use Net::SNMP::Interfaces; my $interfaces = Net::SNMP::Interfaces->new(Hostname => 'localhost', Community => 'public' ); my @ifnames = $interfaces->all_interfaces(); DESCRIPTION =========== Net::SNMP::Interfaces aims to provide simple object methods to obtain information about a host's network interfaces ( be it a server a router or whatever ). The motivation was largely to allow a programmer to use SNMP to obtain this information without needing to know a great deal about the gory details. The module uses Net::SNMP under the hood to do the dirty work although the user shouldn't have to worry about that ( the Net::SNMP object is available though for those who might feel the need ). The actual details for a particular interface are obtained from the methods of Net::SNMP::Interfaces::Details - objects of which type can be obtained for the methods all_interfaces() and interface(). Of course the simpler interface has its limitations and there may well be things that you would like to do which you cant do with this module - in which case I would recommend that you get a good book on SNMP and use Net::SNMP :) The module uses blocking SNMP requests at the current time so if some of the methods are taking too long you may want to time them out yourself using alarm(). METHODS ------- new( HASH %args ) The constructor of the class. It takes three arguments that are passed to Net::SNMP : Hostname The name of the host which you want to connect to. Defaults to 'localhost'. Community The SNMP community string which you want to use for this session. The default is 'public'. Port The UDP port that the SNMP service is listening on. The default is 161. There is a also a fourth optional argument 'RaiseError' which determines the behaviour of the module in the event there is an error while creating the SNMP. Normally new() will return undef if there was an error but if RaiseError is set to a true value it will die() printing the error string to STDERR. Because the interfaces are discovered in the constructor, if the module is to be used in a long running program to monitor a host where interfaces might be added or removed it is recommended that the object returned by new() is periodically destroyed and a new one constructed. if_names() Returns a list of the interface names. if_indices() Returns a list of the indices of the interfaces - this probably shouldn't be necessary but is here for completeness anyway. If you dont know what the index is for you are safe to ignore this. error() Returns the text of the last Net::SNMP error. This method only makes sense if the previous method call indicated an error by a false return. session() Returns the Net::SNMP session object for this instance. Or a false value if there is no open session. This might be used to call methods on the Net::SNMP object if some facility is needed that isnt supplied by this module. all_interfaces() Returns a list of Net::SNMP::Interface::Details objects corresponding to the interfaces discovered on this host. In scalar context it will return a reference to an array. interface( SCALAR $name ) Returns a Net::SNMP::Interfaces::Details object for the named interface. Returns undef if the supplied name is not a known interface. $in_octs = $self->ifInOctets('eth0'); Please see the documentation for Net::SNMP::Interfaces::Details for more on these methods. AUTHOR ====== Jonathan Stowe COPYRIGHT ========= Copyright (c) Jonathan Stowe 2000. All rights reserved. This is free software it can be ditributed and/or modified under the same terms as Perl itself. SEE ALSO ======== perl(1), Net::SNMP, Net::SNMP::Interfaces::Details.  File: pm.info, Node: Net/SNMP/Interfaces/Details, Next: Net/SNPP, Prev: Net/SNMP/Interfaces, Up: Module List Object methods to obtain interface data. **************************************** NAME ==== Net::SNMP::Interfaces::Details - Object methods to obtain interface data. SYNOPSIS ======== $in_octets = $interface->ifInOctets(); DESCRIPTION =========== This class represents an individual interface as discovered by Net::SNMP::Interfaces. Although it is possible to call the contructor directly it is primarily intended that these objects should be returned by methods of Net::SNMP::Interfaces. new HASH $args The constructor for the class. User code should probably never need to call the constructor directly as Net::SNMP::Interface::Details objects are returned by the Net::SNMP::Interfaces methods all_interfaces() and interface(). There are three mandatory arguments: Session A valid Net::SNMP object which will be used to make the requests for the interface information. This Net::SNMP object should currently only be of the blocking variety as no provision has been made for non-blocking requests at present. Index The SNMP ifTable index for this interface. Name The name of this interface (e.g. 'eth0' ). The Name and Index arguments should have previously been obtained by SNMP requests to the same host as the Session object has been created for. name Returns the name of this interace. index Returns the index of this interface. session Returns the Net::SNMP session object that is being used to make requests for this interface. This probably is not needed but is here for completeness' sake. IANAifType Converts from an IANAifType integer value as will be returned by ifType to its text equivalent. The remainder of the methods are named after the literal names for the SNMP entries for network interfaces. The following descriptions are taken from the IF-MIB with some additional comment from the author where necessary. ifIndex A unique value, greater than zero, for each interface. It is recommended that values are assigned contiguously starting from 1. The value for each interface sub-layer must remain constant at least from one re-initialization of the entity's network management system to the next re-initialization. ifDescr A textual string containing information about the interface. This string should include the name of the manufacturer, the product name and the version of the interface hardware/software. (In practice this will be name of the interface e.g. 'eth0') ifType The type of interface. Additional values for ifType are assigned by the Internet Assigned Numbers Authority (IANA), through updating the syntax of the IANAifType textual convention. ifMtu The size of the largest packet which can be sent/received on the interface, specified in octets. For interfaces that are used for transmitting network datagrams, this is the size of the largest network datagram that can be sent on the interface. ifSpeed An estimate of the interface's current bandwidth in bits per second. For interfaces which do not vary in bandwidth or for those where no accurate estimation can be made, this object should contain the nominal bandwidth. If the bandwidth of the interface is greater than the maximum value reportable by this object then this object should report its maximum value (4,294,967,295) and ifHighSpeed must be used to report the interace's speed. For a sub-layer which has no concept of bandwidth, this object should be zero. ifPhysAddress The interface's address at its protocol sub-layer. For example, for an 802.x interface, this object normally contains a MAC address. The interface's media-specific MIB must define the bit and byte ordering and the format of the value of this object. For interfaces which do not have such an address (e.g., a serial line), this object should contain an octet string of zero length. ifAdminStatus The desired state of the interface. The testing(3) state indicates that no operational packets can be passed. When a managed system initializes, all interfaces start with ifAdminStatus in the down(2) state. As a result of either explicit management action or per configuration information retained by the managed system, ifAdminStatus is then changed to either the up(1) or testing(3) states (or remains in the down(2) state). ifOperStatus The current operational state of the interface. The testing(3) state indicates that no operational packets can be passed. If ifAdminStatus is down(2) then ifOperStatus should be down(2). If ifAdminStatus is changed to up(1) then ifOperStatus should change to up(1) if the interface is ready to transmit and receive network traffic; it should change to dormant(5) if the interface is waiting for external actions (such as a serial line waiting for an incoming connection); it should remain in the down(2) state if and only if there is a fault that prevents it from going to the up(1) state; it should remain in the notPresent(6) state if the interface has missing (typically, hardware) components. ifLastChange The value of sysUpTime at the time the interface entered its current operational state. If the current state was entered prior to the last re-initialization of the local network management subsystem, then this object contains a zero value. ifInOctets The total number of octets received on the interface, including framing characters. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifInUcastPkts The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were not addressed to a multicast or broadcast address at this sub-layer. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifInNUcastPkts The number of packets, delivered by this sub-layer to a higher (sub-)layer, which were addressed to a multicast or broadcast address at this sub-layer. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. This object is deprecated in favour of ifInMulticastPkts and ifInBroadcastPkts. ifInDiscards The number of inbound packets which were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol. One possible reason for discarding such a packet could be to free up buffer space. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifInErrors For packet-oriented interfaces, the number of inbound packets that contained errors preventing them from being deliverable to a higher-layer protocol. For character-oriented or fixed-length interfaces, the number of inbound transmission units that contained errors preventing them from being deliverable to a higher-layer protocol. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifInUnknownProtos For packet-oriented interfaces, the number of packets received via the interface which were discarded because of an unknown or unsupported protocol. For character-oriented or fixed-length interfaces that support protocol multiplexing the number of transmission units received via the interface which were discarded because of an unknown or unsupported protocol. For any interface that does not support protocol multiplexing, this counter will always be 0. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifOutOctets The total number of octets transmitted out of the interface, including framing characters. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifOutUcastPkts The total number of packets that higher-level protocols requested be transmitted, and which were not addressed to a multicast or broadcast address at this sub-layer, including those that were discarded or not sent. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifOutNUcastPkts The total number of packets that higher-level protocols requested be transmitted, and which were addressed to a multicast or broadcast address at this sub-layer, including those that were discarded or not sent. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. This object is deprecated in favour of ifOutMulticastPkts and ifOutBroadcastPkts. ifOutDiscards The number of outbound packets which were chosen to be discarded even though no errors had been detected to prevent their being transmitted. One possible reason for discarding such a packet could be to free up buffer space. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifOutErrors For packet-oriented interfaces, the number of outbound packets that could not be transmitted because of errors. For character-oriented or fixed-length interfaces, the number of outbound transmission units that could not be transmitted because of errors. Discontinuities in the value of this counter can occur at re-initialization of the management system, and at other times as indicated by the value of ifCounterDiscontinuityTime. ifOutQLen The length of the output packet queue (in packets). ifSpecific A reference to MIB definitions specific to the particular media being used to realize the interface. It is recommended that this value point to an instance of a MIB object in the media-specific MIB, i.e., that this object have the semantics associated with the InstancePointer textual convention defined in RFC 1903. In fact, it is recommended that the media- specific MIB specify what value ifSpecific should/can take for values of ifType. If no MIB definitions specific to the particular media are available, the value should be set to the OBJECT IDENTIFIER { 0 0 }. AUTHOR ====== Jonathan Stowe COPYRIGHT ========= Copyright (c) Jonathan Stowe 2000. All rights reserved. This is free software it can be distributed and/or modified under the same terms as Perl itself. SEE ALSO ======== perl(1), Net::SNMP, Net::SNMP::Interfaces.  File: pm.info, Node: Net/SNPP, Next: Net/SOCKS, Prev: Net/SNMP/Interfaces/Details, Up: Module List Simple Network Pager Protocol Client ************************************ NAME ==== Net::SNPP - Simple Network Pager Protocol Client SYNOPSIS ======== use Net::SNPP; # Constructors $snpp = Net::SNPP->new('snpphost'); $snpp = Net::SNPP->new('snpphost', Timeout => 60); NOTE ==== This module is not complete, yet ! DESCRIPTION =========== This module implements a client interface to the SNPP protocol, enabling a perl5 application to talk to SNPP servers. This documentation assumes that you are familiar with the SNPP protocol described in RFC1861. A new Net::SNPP object must be created with the new method. Once this has been done, all SNPP commands are accessed through this object. EXAMPLES ======== This example will send a pager message in one hour saying "Your lunch is ready" #!/usr/local/bin/perl -w use Net::SNPP; $snpp = Net::SNPP->new('snpphost'); $snpp->send( Pager => $some_pager_number, Message => "Your lunch is ready", Alert => 1, Hold => time + 3600, # lunch ready in 1 hour :-) ) || die $snpp->message; $snpp->quit; CONSTRUCTOR =========== new ( [ HOST, ] [ OPTIONS ] ) This is the constructor for a new Net::SNPP object. `HOST' is the name of the remote host to which a SNPP connection is required. If `HOST' is not given, then the `SNPP_Host' specified in `Net::Config' will be used. OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are: Timeout - Maximum time, in seconds, to wait for a response from the SNPP server (default: 120) Debug - Enable debugging information Example: $snpp = Net::SNPP->new('snpphost', Debug => 1, ); METHODS ======= Unless otherwise stated all methods return either a *true* or false value, with *true* meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list. reset () help () Request help text from the server. Returns the text or undef upon failure quit () Send the QUIT command to the remote SNPP server and close the socket connection. EXPORTS ======= `Net::SNPP' exports all that `Net::CMD' exports, plus three more subroutines that can bu used to compare against the result of status. These are :- `CMD_2WAYERROR', `CMD_2WAYOK', and `CMD_2WAYQUEUED'. SEE ALSO ======== *Note Net/Cmd: Net/Cmd, RFC1861 AUTHOR ====== Graham Barr COPYRIGHT ========= Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/SOCKS, Next: Net/SSH, Prev: Net/SNPP, Up: Module List a SOCKS client class ******************** NAME ==== Net::SOCKS - a SOCKS client class SYNOPSIS ======== Establishing a connection: my $sock = new Net::SOCKS(socks_addr => '192.168.1.3', socks_port => 1080, user_id => 'the_user', user_password => 'the_password', force_nonanonymous => 1, protocol_version => 5); # connect to finger port and request finger information for some_user my $f= $sock->connect(peer_addr => '192.168.1.3', peer_port => 79); print $f "some_user\n"; # example writing to socket while (<$f>) { print } # example reading from socket $sock->close(); Accepting an incoming connection: my $sock = new Net::SOCKS(socks_addr => '192.168.1.3', socks_port => 1080, user_id => 'the_user', user_password => 'the_password', force_nonanonymous => 1, protocol_version => 5); my ($ip, $ip_dot_dec, $port) = $sock->bind(peer_addr => "128.10.10.11", peer_port => 9999); $f= $sock->accept(); print $f "Hi! Type something.\n"; # example writing to socket while (<$f>) { print } # example reading from socket $sock->close(); DESCRIPTION =========== my $sock = new Net::SOCKS(socks_addr => '192.168.1.3', socks_port => 1080, user_id => 'the_user', user_password => 'the_password', force_nonanonymous => 1, protocol_version => 5); To connect to a SOCKS server, specify the SOCKS server's hostname, port number, SOCKS protocol version, username, and password. Username and password are optional if you plan to use a SOCKS server that doesn't require any authentication. If you would like to force the connection to be nonanoymous, set the force_nonanonymous parameter. my $f= $sock->connect(peer_addr => '192.168.1.3', peer_port => 79); To connect to another machine using SOCKS, use the connect method. Specify the host and port number as parameters. my ($ip, $ip_dot_dec, $port) = $sock->bind(peer_addr => "192.168.1.3", peer_port => 9999); If you wanted to accept a connection with SOCKS, specify the host and port of the machine you expect a connection from. Upon success, bind() returns the ip address and port number that the SOCKS server is listening at on your behalf. $f= $sock->accept(); If a call to bind() returns a success status code SOCKS_OKAY, a call to the accept() method will return when the peer host connects to the host/port that was returned by the bind() method. Upon success, accept() returns SOCKS_OKAY. $sock->close(); Closes the connection. SEE ALSO ======== RFC 1928, RFC 1929. AUTHOR ====== Clinton Wong, clintdw@netcom.com COPYRIGHT ========= Copyright (c) 1997-1998 Clinton Wong. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/SSH, Next: Net/SSH/Perl, Prev: Net/SOCKS, Up: Module List Perl extension for secure shell ******************************* NAME ==== Net::SSH - Perl extension for secure shell SYNOPSIS ======== use Net::SSH qw(ssh issh sshopen2 sshopen3); ssh('user@hostname', $command); issh('user@hostname', $command); sshopen2('user@hostname', $reader, $writer, $command); sshopen3('user@hostname', $reader, $writer, $error, $command); DESCRIPTION =========== Simple wrappers around ssh commands. SUBROUTINES =========== ssh [USER@]HOST, COMMAND [, ARGS ... ] Calls ssh in batch mode. issh [USER@]HOST, COMMAND [, ARGS ... ] Prints the ssh command to be executed, waits for the user to confirm, and (optionally) executes the command. sshopen2 [USER@]HOST, READER, WRITER, COMMAND [, ARGS ... ] Connects the supplied filehandles to the ssh process (in batch mode). sshopen3 HOST, WRITER, READER, ERROR, COMMAND [, ARGS ... ] Connects the supplied filehandles to the ssh process (in batch mode). EXAMPLE ======= use Net::SSH qw(sshopen2); use strict; my $user = "username"; my $host = "hostname"; my $cmd = "command"; sshopen2("$user\@$host", *READER, *WRITER, "$cmd") || die "ssh: $!"; while () { chomp(); print "$_\n"; } close(READER); close(WRITER); AUTHOR ====== Ivan Kohler CREDITS ======= John Harrison contributed an example for the documentation. BUGS ==== Not OO. Look at IPC::Session (also fsh) SEE ALSO ======== ssh(1), *Note IPC/Open2: IPC/Open2,, *Note IPC/Open3: IPC/Open3,  File: pm.info, Node: Net/SSH/Perl, Next: Net/SSH/Perl/Auth, Prev: Net/SSH, Up: Module List Perl client Interface to SSH **************************** NAME ==== Net::SSH::Perl - Perl client Interface to SSH SYNOPSIS ======== use Net::SSH::Perl; my $ssh = Net::SSH::Perl->new($host); $ssh->login($user, $pass); my($stdout, $stderr, $exit) = $ssh->cmd($cmd); DESCRIPTION =========== *Net::SSH::Perl* is an all-Perl module implementing an ssh client. It enables you to simply and securely execute commands on remote machines, and receive the STDOUT, STDERR, and exit status of that remote command. It contains built-in support for various methods of authenticating with the server (password authentication, RSA challenge-response authentication, etc.). It completely implements the I/O buffering, packet transport, and user authentication layers of the SSH protocol, and makes use of external Perl libraries (in the Crypt:: family of modules) to handle encryption of all data sent across the insecure network. It can also read your existing SSH configuration files (`/etc/ssh_config', etc.), RSA identity files, known hosts files, etc. One advantage to using *Net::SSH::Perl* over wrapper-style implementations of ssh clients is that it saves on process overhead: you no longer need to fork and execute a separate process in order to connect to an sshd. Depending on the amount of time and memory needed to fork a process, this win can be quite substantial; particularly if you're running in a persistent Perl environment (mod_perl, for example), where forking a new process is a drain on process and memory resources. It also simplifies the process of using password-based authentications; when writing a wrapper around ssh you probably need to use Expect to control the ssh client and give it your password. *Net::SSH::Perl* has built-in support for the authentication protocols, so there's no longer any hassle of communicating with any external processes. BASIC USAGE =========== Usage of *Net::SSH::Perl* is very simple. Net::SSH::Perl->new($host, %params) ----------------------------------- To set up a new connection, call the new method, which connects to $host and returns a *Net::SSH::Perl* object. new accepts the following named parameters in *%params*: * cipher Specifies the name of the encryption cipher that you wish to use for this connection. This must be one of the supported ciphers (currently, IDEA, *DES*, *DES3*, and *Blowfish*); specifying an unsupported cipher is a fatal error. The default cipher is IDEA. * port The port of the *sshd* daemon to which you wish to connect; if not specified, this is assumed to be the default ssh port. * debug Set to a true value if you want debugging messages printed out while the connection is being opened. These can be helpful in trying to determine connection problems, etc. The messages are similar (and in some cases exact) to those written out by the ssh client when you use the -v option. Defaults to false. * interactive Set to a true value if you're using *Net::SSH* interactively. This is used in determining whether or not to display password prompts, for example. It's basically the inverse of the *BatchMode* parameter in ssh configuration. Defaults to false. * privileged Set to a true value if you want to bind to a privileged port locally. You'll need this if you plan to use Rhosts or Rhosts-RSA authentication, because the remote server requires the client to connect on a privileged port. Of course, to bind to a privileged port you'll need to be root. If you don't provide this parameter, and *Net::SSH::Perl* detects that you're running as root, this will automatically be set to true. Otherwise it defaults to false. * identity_files A list of RSA identity files to be used in RSA authentication. The value of this argument should be a reference to an array of strings, each string identifying the location of an identity file. If you don't provide this, RSA authentication defaults to using "$ENV{HOME}/.ssh/identity". * compression If set to a true value, compression is turned on for the session (assuming that the server supports it). Compression is off by default. Note that compression requires that you have the *Compress::Zlib* module installed on your system. If the module can't be loaded successfully, compression is disabled; you'll receive a warning stating as much if you having debugging on (debug set to 1), and you try to turn on compression. * compression_level Specifies the compression level to use if compression is enabled (note that you must provide both the compression and *compression_level* arguments to set the level; providing only this argument will not turn on encryption). The default value is 6. * use_pty Set this to 1 if you want to request a pseudo tty on the remote machine. This is really only useful if you're setting up a shell connection (see the *shell* method, below); and in that case, unless you've explicitly declined a pty (by setting *use_pty* to 0), this will be set automatically to 1. In other words, you probably won't need to use this, often. The default is 1 if you're starting up a shell, and 0 otherwise. * options Used to specify additional options to the configuration settings; useful for specifying options for which there is no separate constructor argument. This is analogous to the -o command line flag to the ssh program. If used, the value should be a reference to a list of option directives in the format used in the config file. For example: my $ssh = Net::SSH::Perl->new("host", options => [ "BatchMode yes", "RhostsAuthentication no" ]); $ssh->login([ $user [, $password ] ]) ------------------------------------- Sets the username and password to be used when authenticating with the *sshd* daemon. The username *$user* is required for all authentication protocols (to identify yourself to the remote server), but if you don't supply it the username of the user executing the program is used. The password $password is needed only for password authentication (it's not used for RSA passphrase authentication, though perhaps it should be). And if you're running in an interactive session and you've not provided a password, you'll be prompted for one. ($out, $err, $exit) = $ssh->cmd($cmd, [ $stdin ]) ------------------------------------------------- Runs the command *$cmd* on the remote server and returns the stdout, stderr, and exit status of that command. If *$stdin* is provided, it's supplied to the remote command *$cmd* on standard input. NOTE: the ssh protocol does not easily support (so far as I know) running multiple commands per connection, unless those commands are chained together so that the remote shell can evaluate them. Because of this, a new socket connection is created each time you call cmd, and disposed of afterwards. In other words, this code: my $ssh = Net::SSH::Perl->new("host1"); $ssh->login("user1", "pass1"); $ssh->cmd("foo"); $ssh->cmd("bar"); will actually connect to the *sshd* on the first invocation of cmd, then disconnect; then connect again on the second invocation of cmd, then disconnect again. This is less than ideal, obviously. Future version of *Net::SSH::Perl* may find ways around that. $ssh->shell ----------- Opens up an interactive shell on the remote machine and connects it to your STDIN. This is most effective when used with a pseudo tty; otherwise you won't get a command line prompt, and it won't look much like a shell. For this reason-unless you've specifically declined one-a pty will be requested from the remote machine, even if you haven't set the *use_pty* argument to new (described above). This is really only useful in an interactive program. In addition, you'll probably want to set your terminal to raw input before calling this method. This lets *Net::SSH::Perl* process each character and send it off to the remote machine, as you type it. To do so, use Term::ReadKey in your program: use Term::ReadKey; ReadMode('raw'); $ssh->shell; ReadMode('restore'); In fact, you may want to place the restore line in an END block, in case your program exits prior to reaching that line. If you need an example, take a look at `eg/pssh', which uses almost this exact code to implement an ssh shell. $ssh->register_handler($packet_type, $subref) --------------------------------------------- Registers an anonymous subroutine handler *$subref* to handle packets of type *$packet_type* during the client loop. The client loop is entered after the client has sent a command to the remote server, and after any STDIN data has been sent; it consists of reading packets from the server (STDOUT packets, STDERR packets, etc.) until the server sends the exit status of the command executed remotely. At this point the client exits the client loop and disconnects from the server. When you call the cmd method, the client loop by default simply sticks STDOUT packets into a scalar variable and returns that value to the caller. It does the same for STDERR packets, and for the process exit status. (See the docs for cmd). You can, however, override that default behavior, and instead process the packets yourself as they come in. You do this by calling the *register_handler* method and giving it a packet type *$packet_type* and a subroutine reference *$subref*. Your subroutine will receive as arguments the *Net::SSH::Perl* object (with an open connection to the sshd), and a *Net::SSH::Perl::Packet* object, which represents the packet read from the server. *$packet_type* should be an integer constant; you can import the list of constants into your namespace by explicitly loading the *Net::SSH::Perl::Constants* module: use Net::SSH::Perl::Constants qw( :msg ); This will load all of the MSG constants into your namespace so that you can use them when registering the handler. To do that, use this method. For example: $ssh->register_handler(SSH_SMSG_STDOUT_DATA, sub { my($ssh, $packet) = @_; print "I received this: ", $packet->get_str; }); To learn about the methods that you can call on the packet object, take a look at the *Net::SSH::Perl::Packet* docs, as well as the *Net::SSH::Perl::Buffer* docs (the *get_** and *put_** methods). Obviously, writing these handlers requires some knowledge of the contents of each packet. For that, read through the SSH RFC, which explains each packet type in detail. There's a *get_** method for each datatype that you may need to read from a packet. ADVANCED METHODS ================ Your basic SSH needs will hopefully be met by the methods listed above. If they're not, however, you may want to use some of the additional methods listed here. Some of these are aimed at end-users, while others are probably more useful for actually writing an authentication module, or a cipher, etc. $ssh->config ------------ Returns the *Net::SSH::Perl::Config* object managing the configuration data for this SSH object. This is constructed from data passed in to the constructor new (see above), merged with data read from the user and system configuration files. See the *Net::SSH::Perl::Config* docs for details on methods you can call on this object (you'll probably be more interested in the get and set methods). $ssh->sock ---------- Returns the socket connection to sshd. If your client is not connected, dies. $ssh->debug($msg) ----------------- If debugging is turned on for this session (see the debug parameter to the new method, above), writes $msg to `STDERR'. Otherwise nothing is done. $ssh->incoming_data ------------------- Incoming data buffer, an object of type *Net::SSH::Perl::Buffer*. Returns the buffer object. The idea behind this is that we our socket is non-blocking, so we buffer input and periodically check back to see if we've read a full packet. If we have a full packet, we rip it out of the incoming data buffer and process it, returning it to the caller who presumably asked for it. This data "belongs" to the underlying packet layer in *Net::SSH::Perl::Packet*. Unless you really know what you're doing you probably don't want to disturb that data. $ssh->set_cipher($cipher_name) ------------------------------ Sets the cipher for the SSH session *$ssh* to *$cipher_name* (which must be a valid cipher name), and turns on encryption for that session. $ssh->send_cipher ----------------- Returns the "send" cipher object. This is the object that encrypts outgoing data. If it's not defined, encryption is not turned on for the session. $ssh->receive_cipher -------------------- Returns the "receive" cipher object. This is the object that decrypts incoming data. If it's not defined, encryption is not turned on for the session. NOTE: the send and receive ciphers and two *different* objects, each with its own internal state (initialization vector, in particular). Thus they cannot be interchanged. $ssh->compression([ $level ]) ----------------------------- Without arguments, returns the current compression level for the session. If given an argument *$level*, sets the compression level and turns on compression for the session. Note that this should not be used to turn compression off. In fact, I don't think there's a way to turn compression off. But in other words, don't try giving this method a value of 0 and expect that to turn off compression. It won't. If the return value of this method is undefined or 0, compression is turned off. $ssh->send_compression ---------------------- Returns the "send" compression object/stream. This is a *Compress::Zlib* deflation (compression) stream; we keep it around because it contains state that needs to be used throughout the session. $ssh->receive_compression ------------------------- Returns the "receive" compression object/stream. This is a *Compress::Zlib* inflation (uncompression) stream; we keep it around because it contains state that needs to be used throughout the session. $ssh->session_key ----------------- Returns the session key, which is simply 32 bytes of random data and is used as the encryption/decryption key. $ssh->session_id ---------------- Returns the session ID, which is generated from the server's host and server keys, and from the check bytes that it sends along with the keys. The server may require the session ID to be passed along in other packets, as well (for example, when responding to RSA challenges). $packet = $ssh->packet_start($packet_type) ------------------------------------------ Starts building a new packet of type *$packet_type*. This is just a handy method for lazy people. Internally it calls *Net::SSH::Perl::Packet::new*, so take a look at those docs for more details. SUPPORT ======= For samples/tutorials, take a look at the scripts in `eg/' in the distribution directory. If you have any questions, code samples, bug reports, or feedback, please email them to: ben@rhumba.pair.com AUTHOR & COPYRIGHT ================== Benjamin Trott, ben@rhumba.pair.com Except where otherwise noted, Net::SSH::Perl is Copyright 2001 Benjamin Trott. All rights reserved. Net::SSH::Perl is free software; you may redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/SSH/Perl/Auth, Next: Net/SSH/Perl/Auth/Password, Prev: Net/SSH/Perl, Up: Module List Base authentication class, plus utility methods *********************************************** NAME ==== Net::SSH::Perl::Auth - Base authentication class, plus utility methods SYNOPSIS ======== use Net::SSH::Perl::Cipher; # Get list of supported authentication IDs. my $supported = Net::SSH::Perl::Auth::supported(); # Translate an auth name into an ID. my $id = Net::SSH::Perl::Auth::id($name); # Translate an auth ID into a name. my $name = Net::SSH::Perl::Auth::name($id); # Get the order in which auth methods are tested. my $order = Net::SSH::Perl::Auth::order(); DESCRIPTION =========== *Net::SSH::Perl::Auth* provides a base class for each of the authentication method classes. In addition, it defines a set of utility methods that can be called either as functions or object methods. UTILITY METHODS =============== supported( [ $auth_id [, $server_supports ] ]) ---------------------------------------------- Without arguments, returns a reference to an array of auth methods supported by *Net::SSH::Perl*. These are methods that have working Net::SSH::Perl::Auth:: implementations, essentially. With one argument *$auth_id*, returns a true value if that auth method is supported by *Net::SSH::Perl*, and false otherwise. With two arguments, *$auth_id* and *$server_supports*, returns true if the auth represented by *$auth_id* is supported both by *Net::SSH::Perl* and by the sshd server. The list of methods supported by the server should be in *$server_supports*, a bit mask sent from the server during the session identification phase. Can be called either as a non-exported function, i.e. my $i_support = Net::SSH::Perl::Auth::supported(); or as an object method of a *Net::SSH::Perl::Auth* object, or an object of a subclass (in which case the first argument should be *$server_supports*, not the *$auth_id*): if ($auth->supported($server_supports)) { print "Server supports auth method $auth"; } id( [ $auth_name ] ) -------------------- Translates an auth method name into an ID (suitable for sending to the sshd server, for example). If given *$auth_name* translates that name into the corresponding ID. If called as an object method, translates the object's auth class name into the ID. name( [ $auth_id ] ) -------------------- Translates an auth method ID into a name. If given *$auth_id* translates that ID into the corresponding name. If called as an object method, returns the (stripped) object's auth class name; for example, if the object were of type *Net::SSH::Perl::Auth::Rhosts*, name would return *Rhosts*. auth_order() ------------ Returns a reference to an array containing auth method IDs. These IDs describe the order in which authentication should be tested against the server. So, for example, if the array listed (2, 4, 3), then the client should test: RSA, then Rhosts-RSA, then Password authentication. AUTH USAGE ========== Net::SSH::Perl::Auth->new($auth_name, $ssh) ------------------------------------------- Instantiates a new auth object of the type *$auth_name*, and gives it the *Net::SSH::Perl* object *$ssh*, which should contain an open connetion to an sshd server. Returns the auth object, which will be blessed into the actual auth subclass. $valid = $auth->authenticate() ------------------------------ Talks to the sshd server to authenticate the user; if valid, returns true, and if invalid, returns false. AUTH DEVELOPMENT ================ Classes implementing an authentication method must implement the following two methods: * $class->new($ssh) Given a *Net::SSH::Perl* object *$ssh*, should construct a new auth object and bless it into $class, presumably. * $class->authenticate() Authenticate the current user with the remote daemon. This requires following the messaging protocol defined for your authentication method. All of the data you need-user name, password (if required), etc.-should be in the *$ssh* object. Returns 1 if the authentication is successful, 0 otherwise. AUTHOR & COPYRIGHTS =================== Please see the Net::SSH::Perl manpage for author, copyright, and license information.  File: pm.info, Node: Net/SSH/Perl/Auth/Password, Next: Net/SSH/Perl/Auth/RSA, Prev: Net/SSH/Perl/Auth, Up: Module List Password authentication plugin ****************************** NAME ==== Net::SSH::Perl::Auth::Password - Password authentication plugin SYNOPSIS ======== use Net::SSH::Perl::Auth; my $auth = Net::SSH::Perl::Auth->new('Password', $ssh); print "Valid auth" if $auth->authenticate; DESCRIPTION =========== *Net::SSH::Perl::Auth::Password* performs password authentication with a remote sshd server. When you create a new password auth object, you give it an *$ssh* object, which should contain an open connection to an ssh daemon, as well as the data that the authentication module needs to proceed. The authenticate method will enter into a dialog with the server. For password authentication, all that needs to be done is to send a password (encrypted by the standard SSH encryption layer) to the server, and wait for its response. If the *$ssh* object doesn't already have a password that you've given it, *Net::SSH::Perl::Auth::Password* will check to see if you're in an interactive session (see the docs for *Net::SSH::Perl*), and if so will issue a prompt, asking you to enter your password. If the session is not interactive (if it's in batch mode), we send a blank password to comply with the protocol, but odds are the authentication will then fail. AUTHOR & COPYRIGHTS =================== Please see the Net::SSH::Perl manpage for author, copyright, and license information.  File: pm.info, Node: Net/SSH/Perl/Auth/RSA, Next: Net/SSH/Perl/Auth/Rhosts, Prev: Net/SSH/Perl/Auth/Password, Up: Module List Perform RSA authentication ************************** NAME ==== Net::SSH::Perl::Auth::RSA - Perform RSA authentication SYNOPSIS ======== use Net::SSH::Perl::Auth; my $auth = Net::SSH::Perl::Auth->new('RSA', $ssh); print "Valid auth" if $auth->authenticate; DESCRIPTION =========== *Net::SSH::Perl::Auth::RSA* performs RSA authentication with a remote sshd server. When you create a new RSA auth object, you give it an *$ssh* object, which should contain an open connection to an ssh daemon, as well as any data that the authentication module needs to proceed. In this case, for example, the *$ssh* object might contain a list of RSA identity files (see the docs for *Net::SSH::Perl*). The authenticate method tries to load the user's public and private keys, for each of the files listed as identity files. If you haven't listed any identity files, `$ENV{HOME}/.ssh/identity' is used by default. For each identity, authenticate enters into a dialog with the sshd server. The client sends the public key to the server, then waits for a challenge. Once this challenge is received, the client must decrypt the challenge using the private key (loaded from the identity file). When loading the private key, you may need to enter a passphrase to decrypt the private key itself; first authenticate tries to decrypt the key using an empty passphrase (which requires no user intervention). If this fails, the client checks to see if it's running in an interactive session. If so, it queries the user for a passphrase, which is then used to decrypt the private key. If the session is non-interactive and the private key cannot be loaded, the client simply sends a dummy response to the RSA challenge, to comply with the SSH protocol. Otherwise, if the private key has been loaded, and the challenge decrypted, the client sends its response to the server, then waits for success or failure. AUTHOR & COPYRIGHTS =================== Please see the Net::SSH::Perl manpage for author, copyright, and license information.  File: pm.info, Node: Net/SSH/Perl/Auth/Rhosts, Next: Net/SSH/Perl/Auth/Rhosts_RSA, Prev: Net/SSH/Perl/Auth/RSA, Up: Module List Perform Rhosts authentication ***************************** NAME ==== Net::SSH::Perl::Auth::Rhosts - Perform Rhosts authentication SYNOPSIS ======== use Net::SSH::Perl::Auth; my $auth = Net::SSH::Perl::Auth->new('Rhosts', $ssh); print "Valid auth" if $auth->authenticate; DESCRIPTION =========== *Net::SSH::Perl::Auth::Rhosts* performs Rhosts authentication with a remote sshd server. When you create a new Rhosts auth object, you give it an *$ssh* object, which should contain an open connection to an ssh daemon, as well as any data that the authentication module needs to proceed. In this case, the *$ssh* object must contain the name of the user trying to open the connection. Rhosts authentication is fairly simple from a protocol point of view. However, note that the sshd server will require your client to be running on a privileged port (below 1024); this will, in turn, likely require your client to be running as root. If your client is not running on a privileged port, the Rhosts authentication request will be denied. If you're running as root, *Net::SSH::Perl* should automatically detect that and try to start up on a privileged port. If for some reason that isn't happening, take a look at the *Net::SSH::Perl* docs. With that aside, to use Rhosts authentication the client sends a request to the server to authenticate it, including the name of the user trying to authenticate. The server uses its *shosts.equiv*, *hosts.equiv*, etc. files to determine whether the user/host should be allowed access. AUTHOR & COPYRIGHTS =================== Please see the Net::SSH::Perl manpage for author, copyright, and license information.