Managing ScienceLogic Libraries

This chapter describes how to manage ScienceLogic Libraries in SL1.

Viewing the List of ScienceLogic Libraries

The ScienceLogic Library Manager page (System > Customize > ScienceLogic Libraries) displays a list of all available ScienceLogic Libraries. From this page, you can download libraries, import new libraries, delete existing libraries, or view and edit a list of Execution Environments that you can associate with a library.

For each library, the page displays the following information:

To sort the list of ScienceLogic Libraries, click on a column heading. The list will be sorted by the column value, in ascending order. To sort by descending order, click the column heading again. The Last Edited column sorts by descending order on the first click; to sort by ascending order, click the column heading again.

• Library Name. The name of the ScienceLogic Library.
• Version. The version number of the ScienceLogic Library.
• System. Displays True if the ScienceLogic Library is included in the latest release of SL1 and is aligned with the "System" environment. Displays False if the ScienceLogic Library is included in an imported PowerPack or manually installed by an administrator.
• Type. The file type used to bundle and deliver the ScienceLogic Library. Supported types include the following:

• py_directory (.tar format). A py_directory is a tar file that includes Python files and is typically used by novice developers to share short code snippets between Dynamic Applications or SL1 stacks. This format does not let you manage items such as dependencies, version, or test, and is not recommended.
• py_package (.tar format). A py_package is a tar file that contains Python packages and metadata files (name, version, description, etc.). The py_package format is typically used by more experienced developers to build complex solutions. ScienceLogic recommends using the py_package format because it is easier to test and maintain.

• Dependencies. A comma-separated list of other ScienceLogic Libraries on which the selected library is dependent, if applicable. These additional libraries are included in the selected library's py_package.tar file.
• Description. A single-line description of the ScienceLogic Library's intended use.
• Python Version. The Python compatibility version.
• Edited By. The name of the ScienceLogic user who created or last edited the ScienceLogic Library.
• Last Edited. The date and time the ScienceLogic Library was created or last edited.

Searching and Filtering the List of ScienceLogic Libraries

The Filter-While-You-Type fields appear as a row of blank fields at the top of the list. These fields let you filter the items that appear in the list.

The list is dynamically updated as you select each filter. For each filter, you must make a selection from a drop-down menu or type text to match against. SL1 will search for entries that match the text, including partial matches. Text matches are not case-sensitive, and you can use special characters in each text field.

By default, the cursor is placed in the first Filter-While-You-Type field. You can use the <Tab> key or your mouse to move your cursor through the fields.

You can filter by one or more of the following parameters. Only items that meet all of the filter criteria are displayed on the page.

• Library Name. You can enter text to match, including special characters, and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have a matching name.
• Version. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have a matching version number.
• System. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have a matching System value.
• Type. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have a matching Type value.
• Dependencies. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have matching dependencies.
• Description. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have matching descriptions.
• Python Version. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have matching versions.
• Edited By. You can enter text to match, including special characters and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that were created or last edited by a matching username.
• Last Edited. You can select from a list of time periods, and the ScienceLogic Library Manager page will display only ScienceLogic Libraries that have been created or edited within that time period.

Special Characters

You can include the following special characters to filter by each column except those that display date and time:

When searching for a string, SL1 will match substrings by default, even if you do not include any special characters. For example, searching for "hel" will match both "hello" and "helicopter". When searching for a numeric value, SL1 will not match a substring unless you use a special character.

String and Numeric

• , (comma). Specifies an "OR" operation. Works for string and numeric values. For example:

"dell, micro" matches all values that contain the string "dell" OR the string "micro".

• & (ampersand). Specifies an "AND " operation. Works for string and numeric values. For example:

"dell & micro" matches all values that contain both the string "dell" AND the string "micro", in any order.

• ! (exclamation point). Specifies a "not" operation. Works for string and numeric values. For example:

NOTE: You can also use the "!" character in combination with the arithmetical special characters (min-max, >, <, >=, <=, =) described below.

• * (asterisk). Specifies a "match zero or more" operation. Works for string and numeric values. For a string, matches any string that matches the text before and after the asterisk. For a number, matches any number that contains the text. For example:

"hel*er" would match "helpers" and "helicopter" but not "hello".

"325*" would match "325", "32561", and "325000".

"*000" would match "1000", "25000", and "10500000".

• ? (question mark). Specifies "match any one character". Works for string and numeric values. For example:

"l?ver" would match the strings "oliver", "levers", and "lover", but not "believer".

"135?" would match the numbers "1350", "1354", and "1359", but not "135" or "13502"

String

• ^ (caret). For strings only. Specifies "match the beginning". Matches any string that begins with the specified string. For example:

"^sci" would match "scientific" and "sciencelogic", but not "conscious".

"^happy$" would match only the string "happy", with no characters before or after.

"!^micro" would match all values that do not start with "micro".

"!^$" would match all values that are not null.

"!^" would match null values.

• $ (dollar sign). For strings only. Specifies "match the ending". Matches any string that ends with the specified string. For example:

"ter$" would match the string "renter" but not the string "terrific".

"^happy$" would match only the string "happy", with no characters before or after.

"!fer$" would match all values that do not end with "fer".

"!^$" would match all values that are not null.

"!$" would match null values.

NOTE: You can use both ^ and $ if you want to match an entire string and only that string. For example, "^tern$" would match the strings "tern" or "Tern" or "TERN"; it would not match the strings "terne" or "cistern".

Numeric

• min-max. Matches numeric values only. Specifies any value between the minimum value and the maximum value, including the minimum and the maximum. For example:

"1-5 "would match 1, 2, 3, 4, and 5.

• - (dash). Matches numeric values only. A "half open" range. Specifies values including the minimum and greater or including the maximum and lesser. For example:

"1-" matches 1 and greater. So would match 1, 2, 6, 345, etc.

"-5" matches 5 and less. So would match 5, 3, 1, 0, etc.

• > (greater than). Matches numeric values only. Specifies any value "greater than". For example:

">7" would match all values greater than 7.

• < (less than). Matches numeric values only. Specifies any value "less than". For example:

"<12" would match all values less than 12.

• >= (greater than or equal to). Matches numeric values only. Specifies any value "greater than or equal to". For example:

"=>7" would match all values 7 and greater.

• <= (less than or equal to). Matches numeric values only. Specifies any value "less than or equal to". For example:

"=<12" would match all values 12 and less.

• = (equal). Matches numeric values only. For numeric values, allows you to match a negative value. For example:

"=-5 " would match "-5" instead of being evaluated as the "half open range" as described above.

Examples

• "!dell" matches all values that do not contain the string "dell".
• "!^micro" would match all values that do not start with "micro".
• "!fer$" would match all values that do not end with "fer".
• "!^$" would match all values that are not null.
• "!^" would match null values.
• "!$" would match null values.
• "!*" would match null values.
• "happy, !dell" would match values that contain "happy" OR values that do not contain "dell".
• "aio$". Matches only text that ends with "aio".
• "^shu". Matches only text that begins with "shu".
• "^silo$". Matches only the text "silo", with no characters before or after.
• "!silo". Matches only text that does not contains the characters "silo".
• "!^silo". Matches only text that does not start with "silo".
• "!0$". Matches only text that does not end with "0".
• "!^silo$". Matches only text that is not the exact text "silo", with no characters before or after.
• "!^". Matches null values, typically represented as "--" in most pages.
• "!$". Matches null values, typically represented as "--" in most pages.
• "!^$". Matches all text that is not null.
• silo, !aggr". Matches text that contains the characters "silo" and also text that does not contain "aggr".
• "silo, 02, !aggr". Matches text that contains "silo" and also text that contains "02" and also text that does not contain "aggr".
• "silo, 02, !aggr, !01". Matches text that contains "silo" and also text that contains "02" and also text that does not contain "aggr" and also text that does not contain "01".
• "^s*i*l*o$". Matches text that contains the letter "s", "i", "l", "o", in that order. Other letters might lie between these letters. For example "sXiXlXo" would match.
• "!^s*i*l*o$". Matches all text that does not that contains the letter "s", "i", "l", "o", in that order. Other letters might lie between these letters. For example "sXiXlXo" would not match.
• "!vol&!silo". Matches text that does not contain "vol" AND also does not contain "silo". For example, "volume" would match, because it contains "vol" but not "silo".
• "!vol&02". Matches text that does not contain "vol" AND also contains "02". For example, "happy02" would match, because it does not contain "vol' and it does contain "02".
• "aggr,!vol&02". Matches text that contains "aggr" OR text that does not contain "vol" AND also contains "02".
• "aggr,!vol&!infra". Matches text that contains "aggr" OR text that does not contain "vol" AND does not contain "infra".
• "*". Matches all text.
• "!*". Matches null values, typically represented as "--" in most pages.
• "silo". Matches text that contains "silo".
• " !silo ". Matches text that does not contain "silo".
• " !^silo$ ". Matches all text except the text "silo", with no characters before or after.
• "-3,7-8,11,24,50-". Matches numbers 1, 2, 3, 7, 8, 11, 24, 50, and all numbers greater than 50.
• "-3,7-8,11,24,50-,a". Matches numbers 1, 2, 3, 7, 8, 11, 24, 50, and all numbers greater than 50, and text that includes "a".
• "?n". Matches text that contains any single character and the character "n". For example, this string would match "an", "bn", "cn", "1n", and "2n".
• "n*SAN". Matches text the contains "n", zero or any number of any characters and then "SAN". For example, the string would match "nSAN", and "nhamburgerSAN".
• "^?n*SAN$”. Matches text that begins with any single character, is following by "n", and then zero or any number of any characters, and ends in "SAN".

Downloading a ScienceLogic Library

From the ScienceLogic Library Manager page, you can download ScienceLogic Libraries. Libraries that are included in SL1 are bundled in either a py_package or a py_directory format.

ScienceLogic-authored libraries are copyrighted content and should not be modified without the express permission of ScienceLogic.

To download a ScienceLogic Library:

1. Go to the ScienceLogic Library Manager page (System > Customize > ScienceLogic Libraries).
2. Click the save icon () of the ScienceLogic Library you want to download.
3. The library file is downloaded to your computer.

Importing a ScienceLogic Library

In addition to the ScienceLogic Libraries that are included in the latest version of SL1 or included in a PowerPack, you can use the ScienceLogic Library Manager page to import additional libraries.

To import a library:

1. Go to the ScienceLogic Library Manager page (System > Customize > ScienceLogic Libraries).
2. Click the Actions menu and then select Import ScienceLogic Library.
3. The Import ScienceLogic Library dialog box appears. Use the Browse button to navigate to the ScienceLogic Library file you want to import and then click the Import button.
4. The imported ScienceLogic Library appears on the ScienceLogic Library Manager page.

Creating a ScienceLogic Library

You can create your own library to import into SL1 in either a py_directory or py_package library file saved in uncompressed .tar format. This section describes the requirements for a ScienceLogic-compatible library.

Important Notes on Creating ScienceLogic Libraries

The following are important items to note when creating a ScienceLogic library:

• Library files must be saved in uncompressed .tar format.
• For best results, use GNU tar rather than bsdtar.
• For a py_directory library, the library name comes from the name of the directory that you saved.
• You can only include wheel files (.whl) as additional dependencies. You cannot include any additional packages in your library file that require compilation or linking because Python build tools are not included in the SL1 platform.

• Any libraries that are bundled as dependencies in your py_package file will not be used if a newer version of that library exists on the appliance unless you have a restriction in your package specifying a given version to use.

  For example, if your library "my-library" requires the Python community package "requests" version 2.25.1, you would create the library "requests" version "2.25.1" first. You would then import the requests library into SL1 and align it and "my-library" to your Execution Environment. At runtime, both libraries, at those specific versions, will be used.

  For an alternative example, if your library "my-library" requires the Python community package "requests", but the version is not important, you would include the "requests" package as a ".whl" file in your "my-library" library, adding it to the "manifest.txt" file. After aligning "my-library" to your Execution Environment, it will be available at runtime. The "requests" package included in the "manifest.txt" will be available during the install of "my-library", but may not be used if a newer acceptable package is found for install.

• For a py_package library, an optional "metadata.json" file can be included but it must include the requires_python element otherwise an error will be displayed upon import.

Library File Type: py_package

The py_package file type is the preferred library file type used to bundle Python packages and metadata files. A py_package must have the metadata files described below along with the wheel file(s) and must be saved in uncompressed .tar format. You must create this tar file with Red Hat Enterprise Linux or a similar operating system to ensure compatibility. Tar files created on MacOS are not supported.

All metadata files included in the package must be at the root level of the directory.

A py_package tar file must include the following files:

• __init__.py. This file is required for the directory to be used as a Python package. It identifies this as a package.
• name.txt. This text file specifies the name of the library and must match the name of the package being installed.
• version.txt. This text file specifies the version of the library and must match the version of the package being installed.
• type.txt. This text file specifies that the library is a py_package type library.
• manifest.txt. This text file includes the Python package name and version (as specified in the name.txt and version.txt files), followed by a list of additional supporting files that must be deployed to the internal package repository to use the library. For example, if the library is dependent on another package, that other package must be listed in the manifest file.

The package name of the library must be the first entry in the manifest file.

• Wheel (.whl) file. This is a standard wheel file that you create. See Python documentation for more information about creating wheel files. Wheel files must be Python 2 or Python 2/3 compatible and must be created in Red Hat Enterprise Linux or a similar operating system. You may include multiple wheel files in the py_package.

Library File Type: py_directory

The py_directory file type is used to share short code snippets, for example, between Dynamic Applications or SL1 stacks. Files must be organized in a directory. You must then save the directory in uncompressed .tar format in Red Hat Enterprise Linux or a similar operating system. Tar files created in MacOS are not supported.

The name of the library comes from the name of the directory.

A py_directory tar file can include the following files:

• __init__.py. This file is required for the directory to be imported as a Python package.
• version.txt. This text file contains a version string specifying the version of the library.
• dependencies.txt. This text file includes a comma-separated list of other libraries on which the library is dependent.
• description.txt. This text file includes a single-line description of the library's intended use.
• Python bytecode (.pyc) files or other source files. These are the additional relevant files that you might want to include in the library.

Manually Building a ScienceLogic Library

To manually build a ScienceLogic library, follow this example:

1. Use the sample python library called silo_demo-0.0.7-py2.py3-none-any.whl:

   • Create a project folder for your library, for example, myproject.
   • Copy your project's python wheel file into your new project folder.

mkdir my project

cp silo_demo-0.0.7-py2.py3-none-any.whl myproject/

2. Download a complete set of python dependencies for your python package. In this example case there is a dependency on requests. To download the dependency package, you need to change the project directory to download the package and any transitive dependencies using the python binary path in your execution environment.

cd myproject

python3 -m pip download --find-links=. silo_demo==0.0.7

To build these packages, ScienceLogicrecommends that you are on an OL7 or Redhat based x86-64 installation.

Execute the python3 -m pip download command with a python3.6 interpreter to operate correctly with version 11.3 of SL1. Some Linux distributions default the command python to python2.7.

• The corresponding request python package and all its dependencies will download into your project folder.

Looking in links: .

Processing ./silo_demo-0.0.7-py2.py3-none-any.whl

File was already downloaded /ScienceLogic/myproject/silo_demo-0.0.7-py2.py3-none-any.whl

Collecting requests

Using cached requests-2.29.0-py3-none-any.whl (62 kB)

Collecting certifi>=2017.4.17

Using cached certifi-2022.12.7-py3-none-any.whl (155 kB)

Collecting urllib3<1.27,>=1.21.1

Using cached urllib3-1.26.15-py2.py3-none-any.whl (140 kB)

Collecting charset-normalizer<4,>=2

Using cached charset_normalizer-3.1.0-cp39-cp39-macosx_10_9_x86_64.whl (124 kB)

Collecting idna<4,>=2.5

Using cached idna-3.4-py3-none-any.whl (61 kB)

Saved ./requests-2.29.0-py3-none-any.whl

Saved ./certifi-2022.12.7-py3-none-any.whl

Saved ./charset_normalizer-3.1.0-cp39-cp39-macosx_10_9_x86_64.whl

Saved ./idna-3.4-py3-none-any.whl

Saved ./urllib3-1.26.15-py2.py3-none-any.whl

Successfully downloaded silo_demo requests certifi charset-normalizer idna urllib3

• List the dependencies to ensure they are correct.

 

[myproject]$ ls -l

-rw-r--r--@ 1 dev staff 4524 May 2 11:31 silo_demo-0.0.7-py2.py3-none-any.whl

-rw-r--r-- 1 dev staff 62499 May 3 16:31 requests-2.29.0-py3-none-any.whl

-rw-r--r-- 1 dev staff 155255 May 3 16:31 certifi-2022.12.7-py3-none-any.whl

-rw-r--r-- 1 dev staff 124711 May 3 16:31 charset_normalizer-2.0.4-cp36-cp36mu-manylinux1_x86_64.whl

-rw-r--r-- 1 dev staff 61538 May 3 16:31 idna-3.4-py3-none-any.whl

-rw-r--r-- 1 dev staff 140881 May 3 16:31 urllib3-1.26.15-py2.py3-none-any.whl

CAUTION: SL1 comes pre-installed with the proper versions of wheel, setuptools, and pip wheels for each release. Do not include these in your ScienceLogic library as it will cause a deployment failure.

3. Create the metadata.json file

Ensure you are in your project folder, and using your favorite editor tool to create the metadata.json file. The following example includes the minimum set of metadata required by SL1. The information supplied corresponds to the principle python library you set up in step 1. The environment deployer will pip install the principle python library based on the name and version metadata, so they must be accurate. Update the following fields with your information:

• meta_version. Leave this as default "0.2"
• description. A precise description of the ScienceLogic library
• manifest. Contains the complete list of wheel files from Step 2
• name. The precise name of the principle python package used by pip to install the python package. In this example, the name is silo_demo.
• type. Leave this as default "py_package"
• version. The precise version of the principle python package used by pip to install the python package. In this example, the version is 0.0.7.
• requires_python The specific versions of python you will use. For python2, use "~=2.7" and for python3, use "~=3.6". You should follow PEP440 version specifiers.

For more information about the PEP440 version specifiers, see the PEP440 webpage.

{

"meta_version": "0.2",

"fields": {

"description": "A demo ScienceLogic library",

"manifest": ["certifi-2022.12.7-py3-none-any.whl", "charset_normalizer-2.0.4-cp36-cp36mu-manylinux1_x86_64.whl", "idna-3.4-py3-none-any.whl", "requests-2.29.0-py3-none-any.whl", "silo_demo-0.0.7-py2.py3-none-any.whl", "urllib3-1.26.15-py2.py3-none-any.whl"],

"name": "silo_demo",

"type": "py_package",

"version": "0.0.7",

"requires_python": "~=3.6"

}

}

4. Validate the metadata.json file.

Validating your JSON files ensures there aren't any errors in the pairing of braces and syntax. To validate your metadata.json file type:

python -m json.tool metadata.json

5. Create the ScienceLogic library archive.

Give your archive a unique name so that it is easy to recognize and distinguish from other library archives. Since it is possible to support multiple python runtime versions, ScienceLogic recommends that you include the python version(s) supported in the library archive you create.

Use the following naming convention as a guide:

<lib name> + <lib version>. <runtime version/s>.tar

For example:

tar cvf silo_demo+0.0.7.py36.tar *

ls -l *.tar

-rw-r--r-- 1 em7admin em7admin 480256 Nov 29 16:28 silo_demo+0.0.7.py36.tar

tar tvf silo_demo+0.0.7.py36.tar

-rw-r--r-- 1 em7admin em7admin 161120 Nov 29 16:12 certifi-2022.9.24-py3-none-any.whl

-rw-r--r-- 1 em7admin em7admin 39748 Nov 29 16:12 charset_normalizer-2.0.4-cp36-cp36mu-manylinux1_x86_64.whl

-rw-r--r-- 1 em7admin em7admin 61538 Nov 29 16:12 idna-3.4-py3-none-any.whl

-rw-r--r-- 1 em7admin em7admin 479 Nov 29 16:25 metadata.json

-rw-r--r-- 1 em7admin em7admin 62843 Nov 29 16:12 requests-2.28.1-py3-none-any.whl

-rw-r--r-- 1 em7admin em7admin 4524 Nov 29 16:12 silo_demo-0.0.7-py2.py3-none-any.whl

-rw-r--r-- 1 em7admin em7admin 140572 Nov 29 16:12 urllib3-1.26.13-py2.py3-none-any.whl

CAUTION: Depending on your development environment, your .tar archiving tool may generate an archive that is incompatible with the Linux distribution used by SL1. If this occurs, try extracting( tar xvf myarchive.tar ) or just listing the archive( tar tvf my archive.tar ) on your SL1 appliance before archiving to ensure compatibility with the following steps.

6. Import the ScienceLogic library.

To import a ScienceLogic library, see Importing a ScienceLogic Library.

7. Create an SL1 Execution Environment.

• To create your python3 Execution Environment, go to the Environment Manager page (System>Customize>ScienceLogic Libraries>Actions>Execution Environments) and click New.
• In the Environment Name field, select python3.
• For this example, add the Environment Name Snippet Framework Demo py36 and click Save. The compatible libraries are displayed and available to the python3 execution environment.
• Click the lightning bolt () to include all of the libraries in this environment.

The string found in requires_python will follow the same convention used for python packages.

A ScienceLogic library with requires_python>=3.6 would be compatible with any execution environment greater than or equal to 3.6.

• Make note of the environment GUID for the following steps. In this example, the environment GUID was:

0117E1C041D8CE0C69A8391C02E6DC3B

8. Align your ScienceLogic library to the SL1 Execution Environment.

• Return to the Environment Editor page (System>Customize>ScienceLogic Libraries>Actions>Execution Environments). You should see that your ScienceLogic library is available for alignment to your execution environment.
• Click the lightning bolt () to add your library to the environment.

9. Test your ScienceLogic library.

• Log on to the collector and deploy the ScienceLogic Execution Environment.

sudo -u s-em7-core /opt/em7/bin/python3 /opt/em7/lib/python3/sl_envs/env_manager.pyc --debug 0117E1C041D8CE0C69A8391C02E6DC3B

• Activate your new environment.

source /opt/em7/envs/0117E1C041D8CE0C69A8391C02E6DC3B/bin/activate

• From the python command line, try importing your new package and executing its API.

[uenv-3869008638788123352]$ python

Python 3.6.8 (default, Nov 18 2021, 10:07:16)

[GCC 4.8.5 20150623 (Red Hat 4.8.5-44.0.3)] on linux

Type "help", "copyright", "credits" or "license" for more information.

>>> from silo.demo import demo_class

>>>

ScienceLogic is working to minimize the development effort through the use of Snippet Framework and low code specifications. Unless your collection environment is unique, you may not need to develop content such as manually building your ScienceLogic library.

Deleting a ScienceLogic Library

The ScienceLogic Library Manager page allows you to delete ScienceLogic Libraries that are not currently in use.

SL1 will not allow you to delete ScienceLogic Libraries that are aligned to execution environments that are being used by any Dynamic Applications, credential tests, or Run Book Actions. You also cannot delete libraries that are aligned to the "System" environment.

To delete a library:

1. Go to the ScienceLogic Library Manager page (System > Customize > ScienceLogic Libraries).
2. Select the ScienceLogic Library that you want to delete.
3. Click the Select Actions menu in the lower right of the page and select DELETE ScienceLogic Library, and then click the Go button.
4. The selected ScienceLogic Library is deleted from the ScienceLogic Library Manager page.