OTRS Academy » Documentation » OTRS API Reference Perl » Kernel::System::Main

Kernel::System::Main

October 26, 2023

NAME

Kernel::System::Main – main object

DESCRIPTION

All main functions to load modules, die, and handle files.

PUBLIC INTERFACE

new()

create new object. Do not use it directly, instead use:

    my $MainObject = $Kernel::OM->Get('Kernel::System::Main');

Require()

require/load a module

    my $Loaded = $MainObject->Require(
        'Kernel::System::Example',
        Silent => 1,                # optional, no log entry if module was not found
    );

RequireBaseClass()

require/load a module and add it as a base class to the calling package, if not already present (this check is needed for persistent environments).

    my $Loaded = $MainObject->RequireBaseClass(
        'Kernel::System::Example',
    );

Die()

to die

    $MainObject->Die('some message to die');

FilenameCleanUp()

to clean up filenames which can be used in any case (also quoting is done)

    my $Filename = $MainObject->FilenameCleanUp(
        Filename => 'me_to/alal.xml',
        Type     => 'Local', # Local|Attachment|MD5
    );

    my $Filename = $MainObject->FilenameCleanUp(
        Filename => 'some:file.xml',
        Type     => 'MD5', # Local|Attachment|MD5
    );

FileRead()

to read files from file system

    my $ContentSCALARRef = $MainObject->FileRead(
        Directory => 'c:\some\location',
        Filename  => 'file2read.txt',
        # or Location
        Location  => 'c:\some\location\file2read.txt',
    );

    my $ContentARRAYRef = $MainObject->FileRead(
        Directory => 'c:\some\location',
        Filename  => 'file2read.txt',
        # or Location
        Location  => 'c:\some\location\file2read.txt',

        Result    => 'ARRAY', # optional - SCALAR|ARRAY
    );

    my $ContentSCALARRef = $MainObject->FileRead(
        Directory       => 'c:\some\location',
        Filename        => 'file2read.txt',
        # or Location
        Location        => 'c:\some\location\file2read.txt',

        Mode            => 'binmode', # optional - binmode|utf8
        Type            => 'Local',   # optional - Local|Attachment|MD5
        Result          => 'SCALAR',  # optional - SCALAR|ARRAY
        DisableWarnings => 1,         # optional
    );

FileWrite()

to write data to file system

    my $FileLocation = $MainObject->FileWrite(
        Directory => 'c:\some\location',
        Filename  => 'file2write.txt',
        # or Location
        Location  => 'c:\some\location\file2write.txt',

        Content   => \$Content,
    );

    my $FileLocation = $MainObject->FileWrite(
        Directory  => 'c:\some\location',
        Filename   => 'file2write.txt',
        # or Location
        Location   => 'c:\some\location\file2write.txt',

        Content    => \$Content,
        Mode       => 'binmode', # binmode|utf8
        Type       => 'Local',   # optional - Local|Attachment|MD5
        Permission => '644',     # optional - unix file permissions
    );

Platform note: MacOS (HFS+) stores filenames as Unicode NFD internally, and DirectoryRead() will also report them as NFD.

FileStat()

Get file meta data from file system using the Perl stat() function

    my $Result = $MainObject->FileStat(
        Directory       => 'c:\some\location',
        Filename        => 'me_to/alal.xml',
        Type            => 'Local',                       # optional - Local|Attachment|MD5

        # or Location
        Location        => 'c:\absolute\path\to\file.xml'

        DisableWarnings => 1,                             # optional
    );

Returns:

    $Result = {
        Success      => 1,
        Inode        => 8041482,
        ModifiedTime => 1685422853,
        StatusTime   => 1685422853,
    };

or on Error:

    $Result = {
        Success => 0,
        Error   => "File 'c:\absolute\path\to\file.xml': File Stat failed! Message: File does not exist."
    };

FileDelete()

to delete a file from file system

    my $Success = $MainObject->FileDelete(
        Directory       => 'c:\some\location',
        Filename        => 'me_to/alal.xml',
        # or Location
        Location        => 'c:\some\location\me_to\alal.xml'

        Type            => 'Local',   # optional - Local|Attachment|MD5
        DisableWarnings => 1, # optional
    );

FileGetMTime()

get timestamp of file change time

    my $FileMTime = $MainObject->FileGetMTime(
        Directory => 'c:\some\location',
        Filename  => 'me_to/alal.xml',
        # or Location
        Location  => 'c:\some\location\me_to\alal.xml'
    );

MD5sum()

get an MD5 sum of a file or a string

    my $MD5Sum = $MainObject->MD5sum(
        Filename => '/path/to/me_to_alal.xml',
    );

    my $MD5Sum = $MainObject->MD5sum(
        String => \$SomeString,
    );

    # note: needs more memory!
    my $MD5Sum = $MainObject->MD5sum(
        String => $SomeString,
    );

Dump()

dump variable to an string

    my $Dump = $MainObject->Dump(
        $SomeVariable,
    );

    my $Dump = $MainObject->Dump(
        {
            Key1 => $SomeVariable,
        },
    );

    dump only in ascii characters (> 128 will be marked as \x{..})

    my $Dump = $MainObject->Dump(
        $SomeVariable,
        'ascii', # ascii|binary - default is binary
    );

DirectoryRead()

reads a directory and returns an array with results.

    my @FilesInDirectory = $MainObject->DirectoryRead(
        Directory => '/tmp',
        Filter    => 'Filenam*',
    );

    my @FilesInDirectory = $MainObject->DirectoryRead(
        Directory => $Path,
        Filter    => '*',
    );

read all files in subdirectories as well (recursive):

    my @FilesInDirectory = $MainObject->DirectoryRead(
        Directory => $Path,
        Filter    => '*',
        Recursive => 1,
    );

You can pass several additional filters at once:

    my @FilesInDirectory = $MainObject->DirectoryRead(
        Directory => '/tmp',
        Filter    => \@MyFilters,
    );

The result strings are absolute paths, and they are converted to utf8.

Use the 'Silent' parameter to suppress log messages when a directory does not have to exist:

    my @FilesInDirectory = $MainObject->DirectoryRead(
        Directory => '/special/optional/directory/',
        Filter    => '*',
        Silent    => 1,     # will not log errors if the directory does not exist
    );

Platform note: MacOS (HFS+) stores filenames as Unicode NFD internally, and DirectoryRead() will also report them as NFD.

GenerateRandomString()

generate a random string of defined length, and of a defined alphabet. defaults to a length of 16 and alphanumerics ( 0..9, A-Z and a-z).

    my $String = $MainObject->GenerateRandomString();

returns

    $String = 'mHLOx7psWjMe5Pj7';

with specific length:

    my $String = $MainObject->GenerateRandomString(
        Length => 32,
    );

returns

    $String = 'azzHab72wIlAXDrxHexsI5aENsESxAO7';

with specific length and alphabet:

    my $String = $MainObject->GenerateRandomString(
        Length     => 32,
        Dictionary => [ 0..9, 'a'..'f' ], # hexadecimal
        );

returns

    $String = '9fec63d37078fe72f5798d2084fea8ad';

GenerateSecurePassword()

Generate a secure password.

    my $String = $MainObject->GenerateSecurePassword(
        Characters => [ ... ],  # optional, defaults to 0 .. 9, A .. Z, a .. z, -, _, !, @, #, $, %, ^, &, *
        Length     => 32,       # optional, defaults to 16
    );

Returns a random password string.

ShellQuote()

Quotes string so it can be passed through the shell. String is quoted so that the shell will pass it along as a single argument and without further interpretation. Quoting is done by an external library String::ShellQuote.

    my $QuotedString = $MainObject->ShellQuote(
        "Safe string for 'shell arguments'."   # string to quote
    );

Returns quoted string, or undef if unsuccessful:

    $QuotedString = <<'EOS';
'Safe string for '\''shell arguments'\''.'
EOS

GenerateUUID()

Generates a new UUID.

    my $UUID = $MainObject->GenerateUUID();

Returns

    returns the UUID string.

SystemCommandCheck()

Check if a system command is safe to run.

    my %Result = $Kernel::OM->Get('Kernel::System::Main')->SystemCommandCheck(
      CommandString => $CommandString,
    );

    if ( !$Result{Success} ) {
        $Kernel::OM->Get('Kernel::System::Log')->Log(
            Priority => 'error',
            Message  => $Result{Error},
        );
        return;
    }

CommandString Syntax:

    # A CommandString is bound by this syntax:
    # where BINARY can consist of:
    BINARY [--OPTION|ARGUMENT]

    # Simple commands.
    BINARY

    # Multiple commands.
    BINARY1; BINARY2

    # Conditional commands.
    BINARY1 && BINARY2
    BINARY1 || BINARY2

    # Piping commands.
    BINARY1 | BINARY2

    # Redirection commands.
    BINARY < FILE
    BINARY > FILE
    BINARY >> FILE

    # sudo is an optional prefix.
    sudo BINARY

    # Expand <OTRS_CONFIG_$VAR>.
    BINARY > <OTRS_CONFIG_Home>/var/tmp/file

    # BINARY and FILE are validated using whitelists.

Result:

    %Result = (
        Success    => 1,
        Error      => "String message", # Error message.
        _ParseTree => [...],            # Internal representation of the command.
    );

Error Messages:

    Command is not provided!
    Command exceeds 2000 characters!
    Command cannot be parsed!
    Empty statement are forbidden!
    Leading redirection/piping is forbidden!
    Trailing redirection/piping is forbidden!
    '$Directory' is not safe to read or write to!
    Exclamation mark can only be used inside of single quotes!
    Command substitution can only be used inside of single quotes!
    Invalid argument in double quotes: $Argument
    Invalid argument outside of quotes: $Argument
    Binary is not provided!
    '$Binary' is not safe to run!
    Parent directory syntax '../' is forbidden!
FacebookXEmailLinkedIn
Scroll to Top