view release on metacpan or  search on metacpan

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

=head1 NAME

Arc::Connection::Client - Client class 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

Arc::Connection::Client - Client class for ARCv2

 my $arc = new Arc::Connection::Client(
  server => "hyade11",
  port => 4242,
  timeout => 30,
  loglevel=> 7,
  logdestination => 'stderr',
  service => 'arc',
  sasl_mechanism => undef,
  sasl_cb_user => \&username,
  sasl_cb_auth => \&username,
  sasl_cb_pass => \&password,
 );

 if (my $m = $arc->IsError()) {
  die $m;
 }

 if ($arc->StartSession) {
  $arc->CommandStart("test");
  $arc->CommandWrite("hallo\n");
  if (my $t = $arc->CommandRead()) {
   print $t,"\n"; # should give 'all'
  }
  $arc->CommandEnd();
 }

 sub username
 {
  return $ENV{'USER'};
 }

 sub password
 {
  return <>;
 }


=head1 Class VARIABLES

=head3 PUBLIC MEMBERS

=over 2

=item logdestination I<reimplemented from Arc>

B<Default value>: "stderr"

=item logfileprefix I<reimplemented from Arc>

B<Default value>: "client"

=item port 

B<Description>: Port to connect to

B<Default value>: undef

=item protocol I<reimplemented from Arc::Connection>

B<Description>: Which protocol type the shall use.

B<Default value>: 1

=item sasl_cb_auth 

B<Description>: SASL Callback for authname (PLAIN and some other mechs only)

B<Default value>: $ENV{'USER'}

=item sasl_cb_pass 

B<Description>: SASL Callback for password (PLAIN and some other mechs only)

B<Default value>: ""

=item sasl_cb_user 

B<Description>: SASL Callback for username (PLAIN and some other mechs only)

B<Default value>: $ENV{'USER'}

=item sasl_mechanism 

B<Description>: use this mechanism for authentication

B<Default value>: undef

=item server 

B<Description>: Server to connect to

B<Default value>: undef

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

=item IsConnected (  ) I<inherited from Arc::Connection>

B<Description>: are we connected?


B<Returns:> true, if the ARCv2 control connection is connected, otherwise false


B<Example:>

last unless $arc->IsConnected;


=back 

=over 2

=item DESTROY (  ) I<inherited from Arc>

B<Description>: Destructor


=item IsError (  ) I<inherited from Arc>

B<Description>: User function to get the error msg.


B<Returns:> the error message if any otherwise undef


B<Example:>

unless (my $err = $arc->IsError()) { .. } else { print STDERR $err; }


=item Log ( $facility, ... (message) ) I<inherited from Arc>

B<Description>: Log function.
Logs messages to 'logdestination' if 'loglevel' is is set appropriatly.
loglevel behaviour has changed in the 1.0 release of ARCv2, the "Arc"-class can export
LOG_AUTH (authentication information), LOG_USER (connection information), LOG_ERR (errors), 
LOG_CMD (ARCv2 addition internal command information), LOG_SIDE (verbose client/server-specific
information), LOG_DEBUG (verbose debug information). It possible to combine the 
levels with or (resp. +) to allow a message to appear when not all loglevels are 
requested by the user.
Commonly used for logging errors from application level.


B<Returns:> always false


B<Example:>

return $arc->Log(LOG_ERR,"Message");


=item new ( %hash, key => val, ... ) I<inherited from Arc>

B<Description>: Constructor. 
Initializes the object and returns it blessed.
For all sub classes, please override C<_Init> to check the 
parameter which are passed to the C<new> function. This
is necessary because you are not able to call the the new method of a
parent class, when having a class name (new $class::SUPER::new, does not work.).


B<Returns:> blessed object of the class


B<Example:>

my $this = new Arc::Class ( key => value, key2 => value2 );


=back 

=over 2

=back 

=head3 PROTECTED METHODS

=over 2

=item _Authenticate (  ) 

B<Description>: initiate the authentication.
Tells the server which authtype we want to use.
Protocol command: AUTHENTICATE [<authtype>]\r\n


B<Returns:> true when succesful, otherwise false


B<Example:>

$this->_Authenticate();


=item _Cmd ( ... (cmd and parameter) ) 

B<Description>: send an ARCv2 command request
Protocol command: CMD <cmd> <cmdparameter>\r\n


B<Returns:> true when succesful, otherwise false


B<Example:>

$this->_Cmd ("whoami");


=item _Connect (  ) 

B<Description>: connects to the server


B<Returns:> true when succesful, otherwise false