From 1f738edce4cdec1a1f485c83d78646754cb146eb Mon Sep 17 00:00:00 2001
From: Moe-hacker <moe-hacker@outlook.com>
Date: Sat, 23 Nov 2024 07:55:23 +0000
Subject: [PATCH] Add some comments

---
 doc/USAGE_zh.md |  2 +-
 src/caplist.c   |  4 ++++
 src/cgroup.c    |  5 +++++
 src/chroot.c    | 20 +++++++++++++++++---
 src/config.c    |  7 +++++++
 src/elf-magic.c |  4 ++++
 src/info.c      |  6 +++++-
 src/main.c      |  1 +
 src/mount.c     |  4 ++++
 src/passwd.c    |  6 ++++++
 src/ps.c        |  6 +++++-
 src/rootless.c  |  5 +++++
 src/ruri.c      |  3 +++
 src/rurienv.c   |  5 +++++
 src/rurifetch.c |  4 ++++
 src/seccomp.c   |  3 +++
 src/signal.c    |  5 +++++
 src/umount.c    |  4 ++++
 src/unshare.c   |  5 +++++
 19 files changed, 93 insertions(+), 6 deletions(-)

diff --git a/doc/USAGE_zh.md b/doc/USAGE_zh.md
index e4ff958..38694a0 100644
--- a/doc/USAGE_zh.md
+++ b/doc/USAGE_zh.md
@@ -190,6 +190,6 @@ unshare容器和rootless容器会始终在执行命令前fork()自身一次，
 设置主机名，仅供unshare容器。      
 **************
 ```
--x, --disable-network .......................: 禁用网络
+-x, --no-network .......................: 禁用网络
 ```      
 禁用容器网络，这需要net命名空间支持，并将自动启用unshare。      
\ No newline at end of file
diff --git a/src/caplist.c b/src/caplist.c
index 1fc46db..76c791d 100644
--- a/src/caplist.c
+++ b/src/caplist.c
@@ -28,6 +28,10 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides functions to manage capability list.
+ * But drop_caps() to set capabilities is in chroot.c, not here.
+ */
 // Add a cap to caplist.
 void ruri_add_to_caplist(cap_value_t *_Nonnull list, cap_value_t cap)
 {
diff --git a/src/cgroup.c b/src/cgroup.c
index 02e3004..49aa72e 100644
--- a/src/cgroup.c
+++ b/src/cgroup.c
@@ -28,6 +28,11 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides functions to set cgoup limits for container.
+ * ${container_id} is set by the time creating the container,
+ * And it will be unified by .rurienv file.
+ */
 static void mount_cgroup_v1_memory(void)
 {
 	/*
diff --git a/src/chroot.c b/src/chroot.c
index 5c738d4..74c62f5 100644
--- a/src/chroot.c
+++ b/src/chroot.c
@@ -28,11 +28,17 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file is the core of ruri.
+ * It provides functions to run container as info in struct RURI_CONTAINER.
+ * Bisic functions of ruri is implemented here.
+ */
 static bool su_biany_exist(char *_Nonnull container_dir)
 {
 	/*
 	 * Check if /bin/su exists in container.
-	 * Because in some rootfs, /bin/su is not exist.
+	 * Because in some rootfs, /bin/su is not exist,
+	 * so we need to check it.
 	 */
 	char su_path[PATH_MAX] = { '\0' };
 	sprintf(su_path, "%s/bin/su", container_dir);
@@ -51,6 +57,7 @@ static void check_binary(const struct RURI_CONTAINER *_Nonnull container)
 	/*
 	 * Since ruri use execvp() instead of execv(),
 	 * we will not check for init binary here now.
+	 * So, only check for qemu binary.
 	 */
 	// Check QEMU path.
 	if (container->cross_arch != NULL) {
@@ -76,6 +83,7 @@ static void init_container(struct RURI_CONTAINER *_Nonnull container)
 	/*
 	 * It'll be run after chroot(2), so `/` is the root dir of container now.
 	 * The device list and permissions are based on common docker containers.
+	 * If -A is not set, we will mask some dirs in /sys and /proc to avoid security issues.
 	 */
 	// If /proc/1 exists, that means container is already initialized.
 	// I used to check /sys/class/input, but in WSL1, /sys/class/input is not exist.
@@ -261,6 +269,7 @@ static void set_envs(const struct RURI_CONTAINER *_Nonnull container)
 	/*
 	 * Set environment variables.
 	 * $PATH and $TMPDIR will also be set here.
+	 * And $SHELL will be set to sh, for compatibility.
 	 */
 	// Set $PATH to the common value in GNU/Linux,
 	// because $PATH in termux is not correct for common GNU/Linux containers.
@@ -365,6 +374,8 @@ static void copy_qemu_binary(struct RURI_CONTAINER *container)
 {
 	/*
 	 * Copy qemu binary into container.
+	 * ruri support to use qemu-path in host,
+	 * but, to use qemu, we need to copy qemu binary into container.
 	 */
 	// If -q is not set, return.
 	if (container->qemu_path == NULL) {
@@ -408,7 +419,7 @@ static bool pivot_root_succeed(const char *_Nonnull container_dir)
 	/*
 	 * Check if pivot_root(2) succeed.
 	 */
-	// Check if /dev/null is a character device.
+	// Check if ${container_dir}/dev/null is a character device.
 	struct stat dev_null_stat;
 	char dev_null[PATH_MAX] = { '\0' };
 	if (chdir(container_dir) != 0) {
@@ -477,6 +488,9 @@ static void set_hostname(struct RURI_CONTAINER *_Nonnull container)
 {
 	/*
 	 * Set hostname.
+	 * Only for unshare container,
+	 * because hostname is a global setting in the system,
+	 * and we do not want to change the hostname of the host.
 	 */
 	if (container->hostname != NULL) {
 		if (container->enable_unshare) {
@@ -552,7 +566,7 @@ void ruri_run_chroot_container(struct RURI_CONTAINER *_Nonnull container)
 	}
 	// Check binary used.
 	check_binary(container);
-	// chroot(2) into container.
+	// chroot(2) into container, or use pivot_root(2) if `-u` is set.
 	if (!container->enable_unshare) {
 		chdir(container->container_dir);
 		chroot(".");
diff --git a/src/config.c b/src/config.c
index 02c5dae..69a6bad 100644
--- a/src/config.c
+++ b/src/config.c
@@ -28,6 +28,9 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides config file support for ruri.
+ */
 char *ruri_container_info_to_k2v(const struct RURI_CONTAINER *_Nonnull container)
 {
 	/*
@@ -345,6 +348,10 @@ void ruri_read_config(struct RURI_CONTAINER *_Nonnull container, const char *_No
 }
 void ruri_correct_config(const char *_Nonnull path)
 {
+	/*
+	 * Correct the config file.
+	 * This is useful when upgrading ruri to the new version.
+	 */
 	// Disable strict mode for libk2v.
 	k2v_show_warning = false;
 	k2v_stop_at_warning = false;
diff --git a/src/elf-magic.c b/src/elf-magic.c
index 6aa938b..942ade3 100644
--- a/src/elf-magic.c
+++ b/src/elf-magic.c
@@ -28,6 +28,10 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides functions to get ELF magic number and mask for cross_arch.
+ * These info will be used for binfmt_misc.
+ */
 // Get ELF magic number and mask for cross_arch specified.
 struct RURI_ELF_MAGIC *ruri_get_magic(const char *_Nonnull cross_arch)
 {
diff --git a/src/info.c b/src/info.c
index edcb851..a51dc7b 100644
--- a/src/info.c
+++ b/src/info.c
@@ -28,10 +28,14 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides some functions to show help/version info.
+ * As ruri_fetch() is too long but useless, I put it in rurifetch.c.
+ */
 void ruri_show_version_info(void)
 {
 	/*
-	 * Just show version info and license.
+	 * Just show some info.
 	 * Version info is defined in macro RURI_VERSION.
 	 * RURI_COMMIT_ID is defined as -D option of compiler.
 	 */
diff --git a/src/main.c b/src/main.c
index c63e5c1..eec2f7a 100644
--- a/src/main.c
+++ b/src/main.c
@@ -32,6 +32,7 @@ int main(int argc, char **argv)
 {
 	/*
 	 * Nothing here, just call ruri().
+	 * So that we can make ruri built-in into other programs easily.
 	 */
 	return ruri(argc, argv);
 }
\ No newline at end of file
diff --git a/src/mount.c b/src/mount.c
index 39bdb70..a5f0654 100644
--- a/src/mount.c
+++ b/src/mount.c
@@ -28,6 +28,10 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides the mount functions for ruri.
+ * It's used to mount disk devices, loop devices, and dir/files.
+ */
 // Return the same value as mkdir().
 static int mkdirs(const char *_Nonnull dir, mode_t mode)
 {
diff --git a/src/passwd.c b/src/passwd.c
index ca2d862..9808b3e 100644
--- a/src/passwd.c
+++ b/src/passwd.c
@@ -28,6 +28,12 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * Since we cannot statically link getpwuid() in glibc,
+ * we need to implement it by ourselves.
+ * This file provides functions to parse /etc/passwd,
+ * and it can also parse /etc/subuid and /etc/subgid.
+ */
 static char *line_get_username(const char *_Nonnull p)
 {
 	/*
diff --git a/src/ps.c b/src/ps.c
index 7b0f7f2..77ce0ee 100644
--- a/src/ps.c
+++ b/src/ps.c
@@ -28,6 +28,9 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides functions to show or kill all processes in the container.
+ */
 static char *getpid_name(pid_t pid)
 {
 	/*
@@ -234,10 +237,11 @@ static bool is_container_process(pid_t pid, const char *_Nonnull container_dir)
 void ruri_kill_container(const char *_Nonnull container_dir)
 {
 	/*
+	 *
 	 * Check all the processes in /proc,
 	 * If the process is in the container, kill it.
 	 * We check for /proc/pid/root to determine if the process is in the container.
-	 *
+	 * This function is called by ruri_umount_container().
 	 */
 	DIR *proc_dir = opendir("/proc");
 	struct dirent *file = NULL;
diff --git a/src/rootless.c b/src/rootless.c
index 0634ef0..0aff664 100644
--- a/src/rootless.c
+++ b/src/rootless.c
@@ -28,6 +28,11 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides rootless container support,
+ * as ruri_run_rootless_chroot_container() needs some functions in chroot.c,
+ * it's in chroot.c, not here.
+ */
 static int try_execvp(char *_Nonnull argv[])
 {
 	/*
diff --git a/src/ruri.c b/src/ruri.c
index 352c087..39c16a8 100644
--- a/src/ruri.c
+++ b/src/ruri.c
@@ -28,6 +28,9 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file was the main.c of ruri.
+ */
 // Do some checks before chroot(2),called by main().
 static void check_container(const struct RURI_CONTAINER *_Nonnull container)
 {
diff --git a/src/rurienv.c b/src/rurienv.c
index 0789b09..8dbb493 100644
--- a/src/rurienv.c
+++ b/src/rurienv.c
@@ -28,6 +28,11 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides functions to read and store .rurienv file.
+ * ${container_dir}/.rurienv file is a file that stores the runtime info of the container.
+ * It's used when running and umounting container.
+ */
 // Check if the running pid is ruri.
 static bool is_ruri_pid(pid_t pid)
 {
diff --git a/src/rurifetch.c b/src/rurifetch.c
index 9c45ad6..02ea53d 100644
--- a/src/rurifetch.c
+++ b/src/rurifetch.c
@@ -28,6 +28,10 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * A neofetch-like program for ruri.
+ * Nothing useful, just for fun.
+ */
 static void __ruri_fetch(char **logo, char **info)
 {
 	int j = 0;
diff --git a/src/seccomp.c b/src/seccomp.c
index e3ef6a8..986ce86 100644
--- a/src/seccomp.c
+++ b/src/seccomp.c
@@ -28,6 +28,9 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides the built-in seccomp filter rules for ruri.
+ */
 // Setup seccomp filter rule, with libseccomp.
 void ruri_setup_seccomp(const struct RURI_CONTAINER *_Nonnull container)
 {
diff --git a/src/signal.c b/src/signal.c
index a449eca..6e074d2 100644
--- a/src/signal.c
+++ b/src/signal.c
@@ -28,6 +28,11 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file is used to catch segfault,
+ * So that we can show some extra info when segfault.
+ * I hope my program will never panic() QwQ.
+ */
 // Show some extra info when segfault.
 static void panic(int sig)
 {
diff --git a/src/umount.c b/src/umount.c
index 203cfc5..adda1bb 100644
--- a/src/umount.c
+++ b/src/umount.c
@@ -28,6 +28,10 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides function to umount the container.
+ * All pids detected in the container will be killed at the same time.
+ */
 // Umount container.
 void ruri_umount_container(const char *_Nonnull container_dir)
 {
diff --git a/src/unshare.c b/src/unshare.c
index e5bbfc8..3646c04 100644
--- a/src/unshare.c
+++ b/src/unshare.c
@@ -28,6 +28,11 @@
  *
  */
 #include "include/ruri.h"
+/*
+ * This file provides unshare container support for ruri.
+ * The design is: unshare(2) or setns(2), then fork(2),
+ * Then, we can just call ruri_run_container(), the next step have the same logic.
+ */
 // For ruri_run_unshare_container().
 static pid_t init_unshare_container(struct RURI_CONTAINER *_Nonnull container)
 {