diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 8383218..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,29 +0,0 @@ -build: - stage: build - image: - name: antora/antora:latest - script: - - antora --log-failure-level fatal site.yml - artifacts: - paths: - - public/ - expire_in: 1 week - expose_as: 'docs preview' - rules: - - if: $CI_PIPELINE_SOURCE == 'merge_request_event' - environment: - name: preview MR_${CI_MERGE_REQUEST_IID} - url: https://${CI_SERVER_HOST}/${CI_PROJECT_PATH}/-/jobs/${CI_JOB_ID}/artifacts/file/public/index.html - auto_stop_in: 1 week -pages: - stage: build - image: - name: antora/antora:latest - script: - - antora site.yml - artifacts: - paths: - - public - rules: - - if: $CI_COMMIT_BRANCH == "main" && $CI_PROJECT_ROOT_NAMESPACE == "fedora" - diff --git a/LICENSE b/LICENSE index 4d4542d..ba8d521 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license -(“CC-BY-SA”). An explanation of CC-BY-SA is available at +("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. diff --git a/README.md b/README.md index 672d653..d51ede2 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# Fedora System Administrator’s Guide +# Fedora System Administrator Guide Please report Issues and submit Pull Requests for **Content Fixes** here. -Never done a pull request (or “PR”)? Here's the [Pagure documentation for +Never done a pull request (or "PR")? Here's the [Pagure documentation for Pull Requests](https://docs.pagure.org/pagure/usage/pull_requests.html). diff --git a/antora.yml b/antora.yml index d70d031..e17d26f 100644 --- a/antora.yml +++ b/antora.yml @@ -1,5 +1,5 @@ --- name: fedora -version: rawhide +version: f30 # Navigation is in the main 'fedora' component: # https://pagure.io/fedora-docs/release-docs-home diff --git a/build.sh b/build.sh index 96c2b69..91dd641 100755 --- a/build.sh +++ b/build.sh @@ -14,7 +14,6 @@ if uname | grep -iwq darwin; then elif uname | grep -iq linux; then # Running on Linux. - # there isn't an antora/aarch64 container, antora can be installed locally # Check whether podman is available, else faill back to docker # which requires root. diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-01.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-01.png new file mode 100644 index 0000000..214673d Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-01.png differ diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-02.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-02.png new file mode 100644 index 0000000..2c6b837 Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-02.png differ diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-03.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-03.png new file mode 100644 index 0000000..bcebeee Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-03.png differ diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-04.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-04.png new file mode 100644 index 0000000..67cfbda Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-04.png differ diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-05.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-05.png new file mode 100644 index 0000000..fff1bfa Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-05.png differ diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-06.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-06.png new file mode 100644 index 0000000..13d27ee Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-06.png differ diff --git a/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-07.png b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-07.png new file mode 100644 index 0000000..4b454ba Binary files /dev/null and b/modules/system-administrators-guide/assets/images/apache-mod_ssl-genkey-07.png differ diff --git a/modules/system-administrators-guide/assets/images/title_logo.svg b/modules/system-administrators-guide/assets/images/title_logo.svg index 8dd65ac..e8fd52b 100644 --- a/modules/system-administrators-guide/assets/images/title_logo.svg +++ b/modules/system-administrators-guide/assets/images/title_logo.svg @@ -1,53 +1,61 @@ + + - - - - image/svg+xml - - - - - + version="1.0" + width="220" + height="70" + id="svg6180"> + id="defs6182" /> + + + + + + + + + + + + + d="m 181.98344,61.675273 2.81558,0 0,0.37898 -1.18152,0 0,2.94935 -0.45254,0 0,-2.94935 -1.18152,0 0,-0.37898 m 3.26144,0 0.67101,0 0.84937,2.26496 0.85381,-2.26496 0.67102,0 0,3.32833 -0.43917,0 0,-2.9226 -0.85828,2.28279 -0.45255,0 -0.85827,-2.28279 0,2.9226 -0.43694,0 0,-3.32833" + id="path2391" + style="fill:#294172;enable-background:new" /> diff --git a/modules/system-administrators-guide/nav.adoc b/modules/system-administrators-guide/nav.adoc index 8affdd3..c5f6e9c 100644 --- a/modules/system-administrators-guide/nav.adoc +++ b/modules/system-administrators-guide/nav.adoc @@ -1,4 +1,4 @@ -* xref:index.adoc[System Administrator's Guide] +* xref:index.adoc[System Administration Guide] ** xref:Preface.adoc[Preface] ** Basic System Configuration *** xref:basic-system-configuration/intro-basic-system-configuration.adoc[Introduction] @@ -23,6 +23,7 @@ *** xref:servers/Directory_Servers.adoc[Directory Servers] *** xref:servers/File_and_Print_Servers.adoc[File and Print Servers] *** xref:servers/Configuring_NTP_Using_the_chrony_Suite.adoc[Configuring NTP Using the chrony Suite] +*** xref:servers/Configuring_NTP_Using_ntpd.adoc[Configuring NTP Using ntpd] *** xref:servers/Configuring_PTP_Using_ptp4l.adoc[Configuring PTP Using ptp4l] ** Monitoring and Automation *** xref:monitoring-and-automation/intro-monitoring-and-automation.adoc[Introduction] @@ -37,5 +38,4 @@ *** xref:kernel-module-driver-configuration/Working_with_Kernel_Modules.adoc[Working with Kernel Modules] ** xref:RPM.adoc[RPM] ** xref:Wayland.adoc[The Wayland Display Server] -** xref:pam_userdb.adoc[pam_userdb] ** xref:Revision_History.adoc[Revision History] diff --git a/modules/system-administrators-guide/pages/Preface.adoc b/modules/system-administrators-guide/pages/Preface.adoc index 2329e82..4e4a454 100644 --- a/modules/system-administrators-guide/pages/Preface.adoc +++ b/modules/system-administrators-guide/pages/Preface.adoc @@ -83,7 +83,7 @@ xref:monitoring-and-automation/OProfile.adoc[OProfile] covers [application]*OPro xref:kernel-module-driver-configuration/intro-kernel-module-driver-configuration.adoc[Kernel, Module and Driver Configuration]:: This part covers various tools that assist administrators with kernel customization. + -xref:kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc[Working with the GRUB 2 Boot Loader] describes the GNU GRand Unified Boot loader (GRUB) version 2 boot loader, which enables selecting an operating system or kernel to be loaded at system boot time. +xref:kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc[Working with the GRUB 2 Boot Loader] der>> describes the GNU GRand Unified Boot loader (GRUB) version 2 boot loader, which enables selecting an operating system or kernel to be loaded at system boot time. + xref:kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.adoc[Manually Upgrading the Kernel] provides important information on how to manually update a kernel package using the [command]#rpm# command instead of [command]#dnf#. Read this chapter if you cannot update a kernel package with the [application]*DNF* package manager. + @@ -93,8 +93,6 @@ xref:RPM.adoc[RPM]:: This appendix concentrates on the RPM Package Manager (RPM xref:Wayland.adoc[The Wayland Display Server]:: This appendix looks at Wayland, a new display server used in GNOME for {MAJOROS} and how to troubleshoot issues with the Wayland display server. -xref:pam_userdb.adoc[pam_userdb]:: This appendix looks at pam_userdb, providing instructions on how to update to the new database provider. - include::{partialsdir}/Feedback.adoc[] [[pref-Acknowledgments]] diff --git a/modules/system-administrators-guide/pages/RPM.adoc b/modules/system-administrators-guide/pages/RPM.adoc index 445c421..b602585 100644 --- a/modules/system-administrators-guide/pages/RPM.adoc +++ b/modules/system-administrators-guide/pages/RPM.adoc @@ -1,3 +1,4 @@ + :experimental: include::{partialsdir}/entities.adoc[] @@ -477,7 +478,7 @@ indexterm:[RPM,additional resources] indexterm:[RPM,website]indexterm:[RPM,online documentation] - * The [application]*RPM* website — link:++https://rpm.org++[] + * The [application]*RPM* website — link:++http://www.rpm.org/++[] * The [application]*RPM* mailing list — link:++http://lists.rpm.org/mailman/listinfo/rpm-list++[] diff --git a/modules/system-administrators-guide/pages/Revision_History.adoc b/modules/system-administrators-guide/pages/Revision_History.adoc index e17f573..5f37915 100644 --- a/modules/system-administrators-guide/pages/Revision_History.adoc +++ b/modules/system-administrators-guide/pages/Revision_History.adoc @@ -38,7 +38,7 @@ Note that revision numbers relate to the edition of this manual, not to version `1-4.1`:: Tue Oct 27 2015, Stephen Wadeley (swadeley@redhat.com) -* Added "`Gaining Privileges`" chapter, "`Using OpenSSH Certificate Authentication`" section, and made improvements to the GRUB 2 chapter. +* Added "Gaining Privileges" chapter, "Using OpenSSH Certificate Authentication" section, and made improvements to the GRUB 2 chapter. `1-4`:: Mon May 25 2015, Stephen Wadeley (swadeley@redhat.com) @@ -50,7 +50,7 @@ Note that revision numbers relate to the edition of this manual, not to version `1-2.1`:: Wed Mar 4 2015, Stephen Wadeley (swadeley@redhat.com) -* Added "`Working with the GRUB 2 Boot Loader`" chapter. +* Added "Working with the GRUB 2 Boot Loader" chapter. `1-2`:: Tue Dec 9 2014, Stephen Wadeley (swadeley@redhat.com) diff --git a/modules/system-administrators-guide/pages/Wayland.adoc b/modules/system-administrators-guide/pages/Wayland.adoc index 3ba89b9..7da2c73 100644 --- a/modules/system-administrators-guide/pages/Wayland.adoc +++ b/modules/system-administrators-guide/pages/Wayland.adoc @@ -3,13 +3,13 @@ include::{partialsdir}/entities.adoc[] [[ch-Wayland]] -= The Wayland Protocol - -Wayland is a display server protocol which was (at the time of writing) introduced as the default in GNOME. It is said that Wayland will eventually replace X11 as the default display server on Linux and many distributions have begun implementation of Wayland. Wayland is a more modern protocol and has a smaller code base currently. Wayland is still under development, and there are still applications and behaviours that don't work as expected, you may find that some applications have not been updated to work properly in Wayland and currently the only way these applications will run is using Xorg instead of Wayland. This includes some legacy system applications and games. += The Wayland Display Server +Wayland is a display server which was (at the time of writing) introduced as the default display server in GNOME. It is said that Wayland will eventually replace X11 as the default display server on Linux and many distributions have begun implementation of Wayland. Wayland is a more modern display server and has a smaller code base currently. Wayland is still under development, and there are still applications and behaviours that don't work as expected, you may find that some applications have not been updated to work properly in Wayland and currently the only way these applications will run is using Xorg instead of Wayland. This includes some legacy system applications and games. +.Wayland in Fedora Wayland is enabled by default in the GNOME Desktop. You can choose to run GNOME in X11 by choosing the Gnome on xorg option in the session chooser on the login screen. Currently KDE still uses X11 and although there is a plasma-wayland session available, it is not considered stable or bugfree at this time. -== Determining whether you are using Wayland +.Determining whether you are using Wayland One way to determine if you're running in Wayland, is to check the value of the variable $WAYLAND_DISPLAY. To do this type: [source,bash] @@ -34,9 +34,9 @@ There is also a legacy X11 server provided with Wayland for compatibility purpos $ xlsclients ---- -There is also the `lg` (looking glass) tool in GNOME that will allow you to determine which protocol a specific window is using. To do this, you run the application by typing `lg` in the run dialog or at the command line, select "`Windows`" in the upper right corner of the tool, and click on the application name (or open window) you want to know about. If the window is running in wayland it will say "`MetaWindowWayland`" and if it is running in X11 it will say "`MetaWindowX11`". +There is also the `lg` (looking glass) tool in GNOME that will allow you to determine what display server a window is using. To do this, you run the application by typing `lg` in the run dialog or at the command line, select "`Windows`" in the upper right corner of the tool, and click on the application name (or open window) you want to know about. If the window is running in wayland it will say "`MetaWindowWayland`" and if it is running in X11 it will say "`MetaWindowX11`". -== Additional Resources +.Additional Resources To find out more about Wayland, please see the following website: https://wayland.freedesktop.org/ diff --git a/modules/system-administrators-guide/pages/_partials/Legal_Notice.adoc b/modules/system-administrators-guide/pages/_partials/Legal_Notice.adoc index cd7b9ce..5027815 100644 --- a/modules/system-administrators-guide/pages/_partials/Legal_Notice.adoc +++ b/modules/system-administrators-guide/pages/_partials/Legal_Notice.adoc @@ -3,7 +3,7 @@ Copyright {YEAR} {HOLDER}. -The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license (“CC-BY-SA”). An explanation of CC-BY-SA is available at link:++https://creativecommons.org/licenses/by-sa/3.0/++[]. The original authors of this document, and Red Hat, designate the Fedora Project as the “`Attribution Party`” for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. +The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at link:++https://creativecommons.org/licenses/by-sa/3.0/++[]. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. diff --git a/modules/system-administrators-guide/pages/_partials/entities.adoc b/modules/system-administrators-guide/pages/_partials/entities.adoc index baba3b1..9b5902d 100644 --- a/modules/system-administrators-guide/pages/_partials/entities.adoc +++ b/modules/system-administrators-guide/pages/_partials/entities.adoc @@ -1,10 +1,10 @@ :BOOKID: system-administrators-guide -:BZURL: link:https://pagure.io/fedora-docs/system-administrators-guide/issues[https://pagure.io/] +:BZURL: link:https://pagure.io/fedora-docs/install-guide/issues[https://pagure.io/] :HOLDER: Red Hat, Inc. and others :MAJOROS: Fedora -:MAJOROSVER: Fedora Rawhide +:MAJOROSVER: Fedora 30 :OSORG: The Fedora Project -:PKGOS: fc35 +:PKGOS: fc30 :PRODUCT: Fedora Documentation -:PRODVER: Rawhide -:YEAR: 2021 +:PRODVER: 30 +:YEAR: 2019 diff --git a/modules/system-administrators-guide/pages/_partials/servers/FTP.adoc b/modules/system-administrators-guide/pages/_partials/servers/FTP.adoc index eb107d5..522c8c5 100644 --- a/modules/system-administrators-guide/pages/_partials/servers/FTP.adoc +++ b/modules/system-administrators-guide/pages/_partials/servers/FTP.adoc @@ -327,7 +327,7 @@ The default value is [command]#ftp#. + There is no default value for this directive. -* [command]#local_umask# — Specifies the umask value for file creation. Note that the default value is in octal form (a numerical system with a base of eight), which includes a "`0`" prefix. Otherwise the value is treated as a base-10 integer. +* [command]#local_umask# — Specifies the umask value for file creation. Note that the default value is in octal form (a numerical system with a base of eight), which includes a "0" prefix. Otherwise the value is treated as a base-10 integer. + The default value is [command]#022#. diff --git a/modules/system-administrators-guide/pages/_partials/servers/OpenLDAP.adoc b/modules/system-administrators-guide/pages/_partials/servers/OpenLDAP.adoc index 56981e2..ae994ba 100644 --- a/modules/system-administrators-guide/pages/_partials/servers/OpenLDAP.adoc +++ b/modules/system-administrators-guide/pages/_partials/servers/OpenLDAP.adoc @@ -2,7 +2,7 @@ [[s1-OpenLDAP]] == OpenLDAP indexterm:[directory server,OpenLDAP]indexterm:[LDAP,OpenLDAP]indexterm:[X.500,OpenLDAP]indexterm:[X.500 Lite,OpenLDAP] -`LDAP` (Lightweight Directory Access Protocol) is a set of open protocols used to access centrally stored information over a network. It is based on the `X.500` standard for directory sharing, but is less complex and resource-intensive. For this reason, LDAP is sometimes referred to as "`X.500 Lite`". +`LDAP` (Lightweight Directory Access Protocol) is a set of open protocols used to access centrally stored information over a network. It is based on the `X.500` standard for directory sharing, but is less complex and resource-intensive. For this reason, LDAP is sometimes referred to as "X.500 Lite". Like X.500, LDAP organizes information in a hierarchical manner using directories. These directories can store a variety of information such as names, addresses, or phone numbers, and can even be used in a manner similar to the _Network Information Service_ (*NIS*), enabling anyone to access their account from any machine on the LDAP enabled network. diff --git a/modules/system-administrators-guide/pages/_partials/servers/Printer_Configuration.adoc b/modules/system-administrators-guide/pages/_partials/servers/Printer_Configuration.adoc index bfcf3b7..86d806d 100644 --- a/modules/system-administrators-guide/pages/_partials/servers/Printer_Configuration.adoc +++ b/modules/system-administrators-guide/pages/_partials/servers/Printer_Configuration.adoc @@ -349,7 +349,7 @@ Alternatively, to start the graphical firewall configuration tool using the comm The `Firewall Configuration` window opens. -Look for the word "`Connected`" in the lower left corner. This indicates that the [application]*firewall-config* tool is connected to the user space daemon, `firewalld`. +Look for the word "Connected" in the lower left corner. This indicates that the [application]*firewall-config* tool is connected to the user space daemon, `firewalld`. To immediately change the current firewall settings, ensure the drop-down selection menu labeled `Configuration` is set to `Runtime`. Alternatively, to edit the settings to be applied at the next system start, or firewall reload, select `Permanent` from the drop-down list. diff --git a/modules/system-administrators-guide/pages/_partials/servers/Samba.adoc b/modules/system-administrators-guide/pages/_partials/servers/Samba.adoc index a0cc493..8e0dbd2 100644 --- a/modules/system-administrators-guide/pages/_partials/servers/Samba.adoc +++ b/modules/system-administrators-guide/pages/_partials/servers/Samba.adoc @@ -1,8 +1,1192 @@ [[sect-Samba]] == Samba +indexterm:[Samba,Reference]indexterm:[Samba,Samba] +[application]*Samba* is the standard open source Windows interoperability suite of programs for Linux. It implements the _server message block_ (`SMB`) protocol. Modern versions of this protocol are also known as the _common Internet file system_ (`CIFS`) protocol. It allows the networking of Microsoft *Windows*, Linux, UNIX, and other operating systems together, enabling access to Windows-based file and printer shares. Samba's use of `SMB` allows it to appear as a Windows server to Windows clients. +.Installing the samba package +[NOTE] +==== + +In order to use [application]*Samba*, first ensure the [package]*samba* package is installed on your system by running, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}dnf install samba +---- + +For more information on installing packages with DNF, see xref:package-management/DNF.adoc#sec-Installing[Installing Packages]. + +==== + +[[sect-Samba-Introduction_to_Samba]] +=== Introduction to Samba +indexterm:[Samba,Introduction] +Samba is an important component to seamlessly integrate Linux Servers and Desktops into Active Directory (AD) environments. It can function both as a domain controller (NT4-style) or as a regular domain member (AD or NT4-style). +indexterm:[Samba,Abilities] +.What Samba can do: + +* Serve directory trees and printers to Linux, UNIX, and Windows clients + +* Assist in network browsing (with NetBIOS) + +* Authenticate Windows domain logins + +* Provide _Windows Internet Name Service_ (`WINS`) name server resolution + +* Act as a Windows *NT*-style _Primary Domain Controller_ (PDC) + +* Act as a _Backup Domain Controller_ (BDC) for a Samba-based PDC + +* Act as an Active Directory domain member server + +* Join a Windows NT/2000/2003/2008 PDC/Windows Server 2012 + +.What Samba cannot do: + +* Act as a BDC for a Windows PDC (and vice versa) + +* Act as an Active Directory domain controller + +[[sect-Samba_Daemons_and_Related_Services]] +=== Samba Daemons and Related Services +indexterm:[Samba,daemon,overview] +Samba is comprised of three daemons (`smbd`, `nmbd`, and `winbindd`). Three services (`smb`, `nmb`, and `winbind`) control how the daemons are started, stopped, and other service-related features. These services act as different init scripts. Each daemon is listed in detail below, as well as which specific service has control over it. + +.smbdindexterm:[Samba,daemon,smbd] +The `smbd` server daemon provides file sharing and printing services to Windows clients. In addition, it is responsible for user authentication, resource locking, and data sharing through the `SMB` protocol. The default ports on which the server listens for `SMB` traffic are `TCP` ports 139 and 445. + +The `smbd` daemon is controlled by the `smb` service. + +.nmbdindexterm:[Samba,daemon,nmbd] +The `nmbd` server daemon understands and replies to NetBIOS name service requests such as those produced by SMB/CIFS in Windows-based systems. These systems include Windows 95/98/ME, Windows NT, Windows 2000, Windows XP, and LanManager clients. It also participates in the browsing protocols that make up the Windows `Network Neighborhood` view. The default port that the server listens to for `NMB` traffic is `UDP` port `137`. + +The `nmbd` daemon is controlled by the `nmb` service. + +.winbinddindexterm:[Samba,daemon,winbindd] +The `winbind` service resolves user and group information received from a server running Windows NT, 2000, 2003, Windows Server 2008, or Windows Server 2012. This makes Windows user and group information understandable by UNIX platforms. This is achieved by using Microsoft RPC calls, _Pluggable Authentication Modules_ (PAM), and the _Name Service Switch_ (NSS). This allows Windows NT domain and Active Directory users to appear and operate as UNIX users on a UNIX machine. Though bundled with the Samba distribution, the `winbind` service is controlled separately from the `smb` service. + +The `winbind` daemon is controlled by the `winbind` service and does not require the `smb` service to be started in order to operate. `winbind` is also used when Samba is an Active Directory member, and may also be used on a Samba domain controller (to implement nested groups and interdomain trust). Because `winbind` is a client-side service used to connect to Windows NT-based servers, further discussion of `winbind` is beyond the scope of this chapter. + +.Obtaining a list of utilities that are shipped with Samba +[NOTE] +==== + +See xref:File_and_Print_Servers.adoc#sect-Samba_Distribution_Programs[Samba Distribution Programs] for a list of utilities included in the Samba distribution. + +==== + +[[sect-Samba-Connecting_to_a_Samba_Share]] +=== Connecting to a Samba Share +indexterm:[Samba,share,connecting to with Nautilus] +You can use either [application]*Nautilus* or command line to connect to available Samba shares. + +[[proc-Samba-Connecting_to_a_Samba_Share_GUI]] +.Connecting to a Samba Share Using Nautilus +. To view a list of Samba workgroups and domains on your network, select menu:Places[ > `Network`pass:attributes[{blank}]] from the GNOME panel, and then select the desired network. Alternatively, type `smb:` in the menu:File[ > `Open Location`pass:attributes[{blank}]] bar of [application]*Nautilus*. ++ +An icon appears for each available `SMB` workgroup or domain on the network. ++ +[[fig-samba-nautilus-workgroups]] +.SMB Workgroups in Nautilus ++ +image::samba-nautilus-domain.png[SMB Workgroups in Nautilus] + +. Double-click one of the workgroup or domain icon to view a list of computers within the workgroup or domain. + +. An icon exists for each machine within the workgroup. Double-click on an icon to view the Samba shares on the machine. If a user name and password combination is required, you are prompted for them. ++ +Alternately, you can also specify the Samba server and sharename in the `Location:` bar for [application]*Nautilus* using the following syntax (replace _servername_ and _sharename_ with the appropriate values): ++ +[subs="quotes, macros"] +---- +[command]#smb://pass:attributes[{blank}]_servername_pass:attributes[{blank}]/pass:attributes[{blank}]_sharename_pass:attributes[{blank}]# +---- + +indexterm:[Samba,share,connecting to via the command line]indexterm:[Samba,smbclient]indexterm:[smbclient] + +[[proc-Samba-Connecting_to_a_Samba_Share_CLI]] +.Connecting to a Samba Share Using the Command Line +. To connect to a Samba share from a shell prompt, type the following command: ++ +[subs="quotes, macros"] +---- +[command]#~]$ smbclient //pass:attributes[{blank}]_hostname_pass:attributes[{blank}]/pass:attributes[{blank}]_sharename_ -U _username_pass:attributes[{blank}]# +---- ++ +Replace _hostname_ with the host name or `IP` address of the Samba server you want to connect to, _sharename_ with the name of the shared directory you want to browse, and _username_ with the Samba user name for the system. Enter the correct password or press kbd:[Enter] if no password is required for the user. ++ +If you see the `smb:\>` prompt, you have successfully logged in. Once you are logged in, type `help` for a list of commands. If you want to browse the contents of your home directory, replace _sharename_ with your user name. If the [command]#-U# switch is not used, the user name of the current user is passed to the Samba server. + +. To exit [command]#smbclient#, type `exit` at the `smb:\>` prompt. + +[[sect-Mounting_the_Samba_Share]] +=== Mounting the Share +indexterm:[Samba,share,mounting] +Sometimes it is useful to mount a Samba share to a directory so that the files in the directory can be treated as if they are part of the local file system. + +To mount a Samba share to a directory, create a directory to mount it to (if it does not already exist), and execute the following command as `root`: + +[subs="quotes, macros"] +---- +[command]#mount -t cifs //pass:attributes[{blank}]_servername_pass:attributes[{blank}]/pass:attributes[{blank}]_sharename_ _/mnt/point/_ -o username=pass:attributes[{blank}]_username_,password=pass:attributes[{blank}]_password_pass:attributes[{blank}]# +---- + +This command mounts _sharename_ from _servername_ in the local directory _/mnt/point/_. + +For more information about mounting a samba share, see the *mount.cifs*(8) manual page. + +.Installing cifs-utils package +[NOTE] +==== + +The [application]*mount.cifs* utility is a separate RPM (independent from Samba). In order to use [application]*mount.cifs*, first ensure the [package]*cifs-utils* package is installed on your system by running, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}dnf install cifs-utils +---- + +For more information on installing packages with DNF, see xref:package-management/DNF.adoc#sec-Installing[Installing Packages]. + +Note that the [package]*cifs-utils* package also contains the [application]*cifs.upcall* binary called by the kernel in order to perform kerberized CIFS mounts. For more information on [application]*cifs.upcall*, see the *cifs.upcall*(8) manual page. + +==== + +.CIFS servers that require plain text passwords +[WARNING] +==== + +Some CIFS servers require plain text passwords for authentication. Support for plain text password authentication can be enabled using the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}echo 0x37 > /proc/fs/cifs/SecurityFlags +---- + +WARNING: This operation can expose passwords by removing password encryption. + +==== + +[[sect-Samba-Configuring_a_Samba_Server]] +=== Configuring a Samba Server +indexterm:[Samba,configuration]indexterm:[Samba,configuration,default] +The default configuration file (`/etc/samba/smb.conf`) allows users to view their home directories as a Samba share. It also shares all printers configured for the system as Samba shared printers. You can attach a printer to the system and print to it from the Windows machines on your network. + +[[sect-Samba-GUI_Configuration]] +==== Graphical Configuration +indexterm:[Samba,graphical configuration] +To configure Samba using a graphical interface, use one of the available Samba graphical user interfaces. A list of available GUIs can be found at link:++https://www.samba.org/samba/GUI/++[https://www.samba.org/samba/GUI/]. + +[[sect-Samba-Command-Line-Configuration]] +==== Command-Line Configuration +indexterm:[Samba,configuration] +Samba uses `/etc/samba/smb.conf` as its configuration file. If you change this configuration file, the changes do not take effect until you restart the Samba daemon with the following command, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl restart smb.service +---- + +To specify the Windows workgroup and a brief description of the Samba server, edit the following lines in your `/etc/samba/smb.conf` file: + +[subs="quotes, macros"] +---- + +workgroup = _WORKGROUPNAME_ +server string = _BRIEF COMMENT ABOUT SERVER_ +---- + +Replace _WORKGROUPNAME_ with the name of the Windows workgroup to which this machine should belong. The _BRIEF COMMENT ABOUT SERVER_ is optional and is used as the Windows comment about the Samba system. + +To create a Samba share directory on your Linux system, add the following section to your `/etc/samba/smb.conf` file (after modifying it to reflect your needs and your system): + +[[exam-Samba-Configuring_Samba_Server]] +.An Example Configuration of a Samba Server +==== + +[subs="quotes, macros"] +---- + +[pass:attributes[{blank}]_sharename_pass:attributes[{blank}]] +comment = _Insert a comment here_ +path = _/home/share/_ +valid users = _tfox carole_ +writable = yes +create mask = 0765 +---- + +==== + +The above example allows the users [command]#tfox# and [command]#carole# to read and write to the directory `/home/share/`, on the Samba server, from a Samba client. + +[[sect-Samba-Encrypted_Passwords]] +==== Encrypted Passwords + +Encrypted passwords are enabled by default because it is more secure to use them. To create a user with an encrypted password, use the `smbpasswd` utility: + +[subs="quotes, macros"] +---- +[command]#smbpasswd -a _username_pass:attributes[{blank}]# +---- +indexterm:[Samba,with Windows NT 4.0, 2000, ME, and XP]indexterm:[Windows NT 4.0,connecting to shares using Samba]indexterm:[Windows 98,connecting to shares using Samba]indexterm:[Windows 2000,connecting to shares using Samba]indexterm:[Windows ME,connecting to shares using Samba]indexterm:[Windows XP,connecting to shares using Samba]indexterm:[Samba,encrypted passwords] + +[[sect-Samba-Starting_and_Stopping]] +=== Starting and Stopping Samba +indexterm:[Samba,service,starting]indexterm:[Samba,service,stopping]indexterm:[Samba,service,restarting]indexterm:[Samba,service,conditional restarting]indexterm:[Samba,service,reloading] +To start a Samba server, type the following command in a shell prompt, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl start smb.service +---- + +.Setting up a domain member server [IMPORTANT] ==== -Documentation for configuring and using Samba has been removed due to being outdated. Use link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/configuring_and_using_network_file_services/index#assembly_using-samba-as-a-server_configuring-and-using-network-file-services[Red Hat Enterprise Linux 9 Samba documentation] instead. + +To set up a domain member server, you must first join the domain or Active Directory using the [command]#net join# command *before* starting the `smb` service. Also, it is recommended to run `winbind` before `smbd`. + ==== + +To stop the server, type the following command in a shell prompt, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl stop smb.service +---- + +The [option]`restart` option is a quick way of stopping and then starting Samba. This is the most reliable way to make configuration changes take effect after editing the configuration file for Samba. Note that the restart option starts the daemon even if it was not running originally. + +To restart the server, type the following command in a shell prompt, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl restart smb.service +---- + +The [option]`condrestart` (_conditional restart_) option only starts `smb` on the condition that it is currently running. This option is useful for scripts, because it does not start the daemon if it is not running. + +.Applying the changes to the configuration +[NOTE] +==== + +When the `/etc/samba/smb.conf` file is changed, Samba automatically reloads it after a few minutes. Issuing a manual [command]#restart# or [command]#reload# is just as effective. + +==== + +To conditionally restart the server, type the following command, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl try-restart smb.service +---- + +A manual reload of the `/etc/samba/smb.conf` file can be useful in case of a failed automatic reload by the `smb` service. To ensure that the Samba server configuration file is reloaded without restarting the service, type the following command, as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl reload smb.service +---- + +By default, the `smb` service does *not* start automatically at boot time. To configure Samba to start at boot time, type the following at a shell prompt as `root`: + +[subs="attributes"] +---- +~]#{nbsp}systemctl enable smb.service +---- + +See xref:infrastructure-services/Services_and_Daemons.adoc#ch-Services_and_Daemons[Services and Daemons] for more information regarding this tool. + +[[sect-Samba-Server_Types_and_the_smb.conf_File]] +=== Samba Server Types and the `smb.conf` File +indexterm:[Samba,smb.conf]indexterm:[Samba,Server Types] +Samba configuration is straightforward. All modifications to Samba are done in the `/etc/samba/smb.conf` configuration file. Although the default `smb.conf` file is well documented, it does not address complex topics such as LDAP, Active Directory, and the numerous domain controller implementations. + +The following sections describe the different ways a Samba server can be configured. Keep in mind your needs and the changes required to the `/etc/samba/smb.conf` file for a successful configuration. + +[[sect-Samba-Standalone_Server]] +==== Stand-alone Server +indexterm:[Samba,server types,Stand Alone] +A stand-alone server can be a workgroup server or a member of a workgroup environment. A stand-alone server is not a domain controller and does not participate in a domain in any way. The following examples include several user-level security configurations. For more information on security modes, see xref:File_and_Print_Servers.adoc#sect-Samba-Security_Modes[Samba Security Modes]. + +.Anonymous Read-Onlyindexterm:[Samba,smb.conf,Anonymous Read Only example] +The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement anonymous read-only file sharing. Two directives are used to configure anonymous access – `map to guest = Bad user` and `guest account = nobody`. + +[[exam-Samba-Standalone_Anonymous_Read-Only_Server]] +.An Example Configuration of a Anonymous Read-Only Samba Server +==== + +---- +[global] +workgroup = DOCS +netbios name = DOCS_SRV +security = user +guest account = nobody # default value +map to guest = Bad user + +[data] +comment = Documentation Samba Server +path = /export +read only = yes +guest ok = yes +---- + +==== + +.Anonymous Read/Writeindexterm:[Samba,smb.conf,Anonymous Read/Write example] +The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement anonymous read/write file sharing. To enable anonymous read/write file sharing, set the `read only` directive to `no`. The `force user` and `force group` directives are also added to enforce the ownership of any newly placed files specified in the share. + +.Do not use anonymous read/write servers +[NOTE] +==== + +Although having an anonymous read/write server is possible, it is not recommended. Any files placed in the share space, regardless of user, are assigned the user/group combination as specified by a generic user (`force user`) and group (`force group`) in the `/etc/samba/smb.conf` file. + +==== + +[[exam-Samba-Standalone_Anonymous_Read-Write-Server]] +.An Example Configuration of a Anonymous Read/Write Samba Server +==== + +---- + +[global] +workgroup = DOCS +security = user +guest account = nobody # default value +map to guest = Bad user + +[data] +comment = Data +path = /export +guest ok = yes +writeable = yes +force user = user +force group = group +---- + +==== + +.Anonymous Print Serverindexterm:[Samba,smb.conf,Anonymous Print Server example] +The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement an anonymous print server. Setting `browseable` to `no` as shown does not list the printer in Windows `Network Neighborhood`. Although hidden from browsing, configuring the printer explicitly is possible. By connecting to `DOCS_SRV` using NetBIOS, the client can have access to the printer if the client is also part of the `DOCS` workgroup. It is also assumed that the client has the correct local printer driver installed, as the `use client driver` directive is set to `yes`. In this case, the Samba server has no responsibility for sharing printer drivers to the client. + +[[exam-Samba-Standalone_Anonymous_Print-Server]] +.An Example Configuration of a Anonymous Print Samba Server +==== + +---- + +[global] +workgroup = DOCS +netbios name = DOCS_SRV +security = user +map to guest = Bad user +printing = cups + +[printers] +comment = All Printers +path = /var/spool/samba +guest ok = yes +printable = yes +use client driver = yes +browseable = yes +---- + +==== + +.Secure Read/Write File and Print Serverindexterm:[Samba,smb.conf,Secure File and Print Server example] +The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement a secure read/write file and print server. Setting the `security` directive to `user` forces Samba to authenticate client connections. Notice the `[homes]` share does not have a `force user` or `force group` directive as the `[public]` share does. The `[homes]` share uses the authenticated user details for any files created as opposed to the `force user` and `force group` in `[public]`. + +[[exam-Samba-Standalone_Secure_Read_Write_File_and_Print_Server]] +.An Example Configuration of a Secure Read/Write File and Print Samba Server +==== + +---- + +[global] +workgroup = DOCS +netbios name = DOCS_SRV +security = user +printcap name = cups +disable spools = yes +show add printer wizard = no +printing = cups + +[homes] +comment = Home Directories +valid users = %S +read only = no +browseable = no + +[public] +comment = Data +path = /export +force user = docsbot +force group = users +guest ok = yes + +[printers] +comment = All Printers +path = /var/spool/samba +printer admin = john, ed, @admins +create mask = 0600 +guest ok = yes +printable = yes +use client driver = yes +browseable = yes +---- + +==== + +[[sect-Samba-Domain_Member_Server]] +==== Domain Member Server +indexterm:[Samba,server types,Domain Member] +A domain member, while similar to a stand-alone server, is logged into a domain controller (either Windows or Samba) and is subject to the domain's security rules. An example of a domain member server would be a departmental server running Samba that has a machine account on the Primary Domain Controller (PDC). All of the department's clients still authenticate with the PDC, and desktop profiles and all network policy files are included. The difference is that the departmental server has the ability to control printer and network shares. + +.Active Directory Domain Member Serverindexterm:[Samba,smb.conf,Active Directory Member Server example] +To implement an Active Directory domain member server, follow procedure below: + +[[proc-Samba-Adding_an_AD_Member]] +.Adding a Member Server to an Active Directory Domain +. Create the `/etc/samba/smb.conf` configuration file on a member server to be added to the Active Directory domain. Add the following lines to the configuration file: ++ +---- + +[global] +realm = EXAMPLE.COM +security = ADS +encrypt passwords = yes +# Optional. Use only if Samba cannot determine the Kerberos server automatically. +password server = kerberos.example.com +---- ++ +With the above configuration, Samba authenticates users for services being run locally but is also a client of the Active Directory. Ensure that your kerberos `realm` parameter is shown in all caps (for example `realm = EXAMPLE.COM`). Since Windows 2000/2003/2008 requires Kerberos for Active Directory authentication, the `realm` directive is required. If Active Directory and Kerberos are running on different servers, the `password server` directive is required to help the distinction. + +. Configure Kerberos on the member server. Create the `/etc/krb5.conf` configuration file with the following content: ++ +---- + +[logging] + default = FILE:/var/log/krb5libs.log + +[libdefaults] + default_realm = AD.EXAMPLE.COM + dns_lookup_realm = true + dns_lookup_kdc = true + ticket_lifetime = 24h + renew_lifetime = 7d + rdns = false + forwardable = false + +[realms] +# Define only if DNS lookups are not working +# AD.EXAMPLE.COM = { +# kdc = server.ad.example.com +# admin_server = server.ad.example.com +# master_kdc = server.ad.example.com +# } + +[domain_realm] +# Define only if DNS lookups are not working +# .ad.example.com = AD.EXAMPLE.COM +# ad.example.com = AD.EXAMPLE.COM +---- ++ +Uncomment the `[realms]` and `[domain_realm]` sections if DNS lookups are not working. ++ +For more information on Kerberos, and the [command]#/etc/krb5.conf# file, see the [citetitle]_Using Kerberos_ section of the [citetitle]_link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/Using_Kerberos.html++[Red{nbsp}Hat{nbsp}Enterprise{nbsp}Linux{nbsp}7 System Level Authentication Guide]_. + +. To join an Active Directory server, type the following command as `root` on the member server: ++ +---- +~]# net ads join -U administrator%password +---- ++ +The [command]#net# command authenticates as `Administrator` using the NT LAN Manager (NTLM) protocol and creates the machine account. Then [command]#net# uses the machine account credentials to authenticate with Kerberos. ++ +.The security option +[NOTE] +==== + +Since `security = ads` and not `security = user` is used, a local password back end such as `smbpasswd` is not needed. Older clients that do not support `security = ads` are authenticated as if `security = domain` had been set. This change does not affect functionality and allows local users not previously in the domain. + +==== + +.Windows NT4-based Domain Member Serverindexterm:[Samba,smb.conf,NT4-style Domain Member example] +The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement a Windows NT4-based domain member server. Becoming a member server of an NT4-based domain is similar to connecting to an Active Directory. The main difference is NT4-based domains do not use Kerberos in their authentication method, making the `/etc/samba/smb.conf` file simpler. In this instance, the Samba member server functions as a pass through to the NT4-based domain server. + +[[exam-Samba-Domain_Member_Server-Windows_NT4-based_Domain_Memeber_Server]] +.An Example Configuration of Samba Windows NT4-based Domain Member Server +==== + +---- + +[global] +workgroup = DOCS +netbios name = DOCS_SRV +security = domain + +[homes] +comment = Home Directories +valid users = %S +read only = no +browseable = no + +[public] +comment = Data +path = /export +force user = docsbot +force group = users +guest ok = yes +---- + +==== + +Having Samba as a domain member server can be useful in many situations. There are times where the Samba server can have other uses besides file and printer sharing. It may be beneficial to make Samba a domain member server in instances where Linux-only applications are required for use in the domain environment. Administrators appreciate keeping track of all machines in the domain, even if not Windows-based. In the event the Windows-based server hardware is deprecated, it is quite easy to modify the `/etc/samba/smb.conf` file to convert the server to a Samba-based PDC. If Windows NT-based servers are upgraded to Windows 2000/2003/2008 the `/etc/samba/smb.conf` file is easily modifiable to incorporate the infrastructure change to Active Directory if needed. + +.Make sure you join the domain before starting Samba +[IMPORTANT] +==== + +After configuring the `/etc/samba/smb.conf` file, join the domain *before* starting Samba by typing the following command as `root`: + +---- +~]# net rpc join -U administrator%password +---- + +==== + +Note that the [option]`-S` option, which specifies the domain server host name, does not need to be stated in the [command]#net rpc join# command. Samba uses the host name specified by the `workgroup` directive in the `/etc/samba/smb.conf` file instead of it being stated explicitly. + +[[sect-Samba-Domain_Controller]] +==== Domain Controller +indexterm:[Samba,server types,Domain Controller] +A domain controller in Windows NT is functionally similar to a Network Information Service (NIS) server in a Linux environment. Domain controllers and NIS servers both host user and group information databases as well as related services. Domain controllers are mainly used for security, including the authentication of users accessing domain resources. The service that maintains the user and group database integrity is called the _Security Account Manager_ (SAM). The SAM database is stored differently between Windows and Linux Samba-based systems, therefore SAM replication cannot be achieved and platforms cannot be mixed in a PDC/BDC environment. + +In a Samba environment, there can be only one PDC and zero or more BDCs. + +.A mixed Samba/Windows domain controller environment +[IMPORTANT] +==== + +Samba cannot exist in a mixed Samba/Windows domain controller environment (Samba cannot be a BDC of a Windows PDC or vice versa). Alternatively, Samba PDCs and BDCs *can* coexist. + +==== + +.Primary Domain Controller (PDC) Using `tdbsam`pass:attributes[{blank}]indexterm:[Samba,smb.conf,PDC using tdbsam] +The simplest and most common implementation of a Samba PDC uses the new default `tdbsam` password database back end. Replacing the aging `smbpasswd` back end, `tdbsam` has numerous improvements that are explained in more detail in xref:File_and_Print_Servers.adoc#sect-Samba-Account_Information-Databases[Samba Account Information Databases]. The `passdb backend` directive controls which back end is to be used for the PDC. + +The following `/etc/samba/smb.conf` file shows a sample configuration needed to implement a `tdbsam` password database back end. + +[[exam-Samba_Domain_Controller-PDC_Using_tdbsam]] +.An Example Configuration of Primary Domain Controller (PDC) Using `tdbsam` +==== + +---- + +[global] +workgroup = DOCS +netbios name = DOCS_SRV +passdb backend = tdbsam +security = user +add user script = /usr/sbin/useradd -m "%u" +delete user script = /usr/sbin/userdel -r "%u" +add group script = /usr/sbin/groupadd "%g" +delete group script = /usr/sbin/groupdel "%g" +add user to group script = /usr/sbin/usermod -G "%g" "%u" +add machine script = /usr/sbin/useradd -s /bin/false -d /dev/null -g machines "%u" +# The following specifies the default logon script +# Per user logon scripts can be specified in the user +# account using pdbedit logon script = logon.bat +# This sets the default profile path. +# Set per user paths with pdbedit +logon drive = H: +domain logons = yes +os level = 35 +preferred master = yes +domain master = yes + +[homes] + comment = Home Directories + valid users = %S + read only = no + +[netlogon] + comment = Network Logon Service + path = /var/lib/samba/netlogon/scripts + browseable = no + read only = no +# For profiles to work, create a user directory under the +# path shown. +# mkdir -p /var/lib/samba/profiles/john + +[Profiles] + comment = Roaming Profile Share + path = /var/lib/samba/profiles + read only = no + browseable = no + guest ok = yes + profile acls = yes +# Other resource shares ... ... +---- + +==== + +To provide a functional PDC system which uses `tdbsam` follow these steps: + +[[proc-Samba_Domain_Controller-PDC_Using_tdbsam]] + +. Adjust the `smb.conf` configuration file as shown in xref:File_and_Print_Servers.adoc#exam-Samba_Domain_Controller-PDC_Using_tdbsam[An Example Configuration of Primary Domain Controller (PDC) Using `tdbsam`]. + +. Add the `root` user to the Samba password database. You will be prompted to provide a new Samba password for the `root` user: ++ +---- +~]# smbpasswd -a root +New SMB password: +---- + +. Start the `smb` service: ++ +---- +~]# service smb start +---- + +. Make sure all profile, user, and netlogon directories are created. + +. Add groups that users can be members of: ++ +---- +~]# groupadd -f users +~]# groupadd -f nobody +~]# groupadd -f ntadmins +---- + +. Associate the UNIX groups with their respective Windows groups. ++ +---- +~]# net groupmap add ntgroup="Domain Users" unixgroup=users +~]# net groupmap add ntgroup="Domain Guests" unixgroup=nobody +~]# net groupmap add ntgroup="Domain Admins" unixgroup=ntadmins +---- + +. Grant access rights to a user or a group. For example, to grant the right to add client machines to the domain on a Samba domain controller, to the members to the Domain Admins group, execute the following command: ++ +---- +~]# net rpc rights grant 'DOCS\Domain Admins' SetMachineAccountPrivilege -S PDC -U root +---- + +Keep in mind that Windows systems prefer to have a primary group which is mapped to a domain group such as Domain Users. + +Windows groups and users use the same namespace thus not allowing the existence of a group and a user with the same name like in UNIX. + +.Limitations of the tdbsam authentication back end +[NOTE] +==== + +If you need more than one domain controller or have more than 250 users, do *not* use the `tdbsam` authentication back end. LDAP is recommended in these cases. + +==== + +.Primary Domain Controller (PDC) with Active Directoryindexterm:[Samba,smb.conf,PDC using Active Directory] +Although it is possible for Samba to be a member of an Active Directory, it is not possible for Samba to operate as an Active Directory domain controller. + +[[sect-Samba-Security_Modes]] +=== Samba Security Modes +indexterm:[Samba,Security Modes] +There are only two types of security modes for Samba, _share-level_ and _user-level_, which are collectively known as *pass:attributes[{blank}]_security levels_pass:attributes[{blank}]*. Share-level security is deprecated and has been removed from Samba. Configurations containing this mode need to be migrated to use user-level security. User-level security can be implemented in one of three different ways. The different ways of implementing a security level are called _security modes_. + +[[sect-Samba_Security_Modes-User_Level]] +==== User-Level Security +indexterm:[Samba,Security Modes,User Level Security] +User-level security is the default and recommended setting for Samba. Even if the `security = user` directive is not listed in the `/etc/samba/smb.conf` file, it is used by Samba. If the server accepts the client's user name and password, the client can then mount multiple shares without specifying a password for each instance. Samba can also accept session-based user name and password requests. The client maintains multiple authentication contexts by using a unique UID for each logon. + +In the `/etc/samba/smb.conf` file, the `security = user` directive that sets user-level security is: + +[subs="quotes"] +---- + +[GLOBAL] +... +security = user +... +---- + +.Samba Guest Sharesindexterm:[Samba,Security Modes] +As mentioned above, share-level security mode is deprecated. To configure a Samba guest share without using the `security = share` parameter, follow the procedure below: + +[[proc-Samba_Security_Modes-Samba_Guest_Shares]] +.Configuring Samba Guest Shares +. Create a username map file, in this example `/etc/samba/smbusers`, and add the following line to it: ++ +[subs="quotes"] +---- +nobody = guest +---- + +. Add the following directives to the main section in the `/etc/samba/smb.conf` file. Also, do not use the `valid users` directive: ++ +[subs="quotes, macros"] +---- + +[GLOBAL] +... +security = user +map to guest = Bad User +username map = _/etc/samba/smbusers_ +... +---- ++ +The `username map` directive provides a path to the username map file specified in the previous step. + +. Add the following directive to the share section in the `/ect/samba/smb.conf` file. Do not use the `valid users` directive. ++ +[subs="quotes"] +---- +[SHARE] +... +guest ok = yes +... +---- + +The following sections describe other implementations of user-level security. + +.Domain Security Mode (User-Level Security)indexterm:[Samba,Security Modes,Domain Security Mode] +In domain security mode, the Samba server has a machine account (domain security trust account) and causes all authentication requests to be passed through to the domain controllers. The Samba server is made into a domain member server by using the following directives in the `/etc/samba/smb.conf` file: + +[subs="quotes"] +---- + +[GLOBAL] +... +security = domain +workgroup = MARKETING +... +---- + +.Active Directory Security Mode (User-Level Security)indexterm:[Samba,Security Modes,Active Directory Security Mode] +If you have an Active Directory environment, it is possible to join the domain as a native Active Directory member. Even if a security policy restricts the use of NT-compatible authentication protocols, the Samba server can join an ADS using Kerberos. Samba in Active Directory member mode can accept Kerberos tickets. + +In the `/etc/samba/smb.conf` file, the following directives make Samba an Active Directory member server: + +[subs="quotes"] +---- + +[GLOBAL] +... +security = ADS +realm = EXAMPLE.COM +password server = kerberos.example.com +... +---- + +[[sect-Samba_Security_Modes-Share_Level]] +==== Share-Level Security +indexterm:[Samba,Security Modes,Share-Level Security] +With share-level security, the server accepts only a password without an explicit user name from the client. The server expects a password for each share, independent of the user name. There have been recent reports that Microsoft Windows clients have compatibility issues with share-level security servers. This mode is deprecated and has been removed from Samba. Configurations containing `security = share` should be updated to use user-level security. Follow the steps in xref:File_and_Print_Servers.adoc#proc-Samba_Security_Modes-Samba_Guest_Shares[Configuring Samba Guest Shares] to avoid using the `security = share` directive. + +[[sect-Samba-Account_Information-Databases]] +=== Samba Account Information Databases +indexterm:[Samba,Account Information Databases] +The following is a list different back ends you can use with Samba. Other back ends not listed here may also be available. +indexterm:[Samba,Backward Compatible Database Back Ends]indexterm:[Samba,Account Information Databases,Plain Text]indexterm:[Samba,Account Information Databases,smbpasswd]indexterm:[Samba,Account Information Databases,ldapsam_compat]indexterm:[Samba,New Database Back Ends]indexterm:[Samba,Account Information Databases,tdbsam]indexterm:[Samba,Account Information Databases,ldapsam]indexterm:[Samba,Account Information Databases,mysqlsam]indexterm:[Samba,Account Information Databases,xmlsam] + +Plain Text:: Plain text back ends are nothing more than the `/etc/passwd` type back ends. With a plain text back end, all user names and passwords are sent unencrypted between the client and the Samba server. This method is very insecure and is not recommended for use by any means. It is possible that different Windows clients connecting to the Samba server with plain text passwords cannot support such an authentication method. + +`smbpasswd`:: The `smbpasswd` back end utilizes a plain ASCII text layout that includes the MS Windows LanMan and NT account, and encrypted password information. The `smbpasswd` back end lacks the storage of the Windows NT/2000/2003 SAM extended controls. The `smbpasswd` back end is not recommended because it does not scale well or hold any Windows information, such as RIDs for NT-based groups. The `tdbsam` back end solves these issues for use in a smaller database (250 users), but is still not an enterprise-class solution. + +`ldapsam_compat`:: The `ldapsam_compat` back end allows continued OpenLDAP support for use with upgraded versions of Samba. + +`tdbsam`:: The default `tdbsam` password back end provides a database back end for local servers, servers that do not need built-in database replication, and servers that do not require the scalability or complexity of LDAP. The `tdbsam` back end includes all of the `smbpasswd` database information as well as the previously-excluded SAM information. The inclusion of the extended SAM data allows Samba to implement the same account and system access controls as seen with Windows NT/2000/2003/2008-based systems. ++ +The `tdbsam` back end is recommended for 250 users at most. Larger organizations should require Active Directory or LDAP integration due to scalability and possible network infrastructure concerns. + +`ldapsam`:: The `ldapsam` back end provides an optimal distributed account installation method for Samba. LDAP is optimal because of its ability to replicate its database to any number of servers such as the [application]*Red{nbsp}Hat Directory Server* or an [application]*OpenLDAP Server*. LDAP databases are light-weight and scalable, and as such are preferred by large enterprises. Installation and configuration of directory servers is beyond the scope of this chapter. For more information on the [application]*Red{nbsp}Hat Directory Server*, see the [citetitle]_link:++https://access.redhat.com/documentation/en-us/red_hat_directory_server/10/html/deployment_guide/index++[Red Hat Directory Server 10 Deployment Guide]_. For more information on LDAP, see xref:servers/Directory_Servers.adoc#s1-OpenLDAP[OpenLDAP]. ++ +If you are upgrading from a previous version of Samba to 3.0, note that the OpenLDAP schema file (`/usr/share/doc/samba-_version_pass:attributes[{blank}]/LDAP/samba.schema`) and the Red{nbsp}Hat Directory Server schema file (`/usr/share/doc/samba-_version_pass:attributes[{blank}]/LDAP/samba-schema-FDS.ldif`) have changed. These files contain the _attribute syntax definitions_ and _objectclass definitions_ that the `ldapsam` back end needs in order to function properly. ++ +As such, if you are using the `ldapsam` back end for your Samba server, you will need to configure `slapd` to include one of these schema file. See xref:servers/Directory_Servers.adoc#s3-ldap-configuration-schema [Extending Schema] for directions on how to do this. ++ +.Make sure the openldap-servers package is installed +[NOTE] +==== + +You need to have the [package]*openldap-servers* package installed if you want to use the `ldapsam` back end. To ensure that the package is installed, execute the following command as `roots`: + +---- +~]# dnf install openldap-servers +---- + +==== + +[[sect-Samba-Network_Browsing]] +=== Samba Network Browsing +indexterm:[Samba,Network Browsing]indexterm:[Samba,Browsing] +_Network browsing_ enables Windows and Samba servers to appear in the Windows `Network Neighborhood`. Inside the `Network Neighborhood`, icons are represented as servers and if opened, the server's shares and printers that are available are displayed. + +Network browsing capabilities require NetBIOS over `TCP`pass:attributes[{blank}]/pass:attributes[{blank}]`IP`. NetBIOS-based networking uses broadcast (`UDP`) messaging to accomplish browse list management. Without NetBIOS and WINS as the primary method for `TCP`pass:attributes[{blank}]/pass:attributes[{blank}]`IP` host name resolution, other methods such as static files (`/etc/hosts`) or `DNS`, must be used. + +A domain master browser collates the browse lists from local master browsers on all subnets so that browsing can occur between workgroups and subnets. Also, the domain master browser should preferably be the local master browser for its own subnet. + +[[sect-Samba-Domain-Browsing]] +==== Domain Browsing +indexterm:[Samba,Network Browsing,Domain Browsing] +By default, a Windows server PDC for a domain is also the domain master browser for that domain. A Samba server must *not* be set up as a domain master server in this type of situation. + +For subnets that do not include the Windows server PDC, a Samba server can be implemented as a local master browser. Configuring the `/etc/samba/smb.conf` file for a local master browser (or no browsing at all) in a domain controller environment is the same as workgroup configuration (see xref:File_and_Print_Servers.adoc#sect-Samba-Configuring_a_Samba_Server[Configuring a Samba Server]). + +[[sect-Samba-WINS]] +==== WINS (Windows Internet Name Server) +indexterm:[Samba,WINS]indexterm:[Samba,Network Browsing,WINS] +Either a Samba server or a Windows NT server can function as a WINS server. When a WINS server is used with NetBIOS enabled, UDP unicasts can be routed which allows name resolution across networks. Without a WINS server, the UDP broadcast is limited to the local subnet and therefore cannot be routed to other subnets, workgroups, or domains. If WINS replication is necessary, do not use Samba as your primary WINS server, as Samba does not currently support WINS replication. + +In a mixed NT/2000/2003/2008 server and Samba environment, it is recommended that you use the Microsoft WINS capabilities. In a Samba-only environment, it is recommended that you use *only one* Samba server for WINS. + +The following is an example of the `/etc/samba/smb.conf` file in which the Samba server is serving as a WINS server: + +[[exam-Samba-WINS]] +.An Example Configuration of WINS Server +==== + +[subs="quotes"] +---- + +[global] +wins support = yes +---- + +==== + +.Using WINS +[NOTE] +==== + +All servers (including Samba) should connect to a WINS server to resolve NetBIOS names. Without WINS, browsing only occurs on the local subnet. Furthermore, even if a domain-wide list is somehow obtained, hosts cannot be resolved for the client without WINS. + +==== + +[[sect-Samba_with_CUPS_Printing_Support]] +=== Samba with CUPS Printing Support +indexterm:[Samba,CUPS Printing Support] +Samba allows client machines to share printers connected to the Samba server. In addition, Samba also allows client machines to send documents built in Linux to Windows printer shares. Although there are other printing systems that function with {MAJOROS}, CUPS (Common UNIX Print System) is the recommended printing system due to its close integration with Samba. + +[[sect-Samba-CUPS-smb.conf]] +==== Simple `smb.conf` Settings +indexterm:[Samba,CUPS Printing Support,CUPS smb.conf] +The following example shows a very basic `/etc/samba/smb.conf` configuration for CUPS support: + +[[exam-Samba-CUPS-smb.conf]] +.An Example Configuration of Samba with CUPS Support +==== + +[subs="quotes"] +---- + +[global] +load printers = yes +printing = cups +printcap name = cups +[printers] +comment = All Printers +path = /var/spool/samba +browseable = no +guest ok = yes +writable = no +printable = yes +printer admin = @ntadmins +[print$] +comment = Printer Drivers Share +path = /var/lib/samba/drivers +write list = ed, john +printer admin = ed, john +---- + +==== + +Other printing configurations are also possible. To add additional security and privacy for printing confidential documents, users can have their own print spooler not located in a public path. If a job fails, other users would not have access to the file. + +The `print$` directive contains printer drivers for clients to access if not available locally. The `print$` directive is optional and may not be required depending on the organization. + +Setting `browseable` to `yes` enables the printer to be viewed in the Windows Network Neighborhood, provided the Samba server is set up correctly in the domain or workgroup. + +[[sect-Samba_Distribution_Programs]] +=== Samba Distribution Programs +indexterm:[Samba,Programs] +.`net`pass:attributes[{blank}]indexterm:[Samba,Programs,net]indexterm:[net program] +---- +net +---- + +The `net` utility is similar to the `net` utility used for Windows and MS-DOS. The first argument is used to specify the protocol to use when executing a command. The [option]`pass:attributes[{blank}]_protocol_pass:attributes[{blank}]` option can be [option]`ads`, [option]`rap`, or [option]`rpc` for specifying the type of server connection. Active Directory uses [option]`ads`, Win9x/NT3 uses [option]`rap`, and Windows NT4/2000/2003/2008 uses [option]`rpc`. If the protocol is omitted, `net` automatically tries to determine it. + +The following example displays a list of the available shares for a host named `wakko`: + +[subs="quotes, macros"] +---- + +~]$ pass:attributes[{blank}][command]#net -l share -S wakko# +Password: +Enumerating shared resources (exports) on remote server: +Share name Type Description +---------- ---- ----------- +data Disk Wakko data share +tmp Disk Wakko tmp share +IPC$ IPC IPC Service (Samba Server) +ADMIN$ IPC IPC Service (Samba Server) +---- + +The following example displays a list of Samba users for a host named `wakko`: + +[subs="quotes, macros"] +---- + +~]$ pass:attributes[{blank}][command]#net -l user -S wakko# +root password: +User name Comment +----------------------------- +andriusb Documentation +joe Marketing +lisa Sales +---- + +.`nmblookup`pass:attributes[{blank}]indexterm:[Samba,Programs,nmblookup]indexterm:[nmblookup program] +---- +nmblookup +---- + +The `nmblookup` program resolves NetBIOS names into `IP` addresses. The program broadcasts its query on the local subnet until the target machine replies. + +The following example displays the `IP` address of the NetBIOS name `trek`: + +[subs="quotes, macros"] +---- + +~]$ pass:attributes[{blank}][command]#nmblookup trek# +querying trek on 10.1.59.255 +10.1.56.45 trek<00> +---- + +.`pdbedit`pass:attributes[{blank}]indexterm:[Samba,Programs,pdbedit]indexterm:[pdbedit program] +[subs="quotes, macros"] +---- +[command]#pdbedit _<options>_pass:attributes[{blank}]# +---- + +The `pdbedit` program manages accounts located in the SAM database. All back ends are supported including `smbpasswd`, LDAP, and the tdb database library. + +The following are examples of adding, deleting, and listing users: + +[subs="quotes, macros"] +---- + +~]$ pass:attributes[{blank}][command]#pdbedit -a kristin# +new password: +retype new password: +Unix username: kristin +NT username: +Account Flags: [U ] +User SID: S-1-5-21-1210235352-3804200048-1474496110-2012 +Primary Group SID: S-1-5-21-1210235352-3804200048-1474496110-2077 +Full Name: Home Directory: \\wakko\kristin +HomeDir Drive: +Logon Script: +Profile Path: \\wakko\kristin\profile +Domain: WAKKO +Account desc: +Workstations: Munged +dial: +Logon time: 0 +Logoff time: Mon, 18 Jan 2038 22:14:07 GMT +Kickoff time: Mon, 18 Jan 2038 22:14:07 GMT +Password last set: Thu, 29 Jan 2004 08:29:28 +GMT Password can change: Thu, 29 Jan 2004 08:29:28 GMT +Password must change: Mon, 18 Jan 2038 22:14:07 GMT +~]$ pass:attributes[{blank}][command]#pdbedit -v -L kristin# +Unix username: kristin +NT username: +Account Flags: [U ] +User SID: S-1-5-21-1210235352-3804200048-1474496110-2012 +Primary Group SID: S-1-5-21-1210235352-3804200048-1474496110-2077 +Full Name: +Home Directory: \\wakko\kristin +HomeDir Drive: +Logon Script: +Profile Path: \\wakko\kristin\profile +Domain: WAKKO +Account desc: +Workstations: Munged +dial: +Logon time: 0 +Logoff time: Mon, 18 Jan 2038 22:14:07 GMT +Kickoff time: Mon, 18 Jan 2038 22:14:07 GMT +Password last set: Thu, 29 Jan 2004 08:29:28 GMT +Password can change: Thu, 29 Jan 2004 08:29:28 GMT +Password must change: Mon, 18 Jan 2038 22:14:07 GMT +~]$ pass:attributes[{blank}][command]#pdbedit -L# +andriusb:505: +joe:503: +lisa:504: +kristin:506: +~]$ pass:attributes[{blank}][command]#pdbedit -x joe# +~]$ pass:attributes[{blank}][command]#pdbedit -L# +andriusb:505: lisa:504: kristin:506: +---- + +.`rpcclient`pass:attributes[{blank}]indexterm:[Samba,Programs,rpcclient]indexterm:[rpcclient program] +[subs="quotes, macros"] +---- +[command]#rpcclient _<server> <options>_pass:attributes[{blank}]# +---- + +The `rpcclient` program issues administrative commands using Microsoft RPCs, which provide access to the Windows administration graphical user interfaces (GUIs) for systems management. This is most often used by advanced users that understand the full complexity of Microsoft RPCs. + +.`smbcacls`pass:attributes[{blank}]indexterm:[Samba,Programs,smbcacls]indexterm:[smbcacls program] +[subs="quotes, macros"] +---- +[command]#smbcacls _<//server/share> <filename> <options>_pass:attributes[{blank}]# +---- + +The `smbcacls` program modifies Windows ACLs on files and directories shared by a Samba server or a Windows server. + +.`smbclient`pass:attributes[{blank}]indexterm:[Samba,Programs,smbclient]indexterm:[smbclient program] +[subs="quotes, macros"] +---- +[command]#smbclient _<//server/share> <password> <options>_pass:attributes[{blank}]# +---- + +The `smbclient` program is a versatile UNIX client which provides functionality similar to the `ftp` utility. + +.`smbcontrol`pass:attributes[{blank}]indexterm:[Samba,Programs,smbcontrol]indexterm:[smbcontrol program] +[subs="quotes, macros"] +---- +[command]#smbcontrol -i _<options>_pass:attributes[{blank}]# +---- + +[subs="quotes, macros"] +---- +[command]#smbcontrol _<options> <destination> <messagetype> <parameters>_pass:attributes[{blank}]# +---- + +The `smbcontrol` program sends control messages to running `smbd`, `nmbd`, or `winbindd` daemons. Executing [command]#smbcontrol -i# runs commands interactively until a blank line or a `'q'` is entered. + +.`smbpasswd`pass:attributes[{blank}]indexterm:[Samba,Programs,smbpasswd]indexterm:[smbpasswd program] +[subs="quotes, macros"] +---- +[command]#smbpasswd _<options> <username> <password>_pass:attributes[{blank}]# +---- + +The `smbpasswd` program manages encrypted passwords. This program can be run by a superuser to change any user's password and also by an ordinary user to change their own Samba password. + +.`smbspool`pass:attributes[{blank}]indexterm:[Samba,Programs,smbspool]indexterm:[smbspool program] +[subs="quotes, macros"] +---- +[command]#smbspool _<job> <user> <title> <copies> <options> <filename>_pass:attributes[{blank}]# +---- + +The `smbspool` program is a CUPS-compatible printing interface to Samba. Although designed for use with CUPS printers, [command]#smbspool# can work with non-CUPS printers as well. + +.`smbstatus`pass:attributes[{blank}]indexterm:[Samba,Programs,smbstatus]indexterm:[smbstatus program] +[subs="quotes, macros"] +---- +[command]#smbstatus _<options>_pass:attributes[{blank}]# +---- + +The `smbstatus` program displays the status of current connections to a Samba server. + +.`smbtar`pass:attributes[{blank}]indexterm:[Samba,Programs,smbtar]indexterm:[smbtar program] +[subs="quotes, macros"] +---- +[command]#smbtar _<options>_pass:attributes[{blank}]# +---- + +The `smbtar` program performs backup and restores of Windows-based share files and directories to a local tape archive. Though similar to the `tar` utility, the two are not compatible. + +.`testparm`pass:attributes[{blank}]indexterm:[Samba,Programs,testparm]indexterm:[testparm program] +---- +testparm +---- + +The `testparm` program checks the syntax of the `/etc/samba/smb.conf` file. If your `smb.conf` file is in the default location (`/etc/samba/smb.conf`) you do not need to specify the location. Specifying the host name and `IP` address to the `testparm` program verifies that the `hosts.allow` and `host.deny` files are configured correctly. The `testparm` program also displays a summary of your `smb.conf` file and the server's role (stand-alone, domain, etc.) after testing. This is convenient when debugging as it excludes comments and concisely presents information for experienced administrators to read. For example: + +[subs="macros"] +---- + +~]$ testparm +Load smb config files from /etc/samba/smb.conf +Processing section "[homes]" +Processing section "[printers]" +Processing section "[tmp]" +Processing section "[html]" +Loaded services file OK. +Server role: ROLE_STANDALONE +Press enter to see a dump of your service definitions +pass:quotes[`<enter>`] +# Global parameters +[global] + workgroup = MYGROUP + server string = Samba Server + security = SHARE + log file = /var/log/samba/%m.log + max log size = 50 + socket options = TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192 + dns proxy = no +[homes] + comment = Home Directories + read only = no + browseable = no +[printers] + comment = All Printers + path = /var/spool/samba + printable = yes + browseable = no +[tmp] + comment = Wakko tmp + path = /tmp + guest only = yes +[html] + comment = Wakko www + path = /var/www/html + force user = andriusb + force group = users + read only = no + guest only = yes +---- + +.`wbinfo`pass:attributes[{blank}]indexterm:[Samba,Programs,wbinfo]indexterm:[wbinfo program] +[subs="quotes, macros"] +---- +[command]#wbinfo _<options>_pass:attributes[{blank}]# +---- + +The `wbinfo` program displays information from the `winbindd` daemon. The `winbindd` daemon must be running for `wbinfo` to work. + +[[sect-Samba-Resources]] +=== Additional Resources +indexterm:[Samba,Additional Resources] +The following sections give you the means to explore Samba in greater detail. + +.Installed Documentationindexterm:[Samba,Additional Resources,installed documentation] + +* `/usr/share/doc/samba-/` — All additional files included with the Samba distribution. This includes all helper scripts, sample configuration files, and documentation. + +* See the following man pages for detailed information specific [application]*Samba* features: ++ +** *smb.conf*(5) ++ +** *samba*(7) ++ +** *smbd*(8) ++ +** *nmbd*(8) ++ +** *winbindd*(8) + +.Useful Websitesindexterm:[Samba,Additional Resources,useful websites] + +* link:++https://www.samba.org/++[https://www.samba.org/] — Homepage for the Samba distribution and all official documentation created by the Samba development team. Many resources are available in HTML and PDF formats, while others are only available for purchase. Although many of these links are not {MAJOROS} specific, some concepts may apply. + +* link:++https://wiki.samba.org/index.php/User_Documentation++[https://wiki.samba.org/index.php/User_Documentation] — Samba 4.x official documentation. + +* link:++https://www.samba.org/samba/archives.html++[https://www.samba.org/samba/archives.html ] — Active email lists for the Samba community. Enabling digest mode is recommended due to high levels of list activity. + +* Samba newsgroups — Samba threaded newsgroups, such as link:++https://www.gmane.org/++[www.gmane.org], that use the `NNTP` protocol are also available. This an alternative to receiving mailing list emails. diff --git a/modules/system-administrators-guide/pages/_partials/servers/The_Apache_HTTP_Server.adoc b/modules/system-administrators-guide/pages/_partials/servers/The_Apache_HTTP_Server.adoc index 5c3f07d..c07dfd7 100644 --- a/modules/system-administrators-guide/pages/_partials/servers/The_Apache_HTTP_Server.adoc +++ b/modules/system-administrators-guide/pages/_partials/servers/The_Apache_HTTP_Server.adoc @@ -2,7 +2,124 @@ [[s1-The_Apache_HTTP_Server]] == The Apache HTTP Server indexterm:[httpd,Apache HTTP Server] +<<<<<<< HEAD +The web server available in {MAJOROS} is the Apache HTTP server daemon, `httpd`, an open source web server developed by the link:++https://www.apache.org/++[Apache Software Foundation]. In Fedora 19 the Apache server was updated to [application]*Apache HTTP Server 2.4*. This section describes the basic configuration of the `httpd` service, and covers some advanced topics such as adding server modules, setting up virtual hosts, or configuring the secure HTTP server. + +There are important differences between the Apache HTTP Server 2.4 and version 2.2, and if you are upgrading from a release prior to Fedora 19, you will need to update the `httpd` service configuration accordingly. This section reviews some of the newly added features, outlines important changes, and guides you through the update of older configuration files. + +[[s2-apache-changes]] +=== Notable Changes +indexterm:[Apache HTTP Server,version 2.4,changes] +The Apache HTTP Server version 2.4 has the following changes compared to version 2.2: + +httpd Service Control:: With the migration away from SysV init scripts, server administrators should switch to using the [command]#apachectl# and [command]#systemctl# commands to control the service, in place of the [command]#service# command. The following examples are specific to the `httpd` service. + +The command: + +[subs="quotes"] +---- +service httpd graceful +---- + +is replaced by + +[subs="quotes"] +---- +systemctl reload httpd +---- + +The `systemd` unit file for `httpd` has different behavior from the init script as follows: + +** A graceful restart is used by default when the service is reloaded. + +** A graceful stop is used by default when the service is stopped. + +The command: + +[subs="quotes"] +---- +service httpd configtest +---- + +is replaced by + +[subs="quotes"] +---- +apachectl configtest +---- + +Private /tmp:: To enhance system security, the `systemd` unit file runs the `httpd` daemon using a private `/tmp` directory, separate to the system `/tmp` directory. + +Configuration Layout:: Configuration files which load modules are now placed in the `/etc/httpd/conf.modules.d` directory. Packages that provide additional loadable modules for `httpd`, such as [package]*php*, will place a file in this directory. Any configuration files in the `conf.modules.d` directory are processed before the main body of `httpd.conf`. Configuration files in the `/etc/httpd/conf.d` directory are now processed after the main body of `httpd.conf`. + +Some additional configuration files are provided by the [package]*httpd* package itself: + +** `/etc/httpd/conf.d/autoindex.conf` — This configures mod_autoindex directory indexing. + +** `/etc/httpd/conf.d/userdir.conf` — This configures access to user directories, for example, `http://example.com/~username/`pass:attributes[{blank}]; such access is disabled by default for security reasons. + +** `/etc/httpd/conf.d/welcome.conf` — As in previous releases, this configures the welcome page displayed for `http://localhost/` when no content is present. + +Default Configuration:: A minimal `httpd.conf` file is now provided by default. Many common configuration settings, such as `Timeout` or `KeepAlive` are no longer explicitly configured in the default configuration; hard-coded settings will be used instead, by default. The hard-coded default settings for all configuration directives are specified in the manual. See xref:Web_Servers.adoc#bh-The_Apache_HTTP_Server-Installable_Documentation[Installable Documentationindexterm:[Apache HTTP Server,additional resources,installable documentation]] for more information. + +Incompatible Syntax Changes:: If migrating an existing configuration from [application]*httpd 2.2* to [application]*httpd 2.4*, a number of backwards-incompatible changes to the `httpd` configuration syntax were made which will require changes. See the following Apache document for more information on upgrading link:++https://httpd.apache.org/docs/2.4/upgrading.html++[] + +Processing Model:: In previous releases of {MAJOROS}, different _multi-processing models_ (*MPM*) were made available as different `httpd` binaries: the forked model, "prefork", as `/usr/sbin/httpd`, and the thread-based model "worker" as `/usr/sbin/httpd.worker`. + +In {MAJOROSVER}, only a single `httpd` binary is used, and three MPMs are available as loadable modules: worker, prefork (default), and event. Edit the configuration file `/etc/httpd/conf.modules.d/00-mpm.conf` as required, by adding and removing the comment character `#` so that only one of the three MPM modules is loaded. + +Packaging Changes:: The LDAP authentication and authorization modules are now provided in a separate sub-package, [package]*mod_ldap*. The new module [application]*mod_session* and associated helper modules are provided in a new sub-package, [package]*mod_session*. The new modules [application]*mod_proxy_html* and [application]*mod_xml2enc* are provided in a new sub-package, [package]*mod_proxy_html*. + +Packaging Filesystem Layout:: The `/var/cache/mod_proxy/` directory is no longer provided; instead, the `/var/cache/httpd/` directory is packaged with a `proxy` and `ssl` subdirectory. + +Packaged content provided with `httpd` has been moved from `/var/www/` to `/usr/share/httpd/`: + +** `/usr/share/httpd/icons/` — The directory containing a set of icons used with directory indices, previously contained in `/var/www/icons/`, has moved to `/usr/share/httpd/icons`. Available at `http://localhost/icons/` in the default configuration; the location and the availability of the icons is configurable in the `/etc/httpd/conf.d/autoindex.conf` file. + +** `/usr/share/httpd/manual/` — The `/var/www/manual/` has moved to `/usr/share/httpd/manual/`. This directory, contained in the [package]*httpd-manual* package, contains the HTML version of the manual for `httpd`. Available at `http://localhost/manual/` if the package is installed, the location and the availability of the manual is configurable in the `/etc/httpd/conf.d/manual.conf` file. + +** `/usr/share/httpd/error/` — The `/var/www/error/` has moved to `/usr/share/httpd/error/`. Custom multi-language HTTP error pages. Not configured by default, the example configuration file is provided at `/usr/share/doc/httpd-_VERSION_pass:attributes[{blank}]/httpd-multilang-errordoc.conf`. + +Authentication, Authorization and Access Control:: The configuration directives used to control authentication, authorization and access control have changed significantly. Existing configuration files using the `Order`, `Deny` and `Allow` directives should be adapted to use the new `Require` syntax. See the following Apache document for more information link:++https://httpd.apache.org/docs/2.4/howto/auth.html++[] + +suexec:: To improve system security, the [application]*suexec* binary is no longer installed as if by the `root` user; instead, it has file system capability bits set which allow a more restrictive set of permissions. In conjunction with this change, the [application]*suexec* binary no longer uses the `/var/log/httpd/suexec.log` logfile. Instead, log messages are sent to [application]*syslog*pass:attributes[{blank}]; by default these will appear in the `/var/log/secure` log file. + +Module Interface:: Third-party binary modules built against [application]*httpd 2.2* are not compatible with [application]*httpd 2.4* due to changes to the `httpd` module interface. Such modules will need to be adjusted as necessary for the [application]*httpd 2.4* module interface, and then rebuilt. A detailed list of the API changes in version `2.4` is available here: link:++https://httpd.apache.org/docs/2.4/developer/new_api_2_4.html++[]. + +The [application]*apxs* binary used to build modules from source has moved from `/usr/sbin/apxs` to `/usr/bin/apxs`. + +Removed modules:: List of `httpd` modules removed in {MAJOROSVER}: + +mod_auth_mysql, mod_auth_pgsql::: [application]*httpd 2.4* provides SQL database authentication support internally in the [application]*mod_authn_dbd* module. + +mod_authz_ldap::: [application]*httpd 2.4* provides LDAP support in sub-package [package]*mod_ldap* using [application]*mod_authnz_ldap*. + +[[s2-apache-version2-migrating]] +=== Updating the Configuration +indexterm:[Apache HTTP Server,version 2.4,updating from version 2.2] +To update the configuration files from the Apache HTTP Server version 2.2, take the following steps: + +. Make sure all module names are correct, since they may have changed. Adjust the [option]`LoadModule` directive for each module that has been renamed. + +. Recompile all third party modules before attempting to load them. This typically means authentication and authorization modules. + +. indexterm:[Apache HTTP Server,modules,mod_userdir] +If you use the `mod_userdir` module, make sure the [option]`UserDir` directive indicating a directory name (typically `public_html`) is provided. + +. If you use the Apache HTTP Secure Server, edit the `/etc/httpd/conf.d/ssl.conf` to enable the Secure Sockets Layer (SSL) protocol. + +Note that you can check the configuration for possible errors by using the following command: + +[subs="attributes"] +---- +~]#{nbsp}apachectl configtest +Syntax OK +---- + +For more information on upgrading the Apache HTTP Server configuration from version 2.2 to 2.4, see link:++https://httpd.apache.org/docs/2.4/upgrading.html++[]. +======= The web server available in {MAJOROS} is the Apache HTTP server daemon, `httpd`, an open source web server developed by the link:++https://www.apache.org/++[Apache Software Foundation]. This section describes the basic configuration of the `httpd` service, and covers some advanced topics such as adding server modules, setting up virtual hosts, or configuring the secure HTTP server. +>>>>>>> 1cea858... Issue 23 - remove old references to F19 and a useless changelog from httpd section [[s2-apache-running]] === Running the httpd Service @@ -11,7 +128,7 @@ This section describes how to start, stop, restart, and check the current status [subs="attributes"] ---- -#{nbsp}dnf install httpd +~]#{nbsp}dnf install httpd ---- For more information on the concept of targets and how to manage system services in {MAJOROS} in general, see @@ -25,14 +142,14 @@ To run the `httpd` service, type the following at a shell prompt as `root`: [subs="attributes"] ---- -#{nbsp}systemctl start httpd.service +~]#{nbsp}systemctl start httpd.service ---- If you want the service to start automatically at boot time, use the following command: [subs="attributes"] ---- -#{nbsp}systemctl enable httpd.service +~]#{nbsp}systemctl enable httpd.service ln -s '/usr/lib/systemd/system/httpd.service' '/etc/systemd/system/multi-user.target.wants/httpd.service' ---- @@ -51,14 +168,14 @@ To stop the running `httpd` service, type the following at a shell prompt as `ro [subs="attributes"] ---- -#{nbsp}systemctl stop httpd.service +~]#{nbsp}systemctl stop httpd.service ---- To prevent the service from starting automatically at boot time, type: [subs="attributes"] ---- -#{nbsp}systemctl disable httpd.service +~]#{nbsp}systemctl disable httpd.service rm '/etc/systemd/system/multi-user.target.wants/httpd.service' ---- @@ -71,7 +188,7 @@ There are three different ways to restart a running `httpd` service: [subs="attributes"] ---- -#{nbsp}systemctl restart httpd.service +~]#{nbsp}systemctl restart httpd.service ---- This stops the running `httpd` service and immediately starts it again. Use this command after installing or removing a dynamically loaded module such as PHP. @@ -80,7 +197,7 @@ This stops the running `httpd` service and immediately starts it again. Use this [subs="attributes"] ---- -#{nbsp}systemctl reload httpd.service +~]#{nbsp}systemctl reload httpd.service ---- This causes the running `httpd` service to reload its configuration file. Any requests currently being processed will not be interrupted, so configuration changes will only take effect for new client connections. @@ -89,7 +206,7 @@ This causes the running `httpd` service to reload its configuration file. Any re [subs="attributes"] ---- -#{nbsp}systemctl kill --kill-who=main --signal=HUP httpd +~]#{nbsp}systemctl kill --kill-who=main --signal=HUP httpd ---- @@ -100,7 +217,7 @@ To verify that the `httpd` service is running, type the following at a shell pro [subs="attributes"] ---- -#{nbsp}systemctl is-active httpd.service +~]#{nbsp}systemctl is-active httpd.service active ---- @@ -127,7 +244,7 @@ To check the configuration for possible errors, type the following at a shell pr [subs="attributes"] ---- -#{nbsp}apachectl configtest +~]#{nbsp}apachectl configtest Syntax OK ---- @@ -1409,7 +1526,7 @@ The _option_ has to be a valid keyword as described in xref:Web_Servers.adoc#tab |[option]`Includes`|Enables server-side includes. |[option]`IncludesNOEXEC`|Enables server-side includes, but does not allow the execution of commands. |[option]`Indexes`|Enables server-generated directory listings. -|[option]`MultiViews`|Enables content-negotiated "`MultiViews`". +|[option]`MultiViews`|Enables content-negotiated "MultiViews". |[option]`SymLinksIfOwnerMatch`|Enables following symbolic links in the directory when both the link and the target file have the same owner. |[option]`All`|Enables all of the features above with the exception of [option]`MultiViews`. |[option]`None`|Disables all of the features above. @@ -1865,8 +1982,8 @@ The _option_ can be either a name of the directory to look for in user's home di In order for the web server to access the content, the permissions on relevant directories and files must be set correctly. Make sure that all users are able to access the home directories, and that they can access and read the content of the directory specified by the [option]`UserDir` directive. For example, to allow access to `public_html/` in the home directory of user `joe`, type the following at a shell prompt as `root`: ---- -# chmod a+x /home/joe/ -# chmod a+rx /home/joe/public_html/ +~]# chmod a+x /home/joe/ +~]# chmod a+rx /home/joe/public_html/ ---- All files in this directory must be set accordingly. @@ -2127,7 +2244,7 @@ If you intend to create a new DSO module, make sure you have the [package]*httpd [subs="attributes"] ---- -#{nbsp}dnf install httpd-devel +~]#{nbsp}dnf install httpd-devel ---- This package contains the include files, the header files, and the [application]*APache eXtenSion* ([command]#apxs#) utility required to compile a module. @@ -2136,7 +2253,7 @@ Once written, you can build the module with the following command: [subs="attributes"] ---- -#{nbsp}apxs -i -a -c module_name.c +~]#{nbsp}apxs -i -a -c module_name.c ---- If the build was successful, you should be able to load the module the same way as any other module that is distributed with the Apache HTTP Server. @@ -2217,7 +2334,7 @@ If you intend to set up an SSL server, make sure you have the [package]*mod_ssl* [subs="attributes"] ---- -#{nbsp}dnf install mod_ssl openssl +~]#{nbsp}dnf install mod_ssl openssl ---- indexterm:[Apache HTTP Server,files,/etc/httpd/conf.d/ssl.conf] This will create the `mod_ssl` configuration file at `/etc/httpd/conf.d/ssl.conf`, which is included in the main Apache HTTP Server configuration file by default. For the module to be loaded, restart the `httpd` service as described in xref:Web_Servers.adoc#s3-apache-running-restarting[Restarting the Service]. @@ -2232,7 +2349,7 @@ Due to the SSL3.0 protocol vulnerability CVE-2014-3566, described in link:++http [[s3-apache-Enabling_and_Disabling_SSL_and_TLS_in_mod_ssl]] ==== Enabling and Disabling SSL and TLS in mod_ssl -To disable and enable specific versions of the SSL and TLS protocol, either do it globally by adding the [command]#SSLProtocol# directive in the "`\#\# SSL Global Context`" section of the configuration file and removing it everywhere else, or edit the default entry under "`\# SSL Protocol support`" in all "`VirtualHost`" sections. If you do not specify it in the per-domain VirtualHost section then it will inherit the settings from the global section. To make sure that a protocol version is being disabled the administrator should either *only* specify [command]#SSLProtocol# in the "`SSL Global Context`" section, or specify it in *all* per-domain VirtualHost sections. +To disable and enable specific versions of the SSL and TLS protocol, either do it globally by adding the [command]#SSLProtocol# directive in the "\#\# SSL Global Context" section of the configuration file and removing it everywhere else, or edit the default entry under "\# SSL Protocol support" in all "VirtualHost" sections. If you do not specify it in the per-domain VirtualHost section then it will inherit the settings from the global section. To make sure that a protocol version is being disabled the administrator should either *only* specify [command]#SSLProtocol# in the "SSL Global Context" section, or specify it in *all* per-domain VirtualHost sections. [[proc-Disable_SSLv2_and_SSLv3]] .Disable SSLv2 and SSLv3 @@ -2241,7 +2358,7 @@ To disable SSL version 2 and SSL version 3, which implies enabling everything ex . As `root`, open the `/etc/httpd/conf.d/ssl.conf` file and search for *all* instances of the [command]#SSLProtocol# directive. By default, the configuration file contains one section that looks as follows: ---- -# vi /etc/httpd/conf.d/ssl.conf +~]# vi /etc/httpd/conf.d/ssl.conf # SSL Protocol support: # List the enable protocol levels with which clients will be able to # connect. Disable SSLv2 access by default: @@ -2265,16 +2382,16 @@ Repeat this action for all VirtualHost sections. [subs="macros"] ---- -# grep SSLProtocol /etc/httpd/conf.d/ssl.conf +~]# grep SSLProtocol /etc/httpd/conf.d/ssl.conf pass:quotes[*SSLProtocol*] all -SSLv2 -SSLv3 ---- This step is particularly important if you have more than the one default VirtualHost section. -. Restart the Apache service as follows: +. Restart the Apache daemon as follows: ---- -# systemctl restart httpd +~]# service httpd restart ---- Note that any sessions will be interrupted. @@ -2292,14 +2409,14 @@ Certificates are issued for a particular IP address and domain name pair. If one VeriSign, a widely used certificate authority, issues certificates for a particular software product, IP address, and domain name. Changing the software product renders the certificate invalid. -In either of the above cases, you will need to obtain a new certificate. For more information on this topic, see xref:Web_Servers.adoc#s3-apache-mod_ssl-genkey[Generating a New Certificate Using OpenSSL]. +In either of the above cases, you will need to obtain a new certificate. For more information on this topic, see xref:Web_Servers.adoc#s3-apache-mod_ssl-genkey[Generating a New Key and Certificate]. If you want to use an existing key and certificate, move the relevant files to the `/etc/pki/tls/private/` and `/etc/pki/tls/certs/` directories respectively. You can do so by issuing the following commands as `root`: [subs="macros, attributes"] ---- -#{nbsp}mv pass:quotes[`key_file.key`] pass:quotes[`/etc/pki/tls/private/hostname.key`] -#{nbsp}mv pass:quotes[`certificate.crt`] pass:quotes[`/etc/pki/tls/certs/hostname.crt`] +~]#{nbsp}mv pass:quotes[`key_file.key`] pass:quotes[`/etc/pki/tls/private/hostname.key`] +~]#{nbsp}mv pass:quotes[`certificate.crt`] pass:quotes[`/etc/pki/tls/certs/hostname.crt`] ---- Then add the following lines to the `/etc/httpd/conf.d/ssl.conf` configuration file: @@ -2318,66 +2435,139 @@ To load the updated configuration, restart the `httpd` service as described in x [subs="attributes"] ---- -#{nbsp}mv /etc/httpd/conf/httpsd.key /etc/pki/tls/private/penguin.example.com.key -#{nbsp}mv /etc/httpd/conf/httpsd.crt /etc/pki/tls/certs/penguin.example.com.crt +~]#{nbsp}mv /etc/httpd/conf/httpsd.key /etc/pki/tls/private/penguin.example.com.key +~]#{nbsp}mv /etc/httpd/conf/httpsd.crt /etc/pki/tls/certs/penguin.example.com.crt ---- ==== [[s3-apache-mod_ssl-genkey]] -==== Generating a New Certificate Using OpenSSL - -First, generate the private key. In this example we will use a 2048 RSA key: +==== Generating a New Key and Certificate +indexterm:[Apache HTTP Server,SSL server,private key]indexterm:[Apache HTTP Server,SSL server,certificate] +In order to generate a new key and certificate pair, the [package]*crypto-utils* package must be installed on the system. To install it, enter the following command as `root`: [subs="attributes"] ---- -# openssl genrsa -out myhost.com.key 2048 +~]#{nbsp}dnf install crypto-utils ---- -Create a Certificate Signing Request(CSR). The Common Name field must be your server's hostname: +This package provides a set of tools to generate and manage SSL certificates and private keys, and includes [application]*genkey*, the Red{nbsp}Hat Keypair Generation utility that will guide you through the key generation process. + +.Replacing an existing certificate +[IMPORTANT] +==== + +If the server already has a valid certificate and you are replacing it with a new one, specify a different serial number. This ensures that client browsers are notified of this change, update to this new certificate as expected, and do not fail to access the page. To create a new certificate with a custom serial number, use the following command instead of [application]*genkey*: [subs="attributes"] ---- -# openssl req -new -key myhost.com.key -out myhost.com.csr -sha512 +~]#{nbsp}openssl req -x509 -new -set_serial number -key hostname.key -out hostname.crt ---- -A message digest algorithm like SHA2 or stronger is recommended, but it's more important for the certificate than for the request. However your CA decides which message digest they use for the certificate. - -Now give your CSR to your Certificate Authority(CA) so they can sign your key and give you a certificate: - -[subs="attributes"] ----- -# openssl x509 -req -days 365 -in myhost.com.csr -signkey myhost.com.key -out myhost.com.crt -sha512 ----- +==== +.Remove a previously created key [NOTE] ==== -You can also self-sign the CSR, but bear in mind the security issues that it poses and that browsers will warn users about this. + +If there already is a key file for a particular host name in your system, [application]*genkey* will refuse to start. In this case, remove the existing file using the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}rm /etc/pki/tls/private/hostname.key +---- + ==== -Once your CA has signed it, they will give you the certificate(`.crt` file). Now move the private key and the certificate to their respective directories: +To run the utility enter the [command]#genkey# command as `root`, followed by the appropriate host name (for example, `penguin.example.com`): -[subs="attributes"] +[subs="macros, attributes"] ---- -# cp myhost.com.crt /etc/pki/tls/certs/ -# cp myhost.com.key /etc/pki/tls/private/myhost.com.key +~]#{nbsp}genkey pass:quotes[_hostname_] ---- -The Certificate Signing Request(CSR) can be deleted as it becomes useless once you have obtained your certificate. Alternatively you can put it along your private key: +To complete the key and certificate creation, take the following steps: -[subs="attributes"] +. Review the target locations in which the key and certificate will be stored. + +[[figure-apache-mod_ssl-genkey-01]] +.Running the genkey utility + +image::apache-mod_ssl-genkey-01.png[Running the genkey utility] + +Use the kbd:[Tab] key to select the btn:[Next] button, and press kbd:[Enter] to proceed to the next screen. + +. Using the kbd:[up] and kbd:[down] arrow keys, select a suitable key size. Note that while a larger key increases the security, it also increases the response time of your server. The NIST recommends using `2048 bits`. See [citetitle]_link:++https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf++[NIST Special Publication 800-131A Revision 1]_. + +[[figure-apache-mod_ssl-genkey-02]] +.Selecting the key size + +image::apache-mod_ssl-genkey-02.png[Selecting the key size] + +Once finished, use the kbd:[Tab] key to select the btn:[Next] button, and press kbd:[Enter] to initiate the random bits generation process. Depending on the selected key size, this may take some time. + +. Decide whether you want to send a certificate request to a certificate authority. + +[[figure-apache-mod_ssl-genkey-03]] +.Generating a certificate request + +image::apache-mod_ssl-genkey-03.png[Generating a certificate request] + +Use the kbd:[Tab] key to select btn:[Yes] to compose a certificate request, or btn:[No] to generate a self-signed certificate. Then press kbd:[Enter] to confirm your choice. + +. Using the kbd:[Spacebar] key, enable (`[*]`) or disable (`[ ]`) the encryption of the private key. + +[[figure-apache-mod_ssl-genkey-04]] +.Encrypting the private key + +image::apache-mod_ssl-genkey-04.png[Encrypting the private key] + +Use the kbd:[Tab] key to select the btn:[Next] button, and press kbd:[Enter] to proceed to the next screen. + +. If you have enabled the private key encryption, enter an adequate passphrase. Note that for security reasons, it is not displayed as you type, and it must be at least five characters long. + +[[figure-apache-mod_ssl-genkey-05]] +.Entering a passphrase + +image::apache-mod_ssl-genkey-05.png[Entering a passphrase] + +Use the kbd:[Tab] key to select the btn:[Next] button, and press kbd:[Enter] to proceed to the next screen. + +.Do not forget the passphrase +[IMPORTANT] +==== + +Entering the correct passphrase is required in order for the server to start. If you lose it, you will need to generate a new key and certificate. + +==== + +. Customize the certificate details. + +[[figure-apache-mod_ssl-genkey-06]] +.Specifying certificate information + +image::apache-mod_ssl-genkey-06.png[Specifying certificate information] + +Use the kbd:[Tab] key to select the btn:[Next] button, and press kbd:[Enter] to finish the key generation. + +. If you have previously enabled the certificate request generation, you will be prompted to send it to a certificate authority. + +[[figure-apache-mod_ssl-genkey-07]] +.Instructions on how to send a certificate request + +image::apache-mod_ssl-genkey-07.png[Instructions on how to send a certificate request] + +Press kbd:[Enter] to return to a shell prompt. + +Once generated, add the key and certificate locations to the `/etc/httpd/conf.d/ssl.conf` configuration file: + +[subs="quotes, macros"] ---- -# cp myhost.com.csr /etc/pki/tls/private/myhost.com.csr +SSLCertificateFile /etc/pki/tls/certs/pass:attributes[{blank}]_hostname_.crt +SSLCertificateKeyFile /etc/pki/tls/private/pass:attributes[{blank}]_hostname_.key ---- -Set the correct context of these files for SELinux: - -[subs="attributes"] ----- -# restorecon -RvF /etc/pki ----- - -The last step is to configure the webserver of your host for the TLS protocol using the key and the certificate files you have just created - see xref:The_Apache_HTTP_Server.adoc#mod-ssl-configuration[mod_ssl configuration]. +Finally, restart the `httpd` service as described in xref:Web_Servers.adoc#s3-apache-running-restarting[Restarting the Service], so that the updated configuration is loaded. [[s2-apache-resources]] === Additional Resources @@ -2388,6 +2578,8 @@ To learn more about the Apache HTTP Server, see the following resources. * `httpd(8)` — The manual page for the `httpd` service containing the complete list of its command-line options. +* `genkey(1)` — The manual page for [command]#genkey# utility, provided by the [package]*crypto-utils* package. + * `apachectl(8)` — The manual page for the Apache HTTP Server Control Interface. [[bh-The_Apache_HTTP_Server-Installable_Documentation]] @@ -2398,8 +2590,8 @@ To learn more about the Apache HTTP Server, see the following resources. Before accessing the documentation, issue the following commands as `root`: ---- -# dnf install httpd-manual -# apachectl graceful +~]# dnf install httpd-manual +~]# apachectl graceful ---- .Online Documentationindexterm:[Apache HTTP Server,additional resources,useful websites] diff --git a/modules/system-administrators-guide/pages/basic-system-configuration/Configuring_the_Date_and_Time.adoc b/modules/system-administrators-guide/pages/basic-system-configuration/Configuring_the_Date_and_Time.adoc index b63dc51..7fc7bdc 100644 --- a/modules/system-administrators-guide/pages/basic-system-configuration/Configuring_the_Date_and_Time.adoc +++ b/modules/system-administrators-guide/pages/basic-system-configuration/Configuring_the_Date_and_Time.adoc @@ -409,7 +409,7 @@ At the same time, you can also set the hardware clock to keep the time in either .Setting the Hardware Clock to a Specific Date and Time ==== -If you want to set the date and time to a specific value, for example, to "`21:17, October 21, 2014`", and keep the hardware clock in UTC, run the command as `root` in the following format: +If you want to set the date and time to a specific value, for example, to "21:17, October 21, 2014", and keep the hardware clock in UTC, run the command as `root` in the following format: [subs="attributes"] ---- diff --git a/modules/system-administrators-guide/pages/basic-system-configuration/Managing_Users_and_Groups.adoc b/modules/system-administrators-guide/pages/basic-system-configuration/Managing_Users_and_Groups.adoc index d0d7039..cab4d70 100644 --- a/modules/system-administrators-guide/pages/basic-system-configuration/Managing_Users_and_Groups.adoc +++ b/modules/system-administrators-guide/pages/basic-system-configuration/Managing_Users_and_Groups.adoc @@ -1,9 +1,10 @@ + :experimental: include::{partialsdir}/entities.adoc[] [[ch-Managing_Users_and_Groups]] = Managing Users and Groups - +indexterm:[groups,introducing]indexterm:[users,introducing]indexterm:[users,UID]indexterm:[groups,GID] The control of users and groups is a core element of {MAJOROS} system administration. This chapter explains how to add, manage, and delete users and groups in the graphical user interface and on the command line, and covers advanced topics, such as creating group directories. [[s1-users-groups-introduction]] @@ -22,7 +23,7 @@ indexterm:[groups,user private]indexterm:[user private groups,groups]indexterm:[ User private groups make it safe to set default permissions for a newly created file or directory, allowing both the user and *the group of that user* to make modifications to the file or directory. -The setting which determines what permissions are applied to a newly created file or directory is called a _umask_ and is configured in the `/etc/bashrc` file. Traditionally on UNIX-based systems, the [command]#umask# is set to [command]#022#, which allows only the user who created the file or directory to make modifications. Under this scheme, all other users, *including members of the creator's group*, are not allowed to make any modifications. However, under the UPG scheme, this "`group protection`" is not necessary since every user has their own private group. +The setting which determines what permissions are applied to a newly created file or directory is called a _umask_ and is configured in the `/etc/bashrc` file. Traditionally on UNIX-based systems, the [command]#umask# is set to [command]#022#, which allows only the user who created the file or directory to make modifications. Under this scheme, all other users, *including members of the creator's group*, are not allowed to make any modifications. However, under the UPG scheme, this "group protection" is not necessary since every user has their own private group. A list of all groups is stored in the `/etc/group` configuration file. @@ -66,8 +67,6 @@ To make changes to the user accounts, first select the btn:[Unlock] button and a image::managing_users.png[The Users settings tool] -The commandline for call this Gui is : -[user@domain ~]$ kcmshell5 user_manager When a new user is created, the account is disabled until a password is set. The Add User menu contains the options to set a password by the administrator immediately, or to allow the user to choose a password at the first login. [[s1-users-tools]] diff --git a/modules/system-administrators-guide/pages/basic-system-configuration/Opening_GUI_Applications.adoc b/modules/system-administrators-guide/pages/basic-system-configuration/Opening_GUI_Applications.adoc index b7f3a96..7fce065 100644 --- a/modules/system-administrators-guide/pages/basic-system-configuration/Opening_GUI_Applications.adoc +++ b/modules/system-administrators-guide/pages/basic-system-configuration/Opening_GUI_Applications.adoc @@ -1,9 +1,10 @@ + :experimental: include::{partialsdir}/entities.adoc[] [[ch-Opening_GUI_Applications]] = Opening Graphical Applications - +indexterm:[GUI] Fedora provides graphical applications in addition to command line utilities for configuring many features. This chapter describes methods for opening `Graphical User Interface`, or _GUI_, applications in various environments. [[gui-from_cli]] diff --git a/modules/system-administrators-guide/pages/basic-system-configuration/System_Locale_and_Keyboard_Configuration.adoc b/modules/system-administrators-guide/pages/basic-system-configuration/System_Locale_and_Keyboard_Configuration.adoc index 4bd4ccd..c9c1dbf 100644 --- a/modules/system-administrators-guide/pages/basic-system-configuration/System_Locale_and_Keyboard_Configuration.adoc +++ b/modules/system-administrators-guide/pages/basic-system-configuration/System_Locale_and_Keyboard_Configuration.adoc @@ -1,9 +1,10 @@ + :experimental: include::{partialsdir}/entities.adoc[] [[ch-System_Locale_and_Keyboard_Configuration]] = System Locale and Keyboard Configuration - +indexterm:[keyboard configuration] The *system locale* specifies the language settings of system services and user interfaces. The *keyboard layout* settings control the layout used on the text console and graphical user interfaces. These settings can be made by modifying the `/etc/locale.conf` configuration file or by using the [application]*localectl* utility. You can also set these settings during system installation using the installer graphical interface, text mode interface, or the [command]*keyboard* and [command]*lang* Kickstart commands. See the link:https://docs.fedoraproject.org/en-US/fedora/f{MAJOROSVER}/install-guide[{MAJOROS} Installation Guide] for information about these options. @@ -248,24 +249,6 @@ Apart from keyboard layout (_map_), three other options can be specified: Replace _model_ with the keyboard model name, _variant_ and _options_ with keyboard variant and option components, which can be used to enhance the keyboard behavior. These options are not set by default. For more information on X11 Model, X11 Variant, and X11 Options see the `kbd(4)` man page. -[[s2-If_Using_Gnome]] -=== Consider this option if using gnome - -This should work if the following conditions apply: - -* Using gnome as the desktop environment - -* Your layout is not listed under Settings -> Keyboard -> Input Sources - -In your terminal type in: - -`gsettings set org.gnome.desktop.input-sources show-all-sources true` - -after pressing return, try looking under your keyboard settings again as there should be a lot more options available. -As the proper source for help is gnome in this case, here is more information from gnome: - -https://help.gnome.org/users/gnome-help/stable/keyboard-layouts.html.en - [[sect-Keyboard_Configuration-Resources]] == Additional Resources diff --git a/modules/system-administrators-guide/pages/index.adoc b/modules/system-administrators-guide/pages/index.adoc index 26fee82..7bc1045 100644 --- a/modules/system-administrators-guide/pages/index.adoc +++ b/modules/system-administrators-guide/pages/index.adoc @@ -1,3 +1,4 @@ + :experimental: include::{partialsdir}/entities.adoc[] @@ -5,13 +6,6 @@ include::{partialsdir}/entities.adoc[] Deployment, Configuration, and Administration of {MAJOROSVER} -[IMPORTANT] -==== -**Editor's Note** - -_This guide is deprecated!_ Large parts of it are no longer current and it will not receive any updates. A series of shorter, topic-specific documentation will gradually replace it. -==== - [abstract] -- diff --git a/modules/system-administrators-guide/pages/infrastructure-services/OpenSSH.adoc b/modules/system-administrators-guide/pages/infrastructure-services/OpenSSH.adoc index af43707..c3821c3 100644 --- a/modules/system-administrators-guide/pages/infrastructure-services/OpenSSH.adoc +++ b/modules/system-administrators-guide/pages/infrastructure-services/OpenSSH.adoc @@ -4,8 +4,6 @@ include::{partialsdir}/entities.adoc[] [[ch-OpenSSH]] = OpenSSH -:toc: - indexterm:[OpenSSH] `SSH` (Secure Shell) is a protocol which facilitates secure communications between two systems using a client-server architecture and allows users to log into server host systems remotely. Unlike other remote communication protocols, such as `FTP`, `Telnet`, or [command]#rlogin#, SSH encrypts the login session, rendering the connection difficult for intruders to collect unencrypted passwords. @@ -38,9 +36,9 @@ The SSH protocol provides the following safeguards: No one can pose as the intended server:: After an initial connection, the client can verify that it is connecting to the same server it had connected to previously. -No one can capture the authentication information:: The client transmits its authentication information to the server using strong encryption. +No one can capture the authentication information:: The client transmits its authentication information to the server using strong, 128-bit encryption. -No one can intercept the communication:: All data sent and received during a session is transferred using strong encryption, making intercepted transmissions extremely difficult to decrypt and read. +No one can intercept the communication:: All data sent and received during a session is transferred using 128-bit encryption, making intercepted transmissions extremely difficult to decrypt and read. Additionally, it also offers the following options: @@ -55,7 +53,15 @@ It supports Kerberos authentication:: OpenSSH servers and clients can be config [[s2-ssh-versions]] === Protocol Versions indexterm:[SSH protocol,version 1]indexterm:[SSH protocol,version 2] -Two varieties of SSH currently exist: version 1 and version 2. The OpenSSH suite under {MAJOROS} uses SSH version 2, which has an enhanced key exchange algorithm not vulnerable to the known exploit in version 1. Protocol version 1 was removed from OpenSSH suite and is no longer supported. +Two varieties of SSH currently exist: version 1 and version 2. The OpenSSH suite under {MAJOROS} uses SSH version 2, which has an enhanced key exchange algorithm not vulnerable to the known exploit in version 1. However, for compatibility reasons, the OpenSSH suite does support version 1 connections as well, although version 1 is disabled by default and needs to be enabled in the configuration files. + +.Avoid using SSH version 1 +[IMPORTANT] +==== + +To ensure maximum security for your connection, it is recommended that only SSH version 2-compatible servers and clients are used whenever possible. + +==== [[s2-ssh-conn]] === Event Sequence of an SSH Connection @@ -77,15 +83,15 @@ The primary role of the transport layer is to facilitate safe and secure communi Once an SSH client contacts a server, key information is exchanged so that the two systems can correctly construct the transport layer. The following steps occur during this exchange: -* The key exchange algorithm is determined +* Keys are exchanged -* The public key signature algorithm is determined +* The public key encryption algorithm is determined * The symmetric encryption algorithm is determined * The message authentication algorithm is determined -* Keys are exchanged +* The hash algorithm is determined During the key exchange, the server identifies itself to the client with a unique _host key_. If the client has never communicated with this particular server before, the server's host key is unknown to the client and it does not connect. OpenSSH notifies the user that the authenticity of the host cannot be established and prompts the user to accept or reject it. The user is expected to independently verify the new host key before accepting it. In subsequent connections, the server's host key is checked against the saved version on the client, providing confidence that the client is indeed communicating with the intended server. If, in the future, the host key no longer matches, the user must remove the client's saved version before a connection can occur. @@ -99,7 +105,7 @@ It is possible for an attacker to masquerade as an SSH server during the initial SSH is designed to work with almost any kind of public key algorithm or encoding format. After an initial key exchange creates a hash value used for exchanges and a shared secret value, the two systems immediately begin calculating new keys and algorithms to protect authentication and future data sent over the connection. -After a certain amount of data has been transmitted using a given key and algorithm (the exact amount depends on the SSH implementation, encryption algorithm and configuration), another key exchange occurs, generating another set of hash values and a new shared secret value. Even if an attacker is able to determine the hash and shared secret value, this information is only useful for a limited period of time. +After a certain amount of data has been transmitted using a given key and algorithm (the exact amount depends on the SSH implementation), another key exchange occurs, generating another set of hash values and a new shared secret value. Even if an attacker is able to determine the hash and shared secret value, this information is only useful for a limited period of time. [[s2-ssh-protocol-authentication]] ==== Authentication @@ -134,7 +140,7 @@ In order to perform tasks described in this section, you must have superuser pri indexterm:[SSH protocol,configuration files] There are two different sets of configuration files: those for client programs (that is, [command]#ssh#, [command]#scp#, and [command]#sftp#), and those for the server (the [command]#sshd# daemon). indexterm:[SSH protocol,configuration files,system-wide configuration files]indexterm:[SSH protocol,configuration files,user-specific configuration files] -System-wide SSH configuration information is stored in the `/etc/ssh/` directory as described in xref:table-ssh-configuration-configs-system[System-wide configuration files]. User-specific SSH configuration information is stored in `~/.ssh/` within the user's home directory as described in xref:table-ssh-configuration-configs-user[User-specific configuration files]. +System-wide SSH configuration information is stored in the `/etc/ssh/` directory as described in xref:OpenSSH.adoc#table-ssh-configuration-configs-system[System-wide configuration files]. User-specific SSH configuration information is stored in `~/.ssh/` within the user's home directory as described in xref:OpenSSH.adoc#table-ssh-configuration-configs-user[User-specific configuration files]. [[table-ssh-configuration-configs-system]] .System-wide configuration files @@ -142,15 +148,15 @@ System-wide SSH configuration information is stored in the `/etc/ssh/` directory [options="header"] |=== |File|Description -|`/etc/ssh/moduli`|Contains Diffie-Hellman groups used for the "`Diffie-Hellman group exchange`" key exchange method, which is critical for constructing a secure transport layer. When keys are exchanged at the beginning of an SSH session, a shared, secret value is created which cannot be determined by either party alone. If the file is not available, fixed groups will be used. Other key exchange methods do not need this file. +|`/etc/ssh/moduli`|Contains Diffie-Hellman groups used for the Diffie-Hellman key exchange which is critical for constructing a secure transport layer. When keys are exchanged at the beginning of an SSH session, a shared, secret value is created which cannot be determined by either party alone. This value is then used to provide host authentication. |`/etc/ssh/ssh_config`|The default SSH client configuration file. Note that it is overridden by `~/.ssh/config` if it exists. |`/etc/ssh/sshd_config`|The configuration file for the [command]#sshd# daemon. |`/etc/ssh/ssh_host_ecdsa_key`|The ECDSA private key used by the [command]#sshd# daemon. |`/etc/ssh/ssh_host_ecdsa_key.pub`|The ECDSA public key used by the [command]#sshd# daemon. -|`/etc/ssh/ssh_host_rsa_key`|The RSA private key used by the [command]#sshd# daemon. -|`/etc/ssh/ssh_host_rsa_key.pub`|The RSA public key used by the [command]#sshd# daemon. -|`/etc/ssh/ssh_host_ed25519_key`|The EdDSA private key used by the [command]#sshd# daemon. -|`/etc/ssh/ssh_host_ed25519_key.pub`|The EdDSA public key used by the [command]#sshd# daemon. +|`/etc/ssh/ssh_host_key`|The RSA private key used by the [command]#sshd# daemon for version 1 of the SSH protocol. +|`/etc/ssh/ssh_host_key.pub`|The RSA public key used by the [command]#sshd# daemon for version 1 of the SSH protocol. +|`/etc/ssh/ssh_host_rsa_key`|The RSA private key used by the [command]#sshd# daemon for version 2 of the SSH protocol. +|`/etc/ssh/ssh_host_rsa_key.pub`|The RSA public key used by the [command]#sshd# daemon for version 2 of the SSH protocol. |`/etc/pam.d/sshd`|The PAM configuration file for the [command]#sshd# daemon. |`/etc/sysconfig/sshd`|Configuration file for the `sshd` service. |=== @@ -164,10 +170,10 @@ System-wide SSH configuration information is stored in the `/etc/ssh/` directory |`~/.ssh/authorized_keys`|Holds a list of authorized public keys for servers. When the client connects to a server, the server authenticates the client by checking its signed public key stored within this file. |`~/.ssh/id_ecdsa`|Contains the ECDSA private key of the user. |`~/.ssh/id_ecdsa.pub`|The ECDSA public key of the user. -|`~/.ssh/id_rsa`|The RSA private key used by [command]#ssh#. -|`~/.ssh/id_rsa.pub`|The RSA public key used by [command]#ssh#. -|`~/.ssh/id_ed25519`|The EdDSA private key used by [command]#ssh#. -|`~/.ssh/id_ed25519.pub`|The EdDSA public key used by [command]#ssh#. +|`~/.ssh/id_rsa`|The RSA private key used by [command]#ssh# for version 2 of the SSH protocol. +|`~/.ssh/id_rsa.pub`|The RSA public key used by [command]#ssh# for version 2 of the SSH protocol. +|`~/.ssh/identity`|The RSA private key used by [command]#ssh# for version 1 of the SSH protocol. +|`~/.ssh/identity.pub`|The RSA public key used by [command]#ssh# for version 1 of the SSH protocol. |`~/.ssh/known_hosts`|Contains host keys of SSH servers accessed by the user. This file is very important for ensuring that the SSH client is connecting to the correct SSH server. |=== @@ -221,7 +227,7 @@ Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. ---- -To prevent this, you can backup the relevant files from the `/etc/ssh/` directory (see xref:table-ssh-configuration-configs-system[System-wide configuration files] for a complete list), and restore them whenever you reinstall the system. +To prevent this, you can backup the relevant files from the `/etc/ssh/` directory (see xref:OpenSSH.adoc#table-ssh-configuration-configs-system[System-wide configuration files] for a complete list), and restore them whenever you reinstall the system. [[s2-ssh-configuration-requiring]] === Requiring SSH for Remote Connections @@ -253,18 +259,18 @@ See xref:infrastructure-services/Services_and_Daemons.adoc#ch-Services_and_Daemo [[s2-ssh-configuration-keypairs]] === Using Key-based Authentication indexterm:[OpenSSH,using key-based authentication] -To improve the system security even further, generate SSH key pairs and then enforce key-based authentication by disabling password authentication. To do so, create a drop-in configuration file, for example `/etc/ssh/sshd_config.d/01-local.conf`. Make sure it is lexicographically before the `50-redhat.conf` file, providing Fedora defaults. In a text editor such as [application]*vi* or [application]*nano* insert the [option]`PasswordAuthentication` option as follows: +To improve the system security even further, generate SSH key pairs and then enforce key-based authentication by disabling password authentication. To do so, open the `/etc/ssh/sshd_config` configuration file in a text editor such as [application]*vi* or [application]*nano*, and change the [option]`PasswordAuthentication` option as follows: [subs="quotes"] ---- PasswordAuthentication no ---- -If you are working on a system other than a new default installation, check that [command]#PubkeyAuthentication no# has *not* been set in neither `/etc/ssh/sshd_config` nor any included file from drop-in directory. If connected remotely, not using console or out-of-band access, testing the key-based log in process before disabling password authentication is advised. +If you are working on a system other than a new default installation, check that [command]#PubkeyAuthentication no# has *not* been set. If connected remotely, not using console or out-of-band access, testing the key-based log in process before disabling password authentication is advised. To be able to use [command]#ssh#, [command]#scp#, or [command]#sftp# to connect to the server from a client machine, generate an authorization key pair by following the steps below. Note that keys must be generated for each user separately. -{MAJOROSVER} uses SSH Protocol 2 and RSA keys by default (see xref:s2-ssh-versions[Protocol Versions] for more information). +{MAJOROSVER} uses SSH Protocol 2 and RSA keys by default (see xref:OpenSSH.adoc#s2-ssh-versions[Protocol Versions] for more information). .Do not generate key pairs as root [IMPORTANT] @@ -307,7 +313,7 @@ After this, you will be presented with a message similar to this: Your identification has been saved in /home/USER/.ssh/id_rsa. Your public key has been saved in /home/USER/.ssh/id_rsa.pub. The key fingerprint is: -SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 USER@penguin.example.com +e7:97:c7:e2:0e:f9:0e:fc:c4:d7:cb:e5:31:11:92:14 USER@penguin.example.com The key's randomart image is: +--[ RSA 2048]----+ | E. | @@ -368,7 +374,7 @@ After this, you will be presented with a message similar to this: Your identification has been saved in /home/USER/.ssh/id_ecdsa. Your public key has been saved in /home/USER/.ssh/id_ecdsa.pub. The key fingerprint is: -SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 USER@penguin.example.com +fd:1d:ca:10:52:96:21:43:7e:bd:4c:fc:5b:35:6b:63 USER@penguin.example.com The key's randomart image is: +--[ECDSA 256]---+ | .+ +o | @@ -407,7 +413,7 @@ ssh-copy-id -i ~/.ssh/id_ecdsa.pub USER@hostname + This will copy the content of `~/.ssh/id_ecdsa.pub` into the `~/.ssh/authorized_keys` on the machine to which you want to connect. If the file already exists, the keys are appended to its end. -See xref:s3-ssh-configuration-keypairs-agent[Configuring ssh-agent] for information on how to set up your system to remember the passphrase. +See xref:OpenSSH.adoc#s3-ssh-configuration-keypairs-agent[Configuring ssh-agent] for information on how to set up your system to remember the passphrase. .Never share your private key [IMPORTANT] @@ -451,7 +457,7 @@ Support for certificate authentication of users and hosts using the new OpenSSH ---- ~]# dnf install openssh -Last metadata expiration check performed 0:58:01 ago on Sun Sep 6 16:07:22 2020. +Last metadata expiration check performed 0:58:01 ago on Sun Sep 6 16:07:22 2015. Package openssh-7.1p1-1.fc23.x86_64 is already installed, skipping. ---- @@ -508,7 +514,7 @@ Enter same passphrase again: Your identification has been saved in /root/.ssh/ca_user_key. Your public key has been saved in /root/.ssh/ca_user_key.pub. The key fingerprint is: -SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 root@host_name.example.com +11:14:2f:32:fd:5d:f5:e4:7a:5a:d6:b6:a0:62:c9:1f root@host_name.example.com The key's randomart image is: +--[ RSA 2048]----+ | .+. o| @@ -533,7 +539,7 @@ Enter same passphrase again: Your identification has been saved in /root/.ssh/ca_host_key. Your public key has been saved in /root/.ssh/ca_host_key.pub. The key fingerprint is: -SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 root@host_name.example.com +e4:d5:d1:4f:6b:fd:a2:e3:4e:5a:73:52:91:0b:b7:7a root@host_name.example.com The key's randomart image is: +--[ RSA 2048]----+ | .. | @@ -579,7 +585,7 @@ For example: ---- ~]# ssh-keygen -s ~/.ssh/ca_host_key -I host_name -h -n host_name.example.com -V -1w:+54w5d /etc/ssh/ssh_host_rsa.pub Enter passphrase: -Signed host key /root/.ssh/ssh_host_rsa-cert.pub: id "host_name" serial 0 for host_name.example.com valid from 2020-05-15T13:52:29 to 2021-06-08T13:52:29 +Signed host key /root/.ssh/ssh_host_rsa-cert.pub: id "host_name" serial 0 for host_name.example.com valid from 2015-05-15T13:52:29 to 2016-06-08T13:52:29 ---- [[sec-Distributing_and_Trusting_SSH_CA_Public_Keys]] @@ -599,9 +605,9 @@ Where _host_name_ is the host name of a server the is required to authenticate u ---- ~]# scp ~/.ssh/ca_user_key.pub root@host_name.example.com:/etc/ssh/ The authenticity of host 'host_name.example.com (10.34.74.56)' can't be established. -ECDSA key fingerprint is SHA256:ZYEUaevOAEASvYjm58PiPdMebxhhlaTZBjTMr/N2I3c. -Are you sure you want to continue connecting (yes/no/[fingerprint])? yes -Warning: Permanently added 'host_name.example.com,10.34.74.56' (ECDSA) to the list of known hosts. +RSA key fingerprint is fc:23:ad:ae:10:6f:d1:a1:67:ee:b1:d5:37:d4:b0:2f. +Are you sure you want to continue connecting (yes/no)? yes +Warning: Permanently added 'host_name.example.com,10.34.74.56' (RSA) to the list of known hosts. root@host_name.example.com's password: ca_user_key.pub 100% 420 0.4KB/s 00:00 ---- @@ -619,7 +625,7 @@ TrustedUserCAKeys /etc/ssh/ca_user_key.pub Restart `sshd` to make the changes take effect: + ---- -~]#{nbsp}systemctl restart sshd.service +~]# service sshd restart ---- To avoid being presented with the warning about an unknown host, a user's system must trust the CA's public key that was used to sign the host certificates. In this example that is `ca_host_key.pub`. @@ -648,7 +654,7 @@ Where `ssh-rsa _AAAAB5Wm._pass:attributes[{blank}]` is the contents of `ca_host_ [[sec-Signing_SSH_Certificates]] === Creating SSH Certificates -A certificate is a signed public key. The user's and host's public keys must be copied to the CA server for signing by the CA server's private key. +A certifcate is a signed public key. The user's and host's public keys must be copied to the CA server for signing by the CA server's private key. [IMPORTANT] ==== @@ -707,8 +713,8 @@ To authenticate a host to a user, a public key must be generated on the host, pa ---- ~]# scp /etc/ssh/ssh_host_rsa_key.pub admin@ca-server.example.com:~/keys/ssh_host_rsa_key.pub The authenticity of host 'ca-server.example.com (10.34.74.58)' can't be established. -ECDSA key fingerprint is SHA256:ZYEUaevOAEASvYjm58PiPdMebxhhlaTZBjTMr/N2I3c. -Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +RSA key fingerprint is b0:e5:ea:b8:75:e2:f0:b1:fe:5b:07:39:7f:58:64:d9. +Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'ca-server.example.com,10.34.74.58' (RSA) to the list of known hosts. admin@ca-server.example.com's password: ssh_host_rsa_key.pub 100% 382 0.4KB/s 00:00 @@ -725,7 +731,7 @@ Alternately, from the CA: ---- ~]# ssh-keygen -s ~/.ssh/ca_host_key -I host_name -h -n host_name.example.com -V -1d:+54w /home/admin/keys/ssh_host_rsa_key.pub Enter passphrase: -Signed host key /home/admin/keys/ssh_host_rsa_key-cert.pub: id "host_name" serial 0 for host_name.example.com valid from 2020-05-26T12:21:54 to 2021-06-08T12:21:54 +Signed host key /home/admin/keys/ssh_host_rsa_key-cert.pub: id "host_name" serial 0 for host_name.example.com valid from 2015-05-26T12:21:54 to 2016-06-08T12:21:54 ---- + Where _host_name_ is the host name of the system requiring the certificate. @@ -747,12 +753,12 @@ HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub . Restart `sshd` to make the changes take effect: + ---- -~]#{nbsp}systemctl restart sshd.service +~]# service sshd restart ---- -. On user's systems, remove keys belonging to hosts from the `~/.ssh/known_hosts` file if the user has previously logged into the host configured above. When a user logs into the host they should no longer be presented with the warning about the hosts authenticity. +. On user's systems. remove keys belonging to hosts from the `~/.ssh/known_hosts` file if the user has previously logged into the host configured above. When a user logs into the host they should no longer be presented with the warning about the hosts authenticity. -To test the host certificate, on a client system, ensure the client has set up the global `/etc/ssh/known_hosts` file, as described in xref:proc-Trusting_the_Host_Signing_Key[Trusting the Host Signing Key], and that the server's public key is not in the `~/.ssh/known_hosts` file. Then attempt to log into the server over SSH as a remote user. You should not see a warning about the authenticity of the host. If required, add the [option]`-v` option to the SSH command to see logging information. +To test the host certificate, on a client system, ensure the client has set up the global `/etc/ssh/known_hosts` file, as described in xref:OpenSSH.adoc#proc-Trusting_the_Host_Signing_Key[Trusting the Host Signing Key], and that the server's public key is not in the `~/.ssh/known_hosts` file. Then attempt to log into the server over SSH as a remote user. You should not see a warning about the authenticity of the host. If required, add the [option]`-v` option to the SSH command to see logging information. [[sec-Creating_SSH_Certificates_for_Authenticating_Users]] ==== Creating SSH Certificates for Authenticating Users @@ -784,7 +790,7 @@ The default behavior of OpenSSH is that a user is allowed to log in as a remote @cert-authority principals="name1,name2" *.example.com ssh-rsa pass:quotes[_AAAAB5Wm._] ---- -* On the server, create an `AuthorizedPrincipalsFile` file, either per user or globally, and add the principles' names to the file for those users allowed to log in. Then in the `/etc/ssh/sshd_config` file, specify the file using the [command]#AuthorizedPrincipalsFile# directive. +* On the server, create an `AuthorizedPrincipalsFile` file, either per user or glabally, and add the principles' names to the file for those users allowed to log in. Then in the `/etc/ssh/sshd_config` file, specify the file using the [command]#AuthorizedPrincipalsFile# directive. [[proc-Generating_a_User_Certificate]] .Generating a User Certificate @@ -809,7 +815,7 @@ Enter same passphrase again: Your identification has been saved in /home/user1/.ssh/id_rsa. Your public key has been saved in /home/user1/.ssh/id_rsa.pub. The key fingerprint is: -SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 user1@host1.example.com +b1:f8:26:a7:46:87:c3:60:54:a3:6d:85:0d:60:fe:ce user1@host1.example.com The key's randomart image is: +--[ RSA 2048]----+ | oo++. | @@ -835,7 +841,7 @@ drwx------. 3 user1 user1 4096 May 7 12:37 .. -rw-r--r--. 1 user1 user1 421 May 7 12:37 id_rsa.pub ---- + -See xref:s2-ssh-configuration-keypairs[Using Key-based Authentication] for more examples of key generation and for instructions on setting the correct directory permissions. +See xref:OpenSSH.adoc#s2-ssh-configuration-keypairs[Using Key-based Authentication] for more examples of key generation and for instructions on setting the correct directory permissions. . The chosen public key must be copied to the server designated as the CA, in order to be signed. The secure copy command can be used to do this, the command has the following format: + @@ -854,14 +860,14 @@ admin@ca-server.example.com's password: id_rsa.pub 100% 421 0.4KB/s 00:00 ---- + -If you have configured the client system to trust the host signing key as described in xref:proc-Trusting_the_Host_Signing_Key[Trusting the Host Signing Key] then you should not see a warning about the authenticity of the remote host. +If you have configured the client system to trust the host signing key as described in xref:OpenSSH.adoc#proc-Trusting_the_Host_Signing_Key[Trusting the Host Signing Key] then you should not see a warning about the authenticity of the remote host. . On the CA server, sign the user's public key. For example, as `root`: + ---- ~]# ssh-keygen -s ~/.ssh/ca_user_key -I user1 -n user1 -V -1d:+54w /home/admin/keys/id_rsa.pub Enter passphrase: -Signed user key /home/admin/keys/id_rsa-cert.pub: id "user1" serial 0 for host_name.example.com valid from 2020-05-21T16:43:17 to 2021-06-03T16:43:17 +Signed user key /home/admin/keys/id_rsa-cert.pub: id "user1" serial 0 for host_name.example.com valid from 2015-05-21T16:43:17 to 2016-06-03T16:43:17 ---- . Copy the resulting certificate to the user's `~/.ssh/` directory on their system. For example: @@ -907,7 +913,7 @@ It is possible to sign a host key using a CA key stored in a PKCS#11 token by pr ssh-keygen -s ca_host_key.pub -D libpkcs11.so -I pass:quotes[_certificate_ID_] host_key.pub ---- -In all cases, _certificate_ID_ is a "`key identifier`" that is logged by the server when the certificate is used for authentication. +In all cases, _certificate_ID_ is a "key identifier" that is logged by the server when the certificate is used for authentication. Certificates may be configured to be valid only for a set of users or host names, the principals. By default, generated certificates are valid for all users or hosts. To generate a certificate for a specified set of principals, use a comma separated list with the [option]`-n` option as follows: @@ -933,7 +939,7 @@ start and end times. For example: [subs="macros"] ---- -ssh-keygen -s ca_user_key -I pass:quotes[_certificate_ID_] -V "-1w:+54w5d" id_rsa.pub +ssh-keygen -s ca_user_key -I pass:quotes[_certificate_ID_] id_rsa.pub -V "-1w:+54w5d" ---- A certificate that is presented at a time outside this range will not be considered valid. @@ -948,11 +954,11 @@ To view a certificate, use the [option]`-L` to list the contents. For example, f ~]$ ssh-keygen -L -f ~/.ssh/id_rsa-cert.pub /home/user1/.ssh/id_rsa-cert.pub: Type: ssh-rsa-cert-v01@openssh.com user certificate - Public key: RSA-CERT SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 - Signing CA: RSA SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 + Public key: RSA-CERT 3c:9d:42:ed:65:b6:0f:18:bf:52:77:c6:02:0e:e5:86 + Signing CA: RSA b1:8e:0b:ce:fe:1b:67:59:f1:74:cd:32:af:5f:c6:e8 Key ID: "user1" Serial: 0 - Valid: from 2020-05-27T00:09:16 to 2021-06-09T00:09:16 + Valid: from 2015-05-27T00:09:16 to 2016-06-09T00:09:16 Principals: user1 Critical Options: (none) @@ -964,17 +970,17 @@ To view a certificate, use the [option]`-L` to list the contents. For example, f permit-user-rc ---- -To view a host certificate: +To vew a host certificate: ---- ~]# ssh-keygen -L -f /etc/ssh/ssh_host_rsa_key-cert.pub /etc/ssh/ssh_host_rsa_key-cert.pub: Type: ssh-rsa-cert-v01@openssh.com host certificate - Public key: RSA-CERT SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 - Signing CA: RSA SHA256:y6f0DGlHe28YWotEypnhfk3WLYQ5TgaQwoSlOFwmmm0 + Public key: RSA-CERT 1d:71:61:50:05:9b:ec:64:34:27:a5:cc:67:24:03:23 + Signing CA: RSA e4:d5:d1:4f:6b:fd:a2:e3:4e:5a:73:52:91:0b:b7:7a Key ID: "host_name" Serial: 0 - Valid: from 2020-05-26T17:19:01 to 2021-06-08T17:19:01 + Valid: from 2015-05-26T17:19:01 to 2016-06-08T17:19:01 Principals: host_name.example.com Critical Options: (none) @@ -1067,8 +1073,8 @@ The first time you initiate a connection, you will be presented with a message s [subs="quotes"] ---- The authenticity of host 'penguin.example.com' can't be established. -ECDSA key fingerprint is SHA256:ZYEUaevOAEASvYjm58PiPdMebxhhlaTZBjTMr/N2I3c. -Are you sure you want to continue connecting (yes/no/[fingerprint])? +ECDSA key fingerprint is 256 da:24:43:0b:2e:c1:3f:a1:84:13:92:01:52:b4:84:ff. +Are you sure you want to continue connecting (yes/no)? ---- Users should always check if the fingerprint is correct before answering the question in this dialog. The user can ask the administrator of the server to confirm the key is correct. This should be done in a secure and previously agreed way. If the user has access to the server's host keys, the fingerprint can be checked by using the [command]#ssh-keygen# command as follows: @@ -1076,7 +1082,7 @@ Users should always check if the fingerprint is correct before answering the que [subs="attributes"] ---- ~]#{nbsp}ssh-keygen -l -f /etc/ssh/ssh_host_ecdsa_key.pub -256 SHA256:ZYEUaevOAEASvYjm58PiPdMebxhhlaTZBjTMr/N2I3c no comment (ECDSA) +256 da:24:43:0b:2e:c1:3f:a1:84:13:92:01:52:b4:84:ff (ECDSA) ---- Type `yes` to accept the key and confirm the connection. You will see a notice that the server has been added to the list of known hosts, and a prompt asking for your password: @@ -1120,7 +1126,7 @@ For example, the `/etc/redhat-release` file provides information about the {MAJO ---- ~]${nbsp}pass:attributes[{blank}][command]#ssh USER@penguin.example.com cat /etc/redhat-release# USER@penguin.example.com's password: -Fedora release 31 (Thirty One) +Fedora release 20 (Heisenbug) ---- After you enter the correct password, the user name will be displayed, and you will return to your local shell prompt. @@ -1173,16 +1179,10 @@ USER@penguin.example.com's password: .vimrc 100% 2233 2.2KB/s 00:00 ---- -[IMPORTANT] -==== - -The SCP protocol is not well designed and can cause unexpected results. In the past it was source of several CVEs where malicious server could override files in local filesystem when downloading files. It is recommended to use SFTP when possible. See the next section for more information. - -==== [[s2-ssh-clients-sftp]] === Using the [command]#sftp# Utility indexterm:[sftp,OpenSSH]indexterm:[OpenSSH,client,sftp] -The [command]#sftp# utility can be used to open a secure, interactive SFTP session. In its design, it is similar to [command]#ftp# except that it uses a secure, encrypted connection. +The [command]#sftp# utility can be used to open a secure, interactive FTP session. In its design, it is similar to [command]#ftp# except that it uses a secure, encrypted connection. To connect to a remote system, use a command in the following form: @@ -1212,7 +1212,7 @@ After you enter the correct password, you will be presented with a prompt. The [ |[command]#ls# [pass:attributes[{blank}]_directory_pass:attributes[{blank}]]|List the content of a remote _directory_. If none is supplied, a current working directory is used by default. |[command]#cd# _directory_|Change the remote working directory to _directory_. |[command]#mkdir# _directory_|Create a remote _directory_. -|[command]#rmdir# _directory_|Remove a remote _directory_. +|[command]#rmdir# _path_|Remove a remote _directory_. |[command]#put# _localfile_ [pass:attributes[{blank}]_remotefile_pass:attributes[{blank}]]|Transfer _localfile_ to a remote machine. |[command]#get# _remotefile_ [pass:attributes[{blank}]_localfile_pass:attributes[{blank}]]|Transfer _remotefile_ from a remote machine. |=== diff --git a/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.adoc b/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.adoc index 400ac77..8b1a354 100644 --- a/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.adoc +++ b/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.adoc @@ -291,7 +291,7 @@ When you install a kernel using [command]#rpm#, the kernel package creates an en It is always recommended to double-check the boot loader configuration file after installing a new kernel with [command]#rpm# to ensure that the configuration is correct. Otherwise, the system might not be able to boot into {MAJOROS} properly. If this happens, boot the system with the boot media created earlier and re-configure the boot loader. -In the following table, find your system's architecture to determine the boot loader it uses, and then click on the "`See`" link to jump to the correct instructions for your system. +In the following table, find your system's architecture to determine the boot loader it uses, and then click on the "See" link to jump to the correct instructions for your system. [[tb-grub-arch-loaders]] .Boot loaders by architecture diff --git a/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_Kernel_Modules.adoc b/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_Kernel_Modules.adoc index efb9c65..a36afe6 100644 --- a/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_Kernel_Modules.adoc +++ b/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_Kernel_Modules.adoc @@ -399,7 +399,8 @@ In order to enable signing of externally built modules, the tools listed in the |=== |Tool|Provided by Package|Used on|Purpose |[command]#openssl#|[package]*openssl*|Build system|Generates public and private X.509 key pair -|[command]#sign-file#|[package]*kernel-devel*|Build system|C application used to sign kernel modules +|[command]#sign-file#|[package]*kernel-devel*|Build system|Perl script used to sign kernel modules +|[command]#perl#|[package]*perl*|Build system|Perl interpreter used to run the signing script |[command]#mokutil#|[package]*mokutil*|Target system|Optional tool used to manually enroll the public key |[command]#keyctl#|[package]*keyutils*|Target system|Optional tool used to display public keys in the system key ring |=== @@ -428,11 +429,11 @@ During boot, the kernel loads X.509 keys into the system key ring or the system |=== |Source of X.509 Keys|User Ability to Add Keys|UEFI Secure Boot State|Keys Loaded During Boot |Embedded in kernel|No|-|`.system_keyring` -.2+|UEFI Secure Boot "`db`" +.2+|UEFI Secure Boot "db" .2+|Limited |Not enabled|No |Enabled|`.system_keyring` -.2+|UEFI Secure Boot "`dbx`" +.2+|UEFI Secure Boot "dbx" .2+|Limited |Not enabled|No |Enabled|`.system_keyring` @@ -480,7 +481,7 @@ The following is abbreviated example output from a Fedora system where UEFI Secu ...asymmetric: Microsoft Corporation UEFI CA 2011: 13adbf4309bd82709c8... ---- -The above output shows the addition of two keys from the UEFI Secure Boot "`db`" keys plus the `Fedora Secure Boot CA` which is embedded in the `shim.efi` boot loader. +The above output shows the addition of two keys from the UEFI Secure Boot "db" keys plus the `Fedora Secure Boot CA` which is embedded in the `shim.efi` boot loader. [[sect-kernel-module-authentication-requirements]] ==== Kernel Module Authentication Requirements @@ -616,18 +617,18 @@ There are no extra steps required to prepare your kernel module for signing. You ~]#{nbsp}make -C /usr/src/kernels/$(uname -r) M=$PWD modules ---- -. Sign your kernel module with your private key. This is done with a C application. Note that the application requires that you provide both the files that contain your private and the public key as well as the kernel module file that you want to sign. +. Sign your kernel module with your private key. This is done with a Perl script. Note that the script requires that you provide both the files that contain your private and the public key as well as the kernel module file that you want to sign. + [subs="attributes"] ---- -~]#{nbsp}/usr/src/kernels/$(uname -r)/scripts/sign-file \ +~]#{nbsp}perl /usr/src/kernels/$(uname -r)/scripts/sign-file \ sha256 \ my_signing_key.priv \ my_signing_key_pub.der \ my_module.ko ---- -Your kernel module is in ELF image format and this application computes and appends the signature directly to the ELF image in your `my_module.ko` file. The [command]#modinfo# utility can be used to display information about the kernel module's signature, if it is present. For information on using the utility, see xref:Working_with_Kernel_Modules.adoc#sec-Displaying_Information_About_a_Module[Displaying Information About a Module]. +Your kernel module is in ELF image format and this script computes and appends the signature directly to the ELF image in your `my_module.ko` file. The [command]#modinfo# utility can be used to display information about the kernel module's signature, if it is present. For information on using the utility, see xref:Working_with_Kernel_Modules.adoc#sec-Displaying_Information_About_a_Module[Displaying Information About a Module]. Note that this appended signature is not contained in an ELF image section and is not a formal part of the ELF image. Therefore, tools such as [command]#readelf# will not be able to display the signature on your kernel module. diff --git a/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc b/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc index 77e2760..ce0ac3c 100644 --- a/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc +++ b/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc @@ -1,27 +1,20 @@ + :experimental: include::{partialsdir}/entities.adoc[] [[ch-Working_with_the_GRUB_2_Boot_Loader]] = Working with the GRUB 2 Boot Loader - -[IMPORTANT] -==== -**Editor’s Note** - -_This guide is deprecated!_ Large parts of it are no longer current and it will not receive any updates. A series of shorter, topic-specific documentation will gradually replace it. -For additional information about Grub version 2 on Fedora see https://docs.fedoraproject.org/en-US/quick-docs/installing-grub2/[Bootloading with GRUB2]. -==== - +indexterm:[GRUB 2,configuring GRUB 2]indexterm:[GRUB 2,reinstalling GRUB 2]indexterm:[GRUB 2,customizing GRUB 2]indexterm:[boot loader,GRUB 2 boot loader] {MAJOROSVER} is distributed with the GNU GRand Unified Boot loader (GRUB) version 2 boot loader, which allows the user to select an operating system or kernel to be loaded at system boot time. GRUB 2 also allows the user to pass arguments to the kernel. [[sec-Introduction_to_GRUB_2]] == Introduction to GRUB 2 -GRUB 2 reads its configuration from the `/boot/grub2/grub.cfg` file. This file contains menu information. +GRUB 2 reads its configuration from the `/boot/grub2/grub.cfg` file on traditional BIOS-based machines and from the `/boot/efi/EFI/fedora/grub.cfg` file on UEFI machines. This file contains menu information. The GRUB 2 configuration file, `grub.cfg`, is generated during installation, or by invoking the [application]*/usr/sbin/grub2-mkconfig* utility, and is automatically updated by [command]#grubby# each time a new kernel is installed. When regenerated manually using [application]*grub2-mkconfig*, the file is generated according to the template files located in `/etc/grub.d/`, and custom settings in the `/etc/default/grub` file. Edits of `grub.cfg` will be lost any time [application]*grub2-mkconfig* is used to regenerate the file, so care must be taken to reflect any manual changes in `/etc/default/grub` as well. -Normal operations on `grub.cfg`, such as the removal and addition of new kernels, should be done using the [command]#grubby# tool and, for scripts, using [command]#new-kernel-pkg# tool. If you use [command]#grubby# to modify the default kernel the changes will be inherited when new kernels are installed. For more information on [command]#grubby#, see xref:#sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool[Making Persistent Changes to a GRUB 2 Menu Using the grubby Tool]. +Normal operations on `grub.cfg`, such as the removal and addition of new kernels, should be done using the [command]#grubby# tool and, for scripts, using [command]#new-kernel-pkg# tool. If you use [command]#grubby# to modify the default kernel the changes will be inherited when new kernels are installed. For more information on [command]#grubby#, see xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool[Making Persistent Changes to a GRUB 2 Menu Using the grubby Tool]. The `/etc/default/grub` file is used by the [command]#grub2-mkconfig# tool, which is used by `anaconda` when creating `grub.cfg` during the installation process, and can be used in the event of a system failure, for example if the boot loader configurations need to be recreated. In general, it is not recommended to replace the `grub.cfg` file by manually running `grub2-mkconfig` except as a last resort. Note that any manual changes to `/etc/default/grub` require rebuilding the `grub.cfg` file. @@ -66,11 +59,11 @@ For information on using [application]*Dracut*, see xref:kernel-module-driver-co Changes to the GRUB 2 menu can be made temporarily at boot time, made persistent for a single system while the system is running, or as part of making a new GRUB 2 configuration file. -* To make non-persistent changes to the GRUB 2 menu, see xref:#sec-Making_Temporary_Changes_to_a_GRUB_2_Menu[Making Temporary Changes to a GRUB 2 Menu]. +* To make non-persistent changes to the GRUB 2 menu, see xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Making_Temporary_Changes_to_a_GRUB_2_Menu[Making Temporary Changes to a GRUB 2 Menu]. -* To make persistent changes to a running system, see xref:#sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool[Making Persistent Changes to a GRUB 2 Menu Using the grubby Tool]. +* To make persistent changes to a running system, see xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool[Making Persistent Changes to a GRUB 2 Menu Using the grubby Tool]. -* For information on making and customizing a GRUB 2 configuration file, see xref:#sec-Customizing_the_GRUB_2_Configuration_File[Customizing the GRUB 2 Configuration File]. +* For information on making and customizing a GRUB 2 configuration file, see xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Customizing_the_GRUB_2_Configuration_File[Customizing the GRUB 2 Configuration File]. [[sec-Making_Temporary_Changes_to_a_GRUB_2_Menu]] == Making Temporary Changes to a GRUB 2 Menu @@ -96,7 +89,7 @@ linux16 /vmlinuz-4.2.0-1.fc23.x86_64 root=/dev/mapper/fedora-root ro rd.md= The [option]`rhgb` and [option]`quiet` parameters can be removed in order to enable system messages. -These settings are not persistent and apply only for a single boot. To make persistent changes to a menu entry on a system, use the [command]#grubby# tool. See xref:#bh-Adding_and_Removing_Arguments_from_a_GRUB_Menu_Entry[Adding and Removing Arguments from a GRUB Menu Entry] for more information on using [command]#grubby#. +These settings are not persistent and apply only for a single boot. To make persistent changes to a menu entry on a system, use the [command]#grubby# tool. See xref:Working_with_the_GRUB_2_Boot_Loader.adoc#bh-Adding_and_Removing_Arguments_from_a_GRUB_Menu_Entry[Adding and Removing Arguments from a GRUB Menu Entry] for more information on using [command]#grubby#. [[sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool]] == Making Persistent Changes to a GRUB 2 Menu Using the grubby Tool @@ -206,16 +199,6 @@ title=Fedora (4.2.0-1.fc23.x86_64) 23 (Workstation Edition) See the `grubby(8)` manual page for more command options. -.Adding a new entry with additional kernel arguments -To add a new entry with the default kernel but with additional kernel arguments and make it the default entry, use: - -[subs="macros"] ----- -~]# grubby --add-kernel $(grubby --default-kernel) --copy-default --args=crashkernel=128M --title "Default kernel with kdump support" --make-default ----- - -In this example, we set the `crashkernel=128M` argument for kdump support. - [[sec-Customizing_the_GRUB_2_Configuration_File]] == Customizing the GRUB 2 Configuration File @@ -284,13 +267,20 @@ The file name `/etc/grub2.cfg` is a symlink to the `grub.cfg` file, whose locati Changes to `/etc/default/grub` require rebuilding the `grub.cfg` file as follows: -* On both UEFI-based and BIOS-based machines, issue the following command as `root`: +* On BIOS-based machines, issue the following command as `root`: [subs="attributes"] ---- ~]#{nbsp}grub2-mkconfig -o /boot/grub2/grub.cfg ---- +* On UEFI-based machines, issue the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg +---- + [[sec-Editing_a_Menu_Entry]] === Editing a Menu Entry @@ -304,13 +294,20 @@ Where [option]`console=tty0` is the first virtual terminal and [option]`console= Changes to `/etc/default/grub` require rebuilding the `grub.cfg` file as follows: -* On both UEFI-based and BIOS-based machines, issue the following command as `root`: +* On BIOS-based machines, issue the following command as `root`: [subs="attributes"] ---- ~]#{nbsp}grub2-mkconfig -o /boot/grub2/grub.cfg ---- +* On UEFI-based machines, issue the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg +---- + [[sec-Adding_a_new_Entry]] === Adding a new Entry @@ -354,9 +351,9 @@ Note that modifying the `/etc/default/grub` file does not have any effect on cre ==== -. Copy the contents of `/boot/grub2/grub.cfg`. Put the content of the `grub.cfg` into the `/etc/grub.d/40_custom` file below the existing header lines. The executable part of the `40_custom` script has to be preserved. +. On BIOS-based machines, copy the contents of `/boot/grub2/grub.cfg`, or, on UEFI machines, copy the contents of `/boot/efi/EFI/fedora/grub.cfg`. Put the content of the `grub.cfg` into the `/etc/grub.d/40_custom` file below the existing header lines. The executable part of the `40_custom` script has to be preserved. -. From the content put into the `/etc/grub.d/40_custom` file, only the `menuentry` blocks are needed to create the custom menu. The `/boot/grub2/grub.cfg` file might contain function specifications and other content above and below the `menuentry` blocks. If you put these unnecessary lines into the `40_custom` file in the previous step, erase them. +. From the content put into the `/etc/grub.d/40_custom` file, only the `menuentry` blocks are needed to create the custom menu. The `/boot/grub2/grub.cfg` and `/boot/efi/EFI/fedora/grub.cfg` files might contain function specifications and other content above and below the `menuentry` blocks. If you put these unnecessary lines into the `40_custom` file in the previous step, erase them. This is an example of a custom `40_custom` script: @@ -414,17 +411,24 @@ Alternatively, if you want to keep the files in the `/etc/grub2.d/` directory, m . Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows: -* On both UEFI-based and BIOS-based machines, issue the following command as `root`: +** On BIOS-based machines, issue the following command as `root`: [subs="attributes"] ---- ~]#{nbsp}grub2-mkconfig -o /boot/grub2/grub.cfg ---- +** On UEFI-based machines, issue the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg +---- + [[sec-GRUB_2_Password_Protection]] == GRUB 2 Password Protection -GRUB 2 supports both plain-text and encrypted passwords in the GRUB 2 template files. To enable the use of passwords, specify a superuser who can reach the protected entries. Other users can be specified to access these entries as well. Menu entries can be password-protected for booting by adding one or more users to the menu entry as described in xref:#sec-Setting_Up_Users_and_Password_Protection_Specifying_Menu_Entries[Setting Up Users and Password Protection, Specifying Menu Entries]. To use encrypted passwords, see xref:#sec-Password_Encryption[Password Encryption]. +GRUB 2 supports both plain-text and encrypted passwords in the GRUB 2 template files. To enable the use of passwords, specify a superuser who can reach the protected entries. Other users can be specified to access these entries as well. Menu entries can be password-protected for booting by adding one or more users to the menu entry as described in xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Setting_Up_Users_and_Password_Protection_Specifying_Menu_Entries[Setting Up Users and Password Protection, Specifying Menu Entries]. To use encrypted passwords, see xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Password_Encryption[Password Encryption]. [WARNING] ==== @@ -494,13 +498,20 @@ After you have made changes in the template file the GRUB 2 configuration file m Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows: -* On both UEFI-based and BIOS-based machines, issue the following command as `root`: +* On BIOS-based machines, issue the following command as `root`: [subs="attributes"] ---- ~]#{nbsp}grub2-mkconfig -o /boot/grub2/grub.cfg ---- +* On UEFI-based machines, issue the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg +---- + [[sec-Password_Encryption]] === Password Encryption @@ -539,18 +550,6 @@ Reinstalling GRUB 2 is a convenient way to fix certain problems usually caused b * Adding the boot information to another drive. -[[Discovering-the_firmware_type]] -=== Discovering the firmware type === - -To discover what firmware your machine uses, run the following command: - -[subs="attributes"] ----- -~]#{nbsp}[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS ----- - -The output returns only UEFI or BIOS, depending on the firmware your machine runs. - [[sec-grub2-reinstall_on_BIOS-Based_Machines]] === Reinstalling GRUB 2 on BIOS-Based Machines @@ -593,14 +592,21 @@ This method completely removes all GRUB 2 configuration files and system setting . Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows: -* On both UEFI-based and BIOS-based machines, issue the following command as `root`: +** On BIOS-based machines, issue the following command as `root`: [subs="attributes"] ---- ~]#{nbsp}grub2-mkconfig -o /boot/grub2/grub.cfg ---- -. Now follow the procedure in xref:#sec-Reinstalling_GRUB_2[Reinstalling GRUB 2] to restore GRUB2 on the `/boot/` partition. +** On UEFI-based machines, issue the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg +---- + +. Now follow the procedure in xref:Working_with_the_GRUB_2_Boot_Loader.adoc#sec-Reinstalling_GRUB_2[Reinstalling GRUB 2] to restore GRUB2 on the `/boot/` partition. [[sec-GRUB_2_over_a_Serial_Console]] == GRUB 2 over a Serial Console @@ -625,7 +631,7 @@ To make persistent changes to a menu entry on a system, use the [command]#grubby ~]# grubby --remove-args="rhgb quiet" --args=console=ttyS0,115200 --update-kernel=DEFAULT ---- -The [option]`--update-kernel` parameter also accepts the keyword `ALL` or a comma separated list of kernel index numbers. See xref:#bh-Adding_and_Removing_Arguments_from_a_GRUB_Menu_Entry[Adding and Removing Arguments from a GRUB Menu Entry] for more information on using [command]#grubby#. +The [option]`--update-kernel` parameter also accepts the keyword `ALL` or a comma separated list of kernel index numbers. See xref:Working_with_the_GRUB_2_Boot_Loader.adoc#bh-Adding_and_Removing_Arguments_from_a_GRUB_Menu_Entry[Adding and Removing Arguments from a GRUB Menu Entry] for more information on using [command]#grubby#. If required to build a new GRUB 2 configuration file, add the following two lines in the `/etc/default/grub` file: @@ -640,13 +646,20 @@ The first line disables the graphical terminal. Note that specifying the `GRUB_T Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows: -* On both UEFI-based and BIOS-based machines, issue the following command as `root`: +* On BIOS-based machines, issue the following command as `root`: [subs="attributes"] ---- ~]#{nbsp}grub2-mkconfig -o /boot/grub2/grub.cfg ---- +* On UEFI-based machines, issue the following command as `root`: + +[subs="attributes"] +---- +~]#{nbsp}grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg +---- + [NOTE] ==== @@ -659,7 +672,7 @@ console=pass:attributes[{blank}]_ttyS0,9600n8_ Where [option]`console=ttyS0` is the serial terminal to be used, [option]`9600` is the baud rate, [option]`n` is for no parity, and [option]`8` is the word length in bits. A much higher baud rate, for example `115200`, is preferable for tasks such as following log files. -For more information on serial console settings, see xref:#bh-Installable_and_External_Documentation[Installed Documentation] +For more information on serial console settings, see xref:Working_with_the_GRUB_2_Boot_Loader.adoc#bh-Installable_and_External_Documentation[Installed Documentation] ==== @@ -754,9 +767,9 @@ Note that in GRUB 2, resetting the password is no longer performed in single-use Two procedures for resetting the `root` password are shown here: -* xref:#proc-Resetting_the_Root_Password_Using_an_Installation_Disk[Resetting the Root Password Using an Installation Disk] takes you to a shell prompt, without having to edit the grub menu. It is the shorter of the two procedures and it is also the recommended method. You can use a server boot disk or a netinstall installation disk. +* xref:Working_with_the_GRUB_2_Boot_Loader.adoc#proc-Resetting_the_Root_Password_Using_an_Installation_Disk[Resetting the Root Password Using an Installation Disk] takes you to a shell prompt, without having to edit the grub menu. It is the shorter of the two procedures and it is also the recommended method. You can use a server boot disk or a netinstall installation disk. -* xref:#proc-Resetting_the_Root_Password_Using_rd.break[Resetting the Root Password Using rd.break] makes use of [command]#rd.break# to interrupt the boot process before control is passed from `initramfs` to `systemd`. The disadvantage of this method is that it requires more steps, includes having to edit the GRUB menu, and involves choosing between a possibly time consuming SELinux file relabel or changing the SELinux enforcing mode and then restoring the SELinux security context for `/etc/shadow/` when the boot completes. +* xref:Working_with_the_GRUB_2_Boot_Loader.adoc#proc-Resetting_the_Root_Password_Using_rd.break[Resetting the Root Password Using rd.break] makes use of [command]#rd.break# to interrupt the boot process before control is passed from `initramfs` to `systemd`. The disadvantage of this method is that it requires more steps, includes having to edit the GRUB menu, and involves choosing between a possibly time consuming SELinux file relabel or changing the SELinux enforcing mode and then restoring the SELinux security context for `/etc/shadow/` when the boot completes. [[proc-Resetting_the_Root_Password_Using_an_Installation_Disk]] .Resetting the Root Password Using an Installation Disk diff --git a/modules/system-administrators-guide/pages/monitoring-and-automation/OProfile.adoc b/modules/system-administrators-guide/pages/monitoring-and-automation/OProfile.adoc index 3091b4f..6adef5c 100644 --- a/modules/system-administrators-guide/pages/monitoring-and-automation/OProfile.adoc +++ b/modules/system-administrators-guide/pages/monitoring-and-automation/OProfile.adoc @@ -109,7 +109,7 @@ To monitor the kernel, execute the following command: operf --vmlinux=pass:quotes[_vmlinux_path_] ---- -With this option, you can specify a path to a vmlinux file that matches the running kernel. Kernel samples will be attributed to this binary, allowing post-processing tools to attribute samples to the appropriate kernel symbols. If this option is not specified, all kernel samples will be attributed to a pseudo binary named "`no-vmlinux`". +With this option, you can specify a path to a vmlinux file that matches the running kernel. Kernel samples will be attributed to this binary, allowing post-processing tools to attribute samples to the appropriate kernel symbols. If this option is not specified, all kernel samples will be attributed to a pseudo binary named "no-vmlinux". [[s2-operf-events]] === Setting Events to Monitor @@ -178,7 +178,7 @@ xref:OProfile.adoc#tab_event_specifications[Event Specifications] summarizes the |_event-name_|The exact symbolic event name taken from [command]#ophelp# |_sample-rate_|The number of events to wait before sampling again. The smaller the count, the more frequent the samples. For events that do not happen frequently, a lower count may be needed to capture a statistically significant number of event instances. On the other hand, sampling too frequently can overload the system. By default, OProfile uses a time-based event set, which creates a sample every 100,000 clock cycles per processor. |_unit-mask_|Unit masks, which further define the event, are listed in [command]#ophelp#. - You can insert either a hexadecimal value, beginning with "`0x`", or a string that matches the first word of the unit mask description in [command]#ophelp#. Definition by name is valid only for unit masks having "`extra:`" parameters, as shown by the output of [command]#ophelp#. This type of unit mask cannot be defined with a hexadecimal value. Note that on certain architectures, there can be multiple unit masks with the same hexadecimal value. In that case they have to be specified by their names only. + You can insert either a hexadecimal value, beginning with "0x", or a string that matches the first word of the unit mask description in [command]#ophelp#. Definition by name is valid only for unit masks having "extra:" parameters, as shown by the output of [command]#ophelp#. This type of unit mask cannot be defined with a hexadecimal value. Note that on certain architectures, there can be multiple unit masks with the same hexadecimal value. In that case they have to be specified by their names only. |_kernel_|Specifies whether to profile kernel code (insert `0` or `1`(default)) |_user_|Specifies whether to profile user-space code (insert `0` or `1` (default)) |=== @@ -680,7 +680,7 @@ The data is the same as the [option]`-l` option except that for each symbol, eac indexterm:[OProfile,opreport]indexterm:[OProfile] OProfile collects data on a system-wide basis for kernel- and user-space code running on the machine. However, once a module is loaded into the kernel, the information about the origin of the kernel module is lost. The module could come from the `initrd` file on boot up, the directory with the various kernel modules, or a locally created kernel module. As a result, when OProfile records samples for a module, it just lists the samples for the modules for an executable in the root directory, but this is unlikely to be the place with the actual code for the module. You will need to take some steps to make sure that analysis tools get the proper executable. -To get a more detailed view of the actions of the module, you will need to either have the module "`unstripped`" (that is installed from a custom build) or have the [package]*debuginfo* package installed for the kernel. +To get a more detailed view of the actions of the module, you will need to either have the module "unstripped" (that is installed from a custom build) or have the [package]*debuginfo* package installed for the kernel. Find out which kernel is running with the [command]#uname -a# command, obtain the appropriate [package]*debuginfo* package and install it on the machine. @@ -778,7 +778,7 @@ While OProfile can be used by developers to analyze application performance, it [[s1-oprofile-java-support]] == OProfile Support for Java indexterm:[OProfile,Java] -OProfile allows you to profile dynamically compiled code (also known as "`just-in-time`" or JIT code) of the Java Virtual Machine (JVM). OProfile in {MAJOROSVER} includes built-in support for the JVM Tools Interface (JVMTI) agent library, which supports Java 1.5 and higher. +OProfile allows you to profile dynamically compiled code (also known as "just-in-time" or JIT code) of the Java Virtual Machine (JVM). OProfile in {MAJOROSVER} includes built-in support for the JVM Tools Interface (JVMTI) agent library, which supports Java 1.5 and higher. [[s1-oprofile-java-profiling]] === Profiling Java Code diff --git a/modules/system-administrators-guide/pages/monitoring-and-automation/System_Monitoring_Tools.adoc b/modules/system-administrators-guide/pages/monitoring-and-automation/System_Monitoring_Tools.adoc index ba64745..7fef5b1 100644 --- a/modules/system-administrators-guide/pages/monitoring-and-automation/System_Monitoring_Tools.adoc +++ b/modules/system-administrators-guide/pages/monitoring-and-automation/System_Monitoring_Tools.adoc @@ -134,15 +134,12 @@ The `Processes` tab of the [application]*System Monitor* tool allows you to view To start the [application]*System Monitor* tool, either select menu:Applications[System Tools > `System Monitor`pass:attributes[{blank}]] from the Activities menu, or type [command]#gnome-system-monitor# at a shell prompt. Then click the `Processes` tab to view the list of running processes. -For each listed process, the [application]*System Monitor* tool displays its name (`Process Name`), -user (`User`), -percentage of the CPU usage (`% CPU`), -process ID (`ID`), -memory usage (`Memory`), -total disk read and write (`Disk read total` and `Disk write total`), -current disk read and write (`Disk read` and `Disk write`), -and priority (`Priority`). -To sort the information by a specific column in ascending order, click the name of that column. Click the name of the column again to toggle the sort between ascending and descending order. +[[fig-sysinfo-processes]] +.System Monitor — Processes + +image::system-monitor-processes.png[The Processes tab of the System Monitor application.] + +For each listed process, the [application]*System Monitor* tool displays its name (`Process Name`), current status (`Status`), percentage of the memory usage (`% CPU`), nice value (`Nice`), process ID (`ID`), memory usage (`Memory`), the channel the process is waiting in (`Waiting Channel`), and additional details about the session (`Session`). To sort the information by a specific column in ascending order, click the name of that column. Click the name of the column again to toggle the sort between ascending and descending order. By default, the [application]*System Monitor* tool displays a list of processes that are owned by the current user. Selecting various options from the View menu allows you to: @@ -973,7 +970,7 @@ To configure an *SNMP version 2c community*, use either the [option]`rocommunity _directive_ _community_ _source_ _OID_ ---- -… where _community_ is the community string to use, _source_ is an IP address or subnet, and _OID_ is the SNMP tree to provide access to. For example, the following directive provides read-only access to the `system` tree to a client using the community string "`redhat`" on the local machine: +… where _community_ is the community string to use, _source_ is an IP address or subnet, and _OID_ is the SNMP tree to provide access to. For example, the following directive provides read-only access to the `system` tree to a client using the community string "redhat" on the local machine: [subs="quotes"] ---- @@ -993,7 +990,7 @@ SNMPv2-MIB::sysLocation.0 = STRING: Datacenter, Row 3, Rack 2 ---- .Configuring SNMP Version 3 User -To configure an *SNMP version 3 user*, use the [command]#net-snmp-create-v3-user# command. This command adds entries to the `/var/lib/net-snmp/snmpd.conf` and `/etc/snmp/snmpd.conf` files which create the user and grant access to the user. Note that the [command]#net-snmp-create-v3-user# command may only be run when the agent is not running. The following example creates the "`sysadmin`" user with the password "`redhatsnmp`": +To configure an *SNMP version 3 user*, use the [command]#net-snmp-create-v3-user# command. This command adds entries to the `/var/lib/net-snmp/snmpd.conf` and `/etc/snmp/snmpd.conf` files which create the user and grant access to the user. Note that the [command]#net-snmp-create-v3-user# command may only be run when the agent is not running. The following example creates the "sysadmin" user with the password "redhatsnmp": ---- ~]# systemctl stop snmpd.service @@ -1021,7 +1018,7 @@ _directive_ _user_ [option]`noauth`|[option]`auth`|[option]`priv` _OID_ … where _user_ is a username and _OID_ is the SNMP tree to provide access to. By default, the Net-SNMP Agent Daemon allows only authenticated requests (the [option]`auth` option). The [option]`noauth` option allows you to permit unauthenticated requests, and the [option]`priv` option enforces the use of encryption. The [option]`authpriv` option specifies that requests must be authenticated and replies should be encrypted. -For example, the following line grants the user "`admin`" read-write access to the entire tree: +For example, the following line grants the user "admin" read-write access to the entire tree: [subs="quotes"] ---- @@ -1304,7 +1301,7 @@ NET-SNMP-EXTEND-MIB::nsExtendResult."httpd_pids" = INTEGER: 8 NET-SNMP-EXTEND-MIB::nsExtendOutLine."httpd_pids".1 = STRING: ---- -Note that the exit code ("`8`" in this example) is provided as an INTEGER type and any output is provided as a STRING type. To expose multiple metrics as integers, supply different arguments to the script using the [option]`extend` directive. For example, the following shell script can be used to determine the number of processes matching an arbitrary string, and will also output a text string giving the number of processes: +Note that the exit code ("8" in this example) is provided as an INTEGER type and any output is provided as a STRING type. To expose multiple metrics as integers, supply different arguments to the script using the [option]`extend` directive. For example, the following shell script can be used to determine the number of processes matching an arbitrary string, and will also output a text string giving the number of processes: ---- #!/bin/sh @@ -1388,7 +1385,7 @@ The OID `.1.3.6.1.4.1.8072.9999.9999` (`NET-SNMP-MIB::netSnmpPlaypen`) is typica ==== -The handler function will be called with four parameters, `HANDLER`, `REGISTRATION_INFO`, `REQUEST_INFO`, and `REQUESTS`. The `REQUESTS` parameter contains a list of requests in the current call and should be iterated over and populated with data. The `request` objects in the list have get and set methods which allow for manipulating the `OID` and `value` of the request. For example, the following call will set the value of a request object to the string "`hello world`": +The handler function will be called with four parameters, `HANDLER`, `REGISTRATION_INFO`, `REQUEST_INFO`, and `REQUESTS`. The `REQUESTS` parameter contains a list of requests in the current call and should be iterated over and populated with data. The `request` objects in the list have get and set methods which allow for manipulating the `OID` and `value` of the request. For example, the following call will set the value of a request object to the string "hello world": ---- $request->setValue(ASN_OCTET_STR, "hello world"); @@ -1423,7 +1420,7 @@ for($request = $requests; $request; $request = $request->next()) { } ---- -When `getMode` returns `MODE_GET`, the handler analyzes the value of the `getOID` call on the `request` object. The `value` of the `request` is set to either `string_value` if the OID ends in "`.1.0`", or set to `integer_value` if the OID ends in "`.1.1`". If the `getMode` returns `MODE_GETNEXT`, the handler determines whether the OID of the request is "`.1.0`", and then sets the OID and value for "`.1.1`". If the request is higher on the tree than "`.1.0`", the OID and value for "`.1.0`" is set. This in effect returns the "`next`" value in the tree so that a program like [command]#snmpwalk# can traverse the tree without prior knowledge of the structure. +When `getMode` returns `MODE_GET`, the handler analyzes the value of the `getOID` call on the `request` object. The `value` of the `request` is set to either `string_value` if the OID ends in ".1.0", or set to `integer_value` if the OID ends in ".1.1". If the `getMode` returns `MODE_GETNEXT`, the handler determines whether the OID of the request is ".1.0", and then sets the OID and value for ".1.1". If the request is higher on the tree than ".1.0", the OID and value for ".1.0" is set. This in effect returns the "next" value in the tree so that a program like [command]#snmpwalk# can traverse the tree without prior knowledge of the structure. The type of the variable is set using constants from `NetSNMP::ASN`. See the [command]#perldoc# for `NetSNMP::ASN` for a full list of available constants. diff --git a/modules/system-administrators-guide/pages/monitoring-and-automation/Viewing_and_Managing_Log_Files.adoc b/modules/system-administrators-guide/pages/monitoring-and-automation/Viewing_and_Managing_Log_Files.adoc index 81ebe70..4835fa1 100644 --- a/modules/system-administrators-guide/pages/monitoring-and-automation/Viewing_and_Managing_Log_Files.adoc +++ b/modules/system-administrators-guide/pages/monitoring-and-automation/Viewing_and_Managing_Log_Files.adoc @@ -170,7 +170,7 @@ With expression-based filters, you can nest the conditions by using a script enc .Expression-based Filters ==== -The following expression contains two nested conditions. The log files created by a program called *prog1* are split into two files based on the presence of the "`test`" string in the message. +The following expression contains two nested conditions. The log files created by a program called *prog1* are split into two files based on the presence of the "test" string in the message. [subs="quotes"] ---- @@ -261,7 +261,7 @@ The following are some examples of actions that forward syslog messages over the ---- -To forward messages to "`example.com`" using port 18 and the `TCP` protocol, use: +To forward messages to "example.com" using port 18 and the `TCP` protocol, use: ---- @@ -1431,7 +1431,7 @@ As mentioned above, [application]*Rsyslog* and [application]*Journal*, the two l By default, `rsyslogd` uses the `imjournal` module as a default input mode for journal files. With this module, you import not only the messages but also the structured data provided by `journald`. Also, older data can be imported from `journald` (unless forbidden with the [option]`$ImjournalIgnorePreviousMessages` directive). See xref:Viewing_and_Managing_Log_Files.adoc#s2-importing_data_from_journal[Importing Data from Journal] for basic configuration of `imjournal`. -As an alternative, configure `rsyslogd` to read from the socket provided by `journal` as an output for syslog-based applications. The path to the socket is `/run/systemd/journal/syslog`. Use this option when you want to maintain plain rsyslog messages. Compared to `imjournal` the socket input currently offers more features, such as ruleset binding or filtering. To import [application]*Journal* data through the socket, use the following configuration in `/etc/rsyslog.conf`: +As an alternative, configure `rsyslogd` to read from the socket provided by `journal` as an output for syslog-based applications. The path to the socket is `/run/systemd/journal/syslog`. Use this option when you want to maintain plain rsyslog messages. Compared to `imjournal` the socket input currently offers more features, such as ruleset binding or filtering. To import [application]*Journal* data trough the socket, use the following configuration in `/etc/rsyslog.conf`: [subs="quotes"] ---- @@ -1441,7 +1441,7 @@ $OmitLocalLogging off ---- -The above syntax loads the `imuxsock` module and turns off the [option]`$OmitLocalLogging` directive, which enables the import through the system socket. The path to this socket is specified separately in `/etc/rsyslog.d/listen.conf` as follows: +The above syntax loads the `imuxsock` module and turns off the [option]`$OmitLocalLogging` directive, which enables the import trough the system socket. The path to this socket is specified separately in `/etc/rsyslog.d/listen.conf` as follows: [subs="quotes"] ---- @@ -1633,7 +1633,7 @@ To run `rsyslogd` in debugging mode, use the following command: `rsyslogd` [option]`-dn` ---- -With this command, `rsyslogd` produces debugging information and prints it to the standard output. The [option]`-n` stands for "`no fork`". You can modify debugging with environmental variables, for example, you can store the debug output in a log file. Before starting `rsyslogd`, type the following on the command line: +With this command, `rsyslogd` produces debugging information and prints it to the standard output. The [option]`-n` stands for "no fork". You can modify debugging with environmental variables, for example, you can store the debug output in a log file. Before starting `rsyslogd`, type the following on the command line: [subs="macros"] ---- diff --git a/modules/system-administrators-guide/pages/package-management/DNF.adoc b/modules/system-administrators-guide/pages/package-management/DNF.adoc index 5c09d3a..5836d91 100644 --- a/modules/system-administrators-guide/pages/package-management/DNF.adoc +++ b/modules/system-administrators-guide/pages/package-management/DNF.adoc @@ -160,7 +160,7 @@ Add the [option]`all` to match against descriptions and URLs. [command]#dnf# [option]`search all` _term_pass:attributes[{blank}]… ---- -This command displays the list of matches for each term. For example, to list all packages that match "`meld`" or "`kompare`", type: +This command displays the list of matches for each term. For example, to list all packages that match "meld" or "kompare", type: ---- ~]# dnf search meld kompare @@ -217,7 +217,7 @@ See xref:DNF.adoc#ex-Listing_all_ABRT_addons_and_plugins_using_glob_expressions[ .Listing all ABRT addons and plug-ins using glob expressions ==== -Packages with various ABRT addons and plug-ins either begin with "`abrt-addon-`", or "`abrt-plugin-`". To list these packages, type the following at a shell prompt: +Packages with various ABRT addons and plug-ins either begin with "abrt-addon-", or "abrt-plugin-". To list these packages, type the following at a shell prompt: ---- ~]# dnf list abrt-addon\* abrt-plugin\* @@ -265,7 +265,7 @@ indexterm:[packages,listing packages with DNF,dnf list installed] ind .Listing installed packages using a double-quoted glob expression ==== -To list all installed packages that begin with "`krb`" followed by exactly one character and a hyphen, type: +To list all installed packages that begin with "krb" followed by exactly one character and a hyphen, type: ---- ~]# dnf list installed "krb?-*" @@ -283,7 +283,7 @@ indexterm:[packages,listing packages with DNF,dnf list available] ind .Listing available packages using a single glob expression with escaped wildcard characters ==== -To list all available packages with names that contain "`gstreamer`" and then "`plugin`", run the following command: +To list all available packages with names that contain "gstreamer" and then "plugin", run the following command: ---- ~]# dnf list available gstreamer\*plugin\* @@ -788,7 +788,7 @@ _parameter_pass:attributes[{blank}]=pass:attributes[{blank}]_repository_url_:: + ** If the repository is local to the machine, use: `file:///path/to/local/repo` + -** If a specific online repository requires basic HTTP authentication, you can specify your user name and password by prepending it to the URL as [option]`pass:attributes[{blank}]_username_:pass:attributes[{blank}]_password_pass:attributes[{blank}]@pass:attributes[{blank}]_link_pass:attributes[{blank}]`. For example, if a repository on http://www.example.com/repo/ requires a username of "`user`" and a password of "`password`", then the [option]`baseurl` link could be specified as [option]`http://user:password@www.example.com/repo/`. +** If a specific online repository requires basic HTTP authentication, you can specify your user name and password by prepending it to the URL as [option]`pass:attributes[{blank}]_username_:pass:attributes[{blank}]_password_pass:attributes[{blank}]@pass:attributes[{blank}]_link_pass:attributes[{blank}]`. For example, if a repository on http://www.example.com/repo/ requires a username of "user" and a password of "password", then the [option]`baseurl` link could be specified as [option]`http://user:password@www.example.com/repo/`. + Usually this URL is an HTTP link, such as: + diff --git a/modules/system-administrators-guide/pages/package-management/intro-package-management.adoc b/modules/system-administrators-guide/pages/package-management/intro-package-management.adoc index 107a353..554cfe8 100644 --- a/modules/system-administrators-guide/pages/package-management/intro-package-management.adoc +++ b/modules/system-administrators-guide/pages/package-management/intro-package-management.adoc @@ -2,7 +2,7 @@ include::{partialsdir}/entities.adoc[] = Package Management -There are two types of {MAJOROS} system; "`traditional`", which use DNF, and "`image-based`" which use rpm-ostree. +There are two types of {MAJOROS} system; "traditional", which use DNF, and "image-based" which use rpm-ostree. == Traditional package management @@ -11,9 +11,9 @@ can be managed via [application]*DNF*. == Hybrid image/package management -The "`Atomic`" variant of {MAJOROS} uses [application]*rpm-ostree* to update the +The "Atomic" variant of {MAJOROS} uses [application]*rpm-ostree* to update the host. `rpm-ostree` is a hybrid image/package system. By default, installations -are in "`image`" mode using OSTree, but additional packages can be installed. It +are in "image" mode using OSTree, but additional packages can be installed. It also supports overrides, rebases, and many other features. For more information, see link:++https://www.projectatomic.io/docs/os-updates/++[its online documentation]. diff --git a/modules/system-administrators-guide/pages/package-management/rpm-ostree.adoc b/modules/system-administrators-guide/pages/package-management/rpm-ostree.adoc index c457da6..6596eca 100644 --- a/modules/system-administrators-guide/pages/package-management/rpm-ostree.adoc +++ b/modules/system-administrators-guide/pages/package-management/rpm-ostree.adoc @@ -1,3 +1,4 @@ + :experimental: include::{partialsdir}/entities.adoc[] @@ -8,4 +9,4 @@ include::{partialsdir}/entities.adoc[] the most important things to understand is that available RPMs come from the same `/etc/yum.repos.d` sources. -For more information, see the link:https://coreos.github.io/rpm-ostree/[upstream documentation]. +For more information, see the link:https://rpm-ostree.readthedocs.io/en/latest/[upstream documentation]. diff --git a/modules/system-administrators-guide/pages/pam_userdb.adoc b/modules/system-administrators-guide/pages/pam_userdb.adoc deleted file mode 100644 index 3557313..0000000 --- a/modules/system-administrators-guide/pages/pam_userdb.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:experimental: -include::{partialsdir}/entities.adoc[] - -[[ch-pam_userdb]] -= pam_userdb - -pam_userdb is a PAM module to authenticate against a db database. It is used to verify a username/password pair against values stored in a key/data pairs style database (i.e. Berkeley DB, GDBM). The database is indexed by the username, and the data fields corresponding to the username keys are the passwords. This module is most notably used in vsftpd environments. - -Recently, pam_userdb switched its database provider from Berkeley DB to GDBM. If your system uses this module to authenticate users you need to convert the database to the new format. - -== Determining whether you are using pam_userdb -The way to determine if you are using pam_userdb, is to check the PAM stack: - -[source,bash] ----- -$ grep -r pam_userdb /etc/pam.d/ -/etc/pam.d/vsftpd:auth sufficient pam_userdb.so db=/etc/vsftpd/login ----- - -If you are not using pam_userdb, then the search will return no values and you don't have to do anything. - -== Converting the database - -libdb package contains a binary that will handle the conversion for you. You only need to run it by providing the source and destination database files:. Example: - -[source,bash] ----- -$ db_converter --src /etc/vsftpd/login.db --dest /etc/vsftpd/login.gdbm ----- - -== Additional Resources - diff --git a/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_ntpd.adoc b/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_ntpd.adoc index fd1420e..9e531bc 100644 --- a/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_ntpd.adoc +++ b/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_ntpd.adoc @@ -8,11 +8,11 @@ include::{partialsdir}/entities.adoc[] [[s1-Introduction_to_NTP]] == Introduction to NTP -The _Network Time Protocol_ (*NTP*) enables the accurate dissemination of time and date information in order to keep the time clocks on networked computer systems synchronized to a common reference over the network or the Internet. Many standards bodies around the world have atomic clocks which may be made available as a reference. The satellites that make up the Global Position System contain more than one atomic clock, making their time signals potentially very accurate. Their signals can be deliberately degraded for military reasons. An ideal situation would be where each site has a server, with its own reference clock attached, to act as a site-wide time server. Many devices which obtain the time and date via low frequency radio transmissions or the Global Position System (GPS) exist. However for most situations, a range of publicly accessible time servers connected to the Internet at geographically dispersed locations can be used. These `NTP` servers provide "`pass:attributes[{blank}]_Coordinated Universal Time_pass:attributes[{blank}]`" (*UTC*). Information about these time servers can found at [citetitle]_www.pool.ntp.org_. +The _Network Time Protocol_ (*NTP*) enables the accurate dissemination of time and date information in order to keep the time clocks on networked computer systems synchronized to a common reference over the network or the Internet. Many standards bodies around the world have atomic clocks which may be made available as a reference. The satellites that make up the Global Position System contain more than one atomic clock, making their time signals potentially very accurate. Their signals can be deliberately degraded for military reasons. An ideal situation would be where each site has a server, with its own reference clock attached, to act as a site-wide time server. Many devices which obtain the time and date via low frequency radio transmissions or the Global Position System (GPS) exist. However for most situations, a range of publicly accessible time servers connected to the Internet at geographically dispersed locations can be used. These `NTP` servers provide "pass:attributes[{blank}]_Coordinated Universal Time_pass:attributes[{blank}]" (*UTC*). Information about these time servers can found at [citetitle]_www.pool.ntp.org_. Accurate time keeping is important for a number of reasons in IT. In networking for example, accurate time stamps in packets and logs are required. Logs are used to investigate service and security issues and so time stamps made on different systems must be made by synchronized clocks to be of real value. As systems and networks become increasingly faster, there is a corresponding need for clocks with greater accuracy and resolution. In some countries there are legal obligations to keep accurately synchronized clocks. Please see [citetitle]_www.ntp.org_ for more information. In Linux systems, `NTP` is implemented by a daemon running in user space. The default `NTP` user space daemon in {MAJOROSVER} is `chronyd`. It must be disabled if you want to use the `ntpd` daemon. See xref:servers/Configuring_NTP_Using_the_chrony_Suite.adoc#ch-Configuring_NTP_Using_the_chrony_Suite[Configuring NTP Using the chrony Suite] for information on [application]*chrony*. -The user space daemon updates the system clock, which is a software clock running in the kernel. Linux uses a software clock as its system clock for better resolution than the typical embedded hardware clock referred to as the "`pass:attributes[{blank}]_Real Time Clock_pass:attributes[{blank}]`" *(RTC)*. See the `rtc(4)` and `hwclock(8)` man pages for information on hardware clocks. The system clock can keep time by using various clock sources. Usually, the _Time Stamp Counter_ (*TSC*) is used. The TSC is a CPU register which counts the number of cycles since it was last reset. It is very fast, has a high resolution, and there are no interrupts. On system start, the system clock reads the time and date from the RTC. The time kept by the RTC will drift away from actual time by up to 5 minutes per month due to temperature variations. Hence the need for the system clock to be constantly synchronized with external time references. When the system clock is being synchronized by `ntpd`, the kernel will in turn update the RTC every 11 minutes automatically. +The user space daemon updates the system clock, which is a software clock running in the kernel. Linux uses a software clock as its system clock for better resolution than the typical embedded hardware clock referred to as the "pass:attributes[{blank}]_Real Time Clock_pass:attributes[{blank}]" *(RTC)*. See the `rtc(4)` and `hwclock(8)` man pages for information on hardware clocks. The system clock can keep time by using various clock sources. Usually, the _Time Stamp Counter_ (*TSC*) is used. The TSC is a CPU register which counts the number of cycles since it was last reset. It is very fast, has a high resolution, and there are no interrupts. On system start, the system clock reads the time and date from the RTC. The time kept by the RTC will drift away from actual time by up to 5 minutes per month due to temperature variations. Hence the need for the system clock to be constantly synchronized with external time references. When the system clock is being synchronized by `ntpd`, the kernel will in turn update the RTC every 11 minutes automatically. [[s1-NTP_Strata]] == NTP Strata @@ -54,11 +54,11 @@ Specification, Implementation and Analysis]_ and [citetitle]_link:++https://www. This implementation of `NTP` enables sub-second accuracy to be achieved. Over the Internet, accuracy to 10s of milliseconds is normal. On a Local Area Network (LAN), 1 ms accuracy is possible under ideal conditions. This is because clock drift is now accounted and corrected for, which was not done in earlier, simpler, time protocol systems. A resolution of 233 picoseconds is provided by using 64-bit time stamps. The first 32-bits of the time stamp is used for seconds, the last 32-bits are used for fractions of seconds. -`NTP` represents the time as a count of the number of seconds since 00:00 (midnight) 1 January, 1900 GMT. As 32-bits is used to count the seconds, this means the time will "`roll over`" in 2036. However `NTP` works on the difference between time stamps so this does not present the same level of problem as other implementations of time protocols have done. If a hardware clock that is within 68 years of the correct time is available at boot time then `NTP` will correctly interpret the current date. The `NTP4` specification provides for an "`Era Number`" and an "`Era Offset`" which can be used to make software more robust when dealing with time lengths of more than 68 years. Note, please do not confuse this with the Unix Year 2038 problem. +`NTP` represents the time as a count of the number of seconds since 00:00 (midnight) 1 January, 1900 GMT. As 32-bits is used to count the seconds, this means the time will "roll over" in 2036. However `NTP` works on the difference between time stamps so this does not present the same level of problem as other implementations of time protocols have done. If a hardware clock that is within 68 years of the correct time is available at boot time then `NTP` will correctly interpret the current date. The `NTP4` specification provides for an "Era Number" and an "Era Offset" which can be used to make software more robust when dealing with time lengths of more than 68 years. Note, please do not confuse this with the Unix Year 2038 problem. -The `NTP` protocol provides additional information to improve accuracy. Four time stamps are used to allow the calculation of round-trip time and server response time. In order for a system in its role as `NTP` client to synchronize with a reference time server, a packet is sent with an "`originate time stamp`". When the packet arrives, the time server adds a "`receive time stamp`". After processing the request for time and date information and just before returning the packet, it adds a "`transmit time stamp`". When the returning packet arrives at the `NTP` client, a "`receive time stamp`" is generated. The client can now calculate the total round trip time and by subtracting the processing time derive the actual traveling time. By assuming the outgoing and return trips take equal time, the single-trip delay in receiving the `NTP` data is calculated. The full `NTP` algorithm is much more complex than presented here. +The `NTP` protocol provides additional information to improve accuracy. Four time stamps are used to allow the calculation of round-trip time and server response time. In order for a system in its role as `NTP` client to synchronize with a reference time server, a packet is sent with an "originate time stamp". When the packet arrives, the time server adds a "receive time stamp". After processing the request for time and date information and just before returning the packet, it adds a "transmit time stamp". When the returning packet arrives at the `NTP` client, a "receive time stamp" is generated. The client can now calculate the total round trip time and by subtracting the processing time derive the actual traveling time. By assuming the outgoing and return trips take equal time, the single-trip delay in receiving the `NTP` data is calculated. The full `NTP` algorithm is much more complex than presented here. -When a packet containing time information is received it is not immediately responded to, but is first subject to validation checks and then processed together with several other time samples to arrive at an estimate of the time. This is then compared to the system clock to determine the time offset, the difference between the system clock's time and what `ntpd` has determined the time should be. The system clock is adjusted slowly, at most at a rate of 0.5ms per second, to reduce this offset by changing the frequency of the counter being used. It will take at least 2000 seconds to adjust the clock by 1 second using this method. This slow change is referred to as slewing and cannot go backwards. If the time offset of the clock is more than 128ms (the default setting), `ntpd` can "`step`" the clock forwards or backwards. If the time offset at system start is greater than 1000 seconds then the user, or an installation script, should make a manual adjustment. See xref:basic-system-configuration/Configuring_the_Date_and_Time.adoc#ch-Configuring_the_Date_and_Time[Configuring the Date and Time]. With the [option]`-g` option to the [command]#ntpd# command (used by default), any offset at system start will be corrected, but during normal operation only offsets of up to 1000 seconds will be corrected. +When a packet containing time information is received it is not immediately responded to, but is first subject to validation checks and then processed together with several other time samples to arrive at an estimate of the time. This is then compared to the system clock to determine the time offset, the difference between the system clock's time and what `ntpd` has determined the time should be. The system clock is adjusted slowly, at most at a rate of 0.5ms per second, to reduce this offset by changing the frequency of the counter being used. It will take at least 2000 seconds to adjust the clock by 1 second using this method. This slow change is referred to as slewing and cannot go backwards. If the time offset of the clock is more than 128ms (the default setting), `ntpd` can "step" the clock forwards or backwards. If the time offset at system start is greater than 1000 seconds then the user, or an installation script, should make a manual adjustment. See xref:basic-system-configuration/Configuring_the_Date_and_Time.adoc#ch-Configuring_the_Date_and_Time[Configuring the Date and Time]. With the [option]`-g` option to the [command]#ntpd# command (used by default), any offset at system start will be corrected, but during normal operation only offsets of up to 1000 seconds will be corrected. Some software may fail or produce an error if the time is changed backwards. For systems that are sensitive to step changes in the time, the threshold can be changed to 600s instead of 128ms using the [option]`-x` option (unrelated to the [option]`-g` option). Using the [option]`-x` option to increase the stepping limit from 0.128s to 600s has a drawback because a different method of controlling the clock has to be used. It disables the kernel clock discipline and may have a negative impact on the clock accuracy. The [option]`-x` option can be added to the `/etc/sysconfig/ntpd` configuration file. @@ -142,7 +142,7 @@ See [citetitle]_link:++https://access.redhat.com/security/cve/CVE-2013-5211++[CV ==== -Addresses within the range `127.0.0.0/8` are sometimes required by various processes or applications. As the "`restrict default`" line above prevents access to everything not explicitly allowed, access to the standard loopback address for `IPv4` and `IPv6` is permitted by means of the following lines: +Addresses within the range `127.0.0.0/8` are sometimes required by various processes or applications. As the "restrict default" line above prevents access to everything not explicitly allowed, access to the standard loopback address for `IPv4` and `IPv6` is permitted by means of the following lines: ---- # the administrative functions. @@ -152,7 +152,7 @@ restrict ::1 Addresses can be added underneath if specifically required by another application. -Hosts on the local network are not permitted because of the "`restrict default`" line above. To change this, for example to allow hosts from the `192.0.2.0/24` network to query the time and statistics but nothing more, a line in the following format is required: +Hosts on the local network are not permitted because of the "restrict default" line above. To change this, for example to allow hosts from the `192.0.2.0/24` network to query the time and statistics but nothing more, a line in the following format is required: [subs="quotes"] ---- @@ -301,7 +301,7 @@ To start the graphical firewall configuration tool using the command line, enter The `Firewall Configuration` window opens. Note, this command can be run as normal user but you will then be prompted for the `root` password from time to time. -Look for the word "`Connected`" in the lower left corner. This indicates that the [application]*firewall-config* tool is connected to the user space daemon, `firewalld`. +Look for the word "Connected" in the lower left corner. This indicates that the [application]*firewall-config* tool is connected to the user space daemon, `firewalld`. [[s2-Change_the_firewall_settings]] === Change the Firewall Settings @@ -374,7 +374,7 @@ where _option_ is one or more of: * [option]`ignore` — All packets will be ignored, including `ntpq` and `ntpdc` queries. -* [option]`kod` — a "`Kiss-o'-death`" packet is to be sent to reduce unwanted queries. +* [option]`kod` — a "Kiss-o'-death" packet is to be sent to reduce unwanted queries. * [option]`limited` — do not respond to time service requests if the packet violates the rate limit default values or those specified by the [command]#discard# command. `ntpq` and `ntpdc` queries are not affected. For more information on the [command]#discard# command and the default values, see xref:Configuring_NTP_Using_ntpd.adoc#s2_Configure_Rate_Limiting_Access_to_an_NTP_Service[Configure Rate Limiting Access to an NTP Service]. @@ -626,7 +626,7 @@ To specify that a particular _time-to-live_ (*TTL*) value should be used in plac [command]#ttl# _value_ ---- -Specify the time-to-live value to be used in packets sent by broadcast servers and multicast `NTP` servers. Specify the maximum time-to-live value to use for the "`expanding ring search`" by a manycast client. The default value is `127`. +Specify the time-to-live value to be used in packets sent by broadcast servers and multicast `NTP` servers. Specify the maximum time-to-live value to use for the "expanding ring search" by a manycast client. The default value is `127`. [[s2_Configuring_The_Version_of_NTP_to_use]] === Configuring the NTP Version to Use diff --git a/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_the_chrony_Suite.adoc b/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_the_chrony_Suite.adoc index 93fd162..14fdc8f 100644 --- a/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_the_chrony_Suite.adoc +++ b/modules/system-administrators-guide/pages/servers/Configuring_NTP_Using_the_chrony_Suite.adoc @@ -68,7 +68,7 @@ The [application]*chrony* daemon, `chronyd`, can be controlled by the command li [[sect-Understanding_the_chrony_configuration_commands]] === Understanding the chrony Configuration Commands -The default configuration file for `chronyd` is `/etc/chrony.conf`. The [option]`-f` option can be used to specify an alternate configuration file path. See the `chronyd` man page for further options. For a complete list of the directives that can be used see [citetitle]_link:++https://chrony-project.org/doc/4.4/chrony.conf.html++[https://chrony-project.org/doc/4.4/chrony.conf.html]_. Below is a selection of configuration options: +The default configuration file for `chronyd` is `/etc/chrony.conf`. The [option]`-f` option can be used to specify an alternate configuration file path. See the `chronyd` man page for further options. For a complete list of the directives that can be used see [citetitle]_link:++https://chrony.tuxfamily.org/manual.html#Configuration-file++[https://chrony.tuxfamily.org/manual.html#Configuration-file]_. Below is a selection of configuration options: Comments:: Comments should be preceded by #, %, ; or ! @@ -95,13 +95,13 @@ allow 2001:db8::/32 Use this form to specify an `IPv6` address to be allowed access. -cmdallow:: This is similar to the [command]#allow# directive (see section [command]#allow#), except that it allows control access (rather than `NTP` client access) to a particular subnet or host. (By "`control access`" is meant that [application]*chronyc* can be run on those hosts and successfully connect to `chronyd` on this computer.) The syntax is identical. There is also a [command]#cmddeny all# directive with similar behavior to the [command]#cmdallow all# directive. +cmdallow:: This is similar to the [command]#allow# directive (see section [command]#allow#), except that it allows control access (rather than `NTP` client access) to a particular subnet or host. (By "control access" is meant that [application]*chronyc* can be run on those hosts and successfully connect to `chronyd` on this computer.) The syntax is identical. There is also a [command]#cmddeny all# directive with similar behavior to the [command]#cmdallow all# directive. dumpdir:: Path to the directory to save the measurement history across restarts of `chronyd` (assuming no changes are made to the system clock behavior whilst it is not running). If this capability is to be used (via the [command]#dumponexit# command in the configuration file, or the [command]#dump# command in [application]*chronyc*), the [command]#dumpdir# command should be used to define the directory where the measurement histories are saved. dumponexit:: If this command is present, it indicates that `chronyd` should save the measurement history for each of its time sources recorded whenever the program exits. (See the [command]#dumpdir# command above). -local:: The [command]#local# keyword is used to allow `chronyd` to appear synchronized to real time from the viewpoint of clients polling it, even if it has no current synchronization source. This option is normally used on the "`master`" computer in an isolated network, where several computers are required to synchronize to one another, and the "`master`" is kept in line with real time by manual input. +local:: The [command]#local# keyword is used to allow `chronyd` to appear synchronized to real time from the viewpoint of clients polling it, even if it has no current synchronization source. This option is normally used on the "master" computer in an isolated network, where several computers are required to synchronize to one another, and the "master" is kept in line with real time by manual input. An example of the command is: @@ -253,7 +253,7 @@ An example of the format of the default entry in the key file, `/etc/chrony.keys 1 SHA1 HEX:A6CFC50C9C93AB6E5A19754C246242FC5471BCDF ---- -Where `1` is the key ID, SHA1 is the hash function to use, `HEX` is the format of the key, and `A6CFC50C9C93AB6E5A19754C246242FC5471BCDF` is the key randomly generated when [application]*chronyd* was started for the first time. The key can be given in hexadecimal or ASCII format (the default). +Where `1` is the key ID, SHA1 is the hash function to use, `HEX` is the format of the key, and `A6CFC50C9C93AB6E5A19754C246242FC5471BCDF` is the key randomly generated when [application]*chronyd* was started for the first time. The key can be given in hexidecimal or ASCII format (the default). A manual entry in the key file, used to authenticate packets from certain `NTP` servers or peers, can be as simple as the following: @@ -398,7 +398,7 @@ Leap status : Normal The fields are as follows: -Reference ID:: This is the reference ID and name (or `IP` address) if available, of the server to which the computer is currently synchronized. If this is `127.127.1.1` it means the computer is not synchronized to any external source and that you have the "`local`" mode operating (via the local command in [application]*chronyc*, or the [command]#local# directive in the `/etc/chrony.conf` file (see section [command]#local#)). +Reference ID:: This is the reference ID and name (or `IP` address) if available, of the server to which the computer is currently synchronized. If this is `127.127.1.1` it means the computer is not synchronized to any external source and that you have the "local" mode operating (via the local command in [application]*chronyc*, or the [command]#local# directive in the `/etc/chrony.conf` file (see section [command]#local#)). Stratum:: The stratum indicates how many hops away from a computer with an attached reference clock we are. Such a computer is a stratum-1 computer, so the computer in the example is two hops away (that is to say, a.b.c is a stratum-2 and is synchronized from a stratum-1). @@ -410,9 +410,9 @@ Last offset:: This is the estimated local offset on the last clock update. RMS offset:: This is a long-term average of the offset value. -Frequency:: The "`frequency`" is the rate by which the system’s clock would be wrong if `chronyd` was not correcting it. It is expressed in ppm (parts per million). For example, a value of 1ppm would mean that when the system’s clock thinks it has advanced 1 second, it has actually advanced by 1.000001 seconds relative to true time. +Frequency:: The "frequency" is the rate by which the system’s clock would be wrong if `chronyd` was not correcting it. It is expressed in ppm (parts per million). For example, a value of 1ppm would mean that when the system’s clock thinks it has advanced 1 second, it has actually advanced by 1.000001 seconds relative to true time. -Residual freq:: This shows the "`residual frequency`" for the currently selected reference source. This reflects any difference between what the measurements from the reference source indicate the frequency should be and the frequency currently being used. +Residual freq:: This shows the "residual frequency" for the currently selected reference source. This reflects any difference between what the measurements from the reference source indicate the frequency should be and the frequency currently being used. The reason this is not always zero is that a smoothing procedure is applied to the frequency. Each time a measurement from the reference source is obtained and a new residual frequency computed, the estimated accuracy of this residual is compared with the estimated accuracy (see [option]`skew` next) of the existing frequency value. A weighted average is computed for the new frequency, with weights depending on these accuracies. If the measurements from the reference source follow a consistent trend, the residual will be driven to zero over time. @@ -448,8 +448,8 @@ The columns are as follows: M:: This indicates the mode of the source. `^` means a server, `=` means a peer and `#` indicates a locally connected reference clock. -S:: This column indicates the state of the sources. "`*`" indicates the source to which `chronyd` is currently synchronized. "`+`" indicates acceptable sources which are combined with the selected source. "`-`" indicates acceptable sources which are excluded by the combining algorithm. "`?`" indicates sources to which connectivity has been lost or whose packets do not pass all tests. "`x`" indicates a clock which `chronyd` thinks is a _falseticker_ (its time is inconsistent with a majority of other sources). "`~`" indicates a source whose time appears to have too much -variability. The "`?`" condition is also shown at start-up, until at least 3 samples have been gathered from it. +S:: This column indicates the state of the sources. "*" indicates the source to which `chronyd` is currently synchronized. "+" indicates acceptable sources which are combined with the selected source. "-" indicates acceptable sources which are excluded by the combining algorithm. "?" indicates sources to which connectivity has been lost or whose packets do not pass all tests. "x" indicates a clock which `chronyd` thinks is a _falseticker_ (its time is inconsistent with a majority of other sources). "~" indicates a source whose time appears to have too much +variability. The "?" condition is also shown at start-up, until at least 3 samples have been gathered from it. Name/IP address:: This shows the name or the `IP` address of the source, or reference ID for reference clocks. diff --git a/modules/system-administrators-guide/pages/servers/Configuring_PTP_Using_ptp4l.adoc b/modules/system-administrators-guide/pages/servers/Configuring_PTP_Using_ptp4l.adoc index 158325e..76168b1 100644 --- a/modules/system-administrators-guide/pages/servers/Configuring_PTP_Using_ptp4l.adoc +++ b/modules/system-administrators-guide/pages/servers/Configuring_PTP_Using_ptp4l.adoc @@ -166,7 +166,7 @@ The *P2P* mechanism is preferred as it reacts to changes in the network topology [option]`-E`:: The [option]`-E` selects the _end-to-end_ (*E2E*) delay measurement mechanism. This is the default. -The *E2E* mechanism is also referred to as the delay "`request-response`" mechanism. +The *E2E* mechanism is also referred to as the delay "request-response" mechanism. [option]`-A`:: The [option]`-A` enables automatic selection of the delay measurement mechanism. @@ -559,7 +559,7 @@ Notice the section named as follows: [ntp_server pass:quotes[_address_]] ---- -This is an example of an `NTP` server section, "`ntp-server.local`" is an example of a host name for an `NTP` server on the local LAN. Add more sections as required using a host name or `IP` address as part of the section name. Note that the short polling values in that example section are not suitable for a public server, see xref:servers/Configuring_NTP_Using_ntpd.adoc#ch-Configuring_NTP_Using_ntpd[Configuring NTP Using ntpd] for an explanation of suitable [option]`minpoll` and [option]`maxpoll` values. +This is an example of an `NTP` server section, "ntp-server.local" is an example of a host name for an `NTP` server on the local LAN. Add more sections as required using a host name or `IP` address as part of the section name. Note that the short polling values in that example section are not suitable for a public server, see xref:servers/Configuring_NTP_Using_ntpd.adoc#ch-Configuring_NTP_Using_ntpd[Configuring NTP Using ntpd] for an explanation of suitable [option]`minpoll` and [option]`maxpoll` values. Notice the section named as follows: @@ -568,7 +568,7 @@ Notice the section named as follows: [ptp_domain pass:quotes[_number_]] ---- -A "`PTP domain`" is a group of one or more `PTP` clocks that synchronize to each other. They may or may not be synchronized to clocks in another domain. Clocks that are configured with the same domain number make up the domain. This includes a `PTP` grandmaster clock. The domain number in each "`PTP domain`" section needs to correspond to one of the `PTP` domains configured on the network. +A "PTP domain" is a group of one or more `PTP` clocks that synchronize to each other. They may or may not be synchronized to clocks in another domain. Clocks that are configured with the same domain number make up the domain. This includes a `PTP` grandmaster clock. The domain number in each "PTP domain" section needs to correspond to one of the `PTP` domains configured on the network. An instance of [application]*ptp4l* is started for every interface which has its own `PTP` clock and hardware time stamping is enabled automatically. Interfaces that support hardware time stamping have a `PTP` clock (PHC) attached, however it is possible for a group of interfaces on a NIC to share a PHC. A separate [application]*ptp4l* instance will be started for each group of interfaces sharing the same PHC and for each interface that supports only software time stamping. All [application]*ptp4l* instances are configured to run as a slave. If an interface with hardware time stamping is specified in more than one `PTP` domain, then only the first [application]*ptp4l* instance created will have hardware time stamping enabled. diff --git a/modules/system-administrators-guide/pages/servers/Mail_Servers.adoc b/modules/system-administrators-guide/pages/servers/Mail_Servers.adoc index 114f762..fe29838 100644 --- a/modules/system-administrators-guide/pages/servers/Mail_Servers.adoc +++ b/modules/system-administrators-guide/pages/servers/Mail_Servers.adoc @@ -838,7 +838,7 @@ Flags are essential to determine how or if a recipe's conditions are compared to * [command]#w# — Tells Procmail to wait for the specified filter or program to finish, and reports whether or not it was successful before considering the message filtered. -* [command]#W# — Is identical to [command]#w# except that "`Program failure`" messages are suppressed. +* [command]#W# — Is identical to [command]#w# except that "Program failure" messages are suppressed. For a detailed list of additional flags, see the `procmailrc` man page. diff --git a/modules/system-administrators-guide/pages/servers/Web_Servers.adoc b/modules/system-administrators-guide/pages/servers/Web_Servers.adoc index 069ae6b..23e46be 100644 --- a/modules/system-administrators-guide/pages/servers/Web_Servers.adoc +++ b/modules/system-administrators-guide/pages/servers/Web_Servers.adoc @@ -4,18 +4,7 @@ include::{partialsdir}/entities.adoc[] [[ch-Web_Servers]] = Web Servers -// indexterm:[HTTP server,Apache HTTP Server]indexterm:[web server,Apache HTTP Server] - -[IMPORTANT] -==== -**Editor's Note** - -_This guide is deprecated!_ Large parts of it are no longer current and it will not receive any updates. A series of shorter, topic-specific documentation will gradually replace it. - -For additional information about Apache Webserver on Fedora see https://docs.fedoraproject.org/en-US/quick-docs/getting-started-with-apache-http-server/[Getting started with Apache HTTP Server] -==== - - +indexterm:[HTTP server,Apache HTTP Server]indexterm:[web server,Apache HTTP Server] A _web server_ is a network service that serves content to a client over the web. This typically means web pages, but any other documents can be served as well. Web servers are also known as HTTP servers, as they use the _hypertext transport protocol_ (*HTTP*). include::{partialsdir}/servers/The_Apache_HTTP_Server.adoc[] diff --git a/site.yml b/site.yml index 24fd5e7..22baccb 100644 --- a/site.yml +++ b/site.yml @@ -5,10 +5,11 @@ content: sources: - url: . branches: HEAD - - url: https://gitlab.com/fedora/docs/fedora-linux-documentation/release-docs-home.git + - url: https://pagure.io/fedora-docs/release-docs-home.git + branches: f30 ui: bundle: - url: https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable + url: https://asamalik.fedorapeople.org/ui-bundle.zip snapshot: true default_layout: with_menu output: