#253 Samba quick doc (Issue #165)
Merged 3 years ago by pbokoc. Opened 3 years ago by couchfox.
fedora-docs/ couchfox/quick-docs 165-samba-quick-doc  into  master

file modified
+1
@@ -56,6 +56,7 @@ 

  ** xref:using-aide.adoc[Checking file integrity with AIDE]

  ** xref:getting-started-with-apache-http-server.adoc[Getting started with Apache HTTP Server]

  ** xref:how-to-edit-iptables-rules.adoc[How to edit iptables rules]

+ ** xref:samba.adoc[How to create a Samba share]

  ** NVIDIA

  *** xref:bumblebee.adoc[NVIDIA Optimus Bumblebee]

  *** xref:how-to-set-nvidia-as-primary-gpu-on-optimus-based-laptops.adoc[How to Set NVIDIA as Primary GPU on Optimus-based Laptops]

@@ -0,0 +1,287 @@ 

+ [[how_to_create_a_samba_share]]

+ = How to create a Samba share

+ :toc:

+ 

+ Samba allows for Windows and other clients to connect to file share directories on Linux hosts. It implements the server message block (SMB) protocol. This guide covers creating a shared file location on a Fedora machine that can be accessed by other computers on the local network.

+ 

+ [[install_and_enable_samba]]

+ == Install and enable Samba

+ 

+ The following commands install Samba and set it to run via `systemctl`.

+ This also sets the firewall to allow access to Samba from other

+ computers.

+ 

+ ....

+ sudo dnf install samba

+ sudo systemctl enable smb --now

+ firewall-cmd --get-active-zones

+ sudo firewall-cmd --permanent --zone=FedoraWorkstation --add-service=samba

+ sudo firewall-cmd --reload

+ ....

+ 

+ [[sharing_a_directory_inside_home]]

+ == Sharing a directory inside /home

+ 

+ In this example you will share a directory inside your home directory, accessible only by your user.

+ 

+ Samba does not use the operating system users for authentication, so your user account must be duplicated in Samba. So if your account is

+ `jane` on the host, the user `jane` must also be added to Samba. While the usernames must match, the passwords can be different.

+ 

+ Create a user called `jane` in Samba:

+ ....

+ sudo smbpasswd -a jane

+ ....

+ 

+ Create a directory to be the share for jane, and set the correct SELinux

+ context:

+ ....

+ mkdir /home/jane/share

+ sudo semanage fcontext --add --type "samba_share_t" ~/share

+ sudo restorecon -R ~/share

+ ....

+ 

+ Samba configuration lives in the `/etc/samba/smb.conf` file. Adding the following section at the end of the file will instruct Samba to set up a share for jane called "share" at the `/home/jane/share` directory just created.

+ ....

+ [share]

+         comment = My Share

+         path = /home/jane/share

+         writeable = yes

+         browseable = yes

+         public = yes

+         create mask = 0644

+         directory mask = 0755

+         write list = user

+ ....

+ 

+ Restart Samba for the changes to take effect:

+ 

+ ....

+ sudo systemctl restart smb

+ ....

+ 

+ [[sharing_a_directory_for_many_users]]

+ == Sharing a directory for many users

+ 

+ In this example, you will share a directory (outside your home directory) and create a group of users with the ability to read and write to the share.

+ 

+ Remember that a Samba user must also be a system user, in order to

+ respect filesystem permissions. This example creates a system group

+ `myfamily` for two new users `jack` and `maria`.

+ ....

+ sudo groupadd myfamily

+ sudo useradd  -G myfamily jack

+ sudo useradd  -G myfamily maria

+ ....

+ 

+ [TIP]

+ ====

+ You could create these users without a system password. This would prevent access to the system via SSH or local login.

+ ====

+ 

+ Add `jack` and `maria` to Samba and create their passwords:

+ 

+ ....

+ sudo smbpasswd -a jack

+ sudo smbpasswd -a maria

+ ....

+ 

+ Setting up the shared folder:

+ ....

+ sudo mkdir /home/share

+ sudo chgrp myfamily /home/share

+ sudo chmod 770 /home/share

+ sudo semanage fcontext --add --type "samba_share_t" /home/share

+ sudo restorecon -R /home/share

+ ....

+ 

+ Each share is described by its own section in the `/etc/samba/smb.conf`

+ file. Add this section to the bottom of the file:

+ ....

+ [family]

+         comment = Family Share

+         path = /home/share

+         writeable = yes

+         browseable = yes

+         public = yes

+         valid users = @myfamily

+         create mask = 0660

+         directory mask = 0770

+         force group = +myfamily

+ ....

+ 

+ Explanation of the above:

+ 

+ * `valid users`: only users of the group `family` have access rights. The @

+ denotes a group name.

+ * `force group = +myfamily`: files and directories are created with this

+ group, instead of the user group.

+ * `create mask = 0660`: files in the share are created with permissions to

+ allow all group users to read and write files created by other users.

+ * `directory mask = 0770`: as before, but for directories.

+ 

+ Restart Samba for the changes to take effect:

+ 

+ ....

+ sudo systemctl restart smb

+ ....

+ 

+ [[managing_samba_users]]

+ == Managing Samba Users

+ 

+ [[change_a_samba_user_password]]

+ === Change a samba user password

+ 

+ [TIP] 

+ ====

+ Remember: the system user and Samba user passwords can be different. The system user is needed in order to handle filesystem permissions.

+ ====

+ 

+ ....

+ sudo smbpasswd maria

+ ....

+ 

+ [[remove_a_samba_user]]

+ === Remove a samba user

+ 

+ ....

+ sudo smbpasswd -x maria

+ ....

+ 

+ If you don't need the system user, remove it as well:

+ 

+ ....

+ sudo userdel -r maria

+ ....

+ 

+ [[troubleshooting_and_logs]]

+ == Troubleshooting and logs

+ 

+ Samba log files are located in `/var/log/samba/`

+ 

+ ....

+ tail -f /var/log/samba/log.smbd

+ ....

+ 

+ You can increase the verbosity by adding this to the `[global]` section of

+ `/etc/samba/smb.conf`:

+ 

+ ....

+ [global]

+         loglevel = 5

+ ....

+ 

+ To validate the syntax of the configuration file `/etc/samba/smb.conf`

+ use the command `testparm`. Example output:

+ 

+ ....

+ Load smb config files from /etc/samba/smb.conf

+ Loaded services file OK.

+ Server role: ROLE_STANDALONE

+ ....

+ 

+ To display current samba connections, use the `smbstatus` command.

+ Example output:

+ 

+ ....

+ Samba version 4.12.3

+ PID     Username     Group        Machine                                   Protocol Version  Encryption           Signing              

+ ----------------------------------------------------------------------------------------------------------------------------------------

+ 7259    jack         jack         192.168.122.1 (ipv4:192.168.122.1:40148)  SMB3_11           -                    partial(AES-128-CMAC)

+ 

+ Service      pid     Machine       Connected at                     Encryption   Signing     

+ ---------------------------------------------------------------------------------------------

+ family       7259    192.168.122.1 Fri May 29 14:03:26 2020 AEST    -            -           

+ 

+ No locked files

+ ....

+ 

+ [[trouble_with_accessing_the_share]]

+ === Trouble with accessing the share

+ 

+ Some things to check if you cannot access the share.

+ 

+ . Be sure that the user exists as a system user as well as a

+ Samba user

+ +

+ Find `maria` in the Samba database:

+ +

+ ....

+ sudo pdbedit -L | grep maria

+ 

+ maria:1002:

+ ....

+ +

+ Confirm that `maria` also exists as a system user.

+ +

+ ....

+ cat /etc/passwd | grep maria

+ 

+ maria:x:1002:1002::/home/maria:/bin/bash

+ ....

+ +

+ . Check if the shared directory has the correct SELinux context.

+ +

+ ....

+ ls -dZ /home/share

+ 

+ unconfined_u:object_r:samba_share_t:s0 /home/share

+ ....

+ +

+ . Check if the system user has access permission to the shared directory.

+ +

+ ....

+ ls -ld /home/share 

+ 

+ drwxrwx---. 2 root myfamily 4096 May 29 14:03 /home/share

+ ....

+ +

+ In this case, the user should be in the `myfamily` group.

+ 

+ . Check in the configuration file `/etc/samba/smb.conf` that the

+ user and group have access permission.

+ +

+ ....

+ [family]

+         comment = Family Share

+         path = /home/share

+         writeable = yes

+         browseable = yes

+         public = yes

+         valid users = @myfamily

+         create mask = 0660

+         directory mask = 0770

+         force group = +myfamily

+ ....

+ +

+ In this case, the user should be in the `myfamily` group.

+ 

+ [[trouble_with_writing_in_the_share]]

+ === Trouble with writing in the share

+ 

+ . Check in the samba configuration file if the user/group has

+ write permissions.

+ +

+ ....

+ [family]

+         comment = Family Share

+         path = /home/share

+         writeable = yes

+         browseable = yes

+         public = yes

+         valid users = @myfamily

+         create mask = 0660

+         directory mask = 0770

+         force group = +myfamily

+ ....

+ +

+ In this example, the user should be in the `myfamily` group.

+ 

+ . Check the share directory permissions.

+ +

+ ....

+ ls -ld /home/share 

+ 

+ drwxrwx---. 2 root myfamily 4096 May 29 14:03 /home/share

+ ....

+ +

+ This example assumes the user is part of the `myfamily` group which has read, write, and execute permissions for the folder. 

\ No newline at end of file

rebased onto c2495a256d825e2528d32b87115768b91beabdfb

3 years ago

Metadata Update from @pbokoc:
- Request assigned

3 years ago

The whole doc is fairly long, so it could use a table of contents. You can have Antora autogenerate one from headings if you add :toc: on the line below this heading, followed by an empty line.

Let's write this as "under your /home" for clarity

Usernames should be marked up the same way you did filenames a bit later, i.e. `jane`, so they stand out from normal text better. The same also applies to `myfamily`, `jack\, and\maria`\ in the next section.

This should be marked up as a [TIP] so it stands out better.

I generally advise people to avoid the word "right" in docs because it has another meaning and it can be confusing to people with less than stellar English skills - and "correct" is much less ambiguous and has the same meaning with this context. The same applies to the couple instances of "rights" below, that's better expressed as "permissions".

Each item in a numbered list should start with just a . - that waay it Antora will generate the list item number automatically, and if someone edits the list later to add another item, they won't need to renumber everything afterwards.
If you have multiple paragraphs (commands, etc.) that you want to group into a single list item, use + on every newline separating them. Like this:

. list item 1
+
still list item 1

. list item 2

After you want to end the first item, just use an empty line without the +.

@couchfox Alright, I think that's all I have for feedback. Thank you for your work so far!

Metadata Update from @ankursinha:
- Pull-request tagged with: needs changes

3 years ago

1 new commit added

  • Incorporates feedback from @pbokoc
3 years ago

2 new commits added

  • fixed bullet format
  • changes 'right' to 'correct' or 'permission'
3 years ago

rebased onto 2bfaa426b046c7a33dc3f66bbc7b4838af6114ad

3 years ago

@couchfox Thanks for the changes! I have more requests though :)

I recently started asking people to remove the # and $ prompts from commands - they're no longer useful, we used to include them to indicate whether you need to be root for a particular command or not, but since Fedora has been enabling sudo by default for several releases now, it's no longer useful. Can you please remove them?

Also, in sections "Install and enable Samba" and "Sharing a directory inside /home", you have two blocks with multiple commands, and there are newlines between some of them but not others. Can you please remove the newlines so each block follows the same formatting?

1 new commit added

  • Remove `$` and `#` from commands
3 years ago

1 new commit added

  • Remove inconsistent line breaks in commands per @pbokoc feedback
3 years ago

Thanks for the feedback - updates done.

rebased onto 9fa1db0

3 years ago

Pull-Request has been merged by pbokoc

3 years ago

Metadata Update from @pbokoc:
- Pull-request untagged with: needs changes

3 years ago