Skip to content

Commit

Permalink
website: update translation (#2226)
Browse files Browse the repository at this point in the history
  • Loading branch information
igormiguell authored Dec 13, 2024
1 parent 57d4758 commit a634ec2
Show file tree
Hide file tree
Showing 19 changed files with 108 additions and 108 deletions.
2 changes: 1 addition & 1 deletion website/docs/.vitepress/locales/en.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ function sidebarGuide() {
{ text: 'How to build?', link: '/guide/how-to-build' },
{ text: 'Intergrate for non-GKI devices', link: '/guide/how-to-integrate-for-non-gki'},
{ text: 'Unofficially supported devices', link: '/guide/unofficially-support-devices.md' },
{ text: 'Module Guide', link: '/guide/module.md' },
{ text: 'Module guide', link: '/guide/module.md' },
{ text: 'Module WebUI', link: '/guide/module-webui.md' },
{ text: 'App Profile', link: '/guide/app-profile.md' },
{ text: 'Rescue from bootloop', link: '/guide/rescue-from-bootloop.md' },
Expand Down
30 changes: 15 additions & 15 deletions website/docs/guide/app-profile.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# App Profile

The App Profile is a mechanism provided by KernelSU for customizing the configuration of various applications.
The App Profile is a mechanism provided by KernelSU for customizing the configuration of various apps.

For applications granted root permissions (i.e., able to use `su`), the App Profile can also be referred to as the Root Profile. It allows customization of the `uid`, `gid`, `groups`, `capabilities`, and `SELinux` rules of the `su` command, thereby restricting the privileges of the root user. For example, it can grant network permissions only to firewall applications while denying file access permissions, or it can grant shell permissions instead of full root access for freeze applications: **keeping the power confined with the principle of least privilege.**
For apps granted root permissions (i.e., able to use `su`), the App Profile can also be referred to as the Root Profile. It allows customization of the `uid`, `gid`, `groups`, `capabilities`, and `SELinux` rules of the `su` command, thereby restricting the privileges of the root user. For example, it can grant network permissions only to firewall apps while denying file access permissions, or it can grant shell permissions instead of full root access for freeze apps: **keeping the power confined with the principle of least privilege.**

For ordinary applications without root permissions, the App Profile can control the behavior of the kernel and module system towards these applications. For instance, it can determine whether modifications resulting from modules should be addressed. The kernel and module system can make decisions based on this configuration, such as performing operations akin to "hiding".
For ordinary apps without root permissions, the App Profile can control the behavior of the kernel and module system towards these apps. For instance, it can determine whether modifications resulting from modules should be addressed. The kernel and module system can make decisions based on this configuration, such as performing operations akin to "hiding".

## Root Profile

Expand All @@ -14,7 +14,7 @@ Linux systems have two concepts: users and groups. Each user has a user ID (UID)

Users with a UID of 0 are known as root users, and groups with a GID of 0 are known as root groups. The root user group typically holds the highest system privileges.

In the case of the Android system, each app is a separate user (excluding shared UID scenarios) with a unique UID. For example, `0` represents the root user, `1000` represents `system`, `2000` represents the ADB shell, and UIDs ranging from 10000 to 19999 represent ordinary apps.
In the case of the Android system, each app is a separate user (excluding shared UID scenarios) with a unique UID. For example, `0` represents the root user, `1000` represents `system`, `2000` represents the ADB shell, and UIDs ranging from `10000` to `19999` represent ordinary apps.

:::info
Here, the UID mentioned is not the same as the concept of multiple users or work profiles in the Android system. Work profiles are actually implemented by partitioning the UID range. For example, 10000-19999 represents the main user, while 110000-119999 represents a work profile. Each ordinary app among them has its own unique UID.
Expand All @@ -37,13 +37,13 @@ KernelSU's Root Profile allows customization of the UID, GID, and groups for the
The App Profile only controls the permissions of the root process after using `su`; it does not control the permissions of the app itself. If an app has requested network access permission, it can still access the network even without using `su`. Removing the `inet` group from `su` only prevents `su` from accessing the network.
:::

Root Profile is enforced in the kernel and does not rely on the voluntary behavior of root applications, unlike switching users or groups through `su`, the granting of `su` permission is entirely up to the user rather than the developer.
Root Profile is enforced in the kernel and does not rely on the voluntary behavior of root apps, unlike switching users or groups through `su`, the granting of `su` permission is entirely up to the user rather than the developer.

### Capabilities

Capabilities are a mechanism for privilege separation in Linux.

For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: privileged processes (whose effective user ID is 0, referred to as superuser or root), and unprivileged processes (whose effective UID is nonzero). Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list).
For the purpose of performing permission checks, traditional `UNIX` implementations distinguish two categories of processes: privileged processes (whose effective user ID is `0`, referred to as superuser or root), and unprivileged processes (whose effective UID is nonzero). Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list).

Starting with Linux 2.2, Linux divides the privileges traditionally associated with superuser into distinct units, known as capabilities, which can be independently enabled and disabled.

Expand Down Expand Up @@ -91,10 +91,10 @@ Note that the `allow app1 * * *` rule is used for demonstration purposes only. I

If the configuration of the Root Profile is not set properly, an escalation scenario may occur: the restrictions imposed by the Root Profile can unintentionally fail.

For example, if you grant root permission to an ADB shell user (which is a common case), and then you grant root permission to a regular application but configure its root profile with UID 2000 (which is the UID of the ADB shell user), the application can obtain full root access by executing the `su` command twice:
For example, if you grant root permission to an ADB shell user (which is a common case), and then you grant root permission to a regular app but configure its root profile with UID 2000 (which is the UID of the ADB shell user), the app can obtain full root access by executing the `su` command twice:

1. The first `su` execution is subject to the enforcement of the App Profile and will switch to UID `2000` (adb shell) instead of `0` (root).
2. The second `su` execution, since the UID is `2000`, and you have granted root access to the UID `2000` (adb shell) in the configuration, the application will gain full root privileges.
1. The first `su` execution is subject to the enforcement of the App Profile and will switch to UID `2000` (ADB shell) instead of `0` (root).
2. The second `su` execution, since the UID is `2000`, and you have granted root access to the UID `2000` (ADB shell) in the configuration, the app will gain full root privileges.

:::warning Note
This behavior is entirely expected and not a bug. Therefore, we recommend the following:
Expand All @@ -104,15 +104,15 @@ If you genuinely need to grant root permissions to ADB (e.g., as a developer), i

## Non-Root Profile

### Umount Modules
### Umount modules

KernelSU provides a systemless mechanism for modifying system partitions, achieved through overlayfs mounting. However, some apps may be sensitive to such behavior. Thus, we can unload modules mounted on these apps by setting the "umount modules" option.
KernelSU provides a systemless mechanism for modifying system partitions, achieved through OverlayFS mounting. However, some apps may be sensitive to such behavior. Thus, we can unload modules mounted on these apps by setting the "Umount modules" option.

Additionally, the settings interface of the KernelSU manager provides a switch for "umount modules by default". By default, this switch is **enabled**, which means that KernelSU or some modules will unload modules for this app unless additional settings are applied. If you do not prefer this setting or if it affects certain apps, you have the following options:
Additionally, the settings interface of the KernelSU manager provides a switch for "Umount modules by default". By default, this switch is **enabled**, which means that KernelSU or some modules will unload modules for this app unless additional settings are applied. If you do not prefer this setting or if it affects certain apps, you have the following options:

1. Keep the switch for "umount modules by default" and individually disable the "umount modules" option in the App Profile for apps requiring module loading (acting as a "whitelist").
2. Disable the switch for "umount modules by default" and individually enable the "umount modules" option in the App Profile for apps requiring module unloading (acting as a "blacklist").
1. Keep the switch for "Umount modules by default" and individually disable the "Umount modules" option in the App Profile for apps requiring module loading (acting as a "whitelist").
2. Disable the switch for "Umount modules by default" and individually enable the "Umount modules" option in the App Profile for apps requiring module unloading (acting as a "blacklist").

:::info
In devices using kernel version 5.10 and above, the kernel performs without any further action the unloading of modules. However, for devices running kernel versions below 5.10, this switch is merely a configuration option, and KernelSU itself does not take any action. If you want to be able to use the "umount modules" option in kernel versions before 5.10 you need to backport the `path_umount` function in `fs/namespace.c`, you can get more information at the end of the [How to integrate for non GKI](https://kernelsu.org/guide/how-to-integrate-for-non-gki.html#how-to-backport-path_umount) page. Some modules, such as Zygisksu, may also use this switch to determine whether module unloading is necessary.
In devices using kernel version 5.10 and above, the kernel performs without any further action the unloading of modules. However, for devices running kernel versions below 5.10, this switch is merely a configuration option, and KernelSU itself does not take any action. If you want to be able to use the "Umount modules" option in kernel versions before 5.10 you need to backport the `path_umount` function in `fs/namespace.c`, you can get more information at the end of the [How to integrate KernelSU for non-GKI kernels](https://kernelsu.org/guide/how-to-integrate-for-non-gki.html#how-to-backport-path_umount) page. Some modules, such as Zygisksu, may also use this switch to determine whether module unloading is necessary.
:::
6 changes: 3 additions & 3 deletions website/docs/guide/difference-with-magisk.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ Although there are many similarities between KernelSU modules and Magisk modules

- Module file format: both use zip format to organize modules, and the format of modules is almost the same.
- Module installation directory: both located in `/data/adb/modules`.
- Systemless: both support modifying /system in a systemless way through modules.
- Systemless: both support modifying `/system` in a systemless way through modules.
- post-fs-data.sh: the execution time and semantics are exactly the same.
- service.sh: the execution time and semantics are exactly the same.
- system.prop: completely the same.
- sepolicy.rule: completely the same.
- BusyBox: scripts are run in BusyBox with "standalone mode" enabled in both cases.
- BusyBox: scripts are run in BusyBox with "Standalone Mode" enabled in both cases.

## Differences

Expand All @@ -25,4 +25,4 @@ Here are some differences:
- The directories for BusyBox are different. The built-in BusyBox in KernelSU is located in `/data/adb/ksu/bin/busybox`, while in Magisk it is in `/data/adb/magisk/busybox`. **Note that this is an internal behavior of KernelSU and may change in the future!**
- KernelSU does not support `.replace` files; however, KernelSU supports the `REMOVE` and `REPLACE` variable to remove or replace files and folders.
- KernelSU adds `boot-completed` stage to run some scripts on boot completed.
- KernelSU adds `post-mount` stage to run some scripts after mounting overlayfs.
- KernelSU adds `post-mount` stage to run some scripts after mounting OverlayFS.
6 changes: 3 additions & 3 deletions website/docs/guide/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@

First, your devices should be able to unlock the bootloader. If it can't, then it is unsupported.

Then install KernelSU manager App to your device and open it, if it shows `Unsupported` then your device cannot be supported out of box, but you can build kernel source and integrate KernelSU to make it work or using [unofficially-support-devices](unofficially-support-devices).
Then install KernelSU manager App to your device and open it, if it shows `Unsupported` then your device cannot be supported out of box, but you can build kernel source and integrate KernelSU to make it work or using [Unofficially supported devices](unofficially-support-devices).

## Does KernelSU need to unlock Bootloader?

Certainly, yes.

## Does KernelSU support modules?

Yes, check [Module Guide](module.md) please.
Yes, check [Module guide](module.md) please.

## Does KernelSU support Xposed?

Expand Down Expand Up @@ -49,7 +49,7 @@ It is possible, KernelSU is backported to kernel 4.14 now; for older kernel, you

## How to integrate KernelSU for an older kernel?

Please refer to the following [Guide](how-to-integrate-for-non-gki).
Please refer to the following [How to integrate KernelSU for non-GKI kernels](how-to-integrate-for-non-gki) guide.

## Why my Android version is 13, and the kernel shows "android12-5.10"?

Expand Down
2 changes: 1 addition & 1 deletion website/docs/guide/hidden-features.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Hidden Features
# Hidden features

## .ksurc

Expand Down
12 changes: 6 additions & 6 deletions website/docs/guide/how-to-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@

First, you should read the Android Official docs for kernel build:

1. [Building Kernels](https://source.android.com/docs/setup/build/building-kernels)
2. [GKI Release Builds](https://source.android.com/docs/core/architecture/kernel/gki-release-builds)
1. [Build kernels](https://source.android.com/docs/setup/build/building-kernels)
2. [GKI release builds](https://source.android.com/docs/core/architecture/kernel/gki-release-builds)

::: warning
This page is for GKI devices, if you use an old kernel, please refer [How to integrate KernelSU for non-GKI kernels](how-to-integrate-for-non-gki).
:::

## Build Kernel
## Build kernel

### Sync the kernel source code

Expand All @@ -20,13 +20,13 @@ repo init -m manifest.xml
repo sync
```

The `<kernel_manifest.xml>` is a manifest file which can determine a build uniquely, you can use the manifest to do a re-preducable build. You should download the manifest file from [Google GKI release builds](https://source.android.com/docs/core/architecture/kernel/gki-release-builds).
The `<kernel_manifest.xml>` is a manifest file which can determine a build uniquely, you can use the manifest to do a re-preducable build. You should download the manifest file from [GKI release builds](https://source.android.com/docs/core/architecture/kernel/gki-release-builds).

### Build

Please check the [official docs](https://source.android.com/docs/setup/build/building-kernels) first.

For example, to build an aarch64 kernel image:
For example, to build an `aarch64` kernel image:

```sh
LTO=thin BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh
Expand All @@ -50,7 +50,7 @@ rm common/android/abi_gki_protected_exports_*

## Build Kernel with KernelSU

If you're able to build the kernel successfully, then adding KernelSU support to it is relatively easy. In the root of kernel source directory, run any of the command options listed below:
If you are able to build the kernel successfully, then adding KernelSU support to it is relatively easy. In the root of kernel source directory, run any of the command options listed below:

::: code-group

Expand Down
8 changes: 4 additions & 4 deletions website/docs/guide/how-to-integrate-for-non-gki.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ First, add KernelSU to your kernel source tree:
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.9.5
```

Keep in mind that on some devices, your defconfig may be in `arch/arm64/configs` or in other cases `arch/arm64/configs/vendor/your_defconfig`. For whichever defconfig you're using, make sure to enable `CONFIG_KSU` with `y` to enable or `n` to disable it. For example, in case you chose to enable it, you defconfig should contain the following string:
Keep in mind that on some devices, your defconfig may be in `arch/arm64/configs` or in other cases `arch/arm64/configs/vendor/your_defconfig`. For whichever defconfig you are using, make sure to enable `CONFIG_KSU` with `y` to enable or `n` to disable it. For example, in case you chose to enable it, you defconfig should contain the following string:

```txt
# KernelSU
Expand Down Expand Up @@ -258,7 +258,7 @@ index 2ff887661237..e758d7db7663 100644

### Safe Mode

To enable KernelSU's built-in SafeMode, you should additionally modify `input_handle_event` function in `drivers/input/input.c`:
To enable KernelSU's built-in Safe Mode, you should additionally modify `input_handle_event` function in `drivers/input/input.c`:

:::tip
It is strongly recommended to enable this feature, it is very helpful in preventing bootloops!
Expand Down Expand Up @@ -297,7 +297,7 @@ If you use manual integration and do not disable `CONFIG_KPROBES`, then the user

### Failed to execute `pm` in terminal?

You should modify `fs/devpts/inode.c`, reference:
You should modify `fs/devpts/inode.c`. Reference:

```diff
diff --git a/fs/devpts/inode.c b/fs/devpts/inode.c
Expand Down Expand Up @@ -329,7 +329,7 @@ index 32f6f1c68..d69d8eca2 100644

### How to backport path_umount

You can get module umount feature working on pre-GKI kernels by manually backporting `path_umount` from 5.9. You can use this patch as reference:
You can get "Umount modules" feature working on pre-GKI kernels by manually backporting `path_umount` from 5.9. You can use this patch as reference:

```diff
--- a/fs/namespace.c
Expand Down
Loading

0 comments on commit a634ec2

Please sign in to comment.