Patrick Boettcher > ARCv2-1.05 > Arc::Command

Download:
ARCv2-1.05.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

NAME ^

Arc::Command - Abstract base class for ARCv2 commands

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.

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.

SYNOPSIS ^

This module is part of the module suite ARCv2.

This is the command module from ARCv2. If we would use C++, we would say this is an abstract class of an ARC Command. All commands used by ARCv2 should derive from this class.

HOW DOES IT WORKS ^

This abstract class is the base class for all existing ARCv2 commands and should be the base class for all new ARCv2 commands.

When starting the ARCv2 Server you have to pass a important hash:

 $arc = new Arc::Server ( 
    [..] Arc::Server vars [..],
   connection_vars => { 
      commands => { 
        'pv' => 'Arc::Command::Pv'
      } 
   }
 )  
 
 resp.

 $arc->{connection_vars}->{commands}

This hash describes the assignment of Command Name and Command Class. When a client has authenticated and wants to run a command, it will send the Command Name and suitable, optional parameters. The server will look into the commands hash and creates an object of the Command Class associated with Command Name.

 my $perlcmd = $this->{commands}->{$cmd};
 [..]
 eval "require $perlcmd;"
 [..]
 (fork)
 my $ret = eval
 {
  my $object = new $perlcmd(
    _username => $this->{_username},
    _peeraddr => $this->{peeraddr},
    _peerport => $this->{peerport},
    _peername => $this->{peername},
    _cmd => $cmd,
    logfileprefix => "command",
  );
  $object->Execute(@a);
  $cmderr = $object->IsError();

  return -1;
 };

When everything went alright, the command will be executed. The command runs in a separate process. Therefore STDIN, STDOUT and STDERR are duped to two pipes, one for the in, one for the out direction. In the parent process data from the encrypted network command connection is read from and written to these pipes. Same situation on the client side, STDIN and STDOUT are used to put and get the data through the network.

                   encrypted
          /--->>---| net- |--->>-----\   
        / /---<<---| work |---<<-----\ \
      / /                              \ \
     | |     in                         | |    p2
  |--------|->>--\                  |--------|->>--\ 
  | Client | out   \                | Server | p1    \
  |--------|-<<-\    \              |--------|-<<-\    \ 
                /|\  \|/                          /|\  \|/
               |--------|                       |-----------|
               |  User  |                       |  Command  |
               |--------|                       |-----------|

This design makes it easy for ARCv2 Commands to get input and produce output.

Example: sub Execute { while ($_ = <STDIN>) { # ends on EOF s/a/b/g; print; } }

If you want to implement a new Command for ARCv2 you have to derive from Arc::Command and override the sub Execute. See existing Arc::Command::* classes for examples. To get your Command recognised you have to assign a Command Name to your command class. ARCv2 ignores the return code of Execute. If your command runs into an error use the _SetError function and return immediately. This is what ARCv2 will evaluate and send to the client.

Example: sub Execute { my $this = shift; my $pw = <>; if ($pw ne "klaus") { return $this->_SetError("Wrong password."); } }

In ARCv2 some standard commands are already implemented: Arc::Command::Get, Arc::Command::Put, Arc::Command::Uptime, Arc::Command::Whoami, Arc::Command::Test.

By default, these classes are mapped to Command Names as follows (in the default arcxd.conf for arcxd): uptime => Arc::Command::Uptime, whoami => Arc::Command::Whoami, copy => Arc::Command::Get, cp => Arc::Command::Get, get => Arc::Command::Get, put => Arc::Command::Put, test => Arc::Command::Test, help => Arc::Command::Help,

Caution: Especially take care of the Arc::Command::Get and Arc::Command::Put in production environment. As ARCv2 will probably run as root and by default the Get and Put command do NOT have an access control, everyone can get or put any files from/to your ARCv2 server.

There are some member variables, which contain information about the client. See 'Class VARIABLES' for a complete list of them. These values are filled by Arc::Connection::Server, when the client wants to run a command.

Class VARIABLES ^

PUBLIC MEMBERS

logfileprefix reimplemented from Arc

Default value: "command"

logdestination inherited from Arc

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

Default value: 'syslog'

loglevel inherited from Arc

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

Default value: 7

PROTECTED MEMBERS

_cmd

Description: user runs this command

Default value: undef

_commands

Description: the "available commands"-hash from the server,

Default value: {}

_mech

Description: user uses this authentication mechanism (e.g. GSSAPI)

Default value: undef

_peeraddr

Description: users ip address

Default value: undef

_peername

Description: users host address in sockaddr_in format

Default value: undef

_peerport

Description: users port

Default value: undef

_realm

Description: the name of the realm, to which the user belongs (SASL)

Default value: ""

_username

Description: user, who has authenticated against ARCv2 Server by using SASL

Default value: ""

_error inherited from Arc

Description: contains the error message

Default value: undef

_syslog inherited from Arc

Description: log to syslog or to STDERR

Default value: 1

PRIVATE MEMBERS

Class METHODS ^

PUBLIC METHODS

Execute ( ... (parameter from users request) )

Description: execute this command. This function is called by the ARCv2 Server when the user wants to execute this command.

Returns: true if the command has succeeded, false (and please set _SetError) if not.

DESTROY ( ) inherited from Arc

Description: Destructor

IsError ( ) inherited from Arc

Description: User function to get the error msg.

Returns: the error message if any otherwise undef

Example:

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

Log ( $facility, ... (message) ) inherited from Arc

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.

Returns: always false

Example:

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

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

Description: Constructor. Initializes the object and returns it blessed. For all sub classes, please override _Init to check the parameter which are passed to the 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.).

Returns: blessed object of the class

Example:

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

PROTECTED METHODS

_Debug ( ... (message) ) inherited from Arc

Description: Debug function. Logs messages with "DEBUG"

Returns: always false

Example:

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

_Init ( %hash, key => val, ... ) inherited from Arc

Description: Init function (initializes class context) Module dependent initialization, every subclass shall override it and call the _Init of its SUPER class. This method is called by the new method of Arc.

Returns: true, if all passed values are in their definition scope, otherwise false

Example:

see source code of any non-abstract sub class of Arc

_SetError ( ... (message) ) inherited from Arc

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.

Returns: always false

Example:

return $this->_SetError("User is not allowed to do this."); # breaks when an error occured

PRIVATE METHODS

SEE ALSO ^

Arc, Arc::Command, Arc::Connection, Arc::Connection::Server, Arc::Connection::Client, arcx, arcxd, Authen::SASL, Authen::SASL::Cyrus Net::Server::PreFork

AUTHOR ^

 Patrick Boettcher <patrick.boettcher@desy.de>

COPYRIGHT AND LICENSE ^

Copyright (c) 2003-5 Patrick Boettcher <patrick.boettcher@desy.de> and others. All rights reserved. Zeuthen, Germany, (old) Europe

 This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

 Special thanks go to:
DESY Zeuthen, in particular:

- Wolfgang Friebel for bleeding edge testing and heavy bug reporting (and the idea of reimplementing ARC).

- Waltraut Niepraschk and Andreas Haupt for their help and support during the development.

syntax highlighting: