Using SysCare

This chapter describes how to use SysCare on openEuler.

Prerequisites

openEuler 22.03 LTS SP1 has been installed.

Using SysCare CLI Tools

You can use syscare build to create patches and use syscare patch to manage patches, including installing, activating, deactivating, and uninstalling patches.

Creating Patches

syscare-build is used to create patches, for example:

syscare-build --name redis_cve_2021_32675 \
        --source redis-6.2.5-1.src.rpm \
        --debuginfo redis-debuginfo-6.2.5-1.x86_64.rpm \
        --target-elfname redis-server \
        --summary CVE-2021-32675 \
        0001-Prevent-unauthenticated-client-from-easily-consuming.patch

Managing Patches

The format of a patch name is TARGET_PACKAGE_NAME/PATCH_NAME. If PATCH_NAME is unique, TARGET_PACKAGE_NAME/ can be omitted.

Installing a patch:
```
syscare apply PATCH_NAME
```
Activating a patch:
```
syscare active PATCH_NAME
```
Deactivating a patch:
```
syscare deactive PATCH_NAME
```
Uninstalling/removing a patch:
```
syscare remove PATCH_NAME
```
Querying the status of a patch:
```
syscare status PATCH_NAME
```
Querying all SysCare patches:
```
syscare list
```

Patch Making Module

Installing from Source

The syscare/build directory stores the source code of the SysCare patch making module.

cd syscare/build

cargo build

SysCare Patch Making Tool

syscare-build is a CLI tool that creates kernel- and user-mode live patches from RPM packages. Patches are encapsulated into RPM packages.

Command Parameters

usage: syscare-build [OPTIONS] --patch-name <PATCH_NAME> --source <SOURCE> --debuginfo <DEBUGINFO> <PATCHES>...

Arguments:
  <PATCHES>...  Patch file(s)

Options:
  -n, --patch-name <PATCH_NAME>                Patch name
      --patch-arch <PATCH_ARCH>                Patch architecture [default: x86_64]
      --patch-version <PATCH_VERSION>          Patch version [default: 1]
      --patch-description <PATCH_DESCRIPTION>  Patch description [default: (none)]
      --target-name <TARGET_NAME>              Patch target name
  -t, --target-elfname <TARGET_ELFNAME>        Patch target executable name
      --target-arch <TARGET_ARCH>              parch target architecture
      --target-epoch <TARGET_EPOCH>            Patch target epoch
      --target-version <TARGET_VERSION>        Patch target version
      --target-release <TARGET_RELEASE>        Patch target release
      --target-license <TARGET_LICENSE>        Patch target license
  -s, --source <SOURCE>                        Source package
  -d, --debuginfo <DEBUGINFO>                  Debuginfo package
      --workdir <WORKDIR>                      Working directory [default: .]
  -o, --output <OUTPUT>                        Generated patch output directory [default: .]
      --kjobs <N>                              Kernel make jobs [default: 32]
      --skip-compiler-check                    Skip compiler version check (not recommended)
      --skip-cleanup                           Skip post-build cleanup
  -v, --verbose                                Provide more detailed info
  -h, --help                                   Print help information
  -V, --version                                Print version information

Mandatory parameters:

Field	Description
--patch-name	Patch name
--source	Source package of the target software
--debuginfo	Debugging information package of the target software
--target-elfname	Name of the executable file of the target software, which can be omitted for kernel patches
--PATCHES	Patch list

An example command is as follows:

syscare-build \
    --patch-name CVE-2021-32675 \
    --source redis-6.2.5-1.src.rpm \
    --debuginfo redis-debuginfo-6.2.5-1.x86_64.rpm \
    --target-elfname redis-server \
    --output output \
    0001-Prevent-unauthenticated-client-from-easily-consuming.patch

Patch Output

A patch package that contains the binary file of SysCare and meta information. This package is used to install the live patch.
A patch source package that contains the target software source code and the new patch. This package is used to create live patches for new versions.

Naming rules:

Patch package: patch-TARGET_SOFTWARE_FULL_NAME-PATCH_NAME-PATCH_VERSION-PATCH_RELEASE.PATCH_ARCHITECTURE.rpm
Patch source code package: TARGET_SOFTWARE_FULL_NAME.patched.PATCH_NAME.PATCH_VERSION.PATCH_RELEASE.src.rpm

Patch Information

The patch meta information contains the following fields:

Field	Description
name	Patch name
type	Patch type
arch	Patch architecture
target	Target software name
elf_name	Name of the executable file of the target software
license	Target software license
version	Patch version
release	Patch release
description	Patch description
builder	Version of the patch making tool

Example:

Collecting patch info
------------------------------
name:        CVE-2021-32675
type:        UserPatch
target:      redis-6.2.5-1
elf_name:    redis-server
license:     BSD and MIT
version:     1
release:     31fc7544
description: None

patch list:
0001-Prevent-unauthenticated-client-from-easily-consuming.patch 31fc7544
------------------------------

Patch Making Process

Prepare the source package (source RPM) and debugging information package (debuginfo RPM) of the target software.
Example:
```
yumdownloader kernel --source

yumdownloader kernel --debuginfo
```

Ensure that the related software build dependencies are installed.

Example:

dnf install make gcc bison flex openssl-devel dwarves python3-devel elfutils-libelf-devel

Run the syscare-build command.

Example:

syscare-build \
        --patch-name kernel_version \
        --source kernel-5.10.0-60.66.0.91.oe2203.src.rpm \
        --debuginfo kernel-debuginfo-5.10.0-60.66.0.91.oe2203.x86_64.rpm \
        --output output \
        001-kernel-patch-test.patch

During patch making, a temporary folder whose name starts with syscare-build is created in the directory specified by --workdir (the current directory by default) to store temporary files and build logs.

Example:

dev@openeuler-dev:[~]$ ls -l syscare-build.111602/
total 100
-rw-r--r--. 1 dev dev 92303 Nov 12 00:00 build.log
drwxr-xr-x. 6 dev dev 4096 Nov 12 00:00 package
drwxr-xr-x. 4 dev dev 4096 Nov 12 00:00 patch

Build logs (build.log) are generated in the temporary folder.

dev@openeuler-dev:[~]$ cat syscare-build.111602/build.log | less
...

If the patch is created successfully, the temporary folder will be deleted after patch making.

Check the build result.

Example:

dev@openeuler-dev:[~]$ ls -l
total 189680
-rw-r--r--. 1 dev dev 194218767 Nov 12 00:00 kernel-5.10.0-60.66.0.91.oe2203.patched.kernel_version.1.c15c1a6a.src.rpm
-rw-r--r--. 1 dev dev     10937 Nov 12 00:00 patch-kernel-5.10.0-60.66.0.91.oe2203-kernel_version-1-c15c1a6a.x86_64.rpm

In the output:

patch-kernel-5.10.0-60.66.0.91.oe2203-kernel_version-1-c15c1a6a.x86_64.rpm is the patch package.

kernel-5.10.0-60.66.0.91.oe2203.patched.kernel_version.1.c15c1a6a.src.rpm is the patch source package.

Install the patch.
```
rpm -ivh patch-xxx.rpm
```
After the patch is installed, files in the patch are stored in the /usr/lib/syscare/patches/target_software_package_name/patch_name directory
Uninstall the patch.
```
rpm -e patch-xxx.rpm
```
The patch package can be uninstalled only when the patch is in the not-apply state.

Error Handling

If an error occurs, see the build logs:

Error output example:

...
Building patch, this may take a while
ERROR: Process '/usr/libexec/syscare/upatch-build' exited unsuccessfully, exit_code=255

Bug Catching

Buggy Content

Bug Description

Submit As Issue

It's a little complicated....

I'd like to ask someone.

Just a small problem.

I can fix it online!

Bug Type

Specifications and Common Mistakes

● Misspellings or punctuation mistakes;

● Incorrect links, empty cells, or wrong formats;

● Chinese characters in English context;

● Minor inconsistencies between the UI and descriptions;

● Low writing fluency that does not affect understanding;

● Incorrect version numbers, including software package names and version numbers on the UI.

Usability

● Incorrect or missing key steps;

● Missing prerequisites or precautions;

● Ambiguous figures, tables, or texts;

● Unclear logic, such as missing classifications, items, and steps.

Correctness

● Technical principles, function descriptions, or specifications inconsistent with those of the software;

● Incorrect schematic or architecture diagrams;

● Incorrect commands or command parameters;

● Incorrect code;

● Commands inconsistent with the functions;

● Wrong screenshots.

Risk Warnings

● Lack of risk warnings for operations that may damage the system or important data.

Content Compliance

● Contents that may violate applicable laws and regulations or geo-cultural context-sensitive words and expressions;

● Copyright infringement.

We may contact you through email in regard to the bug fixing solution. You will also be notified through email if you win any prize during the activity.

How satisfied are you with this document

Not satisfied at all

Very satisfied

By submitting the contents, you fully understand and agree to the terms of the openEuler Privacy Policy.

Submit

Click to create an issue. An issue template will be automatically generated based on your feedback.