view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    before you call init(). Alternatively you can supply a restricted set of
    Perl opcodes that can be embedded in the config file as described in
    "Restricting what Opcodes can be in a Perl Hook".

  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->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 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->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->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->allow_code() is called with a
    value which is a key of the map previously defined with
    Log::Log4perl::Config->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 ->init() fails is because the
    'restrictive' name maps to an opcode mask of ':default'. getpwuid() is
    not part of ':default', so ->init() fails. The 'safe' name maps to an
    opcode mask of ':browse', which allows getpwuid() to run, so ->init()
    succeeds.

    allowed_code_ops_convenience_map() can be invoked in several ways:

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

    allowed_code_ops_convenience_map( \%map )
        Replaces the entire convenience name map with the supplied hash
        reference.

    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.

    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.

    as can vars_shared_with_safe_compartment():

    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.

    vars_shared_with_safe_compartment( \%packages )
        Replaces the entire map of packages to variables with the supplied
        hash reference.

    vars_shared_with_safe_compartment( $package )
        Returns the arrayref of variables to be shared for a specific
        package.

    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.

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

  Changing the Log Level on a Logger
    Log4perl provides some internal functions for quickly adjusting the log
    level from within a running Perl program.

    Now, some people might argue that you should adjust your levels from
    within an external Log4perl configuration file, but Log4perl is
    everybody's darling.

    Typically run-time adjusting of levels is done at the beginning, or in
    response to some external input (like a "more logging" runtime command
    for diagnostics).

    You get the log level from a logger object with:

        $current_level = $logger->level();

    and you may set it with the same method, provided you first imported the