view release on metacpan or  search on metacpan

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

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::Server - Class for the standalone server for ARCv2

 my $arc = new Arc::Server(
  port => [4242],
  loglevel => 7,
  logdestination => "stderr",
  daemonize => 0,
  connection_type => "Arc::Connection::Server",
  connection_vars => {
   loglevel => 7,
   logdestination => 'syslog',
   timeout => 30,
   sasl_mechanisms => ["GSSAPI","KERBEROS_V4","PLAIN"],
   sasl_cb_getsecret => &getsecret,
   sasl_cb_checkpass => &checkpass,
   commands => {
    'whoami' => 'Arc::Command::Whoami,
    'uptime' => 'Arc::Command::Uptime,
   }
   service => "arc",
  }
 );

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


=head1 Class VARIABLES

=head3 PUBLIC MEMBERS

=over 2

=item connection_type 

B<Description>: Class to use for connections

B<Default value>: 'Arc::Connection::Server'

=item connection_vars 

B<Description>: variables passed directly to every connection handle See C<Arc::Connection::Server>

B<Default value>: undef

=item logfileprefix 

B<Description>: Logfileprefix

B<Default value>: "mainserver"

=item server 

B<Description>: attributes for Net::Server::PreFork

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 

=over 2

=back 

=head3 PROTECTED MEMBERS

=over 2

=item _error I<inherited from Arc>

B<Description>: contains the error message

B<Default value>: undef

=item _syslog I<inherited from Arc>

B<Description>: log to syslog or to STDERR

B<Default value>: 1

=back 

=over 2

=back 

=head3 PRIVATE MEMBERS

=over 2

=item __arc 

B<Description>: stores the Arc::Connection::Server object for optimal PreFork

B<Default value>: undef

=back 

=head1 Class METHODS

=head3 PUBLIC METHODS

=over 2

=item child_init_hook (  ) 

=item post_accept (  ) 

=item process_request (  ) 

=item Start (  ) 

B<Description>: start the server
This function is used by the user to start the server and enter the main accept-loop.
Only by calling the C<Interrupt> function this call can be aborted.


B<Returns:> return true if everything worked fine, otherwise false is returned and C<IsError> should be checked.


B<Example:>

$arc->Start();


=item write_to_log_hook (  ) 

=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 _Init (  ) 

=back