view release on metacpan or  search on metacpan

lib/Arc/Connection.pod  view on Meta::CPAN

=head1 NAME

Arc::Connection - Abstract base class for connection handling for ARCv2

=head1 DESCRIPTION

ARC allows non-privileged users to run privileged commands on the server.
The server decides if the user is allowed to run this command through ACL.

This file is a part of the Perl ARCv2 module suite. ARCv2 is a 
rewrite of ARC by R.Toebbicke, CERN, Switzerland in Perl. 

=head1 ABSTRACT

From ARC by R. Toebbicke, modified by me:
User requests are shipped from a client machine to a server using a
SASL-authenticated socket connection. The purpose is to convey
requests such as privileged commands (e.g. AFS, Crontab) to be executed on the
server under appropriate privileges. Given that all privileges are
confined to the server and the server can be programmed as to filter and
check the command to be executed, the client machine can be less trusted
than the server.

Because ARC-v1-Commands are written in perl anyway, implementing the client/server
in perl makes sense. Platform-independence and "easy-to-read" source code are welcome
too. This package provides two perl command line scripts (arcx, arcxd). They can
be used for working with the ARC server from the command line, resp. to start the
server.

=head1 SYNOPSIS

This module is part of the module suite ARCv2.

This is the connection module from ARCv2. If we would use C++, we would say
this is an abstract class of an ARCv2 Connection. This class provides common
methods to its derived classes. Such as for authentication and basic ARCv2 
protocols.


=head1 Class VARIABLES

=head3 PUBLIC MEMBERS

=over 2

=item protocol 

B<Description>: Which protocol is used (0 = ARC/2.0, 1 = ARC/2.1)

B<Default value>: undef

=item service 

B<Description>: name of the server (for SASL)

B<Default value>: undef

=item timeout 

B<Description>: timeout for all connections (ARCv2 and command) in seconds

B<Default value>: undef

=back 

=over 2

=item logdestination I<inherited from Arc>

B<Description>: Where should all the log output go to ('stderr','syslog')

B<Default value>: 'syslog'

=item logfileprefix I<inherited from Arc>

B<Description>: Prepended to every log entry

B<Default value>: ""

=item loglevel I<inherited from Arc>

B<Description>: loglevel is combination of bits (1=AUTH,2=USER,4=ERR,8=CMDDEBUG,16=VERBSIDE,32=DEBUG) see _Log method

B<Default value>: 7

=back 

lib/Arc/Connection.pod  view on Meta::CPAN

B<Example:>

while (my $cmd = $this->_RecvCommand() && $this->_ProcessLine($cmd)) {}


=item _ReadWriteBinary ( *locfdin, *locfdout ) 

B<Description>: function for reading and writing on the command connection.
This function is always used by the C<Arc::Connection::Server> to handle 
command data. When calling the C<ProcessCommand> from C<Arc::Connection::Client> 
this function is also used.
Data is read from the local socket resp. pipe and is written encrypted 
to the network socket. The other side reads the data from network socket, 
decrypts it and writes it to its local socket. This function behaves differently on 
client and server sides, when the local or network socket is closed.


B<Returns:> always true


B<Example:>

$this->ReadWriteBinary(*STDIN,*STDOUT);


=item _RecvCommand (  ) 

B<Description>: receives an ARCv2 Command. (protocol)
This function gets a line from C<_RecvLine> and extracts the ARCv2 command and
the optional command parameter C<_cmdparameter>.


B<Returns:> ARCv2 command and true if everything works fine, otherwise false


B<Example:>

while (my $cmd = $this->_RecvCommand()) { ... }


=item _RecvLine (  ) 

B<Description>: receive a line (command). (protocol)
This function receives data from the ARCv2 connection and
fills the internal C<__linequeue> and C<__partial>. It returns 
a line from the internal buffer if there is any. It also handles
timeouts and "connection closed by foreign host"'s.


B<Returns:> true (and the line) if everything worked fine, otherwise false (undef)


B<Example:>

if (my $line = $this->_RecvLine()) { ... }


=item _Sasl ( $saslstr ) 

B<Description>: send the ARCv2 SASL command. (protocol)
This function encodes the output from sasl_*_start and sasl_*_step with Base-64 and sends
it to the other side


B<Returns:> true if successful, otherwise false


B<Example:>

$this->_Sasl($sasl->client_start());


=item _SendCommand ( $cmd, $parameter ) 

B<Description>: send a command. (protocol)  
Send a command to the ARCv2 socket.


B<Returns:> true if successful, otherwise false


B<Example:>

$this->_SendCommand("CMDPASV",$consock->sockhost.':'.$consock->sockport);


=item _SendLine ( ... (line) ) 

B<Description>: send a line. (protocol)
This function sends a command line to the ARCv2 socket.


B<Returns:> true if writing has succeeded, otherwise false.


B<Example:>

$this->_SendLine($cmd,"test"); 


=back 

=over 2

=item _Debug ( ... (message) ) I<inherited from Arc>

B<Description>: Debug function.
Logs messages with "DEBUG" 


B<Returns:> always false


B<Example:>

$this->_Debug("hello","world"); # message will be "hello world"


=item _SetError ( ... (message)  ) I<inherited from Arc>

B<Description>: SetError function.
This function prepends the error message (@_) to an existing error message (if any) and
logs the message with LOG_ERR facility.
Use this function for setting an error from class level. Users should use IsError 
to get the message if a function failed.


B<Returns:> always false