Add man pages

Makefile.am

@@ -5,14 +5,14 @@ SUBDIRS = lib mountd adduser addshare control
 EXTRA_DIST = include \
              README.md \
              ksmbd-tools.spec \
-             smb.conf.5ksmbd.in \
+             ksmbd.conf.5.in \
              ksmbdpwd.db.5.in \
              ksmbd.service.in
 
 pkgsysconfdir = $(sysconfdir)/ksmbd
-dist_pkgsysconf_DATA = smb.conf.example
+dist_pkgsysconf_DATA = ksmbd.conf.example
 
-man_MANS = smb.conf.5ksmbd ksmbdpwd.db.5
+man_MANS = ksmbd.conf.5 ksmbdpwd.db.5
 systemdsystemunit_DATA = ksmbd.service
 $(man_MANS) $(systemdsystemunit_DATA): %: %.in; @$(in_script) $< >$@
 

README.md

@@ -11,8 +11,8 @@ merged to mainline in the Linux 5.15 release.
 ## Table of Contents
 
 - [Building and Installing](#building-and-installing)
-- [Example Usage](#example-usage)
-- [Prebuilt binaries](#prebuilt-binaries)
+- [Usage](#usage)
+- [Packages](#packages)
 
 ## Building and Installing
 
@@ -22,11 +22,12 @@ Otherwise, follow these instructions to build it yourself. Either the GNU
 Autotools or Meson build system can be used.
 
 Dependencies for Debian and its derivatives: `git` `gcc` `pkgconf` `autoconf`  
-`automake` `libtool` `meson` `gawk` `libnl-3-dev` `libnl-genl-3-dev`  
-`libglib2.0-dev`
+`automake` `libtool` `make` `meson` `ninja-build` `gawk` `libnl-3-dev`  
+`libnl-genl-3-dev` `libglib2.0-dev`
 
-Dependencies for RHEL, its derivatives, and openSUSE: `git` `gcc` `pkgconf`  
-`autoconf` `automake` `libtool` `meson` `gawk` `libnl3-devel` `glib2-devel`
+Dependencies for RHEL and its derivatives: `git` `gcc` `pkgconf` `autoconf`  
+`automake` `libtool` `make` `meson` `ninja-build` `gawk` `libnl3-devel`  
+`glib2-devel`
 
 Example build and install:
 ```sh
@@ -77,57 +78,69 @@ directory yourself by giving `--with-systemdsystemunitdir=DIR` or
 `-Dsystemdsystemunitdir=DIR` as an option to either `configure` or `meson`,  
 respectively.
 
-## Example Usage
+## Usage
 
+Manual pages:
 ```sh
-# if you built and installed ksmbd-tools yourself, by default,
+man 1 ksmbd.addshare
+man 1 ksmbd.adduser
+man 1 ksmbd.control
+man 1 ksmbd.mountd
+man 5 ksmbd.conf
+man 5 ksmbdpwd.db
+```
+
+Example session:
+```sh
+# If you built and installed ksmbd-tools yourself using autoconf defaults,
 # the utilities are in `/usr/local/sbin',
 # the default user database is `/usr/local/etc/ksmbd/ksmbdpwd.db', and
-# the default config file is `/usr/local/etc/ksmbd/smb.conf'
+# the default configuration file is `/usr/local/etc/ksmbd/ksmbd.conf'.
 
-# otherwise it is likely that,
+# Otherwise it is likely that,
 # the utilities are in `/usr/sbin',
 # the default user database is `/etc/ksmbd/ksmbdpwd.db', and
-# the default config file is `/etc/ksmbd/smb.conf'
+# the default configuration file is `/etc/ksmbd/ksmbd.conf'.
 
-# create the share path directory
-# the share stores files in this directory using its underlying filesystem
+# Create the share path directory.
+# The share stores files in this directory using its underlying filesystem.
 mkdir -vp $HOME/MyShare
 
-# add a share (case insensitive) to the default config file
-# `--options' takes a single argument, so quote it accordingly in your shell
-# note that the shell expands `$HOME' here, `ksmbd.addshare' will never do it
-# newline is the only safe character to use as an option separator
+# Add a share to the default configuration file.
+# Initial share parameters for the share are given with `--options'.
+# `--options' takes a single argument, so quote it accordingly in your shell.
+# Note that `ksmbd.addshare' does not do variable expansion.
+# Newline is the only safe character to use as separator for share parameters.
 sudo ksmbd.addshare --add-share=MyShare --options="
 path = $HOME/MyShare
 read only = no
 "
 
-# the default config file now looks like this:
+# The default configuration file now has a new section for `MyShare'.
 #
 # [myshare]
 #         path = /home/tester/MyShare
 #         read only = no
 #
-# the `[global]' section contains parameters that are not share specific
-# you can set default parameters for all shares by adding them to `[global]'
-# `ksmbd.addshare' cannot edit `[global]' so do it with a text editor
-# see smb.conf(5ksmbd) for more details
+# Each share has its own section with share parameters that apply to it.
+# A share parameter given in `[global]' changes its default value.
+# `[global]' also has global parameters which are not share specific.
+# `ksmbd.addshare' will not change `[global]' so do it with a text editor.
 
-# add a user to the default user database
-# you will be prompted for a password
+# Add a user to the default user database.
+# You will be prompted for a password.
 sudo ksmbd.adduser --add-user=MyUser
 
-# there is no UNIX user called `MyUser' so it has to be mapped to one
-# we can force all users accessing the share to map to a UNIX user and group
+# There is no system user called `MyUser' so it has to be mapped to one.
+# We can force all users accessing the share to map to a system user and group.
 
-# update the parameters of a share in the default config file
+# Update share parameters of a share in the default configuration file.
 sudo ksmbd.addshare --update-share=MyShare --options="
 force user = $USER
 force group = $USER
 "
 
-# the default config file now looks like this:
+# The default configuration file now has the updated share parameters.
 #
 # [myshare]
 #         force user = tester
@@ -136,47 +149,52 @@ force group = $USER
 #         read only = no
 #
 
-# add the kernel module
+# Add the kernel module.
 sudo modprobe ksmbd
 
-# run the user mode and kernel mode daemons
-# all interfaces are listened to by default
+# Start the user and kernel mode daemons.
+# All interfaces are listened to by default.
 sudo ksmbd.mountd
 
-# mount the new share with cifs-utils and authenticate as the new user
-# you will be prompted for a password
+# Mount the new share with cifs-utils and authenticate as the new user.
+# You will be prompted for the password given previously with `ksmbd.adduser'.
 sudo mount -o user=MyUser //127.0.0.1/MyShare /mnt
 
-# you can now access the share at `/mnt'
+# You can now access the share at `/mnt'.
 sudo touch /mnt/new_file_from_cifs_utils
 
-# unmount the share
+# Unmount the share.
 sudo umount /mnt
 
-# update the password of a user in the default user database
-# `--password' can be used to give the password instead of prompting
+# Update the password of a user in the default user database.
+# `--password' can be used to give the password instead of prompting.
 sudo ksmbd.adduser --update-user=MyUser --password=MyNewPassword
 
-# delete a user from the default user database
+# Delete a user from the default user database.
 sudo ksmbd.adduser --del-user=MyUser
 
-# the utilities notify ksmbd.mountd of changes by sending it the SIGHUP signal
-# you can do this manually as well when you have e.g. edited the config file
+# The utilities notify ksmbd.mountd of changes by sending it the SIGHUP signal.
+# This can be done manually when changes are made without using the utilities.
 sudo ksmbd.control --reload
 
-# toggle ksmbd debug printing of the `all' component
-sudo ksmbd.control --debug=all
+# Toggle ksmbd debug printing of the `smb' component.
+sudo ksmbd.control --debug=smb
 
-# some config file changes require restarting the user and kernel mode daemons
-# restarting them means running `ksmbd.mountd' again after shutting them down
+# Some changes require restarting the user and kernel mode daemons.
+# Modifying any global parameter is one example of such a change.
+# Restarting means starting `ksmbd.mountd' after shutting the daemons down.
 
-# shutdown the user and kernel mode daemons
+# Shutdown the user and kernel mode daemons.
 sudo ksmbd.control --shutdown
 
-# remove the kernel module
+# Remove the kernel module.
 sudo modprobe -r ksmbd
 ```
 
-## Prebuilt binaries
+## Packages
+
+The following packaging status tracker is provided by
+[the Repology project](https://repology.org)
+.
 
-You can find them at https://repology.org/project/ksmbd-tools/versions
+[![Packaging status](https://repology.org/badge/vertical-allrepos/ksmbd-tools.svg)](https://repology.org/project/ksmbd-tools/versions)

addshare/addshare.c

@@ -24,15 +24,6 @@
 #include "share_admin.h"
 #include "version.h"
 
-static char *arg_name;
-static char *arg_opts;
-
-enum {
-	COMMAND_ADD_SHARE = 1,
-	COMMAND_DEL_SHARE,
-	COMMAND_UPDATE_SHARE,
-};
-
 static void usage(int status)
 {
 	g_printerr(
@@ -46,24 +37,24 @@ static void usage(int status)
 		g_printerr(
 			"\n"
 			"  -a, --add-share=SHARE       add SHARE to configuration file;\n"
-			"                              SHARE is 1 to " STR(KSMBD_REQ_MAX_SHARE_NAME) " ASCII characters;\n"
+			"                              SHARE is [1, " STR(KSMBD_REQ_MAX_SHARE_NAME) ") ASCII characters;\n"
 			"                              SHARE cannot be `global';\n"
 			"                              initial parameters must be given with `--options'\n"
 			"  -d, --del-share=SHARE       delete SHARE from configuration file\n"
 			"  -u, --update-share=SHARE    update SHARE in configuration file;\n"
 			"                              updated parameters must be given with `--options'\n"
-			"  -o, --options=OPTIONS       use OPTIONS as share parameters;\n"
-			"                              OPTIONS is one argument and has format\n"
-			"                              `1st nam = 1st val<newline>2nd nam = 2nd val...';\n"
+			"  -o, --options=OPTIONS       use OPTIONS as parameters;\n"
+			"                              OPTIONS is one argument and follows format\n"
+			"                              `1st par = 1st val<newline>2nd par = 2nd val...';\n"
 			"                              separators other than newline create ambiguity;\n"
-			"                              global section parameters cannot be given\n"
+			"                              global parameters cannot be given\n"
 			"  -c, --config=SMBCONF        use SMBCONF as configuration file instead of\n"
 			"                              `" PATH_SMBCONF "'\n"
 			"  -v, --verbose               be verbose\n"
 			"  -V, --version               output version information and exit\n"
 			"  -h, --help                  display this help and exit\n"
 			"\n"
-			"See ksmbd.addshare(1) and smb.conf(5ksmbd) for more details.\n");
+			"See ksmbd.addshare(1) for more details.\n");
 }
 
 static const struct option opts[] = {
@@ -90,13 +81,13 @@ static int parse_configs(char *smbconf)
 
 	ret = test_file_access(smbconf);
 	if (ret) {
-		pr_err("Unable to access configuration file\n");
+		pr_err("Failed to access configuration file\n");
 		return ret;
 	}
 
 	ret = cp_smbconfig_hash_create(smbconf);
 	if (ret)
-		pr_err("Unable to parse configuration file\n");
+		pr_err("Failed to parse configuration file\n");
 	return ret;
 }
 
@@ -122,30 +113,36 @@ static int sanity_check_share_name_simple(char *name)
 int main(int argc, char *argv[])
 {
 	int ret = -EINVAL;
-	char *smbconf = PATH_SMBCONF;
-	int c, cmd = 0;
+	char *share = NULL, *options = NULL, *smbconf = NULL;
+	command_fn command = NULL;
+	int c;
 
 	set_logger_app_name("ksmbd.addshare");
 
 	while ((c = getopt_long(argc, argv, "a:d:u:o:c:vVh", opts, NULL)) != EOF)
 		switch (c) {
 		case 'a':
-			arg_name = g_ascii_strdown(optarg, strlen(optarg));
-			cmd = COMMAND_ADD_SHARE;
+			g_free(share);
+			share = g_ascii_strdown(optarg, strlen(optarg));
+			command = command_add_share;
 			break;
 		case 'd':
-			arg_name = g_ascii_strdown(optarg, strlen(optarg));
-			cmd = COMMAND_DEL_SHARE;
+			g_free(share);
+			share = g_ascii_strdown(optarg, strlen(optarg));
+			command = command_del_share;
 			break;
 		case 'u':
-			arg_name = g_ascii_strdown(optarg, strlen(optarg));
-			cmd = COMMAND_UPDATE_SHARE;
+			g_free(share);
+			share = g_ascii_strdown(optarg, strlen(optarg));
+			command = command_update_share;
 			break;
 		case 'o':
-			arg_opts = strdup(optarg);
+			g_free(options);
+			options = g_strdup(optarg);
 			break;
 		case 'c':
-			smbconf = strdup(optarg);
+			g_free(smbconf);
+			smbconf = g_strdup(optarg);
 			break;
 		case 'v':
 			set_log_level(PR_DEBUG);
@@ -167,39 +164,47 @@ int main(int argc, char *argv[])
 		goto out;
 	}
 
-	if (!arg_name) {
+	if (!share) {
 		pr_err("No option with share name given\n");
 		goto out;
 	}
 
-	if (cmd != COMMAND_DEL_SHARE && !arg_opts) {
-		pr_err("No share parameters given\n");
+	if ((command == command_add_share || command == command_update_share) &&
+	    !options) {
+		pr_err("No parameters given\n");
 		goto out;
 	}
 
-	if (sanity_check_share_name_simple(arg_name)) {
+	if (sanity_check_share_name_simple(share)) {
 		pr_err("Share name sanity check failure\n");
 		goto out;
 	}
 
 	if (!smbconf) {
-		pr_err("Out of memory\n");
-		goto out;
+		smbconf = g_strdup(PATH_SMBCONF);
+		if (!smbconf) {
+			pr_err("Out of memory\n");
+			goto out;
+		}
+		if (!g_file_test(smbconf, G_FILE_TEST_EXISTS) &&
+		    g_file_test(PATH_SMBCONF_FALLBACK, G_FILE_TEST_EXISTS)) {
+			pr_err("Use of `%s' is deprecated, rename it to `%s' now!\n",
+					PATH_SMBCONF_FALLBACK, PATH_SMBCONF);
+			g_free(smbconf);
+			smbconf = g_strdup(PATH_SMBCONF_FALLBACK);
+		}
 	}
 
 	ret = parse_configs(smbconf);
 	if (ret)
 		goto out;
 
-	if (cmd == COMMAND_ADD_SHARE)
-		ret = command_add_share(smbconf, arg_name, arg_opts);
-	if (cmd == COMMAND_DEL_SHARE)
-		ret = command_del_share(smbconf, arg_name);
-	if (cmd == COMMAND_UPDATE_SHARE)
-		ret = command_update_share(smbconf, arg_name, arg_opts);
+	if (command) {
+		ret = command(smbconf, share, options);
+		if (!ret && send_signal_to_ksmbd_mountd(SIGHUP))
+			pr_debug("Unable to notify ksmbd.mountd of changes\n");
+	}
 
-	if (cmd && !ret && send_signal_to_ksmbd_mountd(SIGHUP))
-		pr_debug("Unable to notify ksmbd.mountd of changes\n");
 out:
 	cp_smbconfig_destroy();
 	return ret ? EXIT_FAILURE : EXIT_SUCCESS;