[PATCH] ksmbd-tools: update README

[PATCH] ksmbd-tools: update README

[Enzo Matsumiya]

Prettify README with markdown and fix some typos/commands.

Signed-off-by: Enzo Matsumiya <ematsumiya@suse.de>
---
 README    | 98 -------------------------------------------------------
 README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 98 deletions(-)
 delete mode 100644 README
 create mode 100644 README.md

diff --git a/README b/README
deleted file mode 100644
index 3dce3bb41c6e..000000000000
--- a/README
+++ /dev/null
@@ -1,98 +0,0 @@
-________________________
-BUILDING KSMBD TOOLS
-________________________
-
-Install preprequisite packages:
-	For Ubuntu:
-	sudo apt-get install autoconf libtool pkg-config libnl-3-dev \
-	libnl-genl-3-dev libglib2.0-dev
-
-	For Fedora, RHEL:
-	sudo yum install autoconf automake libtool glib2-devel libnl3-devel
-
-	For CentOS:
-	sudo yum install glib2-devel libnl3-devel
-
-Build steps:
-        - cd into the ksmbd-tools directory
-        - ./autogen.sh
-        - ./configure
-        - make
-        - make install
-
-_____________________
-USING KSMBD TOOLS
-_____________________
-
-Setup steps:
-	- install smbd kernel driver
-		modprobe ksmbd
-	- create user/password for SMB share
-		mkdir /etc/ksmbd/
-		ksmbd.adduser -a <Enter USERNAME for SMB share access>
-		Enter password for SMB share access
-	- create /etc/ksmbd/smb.conf file, add SMB share in smb.conf file
-		Refer smb.conf.example
-	- start smbd user space daemon
-		ksmbd.mountd
-	- access share from Windows or Linux using CIFS
-
-_____________________
-RESTART KSMBD
-_____________________
-
-steps:
-	- kill user and kernel space daemon
-		sudo ksmbd.control -s
-	- restart user space daemon
-		ksmbd.mountd
-
-_____________________
-Shutdown KSMBD
-_____________________
-
-steps:
-	- kill user and kernel space daemon
-		sudo ksmbd.control -s
-	- unload ksmbd module
-		rmmod ksmbd
-
-
-_____________________
-Enable debug prints
-_____________________
-
-steps:
-	- Enable all component prints
-		sudo ksmbd.control -d "all"
-	- Enable one of components(smb, auth, vfs, oplock, ipc, conn, rdma)
-		sudo ksmbd.control -d "smb"
-	- Disable prints:
-		If you try the selected component once more, It is disabled without brackets.
-
-
---------------------
-ADMIN TOOLS
---------------------
-
-- ksmbd.adduser
-	Adds, updates or removes (-a/-u/-d) a user from ksmbd pwd file.
-
-- ksmbd.addshare
-	Adds, updates or removes (-a/-u/-d) a net share from smb.conf file.
-
-Usage example:
-
-Creating a new share:
-
-ksmbd.addshare -a files -o "\
-		     path=/home/users/files \
-		     comment=exported files \
-		     writeable=yes \
-		     read only = no \
-		     "
-
-Note that share options (-o) must always be enquoted ("...").
-
-ksmbd.addshare tool does not modify [global] smb.conf section; only net
-share configs are supported at the moment.
diff --git a/README.md b/README.md
new file mode 100644
index 000000000000..b6e4915dc6ff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+# ksmbd-tools
+
+### Building
+
+##### Install prerequisite packages:
+
+- For Ubuntu:
+  - `sudo apt-get install autoconf libtool pkg-config libnl-3-dev libnl-genl-3-dev libglib2.0-dev`
+
+- For Fedora, RHEL:
+  - `sudo yum install autoconf automake libtool glib2-devel libnl3-devel`
+
+- For CentOS:
+  - `sudo yum install glib2-devel libnl3-devel`
+
+- For openSUSE:
+  - `sudo zypper install glib2-devel libnl3-devel`
+
+##### Building:
+
+- clone this repository
+- `cd ksmbd-tools`
+- `./autogen.sh`
+- `./configure`
+- `make`
+- `make install`
+
+
+### Usage
+
+All administration tasks must be done as root.
+
+##### Setup:
+
+- Install ksmbd kernel driver
+	- `modprobe ksmbd`
+- Create user/password for SMB share
+	- `mkdir /etc/ksmbd`
+	- `ksmbd.adduser -a <username>`
+	- Enter password for SMB share access
+- Create `/etc/ksmbd/smb.conf` file
+	- Refer `smb.conf.example`
+- Add share to `smb.conf`
+	- This can be done manually or with `ksmbd.addshare`, e.g.:
+	- `ksmbd.addshare -a myshare -o "guest ok = yes, writable = yes, path = /mnt/data"`
+
+	- Note: share options (-o) must always be enclosed with double quotes ("...").
+- Start ksmbd user space daemon
+	- `ksmbd.mountd`
+- Access share from Windows or Linux using CIFS
+
+
+##### Stopping and restarting the daemon:
+
+- Kill user and kernel space daemon
+  - `ksmbd.control -s`
+- To restart user space daemon
+  - `ksmbd.mountd`
+- To shut it down
+  - `rmmod ksmbd`
+
+
+### Debugging
+
+- Enable all component prints
+  - `ksmbd.control -d "all"`
+- Enable a single component (see below)
+  - `ksmbd.control -d "smb"`
+- Run the command with the same component name again to disable it
+		
+Currently available debug components:
+smb, auth, vfs, oplock, ipc, conn, rdma
+
+
+### More...
+
+- ksmbd.adduser
+  - Adds (-a), updates (-u), or deletes (-d) a user from user database.
+  - Default database file is `/etc/ksmbd/users.db`
+
+- ksmbd.addshare
+  - Adds (-a), updates (-u), or deletes (-d) a net share from config file.
+  - Default config file is `/etc/ksmbd/smb.conf`
+
+`ksmbd.addshare` does not modify `[global]` section in config file; only net
+share configs are supported at the moment.
-- 
2.33.0

Re: [PATCH] ksmbd-tools: update README

[Namjae Jeon]

Hi Enzo,
2021-10-07 1:14 GMT+09:00, Enzo Matsumiya <ematsumiya@suse.de>:
> Prettify README with markdown and fix some typos/commands.
>
> Signed-off-by: Enzo Matsumiya <ematsumiya@suse.de>
> ---
>  README    | 98 -------------------------------------------------------
>  README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 86 insertions(+), 98 deletions(-)
>  delete mode 100644 README
>  create mode 100644 README.md
>
> diff --git a/README b/README
> deleted file mode 100644
> index 3dce3bb41c6e..000000000000
> --- a/README
> +++ /dev/null
> @@ -1,98 +0,0 @@
> -________________________
> -BUILDING KSMBD TOOLS
> -________________________
> -
> -Install preprequisite packages:
> -	For Ubuntu:
> -	sudo apt-get install autoconf libtool pkg-config libnl-3-dev \
> -	libnl-genl-3-dev libglib2.0-dev
> -
> -	For Fedora, RHEL:
> -	sudo yum install autoconf automake libtool glib2-devel libnl3-devel
> -
> -	For CentOS:
> -	sudo yum install glib2-devel libnl3-devel
> -
> -Build steps:
> -        - cd into the ksmbd-tools directory
> -        - ./autogen.sh
> -        - ./configure
> -        - make
> -        - make install
> -
> -_____________________
> -USING KSMBD TOOLS
> -_____________________
> -
> -Setup steps:
> -	- install smbd kernel driver
> -		modprobe ksmbd
> -	- create user/password for SMB share
> -		mkdir /etc/ksmbd/
> -		ksmbd.adduser -a <Enter USERNAME for SMB share access>
> -		Enter password for SMB share access
> -	- create /etc/ksmbd/smb.conf file, add SMB share in smb.conf file
> -		Refer smb.conf.example
> -	- start smbd user space daemon
> -		ksmbd.mountd
> -	- access share from Windows or Linux using CIFS
> -
> -_____________________
> -RESTART KSMBD
> -_____________________
> -
> -steps:
> -	- kill user and kernel space daemon
> -		sudo ksmbd.control -s
> -	- restart user space daemon
> -		ksmbd.mountd
> -
> -_____________________
> -Shutdown KSMBD
> -_____________________
> -
> -steps:
> -	- kill user and kernel space daemon
> -		sudo ksmbd.control -s
> -	- unload ksmbd module
> -		rmmod ksmbd
> -
> -
> -_____________________
> -Enable debug prints
> -_____________________
> -
> -steps:
> -	- Enable all component prints
> -		sudo ksmbd.control -d "all"
> -	- Enable one of components(smb, auth, vfs, oplock, ipc, conn, rdma)
> -		sudo ksmbd.control -d "smb"
> -	- Disable prints:
> -		If you try the selected component once more, It is disabled without
> brackets.
> -
> -
> ---------------------
> -ADMIN TOOLS
> ---------------------
> -
> -- ksmbd.adduser
> -	Adds, updates or removes (-a/-u/-d) a user from ksmbd pwd file.
> -
> -- ksmbd.addshare
> -	Adds, updates or removes (-a/-u/-d) a net share from smb.conf file.
> -
> -Usage example:
> -
> -Creating a new share:
> -
> -ksmbd.addshare -a files -o "\
> -		     path=/home/users/files \
> -		     comment=exported files \
> -		     writeable=yes \
> -		     read only = no \
> -		     "
> -
> -Note that share options (-o) must always be enquoted ("...").
> -
> -ksmbd.addshare tool does not modify [global] smb.conf section; only net
> -share configs are supported at the moment.
> diff --git a/README.md b/README.md
> new file mode 100644
> index 000000000000..b6e4915dc6ff
> --- /dev/null
> +++ b/README.md
> @@ -0,0 +1,86 @@
> +# ksmbd-tools
> +
> +### Building
> +
> +##### Install prerequisite packages:
> +
> +- For Ubuntu:
> +  - `sudo apt-get install autoconf libtool pkg-config libnl-3-dev
> libnl-genl-3-dev libglib2.0-dev`
> +
> +- For Fedora, RHEL:
> +  - `sudo yum install autoconf automake libtool glib2-devel libnl3-devel`
> +
> +- For CentOS:
> +  - `sudo yum install glib2-devel libnl3-devel`
> +
> +- For openSUSE:
> +  - `sudo zypper install glib2-devel libnl3-devel`
> +
> +##### Building:
> +
> +- clone this repository
> +- `cd ksmbd-tools`
> +- `./autogen.sh`
> +- `./configure`
> +- `make`
> +- `make install`
> +
> +
> +### Usage
> +
> +All administration tasks must be done as root.
> +
> +##### Setup:
> +
> +- Install ksmbd kernel driver
> +	- `modprobe ksmbd`
> +- Create user/password for SMB share
> +	- `mkdir /etc/ksmbd`
> +	- `ksmbd.adduser -a <username>`
> +	- Enter password for SMB share access
> +- Create `/etc/ksmbd/smb.conf` file
> +	- Refer `smb.conf.example`
> +- Add share to `smb.conf`
> +	- This can be done manually or with `ksmbd.addshare`, e.g.:
> +	- `ksmbd.addshare -a myshare -o "guest ok = yes, writable = yes, path =
> /mnt/data"`
> +
> +	- Note: share options (-o) must always be enclosed with double quotes
> ("...").
> +- Start ksmbd user space daemon
> +	- `ksmbd.mountd`
> +- Access share from Windows or Linux using CIFS
> +
> +
> +##### Stopping and restarting the daemon:
> +
> +- Kill user and kernel space daemon
> +  - `ksmbd.control -s`
> +- To restart user space daemon
> +  - `ksmbd.mountd`
> +- To shut it down
> +  - `rmmod ksmbd`
It is unclear to me. ksmbd.mountd is still alive.
If session is still opening, We need to call "ksmbd.control -s" first
to kill server(both ksmbd.mountd and ksmbd kernel thread).

> +
> +
> +### Debugging
> +
> +- Enable all component prints
> +  - `ksmbd.control -d "all"`
> +- Enable a single component (see below)
> +  - `ksmbd.control -d "smb"`
> +- Run the command with the same component name again to disable it
> +		
ERROR: trailing whitespace
#263: FILE: README.md:70:
+^I^I$

Thanks!
> +Currently available debug components:
> +smb, auth, vfs, oplock, ipc, conn, rdma
> +
> +
> +### More...
> +
> +- ksmbd.adduser
> +  - Adds (-a), updates (-u), or deletes (-d) a user from user database.
> +  - Default database file is `/etc/ksmbd/users.db`
> +
> +- ksmbd.addshare
> +  - Adds (-a), updates (-u), or deletes (-d) a net share from config file.
> +  - Default config file is `/etc/ksmbd/smb.conf`
> +
> +`ksmbd.addshare` does not modify `[global]` section in config file; only
> net
> +share configs are supported at the moment.
> --
> 2.33.0
>
>

Re: [PATCH] ksmbd-tools: update README

[Enzo Matsumiya]

On 10/08, Namjae Jeon wrote:
>> +##### Stopping and restarting the daemon:
>> +
>> +- Kill user and kernel space daemon
>> +  - `ksmbd.control -s`
>> +- To restart user space daemon
>> +  - `ksmbd.mountd`
>> +- To shut it down
>> +  - `rmmod ksmbd`
>It is unclear to me. ksmbd.mountd is still alive.
>If session is still opening, We need to call "ksmbd.control -s" first
>to kill server(both ksmbd.mountd and ksmbd kernel thread).

Hm I don't understand your concern actually. What is said is that to
both restart and shutdown the server, you need to run "ksmbd.control -s"
before.

Then, to restart you run "ksmbd.mountd" again. To shut it down, run
"rmmod ksmbd".

I'll try coming up with better wording.

>> +		
>ERROR: trailing whitespace
>#263: FILE: README.md:70:
>+^I^I$

Thanks, will fix!


Cheers,

Enzo