view release on metacpan or  search on metacpan

lib/Log/Log4perl.pm  view on Meta::CPAN

L<"Restricting what Opcodes can be in a Perl Hook">.

=head2 Restricting what Opcodes can be in a Perl Hook

The value you pass to Log::Log4perl::Config->allow_code() determines whether
the code that is embedded in the config file is eval'd unrestricted, or
eval'd in a Safe compartment.  By default, a value of '1' is assumed,
which does a normal 'eval' without any restrictions. A value of '0' 
however prevents any embedded code from being evaluated.

If you would like fine-grained control over what can and cannot be included
in embedded code, then please utilize the following methods:

 Log::Log4perl::Config->allow_code( $allow );
 Log::Log4perl::Config->allowed_code_ops($op1, $op2, ... );
 Log::Log4perl::Config->vars_shared_with_safe_compartment( [ \%vars | $package, \@vars ] );
 Log::Log4perl::Config->allowed_code_ops_convenience_map( [ \%map | $name, \@mask ] );

Log::Log4perl::Config-E<gt>allowed_code_ops() takes a list of opcode masks
that are allowed to run in the compartment.  The opcode masks must be
specified as described in L<Opcode>:

 Log::Log4perl::Config->allowed_code_ops(':subprocess');

This example would allow Perl operations like backticks, system, fork, and
waitpid to be executed in the compartment.  Of course, you probably don't
want to use this mask -- it would allow exactly what the Safe compartment is
designed to prevent.

Log::Log4perl::Config-E<gt>vars_shared_with_safe_compartment() 
takes the symbols which
should be exported into the Safe compartment before the code is evaluated. 
The keys of this hash are the package names that the symbols are in, and the
values are array references to the literal symbol names.  For convenience,
the default settings export the '%ENV' hash from the 'main' package into the
compartment:

 Log::Log4perl::Config->vars_shared_with_safe_compartment(
   main => [ '%ENV' ],
 );

Log::Log4perl::Config-E<gt>allowed_code_ops_convenience_map() is an accessor
method to a map of convenience names to opcode masks. At present, the
following convenience names are defined:

 safe        = [ ':browse' ]
 restrictive = [ ':default' ]

For convenience, if Log::Log4perl::Config-E<gt>allow_code() is called with a
value which is a key of the map previously defined with
Log::Log4perl::Config-E<gt>allowed_code_ops_convenience_map(), then the
allowed opcodes are set according to the value defined in the map. If this
is confusing, consider the following:

 use Log::Log4perl;
 
 my $config = <<'END';
  log4perl.logger = INFO, Main
  log4perl.appender.Main = Log::Log4perl::Appender::File
  log4perl.appender.Main.filename = \
      sub { "example" . getpwuid($<) . ".log" }
  log4perl.appender.Main.layout = Log::Log4perl::Layout::SimpleLayout
 END
 
 $Log::Log4perl::Config->allow_code('restrictive');
 Log::Log4perl->init( \$config );       # will fail
 $Log::Log4perl::Config->allow_code('safe');
 Log::Log4perl->init( \$config );       # will succeed

The reason that the first call to -E<gt>init() fails is because the
'restrictive' name maps to an opcode mask of ':default'.  getpwuid() is not
part of ':default', so -E<gt>init() fails.  The 'safe' name maps to an opcode
mask of ':browse', which allows getpwuid() to run, so -E<gt>init() succeeds.

allowed_code_ops_convenience_map() can be invoked in several ways:

=over 4

=item allowed_code_ops_convenience_map()

Returns the entire convenience name map as a hash reference in scalar
context or a hash in list context.

=item allowed_code_ops_convenience_map( \%map )

Replaces the entire convenience name map with the supplied hash reference.

=item allowed_code_ops_convenience_map( $name )

Returns the opcode mask for the given convenience name, or undef if no such
name is defined in the map.

=item allowed_code_ops_convenience_map( $name, \@mask )

Adds the given name/mask pair to the convenience name map.  If the name
already exists in the map, it's value is replaced with the new mask.

=back

as can vars_shared_with_safe_compartment():

=over 4

=item vars_shared_with_safe_compartment()

Return the entire map of packages to variables as a hash reference in scalar
context or a hash in list context.

=item vars_shared_with_safe_compartment( \%packages )

Replaces the entire map of packages to variables with the supplied hash
reference.

=item vars_shared_with_safe_compartment( $package )

Returns the arrayref of variables to be shared for a specific package.

=item vars_shared_with_safe_compartment( $package, \@vars )

Adds the given package / varlist pair to the map.  If the package already
exists in the map, it's value is replaced with the new arrayref of variable
names.

=back

For more information on opcodes and Safe Compartments, see L<Opcode> and
L<Safe>.

=head2 Changing the Log Level on a Logger

Log4perl provides some internal functions for quickly adjusting the
log level from within a running Perl program.