docs-archive/sysadmin-guide
Archived
21
1
Fork 3
Code Issues 26 Pull requests 2 Activity

Initial AsciiDoc/AsciiBinder Commit

Browse source 
Based on F26
This commit is contained in:
Brian (bex) Exelbierd 2017-07-24 18:01:06 +02:00
commit 079b46391f
112 changed files with 22789 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

9
.gitignore vendored Normal file
View file

@ -0,0 +1,9 @@
## AsciiBinder-specific ignores
_preview
_package
*.swp
diag-*.png
diag-*.png.cache
## Project-specific ignores

26
Common_Content/Feedback.adoc Normal file
View file

@ -0,0 +1,26 @@
:experimental:
=== We want feedback
indexterm:[feedback,contact information for this manual]
If you find errors or have suggestions for improvement, we want your advice. Submit a report in Bugzilla against the product `{PRODUCT}` and the component `{BOOKID}`. The following link automatically loads this information for you: {BZURL}.
In Bugzilla:
. Provide a short summary of the error or your suggestion in the `Summary` field.
. Copy the following template into the `Description` field and give us the details of the error or suggestion as specifically as you can. If possible, include some surrounding text so we know where the error occurs or the suggestion fits.
+
[subs="quotes"]
----
Document URL:
Section number and name:
Error or suggestion:
Additional information:
----
. Click the btn:[Submit Bug] button.

22
Common_Content/Legal_Notice.adoc Normal file
View file

@ -0,0 +1,22 @@
:experimental:
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:++http://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.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
For guidelines on the permitted uses of the Fedora trademarks, refer to link:++https://fedoraproject.org/wiki/Legal:Trademark_guidelines++[].
*Linux* (R) is the registered trademark of Linus Torvalds in the United States and other countries.
*Java* (R) is a registered trademark of Oracle and/or its affiliates.
*XFS* (R) is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
*MySQL* (R) is a registered trademark of MySQL AB in the United States, the European Union and other countries.
All other trademarks are the property of their respective owners.

61
Common_Content/images/title_logo.svg Normal file
View file

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
version="1.0"
width="220"
height="70"
id="svg6180">
<defs
id="defs6182" />
<g
transform="translate(-266.55899,-345.34488)"
id="layer1">
<path
d="m 316.7736,397.581 c 0,0 0,0 -20.53889,0 0.3327,4.45245 3.92157,7.77609 8.70715,7.77609 3.38983,0 6.31456,-1.39616 8.64094,-3.65507 0.46553,-0.46679 0.99726,-0.59962 1.59519,-0.59962 0.79781,0 1.59561,0.39932 2.12692,1.06388 0.3327,0.46553 0.53216,0.99726 0.53216,1.52857 0,0.73118 -0.3327,1.52857 -0.93106,2.12734 -2.7919,2.99052 -7.51086,4.98503 -12.16403,4.98503 -8.44149,0 -15.22074,-6.77967 -15.22074,-15.22158 0,-8.44149 6.58022,-15.22074 15.02171,-15.22074 8.37529,0 14.62323,6.51317 14.62323,15.08749 0,1.26418 -1.12924,2.12861 -2.39258,2.12861 z m -12.23065,-11.76512 c -4.45329,0 -7.51085,2.92473 -8.17499,7.17731 10.03626,0 16.35083,0 16.35083,0 -0.59836,-4.05355 -3.78874,-7.17731 -8.17584,-7.17731 z"
id="path11"
style="fill:#3c6eb4" />
<path
d="m 375.46344,410.80807 c -8.44106,0 -15.22074,-6.77968 -15.22074,-15.22159 0,-8.44149 6.77968,-15.22074 15.22074,-15.22074 8.44234,0 15.22159,6.77925 15.22159,15.22074 -4.2e-4,8.44149 -6.77968,15.22159 -15.22159,15.22159 z m 0,-24.65992 c -5.31688,0 -8.77377,4.25427 -8.77377,9.43833 0,5.18364 3.45689,9.43833 8.77377,9.43833 5.31731,0 8.77504,-4.25469 8.77504,-9.43833 -4.2e-4,-5.18406 -3.45773,-9.43833 -8.77504,-9.43833 z"
id="path13"
style="fill:#3c6eb4" />
<path
d="m 412.66183,380.36574 c -4.45963,0 -7.40966,1.319 -10.01391,4.62956 l -0.24036,-1.53995 0,0 c -0.20198,-1.60743 -1.57326,-2.84926 -3.23382,-2.84926 -1.80139,0 -3.26206,1.459 -3.26206,3.26081 0,0.003 0,0.005 0,0.008 l 0,0 0,0.003 0,0 0,23.40712 c 0,1.79464 1.46194,3.25743 3.257,3.25743 1.79465,0 3.25744,-1.46279 3.25744,-3.25743 l 0,-12.56209 c 0,-5.71621 4.98502,-8.57432 10.23613,-8.57432 1.59519,0 2.85726,-1.32953 2.85726,-2.92515 0,-1.59561 -1.26207,-2.85726 -2.85768,-2.85726 z"
id="path15"
style="fill:#3c6eb4" />
<path
d="m 447.02614,395.58648 c 0.0666,-8.17541 -5.78326,-15.22074 -15.222,-15.22074 -8.44192,0 -15.28779,6.77925 -15.28779,15.22074 0,8.44191 6.64684,15.22159 14.68985,15.22159 4.01434,0 7.62682,-2.06621 9.23846,-4.22518 l 0.79359,2.01434 0,0 c 0.42589,1.13177 1.5176,1.93717 2.7978,1.93717 1.65001,0 2.98756,-1.33671 2.99009,-2.98545 l 0,0 0,-7.80687 0,0 0,-4.1556 z m -15.222,9.43833 c -5.31773,0 -8.77419,-4.25469 -8.77419,-9.43833 0,-5.18406 3.45604,-9.43833 8.77419,-9.43833 5.3173,0 8.77419,4.25427 8.77419,9.43833 0,5.18364 -3.45689,9.43833 -8.77419,9.43833 z"
id="path17"
style="fill:#3c6eb4" />
<path
d="m 355.01479,368.3337 c 0,-1.7938 -1.46194,-3.18997 -3.25659,-3.18997 -1.79422,0 -3.25743,1.39659 -3.25743,3.18997 l 0,17.1499 c -1.66097,-3.05756 -5.25026,-5.11786 -9.50495,-5.11786 -8.64052,0 -14.42336,6.51318 -14.42336,15.22074 0,8.70757 5.98229,15.22159 14.42336,15.22159 3.76555,0 7.03057,-1.55429 8.98587,-4.25554 l 0.72317,1.83428 c 0.44782,1.25912 1.64917,2.16024 3.06051,2.16024 1.78621,0 3.24984,-1.45435 3.24984,-3.24815 0,-0.005 0,-0.009 0,-0.0139 l 0,0 0,-38.95128 -4.2e-4,0 z m -15.22116,36.69111 c -5.31731,0 -8.70715,-4.25469 -8.70715,-9.43833 0,-5.18406 3.38984,-9.43833 8.70715,-9.43833 5.31773,0 8.70714,4.0544 8.70714,9.43833 0,5.38309 -3.38941,9.43833 -8.70714,9.43833 z"
id="path19"
style="fill:#3c6eb4" />
<path
d="m 287.21553,365.34023 c -0.59414,-0.0877 -1.19966,-0.13198 -1.80097,-0.13198 -6.73118,0 -12.20746,5.4767 -12.20746,12.20788 l 0,3.8132 -3.98903,0 c -1.46237,0 -2.65908,1.19671 -2.65908,2.65781 0,1.46321 1.19671,2.93738 2.65908,2.93738 l 3.98819,0 0,20.46004 c 0,1.79464 1.46236,3.25743 3.25658,3.25743 1.79507,0 3.25744,-1.46279 3.25744,-3.25743 l 0,-20.46004 4.40986,0 c 1.46194,0 2.65823,-1.47417 2.65823,-2.93738 0,-1.46152 -1.19629,-2.65823 -2.65823,-2.65823 l -4.40733,0 0,-3.8132 c 0,-3.13852 2.55323,-6.11469 5.69175,-6.11469 0.28294,0 0.56757,0.0211 0.84672,0.062 1.78031,0.26355 3.4358,-0.54269 3.70019,-2.32342 0.2627,-1.77904 -0.96606,-3.43538 -2.74594,-3.69935 z"
id="path21"
style="fill:#3c6eb4" />
<path
d="m 482.01243,363.57426 c 0,-10.06788 -8.16108,-18.22938 -18.22897,-18.22938 -10.06282,0 -18.22179,8.15475 -18.22854,18.21631 l -4.2e-4,-4.2e-4 0,14.1071 4.2e-4,4.2e-4 c 0.005,2.28463 1.85832,4.13409 4.14463,4.13409 0.007,0 0.0127,-8.4e-4 0.0194,-8.4e-4 l 0.001,8.4e-4 14.07083,0 0,0 c 10.06409,-0.004 18.22138,-8.16276 18.22138,-18.22812 z"
id="path25"
style="fill:#294172" />
<path
d="m 469.13577,349.66577 c -4.72528,0 -8.55576,3.83049 -8.55576,8.55577 0,0.002 0,0.004 0,0.006 l 0,4.52836 -4.51444,0 c -8.5e-4,0 -8.5e-4,0 -0.001,0 -4.72528,0 -8.55576,3.81193 -8.55576,8.53678 0,4.72528 3.83048,8.55577 8.55576,8.55577 4.72486,0 8.55534,-3.83049 8.55534,-8.55577 0,-0.002 0,-0.004 0,-0.006 l 0,-4.54733 4.51444,0 c 8.5e-4,0 0.001,0 0.002,0 4.72486,0 8.55534,-3.79296 8.55534,-8.51781 0,-4.72528 -3.83048,-8.55577 -8.55534,-8.55577 z m -8.55576,21.63483 c -0.004,2.48998 -2.02446,4.50811 -4.51571,4.50811 -2.49378,0 -4.53426,-2.02193 -4.53426,-4.5157 0,-2.49421 2.04048,-4.55366 4.53426,-4.55366 0.002,0 0.004,4.2e-4 0.006,4.2e-4 l 3.86971,0 c 0.001,0 0.002,-4.2e-4 0.003,-4.2e-4 0.35209,0 0.63799,0.28505 0.63799,0.63715 0,4.2e-4 -4.2e-4,8.4e-4 -4.2e-4,0.001 l 0,3.92284 -4.2e-4,0 z m 8.55534,-8.5448 c -0.001,0 -0.003,0 -0.004,0 l -3.87223,0 c -8.4e-4,0 -0.002,0 -0.002,0 -0.35252,0 -0.63757,-0.28506 -0.63757,-0.63758 l 0,-4.2e-4 0,-3.90343 c 0.004,-2.49083 2.02446,-4.50854 4.51571,-4.50854 2.49378,0 4.53468,2.02193 4.53468,4.51613 4.2e-4,2.49336 -2.04048,4.53384 -4.53426,4.53384 z"
id="path29"
style="fill:#3c6eb4" />
<path
d="m 460.58001,362.7558 0,-4.52836 c 0,-0.002 0,-0.004 0,-0.006 0,-4.72528 3.83048,-8.55577 8.55576,-8.55577 0.71685,0 1.22623,0.0805 1.88952,0.25469 0.96774,0.25385 1.75796,1.04618 1.75838,1.96922 4.2e-4,1.11575 -0.80919,1.92621 -2.0194,1.92621 -0.57642,0 -0.78473,-0.11048 -1.62892,-0.11048 -2.49125,0 -4.51149,2.01771 -4.51571,4.50854 l 0,3.90385 0,4.2e-4 c 0,0.35252 0.28505,0.63758 0.63757,0.63758 4.3e-4,0 0.001,0 0.002,0 l 2.96521,0 c 1.10521,0 1.99747,0.88467 1.99832,1.99283 0,1.10816 -0.89353,1.99114 -1.99832,1.99114 l -3.60489,0 0,4.54733 c 0,0.002 0,0.004 0,0.006 0,4.72485 -3.83048,8.55534 -8.55534,8.55534 -0.71684,0 -1.22623,-0.0805 -1.88952,-0.25469 -0.96774,-0.25343 -1.75838,-1.04618 -1.7588,-1.9688 0,-1.11575 0.80919,-1.92663 2.01982,-1.92663 0.576,0 0.78473,0.11048 1.6285,0.11048 2.49125,0 4.51191,-2.01771 4.51613,-4.50811 0,0 0,-3.92368 0,-3.9241 0,-0.35168 -0.2859,-0.63673 -0.63799,-0.63673 -4.3e-4,0 -8.5e-4,0 -0.002,0 l -2.96521,-4.2e-4 c -1.10521,0 -1.99831,-0.88214 -1.99831,-1.9903 -4.3e-4,-1.11533 0.90238,-1.99367 2.01939,-1.99367 l 3.58339,0 0,0 z"
id="path31"
style="fill:#ffffff" />
<path
d="m 477.41661,378.55292 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="text6223"
style="fill:#294172;enable-background:new" />
</g>
<path
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" />
</svg>
Side by side

After

Width:  |  Height:  |  Size: 7.6 KiB

4
LICENSE.txt Normal file
View file

@ -0,0 +1,4 @@
This work is licensed under the Creative Commons Attribution 4.0 International
License. To view a copy of this license, visit
http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative
Commons, PO Box 1866, Mountain View, CA 94042, USA.

22
README.md Normal file
View file

@ -0,0 +1,22 @@
# Fedora System Administrators Guide
This is the content repository for the Fedora System Administrators Guide.
Please report Issues and submit Pull Requests for **Content Fixes** here. General appearance issues and publishing issues should be reported against the [publisher](https://pagure.io/docs-reboot/docs-fp-o).
## How to edit this document
This document is coded in AsciiDoc. The content is in the en-US directory. There is a shared entity file in the en-US directory. Do not edit the content in the Common_Content directory.
## Testing your changes locally
To test your changes, first install `asciibinder`
$ gem install ascii_binder
To build your changes, from the root directory:
```
$ asciibinder package
$ firefox _package/main/index.html
```

14
_distro_map.yml Normal file
View file

@ -0,0 +1,14 @@
---
ascii_binder:
name: Fedora System Administrators Guide
author: Fedora Documentation Project <docs@lists.fedoraproject.org>
site: main
site_name: Home
site_url: https://docs.fedoraproject.org/
branches:
master:
name: Rawhide
dir: rawhide
f26:
name: 26
dir: f26

BIN
_images/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.3 KiB

BIN
_images/favicon32x32.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.5 KiB

61
_images/fedora.svg Normal file
View file

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
version="1.0"
width="220"
height="70"
id="svg6180">
<defs
id="defs6182" />
<g
transform="translate(-266.55899,-345.34488)"
id="layer1">
<path
d="m 316.7736,397.581 c 0,0 0,0 -20.53889,0 0.3327,4.45245 3.92157,7.77609 8.70715,7.77609 3.38983,0 6.31456,-1.39616 8.64094,-3.65507 0.46553,-0.46679 0.99726,-0.59962 1.59519,-0.59962 0.79781,0 1.59561,0.39932 2.12692,1.06388 0.3327,0.46553 0.53216,0.99726 0.53216,1.52857 0,0.73118 -0.3327,1.52857 -0.93106,2.12734 -2.7919,2.99052 -7.51086,4.98503 -12.16403,4.98503 -8.44149,0 -15.22074,-6.77967 -15.22074,-15.22158 0,-8.44149 6.58022,-15.22074 15.02171,-15.22074 8.37529,0 14.62323,6.51317 14.62323,15.08749 0,1.26418 -1.12924,2.12861 -2.39258,2.12861 z m -12.23065,-11.76512 c -4.45329,0 -7.51085,2.92473 -8.17499,7.17731 10.03626,0 16.35083,0 16.35083,0 -0.59836,-4.05355 -3.78874,-7.17731 -8.17584,-7.17731 z"
id="path11"
style="fill:#3c6eb4" />
<path
d="m 375.46344,410.80807 c -8.44106,0 -15.22074,-6.77968 -15.22074,-15.22159 0,-8.44149 6.77968,-15.22074 15.22074,-15.22074 8.44234,0 15.22159,6.77925 15.22159,15.22074 -4.2e-4,8.44149 -6.77968,15.22159 -15.22159,15.22159 z m 0,-24.65992 c -5.31688,0 -8.77377,4.25427 -8.77377,9.43833 0,5.18364 3.45689,9.43833 8.77377,9.43833 5.31731,0 8.77504,-4.25469 8.77504,-9.43833 -4.2e-4,-5.18406 -3.45773,-9.43833 -8.77504,-9.43833 z"
id="path13"
style="fill:#3c6eb4" />
<path
d="m 412.66183,380.36574 c -4.45963,0 -7.40966,1.319 -10.01391,4.62956 l -0.24036,-1.53995 0,0 c -0.20198,-1.60743 -1.57326,-2.84926 -3.23382,-2.84926 -1.80139,0 -3.26206,1.459 -3.26206,3.26081 0,0.003 0,0.005 0,0.008 l 0,0 0,0.003 0,0 0,23.40712 c 0,1.79464 1.46194,3.25743 3.257,3.25743 1.79465,0 3.25744,-1.46279 3.25744,-3.25743 l 0,-12.56209 c 0,-5.71621 4.98502,-8.57432 10.23613,-8.57432 1.59519,0 2.85726,-1.32953 2.85726,-2.92515 0,-1.59561 -1.26207,-2.85726 -2.85768,-2.85726 z"
id="path15"
style="fill:#3c6eb4" />
<path
d="m 447.02614,395.58648 c 0.0666,-8.17541 -5.78326,-15.22074 -15.222,-15.22074 -8.44192,0 -15.28779,6.77925 -15.28779,15.22074 0,8.44191 6.64684,15.22159 14.68985,15.22159 4.01434,0 7.62682,-2.06621 9.23846,-4.22518 l 0.79359,2.01434 0,0 c 0.42589,1.13177 1.5176,1.93717 2.7978,1.93717 1.65001,0 2.98756,-1.33671 2.99009,-2.98545 l 0,0 0,-7.80687 0,0 0,-4.1556 z m -15.222,9.43833 c -5.31773,0 -8.77419,-4.25469 -8.77419,-9.43833 0,-5.18406 3.45604,-9.43833 8.77419,-9.43833 5.3173,0 8.77419,4.25427 8.77419,9.43833 0,5.18364 -3.45689,9.43833 -8.77419,9.43833 z"
id="path17"
style="fill:#3c6eb4" />
<path
d="m 355.01479,368.3337 c 0,-1.7938 -1.46194,-3.18997 -3.25659,-3.18997 -1.79422,0 -3.25743,1.39659 -3.25743,3.18997 l 0,17.1499 c -1.66097,-3.05756 -5.25026,-5.11786 -9.50495,-5.11786 -8.64052,0 -14.42336,6.51318 -14.42336,15.22074 0,8.70757 5.98229,15.22159 14.42336,15.22159 3.76555,0 7.03057,-1.55429 8.98587,-4.25554 l 0.72317,1.83428 c 0.44782,1.25912 1.64917,2.16024 3.06051,2.16024 1.78621,0 3.24984,-1.45435 3.24984,-3.24815 0,-0.005 0,-0.009 0,-0.0139 l 0,0 0,-38.95128 -4.2e-4,0 z m -15.22116,36.69111 c -5.31731,0 -8.70715,-4.25469 -8.70715,-9.43833 0,-5.18406 3.38984,-9.43833 8.70715,-9.43833 5.31773,0 8.70714,4.0544 8.70714,9.43833 0,5.38309 -3.38941,9.43833 -8.70714,9.43833 z"
id="path19"
style="fill:#3c6eb4" />
<path
d="m 287.21553,365.34023 c -0.59414,-0.0877 -1.19966,-0.13198 -1.80097,-0.13198 -6.73118,0 -12.20746,5.4767 -12.20746,12.20788 l 0,3.8132 -3.98903,0 c -1.46237,0 -2.65908,1.19671 -2.65908,2.65781 0,1.46321 1.19671,2.93738 2.65908,2.93738 l 3.98819,0 0,20.46004 c 0,1.79464 1.46236,3.25743 3.25658,3.25743 1.79507,0 3.25744,-1.46279 3.25744,-3.25743 l 0,-20.46004 4.40986,0 c 1.46194,0 2.65823,-1.47417 2.65823,-2.93738 0,-1.46152 -1.19629,-2.65823 -2.65823,-2.65823 l -4.40733,0 0,-3.8132 c 0,-3.13852 2.55323,-6.11469 5.69175,-6.11469 0.28294,0 0.56757,0.0211 0.84672,0.062 1.78031,0.26355 3.4358,-0.54269 3.70019,-2.32342 0.2627,-1.77904 -0.96606,-3.43538 -2.74594,-3.69935 z"
id="path21"
style="fill:#3c6eb4" />
<path
d="m 482.01243,363.57426 c 0,-10.06788 -8.16108,-18.22938 -18.22897,-18.22938 -10.06282,0 -18.22179,8.15475 -18.22854,18.21631 l -4.2e-4,-4.2e-4 0,14.1071 4.2e-4,4.2e-4 c 0.005,2.28463 1.85832,4.13409 4.14463,4.13409 0.007,0 0.0127,-8.4e-4 0.0194,-8.4e-4 l 0.001,8.4e-4 14.07083,0 0,0 c 10.06409,-0.004 18.22138,-8.16276 18.22138,-18.22812 z"
id="path25"
style="fill:#294172" />
<path
d="m 469.13577,349.66577 c -4.72528,0 -8.55576,3.83049 -8.55576,8.55577 0,0.002 0,0.004 0,0.006 l 0,4.52836 -4.51444,0 c -8.5e-4,0 -8.5e-4,0 -0.001,0 -4.72528,0 -8.55576,3.81193 -8.55576,8.53678 0,4.72528 3.83048,8.55577 8.55576,8.55577 4.72486,0 8.55534,-3.83049 8.55534,-8.55577 0,-0.002 0,-0.004 0,-0.006 l 0,-4.54733 4.51444,0 c 8.5e-4,0 0.001,0 0.002,0 4.72486,0 8.55534,-3.79296 8.55534,-8.51781 0,-4.72528 -3.83048,-8.55577 -8.55534,-8.55577 z m -8.55576,21.63483 c -0.004,2.48998 -2.02446,4.50811 -4.51571,4.50811 -2.49378,0 -4.53426,-2.02193 -4.53426,-4.5157 0,-2.49421 2.04048,-4.55366 4.53426,-4.55366 0.002,0 0.004,4.2e-4 0.006,4.2e-4 l 3.86971,0 c 0.001,0 0.002,-4.2e-4 0.003,-4.2e-4 0.35209,0 0.63799,0.28505 0.63799,0.63715 0,4.2e-4 -4.2e-4,8.4e-4 -4.2e-4,0.001 l 0,3.92284 -4.2e-4,0 z m 8.55534,-8.5448 c -0.001,0 -0.003,0 -0.004,0 l -3.87223,0 c -8.4e-4,0 -0.002,0 -0.002,0 -0.35252,0 -0.63757,-0.28506 -0.63757,-0.63758 l 0,-4.2e-4 0,-3.90343 c 0.004,-2.49083 2.02446,-4.50854 4.51571,-4.50854 2.49378,0 4.53468,2.02193 4.53468,4.51613 4.2e-4,2.49336 -2.04048,4.53384 -4.53426,4.53384 z"
id="path29"
style="fill:#3c6eb4" />
<path
d="m 460.58001,362.7558 0,-4.52836 c 0,-0.002 0,-0.004 0,-0.006 0,-4.72528 3.83048,-8.55577 8.55576,-8.55577 0.71685,0 1.22623,0.0805 1.88952,0.25469 0.96774,0.25385 1.75796,1.04618 1.75838,1.96922 4.2e-4,1.11575 -0.80919,1.92621 -2.0194,1.92621 -0.57642,0 -0.78473,-0.11048 -1.62892,-0.11048 -2.49125,0 -4.51149,2.01771 -4.51571,4.50854 l 0,3.90385 0,4.2e-4 c 0,0.35252 0.28505,0.63758 0.63757,0.63758 4.3e-4,0 0.001,0 0.002,0 l 2.96521,0 c 1.10521,0 1.99747,0.88467 1.99832,1.99283 0,1.10816 -0.89353,1.99114 -1.99832,1.99114 l -3.60489,0 0,4.54733 c 0,0.002 0,0.004 0,0.006 0,4.72485 -3.83048,8.55534 -8.55534,8.55534 -0.71684,0 -1.22623,-0.0805 -1.88952,-0.25469 -0.96774,-0.25343 -1.75838,-1.04618 -1.7588,-1.9688 0,-1.11575 0.80919,-1.92663 2.01982,-1.92663 0.576,0 0.78473,0.11048 1.6285,0.11048 2.49125,0 4.51191,-2.01771 4.51613,-4.50811 0,0 0,-3.92368 0,-3.9241 0,-0.35168 -0.2859,-0.63673 -0.63799,-0.63673 -4.3e-4,0 -8.5e-4,0 -0.002,0 l -2.96521,-4.2e-4 c -1.10521,0 -1.99831,-0.88214 -1.99831,-1.9903 -4.3e-4,-1.11533 0.90238,-1.99367 2.01939,-1.99367 l 3.58339,0 0,0 z"
id="path31"
style="fill:#ffffff" />
<path
d="m 477.41661,378.55292 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="text6223"
style="fill:#294172;enable-background:new" />
</g>
<path
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" />
</svg>
Side by side

After

Width:  |  Height:  |  Size: 7.6 KiB

BIN
_images/redhat-logo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3.9 KiB

0
_javascripts/.gitkeep Normal file
View file

6
_javascripts/bootstrap-offcanvas.js vendored Normal file
View file

@ -0,0 +1,6 @@
$(document).ready(function () {
$('[data-toggle="offcanvas"]').click(function () {
$('.sidebar').show();
$('.row-offcanvas').toggleClass('active');
});
});

568
_stylesheets/asciibinder.css Normal file
View file

@ -0,0 +1,568 @@
@import url(https://maxcdn.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css);
/* ------------------------------------------------------------
Image: "Spin" https://www.flickr.com/photos/eflon/3655695161/
Author: eflon https://www.flickr.com/photos/eflon/
License: https://creativecommons.org/licenses/by/2.0/
---------------------------------------------------------------*/
.attribution {
text-align: center;
position: relative;
bottom: -20px;
}
.attribution .btn {
color: #808080;
color: rgba(175,175,175, .65);
font-size: 11px;
}
.attribution .btn:hover {
text-decoration: none;
color: #aaa;
}
.popover-content {
font-size: 12px;
line-height: 1.3;
font-weight: normal;
}
@media screen and (max-width: 980px) {
body {
margin-bottom: 200px;
}
footer {
text-align: center;
}
footer .text-right {
text-align: center !important;
}
#footer_social .first {
margin-left: 0;
}
#footer_social > a {
top: 24px;
}
}
.fa-inverse:hover {
color: #ccc;
}
.collapse a.active {
background-color: #DEEAF4;
color: #000;
position: relative;
}
.collapse a.active:hover {
text-decoration: none;
}
.collapse a.active:before {
background-color: #A0C3E5;
content: "";
display: inline-block;
height: 100%;
left: 0;
position: absolute;
top: 0;
width: 3px;
}
.main h2, .main .h2 {
border-top: 0px;
padding-top: 10px;
}
.page-header {
height: 100% !important;
}
.page-header h2{
font-size: 28px;
}
.navbar-brand {
padding: initial;
height: initial;
}
.nav > li > a.hover{
background-color: none;
}
h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 {
position: relative;
}
h2 > a.anchor, h3 > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor {
display: block;
font-weight: normal;
margin-left: -1.5ex;
position: absolute;
text-align: center;
text-decoration: none !important;
visibility: hidden;
width: 1.5ex;
z-index: 1001;
}
h2 > a.anchor:before, h3 > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before {
content: "\f0c1";
display: block;
font-family: FontAwesome;
font-size: 0.7em;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
padding-top: 0.2em;
}
h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before {
font-size: 1em;
}
h2:hover > a.anchor,
h2 > a.anchor:hover,
h3:hover > a.anchor,
h3 > a.anchor:hover,
h4:hover > a.anchor,
h4 > a.anchor:hover,
h5:hover > a.anchor,
h5 > a.anchor:hover,
h6:hover > a.anchor,
h6 > a.anchor:hover {
visibility: visible;
}
.main {
border-left: 1px solid #e7e7e7;
margin-left: -1px;
padding-left: 25px;
}
@media (min-width: 768px) {
.main {
padding-left: 30px;
}
}
/*
* Sidebar
*/
.nav-header {
font-size: 16px;
}
.nav-header ul {
font-size: 14px;
}
.nav-header ul li a {
display: block;
padding: 5px 20px 5px 25px;
font-size: 13px;
font-weight: normal;
}
.nav-sidebar .fa {
text-align: center;
top: -1px;
width: 14px;
}
.nav-sidebar li a {
color: inherit;
}
.nav-sidebar li a:hover {
color: #000;
}
.nav-sidebar ul li ul.nav-tertiary li a {
padding-left: 50px;
}
.nav-sidebar > li > a {
padding: 7px 0;
}
.nav-sidebar > li > a:focus, .nav-sidebar > li > a:hover {
background: transparent;
}
.sidebar {
font-weight: 300;
display: none;
padding-top: 13px;
}
@media screen and (max-width: 767px) {
.sidebar {
padding-left: 30px;
padding-right: 0;
}
}
@media screen and (min-width: 768px) {
.sidebar {
border-right: 1px solid #e7e7e7;
display: block;
}
}
/*
* Off Canvas
* --------------------------------------------------
*/
body, html {
overflow-x: hidden; /* Prevent scroll on narrow devices */
}
.toggle-nav {
margin-right: 20px;
}
@media screen and (max-width: 767px) {
.row-offcanvas {
position: relative;
-webkit-transition: all .25s ease-out;
-o-transition: all .25s ease-out;
transition: all .25s ease-out;
}
.row-offcanvas-right {
right: 0;
}
.row-offcanvas-left {
left: 0;
}
.row-offcanvas-right
.sidebar-offcanvas {
right: -75%; /* 8 columns */
}
.row-offcanvas-left
.sidebar-offcanvas {
left: -75%; /* 8 columns */
}
.row-offcanvas-right.active {
right: 75%; /* 8 columns */
}
.row-offcanvas-left.active {
left: 75%; /* 8 columns */
}
.sidebar-offcanvas {
overflow: hidden;
position: absolute;
top: 0;
width: 75%; /* 8 columns */
}
}
p {
margin: 0 0 1.6em;
}
/* Remnants of Asciidoctor default stylesheet - remove styles as needed */
#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }
.left { float: left !important; }
.right { float: right !important; }
.text-left { text-align: left !important; }
.text-right { text-align: right !important; }
.text-center { text-align: center !important; }
.text-justify { text-align: justify !important; }
.hide { display: none; }
.subheader, #content #toctitle, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: #7a2518; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }
abbr, acronym { text-transform: uppercase; font-size: 90%; color: #333333; border-bottom: 1px dotted #dddddd; cursor: help; }
abbr { text-transform: none; }
blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 3px solid #487c58; }
blockquote cite { display: block; font-size: inherit; color: #454545; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #454545; }
blockquote, blockquote p { line-height: 1.6; color: #6e6e6e; }
@media only screen and (min-width: 768px) {
#toctitle, .sidebarblock > .content > .title { line-height: 1.4; }
#toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
}
table { background: white; margin-bottom: 1.25em; border: solid 1px #dddddd; }
table thead, table tfoot { background: whitesmoke; font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #333333; text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #333333; }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f9f9f9; }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.6; }
.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }
*:not(pre) > code { font-size: inherit; padding: 0; white-space: nowrap; background-color: inherit; border: 0 solid #dddddd; -webkit-border-radius: 4px; border-radius: 4px; text-shadow: none; line-height: 1; }
.keyseq { color: #666666; }
kbd:not(.keyseq) { display: inline-block; color: #333333; font-size: 0.75em; line-height: 1.4; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; }
.keyseq kbd:first-child { margin-left: 0; }
.keyseq kbd:last-child { margin-right: 0; }
.menuseq, .menu { color: #1a1a1a; }
b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }
b.button:before { content: "["; padding: 0 3px 0 2px; }
b.button:after { content: "]"; padding: 0 2px 0 3px; }
p a > code:hover { color: #561309; }
#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }
#content:before { content: none; }
#header { margin-bottom: 2.5em; }
#header > h1 { color: black; font-weight: 300; border-bottom: 1px solid #d8d8d8; margin-bottom: -28px; padding-bottom: 32px; }
#header span { color: #6e6e6e; }
#header #revnumber { text-transform: capitalize; }
#header br { display: none; }
#header br + span { padding-left: 3px; }
#header br + span:before { content: "\2013 \0020"; }
#header br + span.author { padding-left: 0; }
#header br + span.author:before { content: ", "; }
#toc { border-bottom: 3px double #e5e5e5; padding-top: 1em; padding-bottom: 1.25em; }
#toc > ul { margin-left: 0.25em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
#toc ul { font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; list-style-type: none; }
#toc a { text-decoration: none; }
#toc a:active { text-decoration: underline; }
#toctitle { color: #7a2518; }
@media only screen and (min-width: 768px) { body.toc2 { padding-left: 15em; padding-right: 0; }
#toc.toc2 { background-color: #fafaf9; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #e5e5e5; border-bottom: 0; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; }
#toc.toc2 #toctitle { margin-top: 0; font-size: 1.2em; }
#toc.toc2 > ul { font-size: .90em; margin-bottom: 0; }
#toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
#toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
body.toc2.toc-right #toc.toc2 { border-right: 0; border-left: 1px solid #e5e5e5; left: auto; right: 0; } }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
#toc.toc2 { width: 20em; }
#toc.toc2 #toctitle { font-size: 1.375em; }
#toc.toc2 > ul { font-size: 0.95em; }
#toc.toc2 ul ul { padding-left: 1.25em; }
body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #e3e3dd; margin-bottom: 1.25em; padding: 1.25em; background: #fafaf9; border-width: 0; -webkit-border-radius: 4px; border-radius: 4px; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }
#content #toctitle { font-size: 1.375em; }
#footer { max-width: 100%; background-color: #333333; padding: 1.25em; }
#footer-text { color: #cccccc; line-height: 1.44; }
.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .verseblock, .videoblock { margin-bottom: 2.5em; }
.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; font-family: "Noto Serif", "DejaVu Serif", "Serif", serif; font-weight: normal; font-style: italic; }
table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; }
table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; }
.admonitionblock > table { border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: none; }
.admonitionblock > table td.icon .title { font-weight: 300; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 0; padding-right: 1.25em; color: #6e6e6e; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }
.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 4px; border-radius: 4px; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }
.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { color: #333333; }
.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { line-height: 1; margin-bottom: 0.625em; }
.exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { line-height: 1.4; }
.exampleblock.result > .content { -webkit-box-shadow: 0 1px 8px #e3e3dd; box-shadow: 0 1px 8px #e3e3dd; }
.sidebarblock { border-style: solid; border-width: 1px; border-color: #e3e3dd; margin-top: -1.0em; margin-bottom: 1.6em; padding: .5em; background: #F1F3F5; -webkit-border-radius: 4px; border-radius: 4px; overflow-x: auto; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { color: #333333; }
.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { line-height: 1; margin-bottom: 0.625em; }
.sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { line-height: 1.4; }
.sidebarblock > .content > .title { color: #7a2518; margin-top: 0; line-height: 1.6; }
.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 0px; background-color: #F0F3F5; -webkit-border-radius: 5px; border-radius: 5px; padding: 1.5em 2.5em; word-wrap: break-word; }
.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
.literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { display: block; }
.listingblock > .content { position: relative; }
.listingblock:hover code[class*=" language-"]:before { text-transform: uppercase; font-size: 0.9em; color: #999; position: absolute; top: 0.375em; right: 0.375em; }
.listingblock:hover code.asciidoc:before { content: "asciidoc"; }
.listingblock:hover code.clojure:before { content: "clojure"; }
.listingblock:hover code.css:before { content: "css"; }
.listingblock:hover code.go:before { content: "go"; }
.listingblock:hover code.groovy:before { content: "groovy"; }
.listingblock:hover code.html:before { content: "html"; }
.listingblock:hover code.java:before { content: "java"; }
.listingblock:hover code.javascript:before { content: "javascript"; }
.listingblock:hover code.python:before { content: "python"; }
.listingblock:hover code.ruby:before { content: "ruby"; }
.listingblock:hover code.sass:before { content: "sass"; }
.listingblock:hover code.scss:before { content: "scss"; }
.listingblock:hover code.xml:before { content: "xml"; }
.listingblock:hover code.yaml:before { content: "yaml"; }
.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }
.listingblock.terminal pre .command:not([data-prompt]):before { content: '$'; }
table.pyhltable { border: 0; margin-bottom: 0; }
table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; }
table.pyhltable td.code { padding-left: .75em; padding-right: 0; }
.highlight.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #d8d8d8; }
.highlight.pygments .lineno { display: inline-block; margin-right: .25em; }
table.pyhltable .linenodiv { background-color: transparent !important; padding-right: 0 !important; }
.quoteblock { margin: 0 0 1.25em 0; padding: 0.5625em 1.25em 0 1.1875em; border-left: 3px solid #487c58; }
.quoteblock blockquote { margin: 0 0 1.25em 0; padding: 0 0 0.625em 0; border: 0; }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: -0.625em; padding-bottom: 0.625em; font-size: inherit; color: #454545; line-height: 1.6; }
.quoteblock .attribution br { display: none; }
.quoteblock .attribution cite { display: block; }
table.tableblock { max-width: 100%; }
table.tableblock td .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; }
table.spread { width: 100%; }
table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dddddd; }
table.grid-all th.tableblock, table.grid-all td.tableblock { border-width: 0 1px 1px 0; }
table.grid-all tfoot > tr > th.tableblock, table.grid-all tfoot > tr > td.tableblock { border-width: 1px 1px 0 0; }
table.grid-cols th.tableblock, table.grid-cols td.tableblock { border-width: 0 1px 0 0; }
table.grid-all * > tr > .tableblock:last-child, table.grid-cols * > tr > .tableblock:last-child { border-right-width: 0; }
table.grid-rows th.tableblock, table.grid-rows td.tableblock { border-width: 0 0 1px 0; }
table.grid-all tbody > tr:last-child > th.tableblock, table.grid-all tbody > tr:last-child > td.tableblock, table.grid-all thead:last-child > tr > th.tableblock, table.grid-rows tbody > tr:last-child > th.tableblock, table.grid-rows tbody > tr:last-child > td.tableblock, table.grid-rows thead:last-child > tr > th.tableblock { border-bottom-width: 0; }
table.grid-rows tfoot > tr > th.tableblock, table.grid-rows tfoot > tr > td.tableblock { border-width: 1px 0 0 0; }
table.frame-all { border-width: 1px; }
table.frame-sides { border-width: 0 1px; }
table.frame-topbot { border-width: 1px 0; }
th.halign-left, td.halign-left { text-align: left; }
th.halign-right, td.halign-right { text-align: right; }
th.halign-center, td.halign-center { text-align: center; }
th.valign-top, td.valign-top { vertical-align: top; }
th.valign-bottom, td.valign-bottom { vertical-align: bottom; }
th.valign-middle, td.valign-middle { vertical-align: middle; }
table thead th, table tfoot th { font-weight: bold; }
tbody tr th { display: table-cell; line-height: 1.6; background: whitesmoke; }
tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: #333333; font-weight: bold; }
td > div.verse { white-space: pre; }
ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; }
ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; }
ul.checklist li > p:first-child > .fa-check-square-o:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }
ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; }
ul.inline { margin: 0 auto 0.625em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; }
ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; }
ul.inline > li > * { display: block; }
.unstyled dl dt { font-weight: normal; font-style: normal; }
ol.arabic { list-style-type: decimal; }
ol.decimal { list-style-type: decimal-leading-zero; }
ol.loweralpha { list-style-type: lower-alpha; }
ol.upperalpha { list-style-type: upper-alpha; }
ol.lowerroman { list-style-type: lower-roman; }
ol.upperroman { list-style-type: upper-roman; }
ol.lowergreek { list-style-type: lower-greek; }
.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }
td.hdlist1 { padding-right: .75em; font-weight: bold; }
td.hdlist1, td.hdlist2 { vertical-align: top; }
.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
.colist > table tr > td:first-of-type { padding: 0 .75em; line-height: 1; }
.colist > table tr > td:last-of-type { padding: 0.25em 0; }
.qanda > ol > li > p > em:only-child { color: #1d4b8f; }
.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }
.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }
.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }
a.image { text-decoration: none; }
span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; }
span.footnote a, span.footnoteref a { text-decoration: none; }
span.footnote a:active, span.footnoteref a:active { text-decoration: underline; }
#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }
.gist .file-data > table { border: none; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }
div.unbreakable { page-break-inside: avoid; }
.replaceable { font-style: italic; font-color: inherit; font-family: inherit; }
.parameter { font-style: italic; font-family: monospace; }
.userinput { font-weight: bold; font-family: monospace; }
.envar { font-weight: bold; font-family: monospace; font-size: 90%; }
.sysitem { font-weight: bold; font-size: 90%; }
.package { font-weight: bold; font-size: 90%; }
.filename { font-weight: bold; font-style: italic; font-size: 90%; }
.big { font-size: larger; }
.small { font-size: smaller; }
.underline { text-decoration: underline; }
.overline { text-decoration: overline; }
.line-through { text-decoration: line-through; }
.aqua { color: #00bfbf; }
.aqua-background { background-color: #00fafa; }
.black { color: black; }
.black-background { background-color: black; }
.blue { color: #0000bf; }
.blue-background { background-color: #0000fa; }
.fuchsia { color: #bf00bf; }
.fuchsia-background { background-color: #fa00fa; }
.gray { color: #606060; }
.gray-background { background-color: #7d7d7d; }
.green { color: #006000; }
.green-background { background-color: #007d00; }
.lime { color: #00bf00; }
.lime-background { background-color: #00fa00; }
.maroon { color: #600000; }
.maroon-background { background-color: #7d0000; }
.navy { color: #000060; }
.navy-background { background-color: #00007d; }
.olive { color: #606000; }
.olive-background { background-color: #7d7d00; }
.purple { color: #600060; }
.purple-background { background-color: #7d007d; }
.red { color: #bf0000; }
.red-background { background-color: #fa0000; }
.silver { color: #909090; }
.silver-background { background-color: #bcbcbc; }
.teal { color: #006060; }
.teal-background { background-color: #007d7d; }
.white { color: #bfbfbf; }
.white-background { background-color: #fafafa; }
.yellow { color: #bfbf00; }
.yellow-background { background-color: #fafa00; }
span.icon > .fa { cursor: default; }
.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #4E9FDD; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; color: #2C8596; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #ec7a08; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #ec7a08; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #c00; }
.conum[data-value] { display: inline-block; color: white !important; background-color: #333333; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; width: 20px; height: 20px; font-size: 12px; line-height: 20px; font-family: "Open Sans", "Sans", sans-serif; font-style: normal; font-weight: bold; text-indent: -1px; }
.conum[data-value] * { color: white !important; }
.conum[data-value] + b { display: none; }
.conum[data-value]:after { content: attr(data-value); }
pre .conum[data-value] { position: relative; top: -2px; }
b.conum * { color: inherit !important; }
.conum:not([data-value]):empty { display: none; }
.print-only { display: none !important; }
@media print { @page { margin: 1.25cm 0.75cm; }
* { -webkit-box-shadow: none !important; box-shadow: none !important; text-shadow: none !important; }
a, a:visited { color: inherit !important; text-decoration: underline !important; }
a[href^="http:"]:after, a[href^="https:"]:after { content: " (" attr(href) ")"; }
a[href^="#"], a[href^="#"]:visited, a[href^="mailto:"], a[href^="mailto:"]:visited { text-decoration: none !important; }
abbr[title]:after { content: " (" attr(title) ")"; }
pre, blockquote { page-break-inside: avoid; }
code { color: #191919; }
thead { display: table-header-group; }
tr, img { page-break-inside: avoid; }
img { max-width: 100% !important; }
p { orphans: 3; widows: 3; }
h2, h3, #toctitle, .sidebarblock > .content > .title, #toctitle, .sidebarblock > .content > .title { page-break-after: avoid; }
#toc, .sidebarblock { background: none !important; }
#toc { border-bottom: 1px solid #d8d8d8 !important; padding-bottom: 0 !important; }
.sect1 { padding-bottom: 0 !important; }
.sect1 + .sect1 { border: none !important; }
body.book #header { text-align: center; }
body.book #header > h1 { border: none !important; margin: 2.5em 0 1em 0; padding: 0; }
body.book #header span { line-height: 1.6; }
body.book #header br { display: block; }
body.book #header br + span { padding-left: 0; }
body.book #header br + span:before { content: none !important; }
body.book #toc { border: none !important; text-align: left !important; padding: 0 !important; }
#footer { background: none !important; }
#footer-text { color: #333333 !important; }
.hide-on-print { display: none !important; }
.print-only { display: block !important; }
.hide-for-print { display: none !important; }
.show-for-print { display: inherit !important; } }

3
_templates/_css.html.erb Normal file
View file

@ -0,0 +1,3 @@
<%- Dir.glob("_stylesheets/*").sort.each do |sheet| -%>
<link href="<%= File.join(css_path, File.basename(sheet)) %>" rel="stylesheet" />
<%- end -%>

88
_templates/_footer.html.erb Normal file
View file

@ -0,0 +1,88 @@
<div id="bottom" class="text-muted py-3" >
<div class="foot">
<div class="container">
<div class="row footerlinks">
<div class="col-sm-3 col-xs-6 widget">
<h3 class="widget-title">About</h3>
<div class="widget-body">
<dl>
<dd><a href="https://fedoraproject.org/wiki/Overview">About Fedora</a></dd>
<dd><a href="https://getfedora.org/en/sponsors">Sponsors</a></dd>
<dd><a href="https://fedoramagazine.org">Fedora Magazine</a></dd>
<dd><a href="https:https://fedoraproject.org/wiki/Legal:Main#Legal">Legal</a></dd>
</dl>
<ul class="list-inline">
<li>
<a href="https:https://www.facebook.com/TheFedoraProject" class="btn-social btn-outline"><i class="fa fa-fw fa-facebook"></i></a>
</li>
<li>
<a href="https:https://plus.google.com/112917221531140868607" class="btn-social btn-outline"><i class="fa fa-fw fa-google-plus"></i></a>
</li>
<li>
<a href="https:https://twitter.com/fedora" class="btn-social btn-outline"><i class="fa fa-fw fa-twitter"></i></a>
</li>
</ul>
</div>
</div>
<div class="col-sm-3 col-xs-6 widget">
<h3 class="widget-title uppercase">Download</h3>
<div class="widget-body">
<dl>
<dd><a href="https://getfedora.org/en/workstation/download">Get Fedora Workstation</a></dd>
<dd><a href="https://getfedora.org/en/server/download">Get Fedora Server</a></dd>
<dd><a href="https://getfedora.org/en/atomic/download">Get Fedora Atomic</a></dd>
<dd><a href="https://spins.fedoraproject.org">Fedora Spins</a></dd>
<dd><a href="https://labs.fedoraproject.org">Fedora Labs</a></dd>
<dd><a href="https://arm.fedoraproject.org">Fedora ARM<span class="sup">&reg;</span></a></dd>
<dd><a href="https://alt.fedoraproject.org/">Alternative Downloads</a></dd>
</dl>
</div>
</div>
<div class="col-sm-3 col-xs-6 widget">
<h3 class="widget-title">Support</h3>
<div class="widget-body">
<dl>
<dd><a href="https://fedoraproject.org/wiki/Communicating_and_getting_help">Get Help</a></dd>
<dd><a href="https://ask.fedoraproject.org/">Ask Fedora</a></dd>
<dd><a href="https://fedoraproject.org/wiki/Common_F${global_variables.release['curr_id']}_bugs">Common Bugs</a></dd>
<dd><a href="https://developer.fedoraproject.org/">Fedora Developer Portal</a></dd>
<dd><a href="https://docs.fedoraproject.org/en-US/Fedora/${global_variables.release['curr_id']}/html/Installation_Guide">Installation Guide</a></dd>
</dl>
</div>
</div>
<div class="col-sm-3 col-xs-6 widget">
<h3 class="widget-title">Join</h3>
<div class="widget-body">
<dl>
<dd><a href="https://fedoraproject.org/wiki/Join">Join Fedora</a></dd>
<dd><a href="http://fedoraplanet.org">Planet Fedora</a></dd>
<dd><a href="https://fedoraproject.org/wiki/SIGs">Fedora SIGs</a></dd>
<dd><a href="https://admin.fedoraproject.org/accounts/">Fedora Account System</a></dd>
<dd><a href="http://fedoracommunity.org/">Fedora Community</a></dd>
</dl>
</div>
</div>
</div> <!-- /row of widgets -->
<div class="row">
<div class="col-md-2">
<div class="widget-body">
<a href="http://www.redhat.com/"><img class="rh-logo" src="../_images/redhat-logo.png" alt="Red Hat Logo" /></a>
</div>
</div>
<div class="col-md-7">
<div class="widget-body">
<p class="sponsor">Fedora is sponsored by Red Hat.</p>
<p class="sponsor"><a href="https://www.redhat.com/en/technologies/linux-platforms/articles/relationship-between-fedora-and-rhel">Learn more about the relationship between Red Hat and Fedora &raquo;</a></p>
<p class="copy">&copy; 2017 Red Hat, Inc. and others. Please send any comments or corrections to the <a href="https://fedorahosted.org/fedora-websites/">websites team</a></p>
</div>
</div>
</div> <!-- /row of widgets -->
</div>
</div>
</div>

31
_templates/_nav.html.erb Normal file
View file

@ -0,0 +1,31 @@
<ul class="nav nav-sidebar">
<%- navigation.each.with_index do |topic_group, groupidx| -%>
<%- current_group = topic_group[:id] == group_id -%>
<li class="nav-header">
<a class="" href="#" data-toggle="collapse" data-target="#topicGroup<%= groupidx %>">
<span id="tgSpan<%= groupidx %>" class="fa <%= current_group ? 'fa-angle-down' : 'fa-angle-right' %>"></span><%= topic_group[:name] %>
</a>
<ul id="topicGroup<%= groupidx %>" class="collapse <%= current_group ? 'in' : '' %> list-unstyled">
<%- topic_group[:topics].each.with_index do |topic, topicidx| -%>
<%- if not topic.has_key?(:topics) -%>
<%- current_topic = current_group && (topic[:id] == topic_id) -%>
<li><a class="<%= current_topic ? ' active' : '' %>" href="<%= subtopic_shim %><%= topic[:path] %>"><%= topic[:name] %></a></li>
<%- else -%>
<%- current_subgroup = topic[:id] == subgroup_id -%>
<li class="nav-header">
<a class="" href="#" data-toggle="collapse" data-target="#topicSubGroup-<%= groupidx %>-<%= topicidx %>">
<span id="sgSpan-<%= groupidx %>-<%= topicidx %>" class="fa <%= current_subgroup ? 'fa-caret-down' : 'fa-caret-right' %>"></span>&nbsp;<%= topic[:name] %>
</a>
<ul id="topicSubGroup-<%= groupidx %>-<%= topicidx %>" class="nav-tertiary list-unstyled collapse<%= current_subgroup ? ' in' : '' %>">
<%- topic[:topics].each do |subtopic| -%>
<%- current_subtopic = current_group && current_subgroup && (subtopic[:id] == topic_id) %>
<li><a class="<%= current_subtopic ? ' active' : '' %>" href="<%= subtopic_shim %><%= subtopic[:path] %>"><%= subtopic[:name] %></a></li>
<%- end -%>
</ul>
</li>
<%- end -%>
<%- end -%>
</ul>
</li>
<%- end -%>
</ul>

93
_templates/page.html.erb Normal file
View file

@ -0,0 +1,93 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta content="IE=edge" http-equiv="X-UA-Compatible">
<meta content="width=device-width, initial-scale=1.0" name="viewport">
<title><%= distro %> <%= version %> | <%= [group_title, subgroup_title, topic_title].compact.join(' | ') %></title>
<!-- Bootstrap -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap-theme.min.css">
<%= render("_templates/_css.html.erb", :css_path => css_path) %>
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<link href="<%= File.join(images_path, "favicon32x32.png") %>" rel="shortcut icon" type="text/css">
<!--[if IE]><link rel="shortcut icon" href="<%= File.join(images_path, "favicon.ico") %>"><![endif]-->
<meta content="AsciiBinder" name="application-name">
</head>
<body>
<div class="navbar navbar-default" role="navigation">
<div class="container-fluid">
<div class="navbar-header">
<a class="navbar-brand" href="https://docs.fedoraproject.org/"><img alt="Fedora Documentation" src="<%= File.join(images_path, "fedora.svg") %>"></a>
</div>
</div>
</div>
<div class="container">
<p class="toggle-nav visible-xs pull-left">
<button class="btn btn-default btn-sm" type="button" data-toggle="offcanvas">Toggle nav</button>
</p>
<ol class="breadcrumb">
<li class="sitename">
<a href="<%= site_home_path %>"><%= site_name %></a>
</li>
<li class="hidden-xs active">
<%= breadcrumb_root %>
</li>
<li class="hidden-xs active">
<%= breadcrumb_group %>
</li>
<%= breadcrumb_subgroup_block %>
<li class="hidden-xs active">
<%= breadcrumb_topic %>
</li>
</ol>
<div class="row row-offcanvas row-offcanvas-left">
<div class="col-xs-8 col-sm-3 col-md-3 sidebar sidebar-offcanvas">
<%= render("_templates/_nav.html.erb", :navigation => navigation, :group_id => group_id, :topic_id => topic_id, :subgroup_id => subgroup_id, :subtopic_shim => subtopic_shim) %>
</div>
<div class="col-xs-12 col-sm-9 col-md-9 main">
<div class="page-header">
<h2><%= article_title %></h2>
</div>
<%= content %>
</div>
</div>
</div>
<%= render("_templates/_footer.html.erb") %>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<!-- Latest compiled and minified JavaScript -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
$(document).ready(function() {
$("[id^='topicGroup']").on('show.bs.collapse', function (event) {
if (!($(event.target).attr('id').match(/^topicSubGroup/))) {
$(this).parent().find("[id^='tgSpan']").toggleClass("fa-angle-right fa-angle-down");
}
});
$("[id^='topicGroup']").on('hide.bs.collapse', function (event) {
if (!($(event.target).attr('id').match(/^topicSubGroup/))) {
$(this).parent().find("[id^='tgSpan']").toggleClass("fa-angle-right fa-angle-down");
}
});
$("[id^='topicSubGroup']").on('show.bs.collapse', function () {
$(this).parent().find("[id^='sgSpan']").toggleClass("fa-caret-right fa-caret-down");
});
$("[id^='topicSubGroup']").on('hide.bs.collapse', function () {
$(this).parent().find("[id^='sgSpan']").toggleClass("fa-caret-right fa-caret-down");
});
});
/*]]>*/
</script>
</body>
</html>

112
_topic_map.yml Normal file
View file

@ -0,0 +1,112 @@
# This configuration file dictates the organization of the topic groups and
# topics on the main page of the doc site for this branch. Each record
# consists of the following:
#
# --- <= Record delimiter
# Name: Origin of the Species <= Display name of topic group
# Dir: origin_of_the_species <= Directory name of topic group
# Topics:
# - Name: The Majestic Marmoset <= Topic name
# File: the_majestic_marmoset <= Topic file under group dir +/-
# - Name: The Curious Crocodile <= Topic 2 name
# File: the_curious_crocodile <= Topic 2 file
# - Name: The Numerous Nematodes <= Sub-topic group name
# Dir: the_numerous_nematodes <= Sub-topic group dir
# Topics:
# - Name: The Wily Worm <= Sub-topic name
# File: the_wily_worm <= Sub-topic file under <group dir>/<subtopic dir>
# - Name: The Acrobatic Ascarid <= Sub-topic 2 name
# File: the_acrobatic_ascarid <= Sub-topic 2 file under <group dir>/<subtopic dir>
#
# The ordering of the records in this document determines the ordering of the
# topic groups and topics on the main page.
---
Name: Fedora System Administration Guide
Dir: en-US
Topics:
- Name: Book Information
File: Book_Info
- Name: Preface
File: Preface
- Name: Basic System Configuration
Dir: basic-system-configuration
Topics:
- Name: Introduction
File: intro-basic-system-configuration
- Name: Opening Graphical Applications
File: Opening_GUI_Applications
- Name: System Locale and Keyboard Configuration
File: System_Locale_and_Keyboard_Configuration
- Name: Configuring the Date and Time
File: Configuring_the_Date_and_Time
- Name: Managing Users and Groups
File: Managing_Users_and_Groups
- Name: Gaining Privileges
File: Gaining_Privileges
- Name: Package Management
Dir: package-management
Topics:
- Name: Introduction
File: intro-package-management
- Name: DNF
File: DNF
- Name: Infrastructure Services
Dir: infrastructure-services
Topics:
- Name: Introduction
File: intro-infrastructure-services
- Name: Services and Daemons
File: Services_and_Daemons
- Name: OpenSSH
File: OpenSSH
- Name: TigerVNC
File: TigerVNC
- Name: Servers
Dir: servers
Topics:
- Name: Introduction
File: intro-servers
- Name: Web Servers
File: Web_Servers
- Name: Mail Servers
File: Mail_Servers
- Name: Directory Servers
File: Directory_Servers
- Name: File and Print Servers
File: File_and_Print_Servers
- Name: Configuring NTP Using the chrony Suite
File: Configuring_NTP_Using_the_chrony_Suite
- Name: Configuring NTP Using ntpd
File: Configuring_NTP_Using_ntpd
- Name: Configuring PTP Using ptp4l
File: Configuring_PTP_Using_ptp4l
- Name: Monitoring and Automation
Dir: monitoring-and-automation
Topics:
- Name: Introduction
File: intro-monitoring-and-automation
- Name: System Monitoring Tools
File: System_Monitoring_Tools
- Name: Viewing and Managing Log Files
File: Viewing_and_Managing_Log_Files
- Name: Automating System Tasks
File: Automating_System_Tasks
- Name: OProfile
File: OProfile
- Name: Kernel, Module and Driver Configuration
Dir: kernel-module-driver-configuration
Topics:
- Name: Introduction
File: intro-kernel-module-driver-configuration
- Name: Working with the GRUB 2 Boot Loader
File: Working_with_the_GRUB_2_Boot_Loader
- Name: Manually Upgrading the Kernel
File: Manually_Upgrading_the_Kernel
- Name: Working with Kernel Modules
File: Working_with_Kernel_Modules
- Name: RPM
File: RPM
- Name: The Wayland Display Server
File: Wayland
- Name: Revision History
File: Revision_History

76
en-US/Author_Group.adoc Normal file
View file

@ -0,0 +1,76 @@
.Stephen Wadeley
*Red Hat*
Customer Content Services
swadeley@redhat.com
.Jaromír Hradílek
*Red Hat*
Customer Content Services
jhradilek@redhat.com
.Petr Bokoč
*Red{nbsp}Hat*
Customer Content Services
pbokoc@redhat.com
.Petr Kovář
*Red Hat*
Customer Content Services
pkovar@redhat.com
.Tomáš Čapek
*Red Hat*
Customer Content Services
tcapek@redhat.com
.Douglas Silas
*Red Hat*
Customer Content Services
silas@redhat.com
.Martin Prpič
*Red Hat*
Customer Content Services
.Eliška Slobodová
*Red Hat*
Customer Content Services
.Miroslav Svoboda
*Red Hat*
Customer Content Services
.John Ha
*Red Hat*
Customer Content Services
.David O'Brien
*Red Hat*
Customer Content Services
.Michael Hideo
*Red Hat*
Customer Content Services
.Don Domingo
*Red Hat*
Customer Content Services

18
en-US/Book_Info.adoc Normal file
View file

@ -0,0 +1,18 @@
:experimental:
include::en-US/entities.adoc[]
= System Administrator's Guide
Deployment, Configuration, and Administration of {MAJOROSVER}
[abstract]
--
The [citetitle]_System Administrator's Guide_ documents relevant information regarding the deployment, configuration, and administration of {MAJOROSVER}. It is oriented towards system administrators with a basic understanding of the system.
--
image:../../Common_Content/images/title_logo.svg[Fedora Documentation Team]
include::Common_Content/Legal_Notice.adoc[]
include::en-US/Author_Group.adoc[]

8
en-US/Feedback.adoc Normal file
View file

@ -0,0 +1,8 @@
:experimental:
=== We Need Feedback!
indexterm:[feedback,contact information for this manual]
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora%20Documentation&component=system-administrator's-guide[Bugzilla].
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

105
en-US/Preface.adoc Normal file
View file

@ -0,0 +1,105 @@
:experimental:
include::en-US/entities.adoc[]
== Preface
The [citetitle]_System Administrator's Guide_ contains information on how to customize the {MAJOROSVER} system to fit your needs. If you are looking for a comprehensive, task-oriented guide for configuring and customizing your system, this is the manual for you.
This manual discusses many intermediate topics such as the following:
* Installing and managing packages using [application]*DNF*
* Configuring [application]*Apache HTTP Server*, [application]*Postfix*, [application]*Sendmail* and other enterprise-class servers and software
* Working with kernel modules and upgrading the kernel
[NOTE]
====
Some of the graphical procedures and menu locations are specific to GNOME, but most command line instructions will be universally applicable.
====
[[sect-Preface-Target_Audience]]
=== Target Audience
The [citetitle]_System Administrator's Guide_ assumes you have a basic understanding of the {MAJOROS} operating system. If you need help with the installation of this system, refer to the link:++http://docs.fedoraproject.org/install-guide++[{MAJOROS} Installation Guide].
[[sect-Preface-Book_Organization]]
=== How to Read this Book
This manual is divided into the following main categories:
link:++basic-system-configuration/intro-basic-system-configuration.html++[Basic System Configuration]:: This part covers basic system administration tasks such as keyboard configuration, date and time configuration, managing users and groups, and gaining privileges.
+
link:++basic-system-configuration/Opening_GUI_Applications.html++[Opening Graphical Applications] describes methods for opening `Graphical User Interface`, or _GUI_, applications in various environments.
+
link:++basic-system-configuration/System_Locale_and_Keyboard_Configuration.html++[System Locale and Keyboard Configuration] covers basic language and keyboard setup. Read this chapter if you need to configure the language of your desktop, change the keyboard layout, or add the keyboard layout indicator to the panel.
+
link:++basic-system-configuration/Configuring_the_Date_and_Time.html++[Configuring the Date and Time] covers the configuration of the system date and time. Read this chapter if you need to set or change the date and time.
+
link:++basic-system-configuration/Managing_Users_and_Groups.html++[Managing Users and Groups] covers the management of users and groups in a graphical user interface and on the command line. Read this chapter if you need to manage users and groups on your system, or enable password aging.
+
link:++basic-system-configuration/Gaining_Privileges.html++[Gaining Privileges] covers ways to gain administrative privileges using setuid programs such as [command]#su# and [command]#sudo#.
link:++package-management/intro-package-management.html++[Package Management]:: This part describes how to manage software packages on {MAJOROS} using [application]*DNF*.
+
link:++package-management/DNF.html++[DNF] describes the [application]*DNF* package manager. Read this chapter for information how to search, install, update, and uninstall packages on the command line.
link:++infrastructure-services/intro-infrastructure-services.html++[Infrastructure Services]:: This part provides information on how to configure services and daemons, configure authentication, and enable remote logins.
+
link:++infrastructure-services/Services_and_Daemons.html++[Services and Daemons] covers the configuration of the services to be run when a system is started, and provides information on how to start, stop, and restart the services on the command line using the [command]#systemctl# utility.
+
link:++infrastructure-services/OpenSSH.html++[OpenSSH] describes how to enable a remote login via the SSH protocol. It covers the configuration of the `sshd` service, as well as a basic usage of the [command]#ssh#, [command]#scp#, [command]#sftp# client utilities. Read this chapter if you need a remote access to a machine.
+
link:++infrastructure-services/TigerVNC.html++[TigerVNC] describes the _virtual network computing_ (*VNC*) method of graphical desktop sharing which allows you to remotely control other computers.
link:++servers/intro-servers.html++[Servers]:: This part discusses various topics related to servers such as how to set up a Web server or share files and directories over the network.
+
link:++servers/Web_Servers.html++[Web Servers] focuses on the [application]*Apache HTTP Server*, a robust, full-featured open source web server developed by the Apache Software Foundation. Read this chapter if you need to configure a web server on your system.
+
link:++servers/Mail_Servers.html++[Mail Servers] reviews modern email protocols in use today, and some of the programs designed to send and receive email, including [application]*Postfix*, [application]*Sendmail*, [application]*Fetchmail*, and [application]*Procmail*. Read this chapter if you need to configure a mail server on your system.
+
link:++servers/Directory_Servers.html++[Directory Servers] covers the installation and configuration of [application]*OpenLDAP*, an open source implementation of the LDAPv2 and LDAPv3 protocols. Read this chapter if you need to configure a directory server on your system.
+
link:++servers/File_and_Print_Servers.html++[File and Print Servers] guides you through the installation and configuration of [application]*Samba*, an open source implementation of the Server Message Block (SMB) protocol, and [application]*vsftpd*, the primary FTP server shipped with {MAJOROS}. Additionally, it explains how to use the [application]*Printer Configuration* tool to configure printers. Read this chapter if you need to configure a file or print server on your system.
+
link:++servers/Configuring_NTP_Using_the_chrony_Suite.html++[Configuring NTP Using the chrony Suite] covers the installation and configuration of the [application]*chrony* suite, a client and a server for the Network Time Protocol (`NTP`). Read this chapter if you need to configure the system to synchronize the clock with a remote `NTP` server, or set up an `NTP` server on this system.
+
link:++servers/Configuring_NTP_Using_ntpd.html++[Configuring NTP Using ntpd] covers the installation and configuration of the `NTP` daemon, `ntpd`, for the Network Time Protocol (`NTP`). Read this chapter if you need to configure the system to synchronize the clock with a remote `NTP` server, or set up an `NTP` server on this system, and you prefer not to use the [application]*chrony* application.
+
link:++servers/Configuring_PTP_Using_ptp4l.html++[Configuring PTP Using ptp4l] covers the installation and configuration of the Precision Time Protocol application, [application]*ptp4l*, an application for use with network drivers that support the Precision Network Time Protocol (`PTP`). Read this chapter if you need to configure the system to synchronize the system clock with a master `PTP` clock.
link:++monitoring-and-automation/intro-monitoring-and-automation.html++[Monitoring and Automation]:: This part describes various tools that allow system administrators to monitor system performance, automate system tasks, and report bugs.
+
link:++monitoring-and-automation/System_Monitoring_Tools.html++[System Monitoring Tools] discusses applications and commands that can be used to retrieve important information about the system. Read this chapter to learn how to gather essential system information.
+
link:++monitoring-and-automation/Viewing_and_Managing_Log_Files.html++[Viewing and Managing Log Files] describes the configuration of the `rsyslog` daemon, and explains how to locate, view, and monitor log files. Read this chapter to learn how to work with log files.
+
link:++monitoring-and-automation/Automating_System_Tasks.html++[Automating System Tasks] provides an overview of the [command]#cron#, [command]#at#, and [command]#batch# utilities. Read this chapter to learn how to use these utilities to perform automated tasks.
+
link:++monitoring-and-automation/OProfile.html++[OProfile] covers [application]*OProfile*, a low overhead, system-wide performance monitoring tool. Read this chapter for information on how to use [application]*OProfile* on your system.
link:++kernel-module-driver-configuration/intro-kernel-module-driver-configuration.html++[Kernel, Module and Driver Configuration]:: This part covers various tools that assist administrators with kernel customization.
+
link:++kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.html++[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.
+
link:++kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.html++[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.
+
link:++kernel-module-driver-configuration/Working_with_Kernel_Modules.html++[Working with Kernel Modules] explains how to display, query, load, and unload kernel modules and their dependencies, and how to set module parameters. Additionally, it covers specific kernel module capabilities such as using multiple Ethernet cards and using channel bonding. Read this chapter if you need to work with kernel modules.
link:++RPM.html++[RPM]:: This appendix concentrates on the RPM Package Manager (RPM), an open packaging system used by {MAJOROS}, and the use of the [command]#rpm# utility. Read this appendix if you need to use [command]#rpm# instead of [command]#dnf#.
link:++Wayland.html++[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.
include::en-US/Feedback.adoc[]
[[pref-Acknowledgments]]
=== Acknowledgments
Certain portions of this text first appeared in the [citetitle]_Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 System Administrator's Guide_, copyright &copy; 2014&ndash;{YEAR} Red{nbsp}Hat, Inc., available at link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/index.html++[].
link:++monitoring-and-automation/System_Monitoring_Tools.html#sect-System_Monitoring_Tools-Net-SNMP++[Monitoring Performance with Net-SNMP] is based on an article written by Michael Solberg.
The authors of this book would like to thank the following people for their valuable contributions: Adam Tkáč, Andrew Fitzsimon, Andrius Benokraitis, Brian Cleary Edward Bailey, Garrett LeSage, Jeffrey Fearn, Joe Orton, Joshua Wulf, Karsten Wade, Lucy Ringland, Marcela Mašláňová, Mark Johnson, Michael Behm, Miroslav Lichvár, Radek Vokál, Rahul Kavalapara, Rahul Sundaram, Sandra Moore, Zbyšek Mráz, Jan Včelák, Peter Hutterer, T.C. Hollingsworth, and James Antill, among many others.

484
en-US/RPM.adoc Normal file
View file

@ -0,0 +1,484 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-RPM]]
== RPM
indexterm:[RPM Package Manager,RPM]indexterm:[RPM]indexterm:[packages,RPM]
The _RPM Package Manager_ ([application]*RPM*) is an open packaging system that runs on {MAJOROS} as well as other Linux and UNIX systems. Red{nbsp}Hat and the Fedora Project encourage other vendors to use [application]*RPM* for their own products. [application]*RPM* is distributed under the terms of the _GPL_ (_GNU General Public License_).
The [application]*RPM Package Manager* only works with packages built in the *RPM format*. [application]*RPM* itself is provided as the pre-installed [package]*rpm* package. For the end user, [application]*RPM* makes system updates easy. Installing, uninstalling, and upgrading [application]*RPM* packages can be accomplished with short commands. [application]*RPM* maintains a database of installed packages and their files, so you can make queries and verify installed files on your system. There are several applications, such as [application]*DNF* or [application]*PackageKit*, that can make working with packages in the [application]*RPM* format even easier.
[[warning-Use_DNF_Instead_of_RPM_Whenever_Possible]]
.Use DNF Instead of RPM Whenever Possible
[WARNING]
====
indexterm:[packages,DNF instead of RPM]
For most package-management tasks, the [application]*DNF* package manager offers equal and often greater capabilities and utility than [application]*RPM*. [application]*DNF* also performs and tracks complicated system-dependency resolutions. [application]*DNF* maintains the system integrity and forces a system integrity check if packages are installed or removed using another application, such as [application]*RPM*, instead of [application]*DNF*. For these reasons, it is highly recommended that you use [application]*DNF* instead of [application]*RPM* whenever possible to perform package-management tasks. See <<ch-DNF>>.
If you prefer a graphical interface, you can use the [application]*PackageKit* GUI application, which uses [application]*DNF* as its back end, to manage your system's packages.
====
During upgrades, [application]*RPM* handles configuration files carefully, so that you never lose your customizations &mdash; something that you cannot accomplish with regular `.tar.gz` files.
indexterm:[packages,RPM,source and binary packages]
For the developer, [application]*RPM* enables software source code to be packaged into source and binary packages for end users. This process is quite simple and is driven from a single file and optional patches that you create. This clear delineation between pristine sources and your patches along with build instructions eases the maintenance of the package as new versions of the software are released.
[[note-Root_Permissions]]
.Note
[NOTE]
====
Because [application]*RPM* can make changes to the system itself, performing operations like installing, upgrading, downgrading, and uninstalling binary packages system-wide requires `root` privileges in most cases.
====
[[s1-rpm-design]]
=== RPM Design Goals
indexterm:[RPM,design goals]
To understand how to use [application]*RPM*, it is helpful to understand the design goals of [application]*RPM*:
indexterm:[RPM,design goals,upgradability] Upgradability:: With [application]*RPM*, you can upgrade individual components of your system without a complete reinstallation. When you get a new release of an operating system based on [application]*RPM*, such as {MAJOROS}, you do not need to reinstall a fresh copy of the operating system on your machine (as you might need to with operating systems based on other packaging systems). [application]*RPM* allows for intelligent, fully-automated, in-place upgrades of your system. In addition, configuration files in packages are preserved across upgrades, so you do not lose your customizations. There are no special upgrade files needed to upgrade a package because the same [application]*RPM* file is used to both install and upgrade the package on the system.
indexterm:[RPM,design goals,powerful querying] Powerful Querying:: [application]*RPM* is designed to provide powerful querying options. You can perform searches on your copy of the database for packages or even just certain files. You can also easily find out what package a file belongs to and where the package came from. The files an [application]*RPM* package contains are in a compressed archive, with a custom binary header containing useful information about the package and its contents, allowing you to query individual packages quickly and easily.
indexterm:[RPM,design goals,system verification] System Verification:: Another powerful [application]*RPM* feature is the ability to verify packages. It allows you to verify that the files installed on the system are the same as the ones supplied by a given package. If an inconsistency is detected, [application]*RPM* notifies you, and you can reinstall the package if necessary. Any configuration files that you modified are preserved during reinstallation.
indexterm:[packages,RPM,pristine sources] Pristine Sources:: A crucial design goal was to allow the use of *pristine* software sources, as distributed by the original authors of the software. With [application]*RPM*, you have the pristine sources along with any patches that were used, plus complete build instructions. This is an important advantage for several reasons. For instance, if a new version of a program is released, you do not necessarily have to start from scratch to get it to compile. You can look at the patch to see what you *might* need to do. All the compiled-in defaults, and all of the changes that were made to get the software to build properly, are easily visible using this technique.
The goal of keeping sources pristine may seem important only for developers, but it results in higher quality software for end users.
[[s1-rpm-using]]
=== Using RPM
[application]*RPM* has five basic modes of operationindexterm:[RPM,basic modes] (not counting package building): installing, uninstalling, upgrading, querying, and verifying. This section contains an overview of each mode. For complete details and options, try [command]#rpm --help# or see *rpm*(8). Also, see <<s1-rpm-additional-resources>> for more information on [application]*RPM*.
[[sec-Installing_and_Upgrading]]
==== Installing and Upgrading Packages
indexterm:[RPM,installing]indexterm:[RPM,upgrading]indexterm:[packages,installing RPM]indexterm:[packages,upgrading RPM]indexterm:[RPM,file name]
[application]*RPM* packages typically have file names in the following form:
----
package_name-version-release-operating_system-CPU_architecture.rpm
----
For example the `tree-1.7.0-3.{PKGOS}.x86_64.rpm` file name includes the package name (`tree`), version (`1.7.0`), release (`3`), operating system major version (`{PKGOS}`) and *CPU* architecture (`x86_64`).
.Important
[IMPORTANT]
====
When installing a package, ensure it is compatible with your operating system and processor architecture. This can usually be determined by checking the package name. For example, the file name of an [application]*RPM* package compiled for the AMD64/Intel{nbsp}64 computer architectures ends with `x86_64.rpm`.
====
The [option]`-U` (or [option]`--upgrade`) option has two functions, it can be used to:
* upgrade an existing package on the system to a newer version, or
* install a package if an older version is not already installed.
The [command]#rpm -U _package.rpm_pass:attributes[{blank}]# command is therefore able to either *upgrade* or *install*, depending on the presence of an older version of _package.rpm_ on the system.
Assuming the `tree-1.7.0-3.{PKGOS}.x86_64.rpm` package is in the current directory, log in as `root` and type the following command at a shell prompt to either upgrade or install the [package]*tree* package:
[subs="attributes"]
----
~]#{nbsp}rpm -Uvh tree-1.7.0-3.{PKGOS}.x86_64.rpm
----
[[note-Use_-Uvh_for_nicely-formatted_RPM_installs]]
.Use -Uvh for nicely-formatted RPM installs
[NOTE]
====
The [option]`-v` and [option]`-h` options (which are combined with [option]`-U`) cause [application]*rpm* to print more verbose output and display a progress meter using hash signs.
====
If the upgrade or installation is successful, the following output is displayed:
----
Preparing... ########################################### [100%]
1:tree ########################################### [100%]
----
[[warning-Always_use_the_-i_install_option_to_install_new_kernel_packages]]
.Always use the -i (install) option to install new kernel packages!
[WARNING]
====
[command]#rpm# provides two different options for installing packages: the aforementioned [option]`-U` option (which historically stands for *upgrade*), and the [option]`-i` option (which historically stands for *install*). Because the [option]`-U` option includes both install and upgrade functions, the use of [command]#rpm -Uvh# with all packages, *except kernel packages*, is recommended.
You should always use the [option]`-i` option to *install* a new kernel package instead of upgrading it. This is because using the [option]`-U` option to upgrade a kernel package removes the previous (older) kernel package, which could render the system unable to boot if there is a problem with the new kernel. Therefore, use the [command]#rpm -i _kernel_package_pass:attributes[{blank}]# command to install a new kernel *without replacing any older kernel packages*. For more information on installing [package]*kernel* packages, see <<ch-Manually_Upgrading_the_Kernel>>.
====
The signature of a package is checked automatically when installing or upgrading a package. The signature confirms that the package was signed by an authorized party. If the verification of the signature fails, an error message is displayed.
If you do not have the appropriate key installed to verify the signature, the message contains the word `NOKEY`:
[subs="attributes"]
----
warning: tree-1.7.0-3.{PKGOS}.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 431d51: NOKEY
----
See <<s1-check-rpm-sig>> for more information on checking package signatures.
[[s3-rpm-errors]]
===== Replacing Already-Installed Packages
indexterm:[RPM,already installed]indexterm:[packages,RPM,already installed]
If a package of the same name and version is already installed, the following output is displayed:
[subs="attributes"]
----
Preparing... ########################################### [100%]
package tree-1.7.0-3.{PKGOS}.x86_64 is already installed
----
To install the package anyway, use the [option]`--replacepkgs` option, which tells [application]*RPM* to ignore the error:
[subs="attributes"]
----
~]#{nbsp}rpm -Uvh --replacepkgs tree-1.7.0-3.{PKGOS}.x86_64.rpm
----
This option is helpful if files installed from the package were deleted or if you want the original configuration files to be installed.
If you attempt an upgrade to an *older* version of a package (that is, if a newer version of the package is already installed), [application]*RPM* informs you that a newer version is already installed. To force [application]*RPM* to perform the downgrade, use the [command]#--oldpackage# option:
----
rpm -Uvh --oldpackage older_package.rpm
----
[[s3-rpm-conflicting-files]]
===== Resolving File Conflicts
indexterm:[RPM,file conflicts,resolving]indexterm:[RPM,conflicts]indexterm:[packages,RPM,conflict]
If you attempt to install a package that contains a file that has already been installed by another package, a conflict message is displayed. To make [application]*RPM* ignore this error, use the [command]#--replacefiles# option:
[subs="quotes, macros"]
----
[command]#rpm -Uvh --replacefiles _package.rpm_pass:attributes[{blank}]#
----
[[s3-rpm-unresolved-dependency]]
===== Satisfying Unresolved Dependencies
indexterm:[RPM,dependencies]indexterm:[packages,dependencies]indexterm:[RPM,failed dependencies]indexterm:[packages,RPM,failed dependencies]
[application]*RPM* packages sometimes depend on other packages, which means that they require other packages to be installed to run properly. If you try to install a package that has an unresolved dependency, a message about a failed dependency is displayed.
Find the suggested package(s) on the {MAJOROS} installation media or on one of the active {MAJOROS} mirrors and add it to the installation command. To determine which package contains the required file, use the [option]`--whatprovides` option:
----
rpm -q --whatprovides "required_file"
----
If the package that contains _required_file_ is in the [application]*RPM* database, the name of the package is displayed.
[[warning-Forcing_Package_Installation]]
.Warning
[WARNING]
====
Although you can *force* [command]#rpm# to install a package that has an unresolved dependency (using the [option]`--nodeps` option), this is *not* recommended and will usually result in the installed software failing to run. Installing packages with [option]`--nodeps` can cause applications to misbehave or terminate unexpectedly. It can also cause serious package-management problems or system failure. For these reasons, heed the warnings about missing dependencies. The [application]*DNF* package manager performs automatic dependency resolution and fetches dependencies from on-line repositories.
====
[[sec-Configuration_File_Changes]]
===== Preserving Changes in Configuration Files
indexterm:[RPM,configuration file changes]indexterm:[packages,RPM,configuration file changes]indexterm:[RPM,configuration file changes,conf.rpmsave]
Because [application]*RPM* performs intelligent upgrading of packages with configuration files, you may see the following message:
[subs="macros"]
----
saving pass:quotes[_/etc/configuration_file.conf_] as pass:quotes[_/etc/configuration_file.conf_].rpmsave
----
This message means that the changes you made to the configuration file may not be *forward-compatible* with the new configuration file in the package, so [application]*RPM* saved your original file and installed a new one. You should investigate the differences between the two configuration files and resolve them as soon as possible to ensure that your system continues to function properly.
Alternatively, [application]*RPM* may save the package's *new* configuration file as, for example, `pass:attributes[{blank}]_configuration_file.conf_.rpmnew` and leave the configuration file you modified untouched. You should still resolve any conflicts between your modified configuration file and the new one, usually by merging changes from the old one to the new one, for example using the [command]#diff# program.
[[s2-rpm-uninstalling]]
==== Uninstalling Packages
indexterm:[RPM,uninstalling]indexterm:[packages,removing]indexterm:[packages,RPM,uninstalling]indexterm:[packages,RPM,removing]
Uninstalling a package is just as simple as installing one. Type the following command at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#rpm -e _package_pass:attributes[{blank}]#
----
.rpm -e and package name errors
[NOTE]
====
Note that the command expects only the package *name*, not the name of the original package *file*. If you attempt to uninstall a package using the [command]#rpm{nbsp}-e# command and provide the original full file name, you receive a package-name error.
====
You can encounter dependency errors when uninstalling a package if another installed package depends on the one you are trying to remove. For example:
[subs="attributes"]
----
~]#{nbsp}rpm -e ghostscript
error: Failed dependencies:
ghostscript is needed by (installed) ghostscript-cups-9.07-16.{PKGOS}.x86_64
ghostscript is needed by (installed) foomatic-4.0.9-6.{PKGOS}.x86_64
libgs.so.9()(64bit) is needed by (installed) libspectre-0.2.7-4.{PKGOS}.x86_64
libijs-0.35.so()(64bit) is needed by (installed) gutenprint-5.2.9-15.{PKGOS}.x86_64
libijs-0.35.so()(64bit) is needed by (installed) cups-filters-1.0.35-15.{PKGOS}.x86_64
----
[[warning-uninstall-Warning-Forcing_Package_Installation]]
.Warning: Forcing Package Installation
[WARNING]
====
Although you can *force* [command]#rpm# to uninstall a package that has unresolved dependencies (using the [option]`--nodeps` option), this is *not* recommended. Removing packages with [option]`--nodeps` can cause applications from the packages whose dependencies are removed to misbehave or terminate unexpectedly. It can also cause serious package-management problems or system failure. For these reasons, heed the warnings about failed dependencies.
====
[[s2-rpm-freshening]]
==== Freshening Packages
indexterm:[RPM,freshening]indexterm:[packages,RPM,freshening]
Freshening is similar to upgrading, except that only installed packages are upgraded. Type the following command at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#rpm -Fvh _package.rpm_pass:attributes[{blank}]#
----
The [option]`-F` (or [option]`--freshen`) option compares the versions of the packages specified on the command line with the versions of packages that are already installed on the system. When a newer version of an already-installed package is processed by the [option]`--freshen` option, it is upgraded to the newer version. However, the [option]`--freshen` option does not install a package if no previously-installed package of the same name exists. This differs from regular upgrading, as an upgrade installs all specified packages regardless of whether or not older versions of the packages are already installed.
Freshening works for single packages or package groups. For example, freshening can help if you download a large number of different packages, and you only want to upgrade those packages that are already installed on the system. In this case, issue the following command with the `*.rpm` global expression:
[subs="attributes"]
----
~]#{nbsp}rpm -Fvh *.rpm
----
[application]*RPM* then automatically upgrades only those packages that are already installed.
[[s2-rpm-querying]]
==== Querying Packages
indexterm:[RPM,querying]indexterm:[packages,RPM,querying]
The [application]*RPM* database stores information about all [application]*RPM* packages installed on the system. It is stored in the `/var/lib/rpm/` directory and is used for many things, including querying what packages are installed, what version each package is, and for calculating changes to files in packages since their installation. To query this database, use the [command]#rpm# command with the [option]`-q` (or [option]`--query`) option:
----
rpm -q package_name
----
This command displays the package name, version, and release number of the installed package _package_name_. For example:
[subs="attributes"]
----
~]${nbsp}rpm -q tree
tree-1.7.0-3.{PKGOS}.x86_64
----
See the `Package Selection Options` subheading in the *rpm*(8) manual page for a list of options that can be used to further refine or qualify your query. Use options listed below the `Package Query Options` subheading to specify what information to display about the queried packages.
[[s2-rpm-verifying]]
==== Verifying Packages
indexterm:[RPM,verifying]indexterm:[packages,RPM,verifying]
Verifying a package is comparing information about files on the system installed from a package with the same information from the original package. Among other parameters, verifying compares the file size, MD5 sum, permissions, type, owner, and the group of each file.
Use the [command]#rpm# command with the [option]`-V` (or [option]`--verify`) option to verify packages. For example:
[subs="quotes, macros, attributes"]
----
~]${nbsp}pass:attributes[{blank}][command]#rpm -V tree#
----
See the `Package Selection Options` subheading in the *rpm*(8) manual page for a list of options that can be used to further refine or qualify your query. Use options listed below the `Verify Options` subheading to specify what characteristics to verify in the queried packages.
If everything verifies properly, there is no output. If there are any discrepancies, they are displayed. The output consists of lines similar to these:
[subs="attributes"]
----
~]#{nbsp}rpm -V abrt
S.5....T. c /etc/abrt/abrt.conf
.M....... /var/spool/abrt-upload
----
The format of the output is a string of nine characters followed by an optional attribute marker and the name of the processed file.
The first nine characters are the results of tests performed on the file. Each test is the comparison of one attribute of the file to the value of that attribute as recorded in the [application]*RPM* database. A single period (`.`) means the test passed, and the question-mark character (`?`) signifies that the test could not be performed. The following table lists symbols that denote specific discrepancies:
[[tab-rpm-verification-symbols]]
.RPM Verification Symbols
indexterm:[RPM,verification]
[options="header"]
|===
|Symbol|Description
|`S`|file size differs
|`M`|mode differs (includes permissions and file type)
|`5`|digest (formerly MD5 sum) differs
|`D`|device major/minor number mismatch
|`L`|*readLink*(2) path mismatch
|`U`|user ownership differs
|`G`|group ownership differs
|`T`|mtime differs
|`P`|capabilities differ
|===
The attribute marker, if present, describes the purpose of the given file. The following table lists the available attribute markers:
[[tab-rpm-verification-markers]]
.RPM Verification Symbols
indexterm:[RPM,verification]
[options="header"]
|===
|Marker|Description
|`c`|configuration file
|`d`|documentation file
|`l`|license file
|`r`|readme file
|===
If you see any output, use your best judgment to determine if you should remove the package, reinstall it, or fix the problem in another way.
[[s1-find-verify-rpm]]
=== Finding and Verifying RPM Packages
indexterm:[RPM,finding and verifying RPM packages]
Before using any [application]*RPM* packages, you must know where to find them and be able to verify if you can trust them.
[[s2-rpm-finding]]
==== Finding RPM Packages
indexterm:[packages,finding Fedora RPM packages]indexterm:[RPM,finding Fedora RPM packages]
Although there are many [application]*RPM* repositories on the Internet, for security and compatibility reasons, you should consider installing only official Fedora-provided RPM packages. The following is a list of sources for [application]*RPM* packages:
* indexterm:[{MAJOROS} installation media,installable packages]
indexterm:[packages,{MAJOROS} installation media]
Official {MAJOROS} installation media.
* indexterm:[initial RPM repositories,installable packages]
indexterm:[packages,initial RPM repositories]
Official [application]*RPM* repositories provided with the [application]*DNF* package manager. See <<ch-DNF>> for details on how to use the official {MAJOROS} package repositories.
* Unofficial, third-party repositories not affiliated with {OSORG} also provide RPM packages.
.Important
[IMPORTANT]
====
When considering third-party repositories for use with your {MAJOROS} system, pay close attention to the repository's web site with regard to package compatibility before adding the repository as a package source. Alternate package repositories may offer different, incompatible versions of the same software, including packages already included in the {MAJOROS} repositories.
====
[[s1-check-rpm-sig]]
==== Checking Package Signatures
indexterm:[RPM,GnuPG]indexterm:[RPM,checking package signatures]indexterm:[GnuPG,checking RPM package signatures]
[application]*RPM* packages can be signed using [application]*GNU Privacy Guard* (or [application]*GPG*), which helps you make certain that downloaded packages are trustworthy. [application]*GPG* is a tool for secure communication. With [application]*GPG*, you can authenticate the validity of documents and encrypt or decrypt data.
To verify that a package has not been corrupted or tampered with, check its [application]*GPG* signature by using the [command]#rpmkeys# command with the [option]`-K` (or [option]`--checksig`) option:
[subs="quotes, macros"]
----
[command]#rpmkeys -K _package.rpm_pass:attributes[{blank}]#
----
Note that the [application]*DNF* package manager performs automatic checking of [application]*GPG* signatures during installations and upgrades.
[application]*GPG* is installed by default, as well as a set of Red{nbsp}Hat keys for verifying packages. To import additional keys for use with [application]*RPM*, see <<s2-keys-importing>>.
[[s2-keys-importing]]
===== Importing GPG Keys
To verify Red Hat packages, a Red{nbsp}Hat [application]*GPG* key needs to be installed. A set of basic keys is installed by default. To view a list of installed keys, execute the following command at a shell prompt:
[subs="attributes"]
----
~]${nbsp}rpm -qa gpg-pubkey*
----
To display details about a specific key, use [command]#rpm{nbsp}-qi# followed by the output from the previous command. For example:
[subs="quotes, macros, attributes"]
----
~]${nbsp}pass:attributes[{blank}][command]#rpm -qi gpg-pubkey-fd431d51-4ae0493b#
----
Use the [command]#rpmkeys# command with the [option]`--import` option to install a new key for use with [application]*RPM*. The default location for storing [application]*RPM* *GPG* keys is the `/etc/pki/rpm-gpg/` directory. To import new keys, use a command like the following as `root`:
[subs="attributes"]
----
~]#{nbsp}rpmkeys --import /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
----
See the link:++https://access.redhat.com/security/team/key/++[Product Signing (GPG) Keys] article on the Red{nbsp}Hat Customer{nbsp}Portal for additional information about Red{nbsp}Hat package-signing practices.
[[s1-rpm-usage-examples]]
=== Common Examples of RPM Usage
indexterm:[RPM,tips]indexterm:[packages,RPM,tips]
[application]*RPM* is a useful tool for both managing your system and diagnosing and fixing problems. See the following examples for an overview of some of the most-used options.
* To verify your entire system and see what files are missing, issue the following command as `root`:
indexterm:[RPM,finding deleted files with]indexterm:[packages,finding deleted files from]
[subs="quotes, macros"]
----
[command]#rpm -Va#
----
If some files are missing or appear corrupted, consider reinstalling relevant packages.
* To determine which package owns a file, enter:
indexterm:[RPM,determining file ownership with]indexterm:[packages,determining file ownership with]
[subs="quotes, macros"]
----
[command]#rpm -qf _file_pass:attributes[{blank}]#
----
* To verify the package that owns a particular file, enter as `root`:
[subs="quotes, macros"]
----
[command]#rpm -Vf _file_pass:attributes[{blank}]#
----
* To locate documentation files that are a part of a package to which a file belongs, enter:
indexterm:[RPM,documentation with]indexterm:[packages,locating documentation for]indexterm:[documentation,finding installed]
[subs="quotes, macros"]
----
[command]#rpm -qdf _file_pass:attributes[{blank}]#
----
* To find information about a (non-installed) package file, use the following command:
indexterm:[RPM,querying uninstalled packages]indexterm:[packages,querying uninstalled]
[subs="quotes, macros"]
----
[command]#rpm -qip _package.rpm_pass:attributes[{blank}]#
----
* To list files contained in a package, use:
indexterm:[RPM,querying for file list]indexterm:[packages,obtaining list of files]
[subs="quotes, macros"]
----
[command]#rpm -qlp _package.rpm_pass:attributes[{blank}]#
----
See the *rpm*(8) manual page for more options.
[[s1-rpm-additional-resources]]
=== Additional Resources
indexterm:[RPM,additional resources]
[application]*RPM* is a complex utility with many options and methods for querying, installing, upgrading, and removing packages. See the following resources to learn more about [application]*RPM*.
.Installed Documentation
* [command]#rpm --help# — This command displays a quick reference of [application]*RPM* parameters.
* *rpm*(8) — The [application]*RPM* manual page offers an overview of all available [application]*RPM* parameters.
.Online Documentation
indexterm:[RPM,website]indexterm:[RPM,online documentation]
* The [application]*RPM* website — link:++http://www.rpm.org/++[]
* The [application]*RPM* mailing list — link:++http://lists.rpm.org/mailman/listinfo/rpm-list++[]
.See Also
indexterm:[RPM,see also]
* <<ch-DNF>> describes how to use the [application]*DNF* package manager to search, install, update, and uninstall packages on the command line.

49
en-US/Revision_History.adoc Normal file
View file

@ -0,0 +1,49 @@
:experimental:
[[app-Revision_History]]
== Revision History
`1-9`:: Sun Jun 25, 2017, Ryan (t3rm1n4l@fedoraproject.org)
* Converted document to asciidocs, updated table refs, removed manual line breaks, fixed formatting and some grammar
`1-8`:: Mon Nov 14 2016, Petr Bokoč (pbokoc@redhat.com)
* Fedora 25 release of the [citetitle]_System Administrator's Guide_.
`1-7`:: Tue June 21 2016, Stephen Wadeley (swadeley@redhat.com)
* Fedora 24 release of the [citetitle]_System Administrator's Guide_.
`1-5`:: Mon Nov 02 2015, Stephen Wadeley (swadeley@redhat.com)
* Fedora 23 release of the [citetitle]_System Administrator's Guide_.
`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.
`1-4`:: Mon May 25 2015, Stephen Wadeley (swadeley@redhat.com)
* Fedora 22 release of the [citetitle]_System Administrator's Guide_.
`1-3`:: Mon Apr 4 2015, Stephen Wadeley (swadeley@redhat.com)
* Replaced Yum chapter with DNF chapter.
`1-2.1`:: Wed Mar 4 2015, Stephen Wadeley (swadeley@redhat.com)
* Added "Working with the GRUB 2 Boot Loader" chapter.
`1-2`:: Tue Dec 9 2014, Stephen Wadeley (swadeley@redhat.com)
* Fedora 21 release of the [citetitle]_System Administrator's Guide_.
`1-1`:: Thu Aug 9 2012, Jaromír Hradílek (jhradilek@redhat.com)
* Updated Network Interfaces.
`1-0`:: Tue May 29 2012, Jaromír Hradílek (jhradilek@redhat.com)
* Fedora 17 release of the [citetitle]_System Administrator's Guide_.

46
en-US/Wayland.adoc Normal file
View file

@ -0,0 +1,46 @@
:hardbreaks:
:experimental:
include::en-US/entities.adoc[]
[[ch-Wayland]]
== 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
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]
----
$ echo $WAYLAND_DISPLAY
wayland-0
----
If you are not running under Wayland the variable will not contain any values. You can also use loginctl to show you what tpe of session is running:
[source,bash]
----
$ loginctl show-session <YOUR_SESSION_NUMBER> -p Type
----
To determine your session number, simply typing `loginctl` should provide your session details.
There is also a legacy X11 server provided with Wayland for compatibility purposes. To determine what applications are running in this mode, you can run the following command:
[source,bash]
----
$ xlsclients
----
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
To find out more about Wayland, please see the following website:
https://wayland.freedesktop.org/
If you need to determine if an issue you are experiencing is related to wayland, see the Fedora wiki at the link below:
https://fedoraproject.org/wiki/How_to_debug_Wayland_problems

476
en-US/basic-system-configuration/Configuring_the_Date_and_Time.adoc Normal file
View file

@ -0,0 +1,476 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-Configuring_the_Date_and_Time]]
=== Configuring the Date and Time
Modern operating systems distinguish between the following two types of clocks:
* A _real-time clock_ (*RTC*), commonly referred to as a _hardware clock_, (typically an integrated circuit on the system board) that is completely independent of the current state of the operating system and runs even when the computer is shut down.
* A _system clock_, also known as a _software clock_, that is maintained by the kernel and its initial value is based on the real-time clock. Once the system is booted and the system clock is initialized, the system clock is completely independent of the real-time clock.
The system time is always kept in _Coordinated Universal Time_ (*UTC*) and converted in applications to local time as needed. _Local time_ is the actual time in your current time zone, taking into account _daylight saving time_ (*DST*). The real-time clock can use either UTC or local time. UTC is recommended.
{MAJOROSVER} offers three command line tools that can be used to configure and display information about the system date and time: the [command]#timedatectl# utility, which is new in {MAJOROSVER} and is part of `systemd`pass:attributes[{blank}]; the traditional [command]#date# command; and the [command]#hwclock# utility for accessing the hardware clock.
[[sect-Configuring_the_Date_and_Time-timedatectl]]
==== Using the timedatectl Command
The [application]*timedatectl* utility is distributed as part of the `systemd` system and service manager and allows you to review and change the configuration of the system clock. You can use this tool to change the current date and time, set the time zone, or enable automatic synchronization of the system clock with a remote server.
For information on how to display the current date and time in a custom format, see also <<sect-Configuring_the_Date_and_Time-date>>.
[[sect-Configuring_the_Date_and_Time-timedatectl-Display]]
===== Displaying the Current Date and Time
To display the current date and time along with detailed information about the configuration of the system and hardware clock, run the [command]#timedatectl# command with no additional command line options:
[subs="quotes, macros"]
----
[command]#timedatectl#
----
This displays the local and universal time, the currently used time zone, the status of the Network Time Protocol (`NTP`) configuration, and additional information related to DST.
[[exam-Configuring_the_Date_and_Time-timedatectl-Display]]
.Displaying the Current Date and Time
====
The following is an example output of the [command]#timedatectl# command on a system that does not use `NTP` to synchronize the system clock with a remote server:
[subs="attributes"]
----
~]${nbsp}timedatectl
Local time: Mon 2013-09-16 19:30:24 CEST
Universal time: Mon 2013-09-16 17:30:24 UTC
Timezone: Europe/Prague (CEST, +0200)
NTP enabled: no
NTP synchronized: no
RTC in local TZ: no
DST active: yes
Last DST change: DST began at
Sun 2013-03-31 01:59:59 CET
Sun 2013-03-31 03:00:00 CEST
Next DST change: DST ends (the clock jumps one hour backwards) at
Sun 2013-10-27 02:59:59 CEST
Sun 2013-10-27 02:00:00 CET
----
====
[[sect-Configuring_the_Date_and_Time-timedatectl-Time]]
===== Changing the Current Time
To change the current time, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#timedatectl# [option]`set-time` _HH:MM:SS_
----
Replace _HH_ with an hour, _MM_ with a minute, and _SS_ with a second, all typed in two-digit form.
This command updates both the system time and the hardware clock. The result it is similar to using both the [command]#date --set# and [command]#hwclock --systohc# commands.
The command will fail if an `NTP` service is enabled. See <<sect-Configuring_the_Date_and_Time-timedatectl-NTP>> to temporally disable the service.
[[exam-Configuring_the_Date_and_Time-timedatectl-Time]]
.Changing the Current Time
====
To change the current time to 11:26 p.m., run the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}timedatectl set-time 23:26:00
----
====
By default, the system is configured to use UTC. To configure your system to maintain the clock in the local time, run the [command]#timedatectl# command with the [option]`set-local-rtc` option as `root`:
[subs="quotes, macros"]
----
[command]#timedatectl# [option]`set-local-rtc` _boolean_
----
To configure your system to maintain the clock in the local time, replace _boolean_ with `yes` (or, alternatively, `y`, `true`, `t`, or `1`). To configure the system to use UTC, replace _boolean_ with `no` (or, alternatively, `n`, `false`, `f`, or `0`). The default option is `no`.
[[sect-Configuring_the_Date_and_Time-timedatectl-Date]]
===== Changing the Current Date
To change the current date, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#timedatectl# [option]`set-time` _YYYY-MM-DD_
----
Replace _YYYY_ with a four-digit year, _MM_ with a two-digit month, and _DD_ with a two-digit day of the month.
Note that changing the date without specifying the current time results in setting the time to 00:00:00.
[[exam-Configuring_the_Date_and_Time-timedatectl-Date]]
.Changing the Current Date
====
To change the current date to 2 June 2013 and keep the current time (11:26 p.m.), run the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}timedatectl set-time "2013-06-02 23:26:00"
----
====
[[sect-Configuring_the_Date_and_Time-timedatectl-Time_Zone]]
===== Changing the Time Zone
To list all available time zones, type the following at a shell prompt:
[subs="quotes, macros"]
----
[command]#timedatectl# [option]`list-timezones`
----
To change the currently used time zone, type as `root`:
[subs="macros"]
----
timedatectl set-timezone pass:quotes[_time_zone_]
----
Replace _time_zone_ with any of the values listed by the [command]#timedatectl list-timezones# command.
[[exam-Configuring_the_Date_and_Time-timedatectl-Time_Zone]]
.Changing the Time Zone
====
To identify which time zone is closest to your present location, use the [command]#timedatectl# command with the [option]`list-timezones` command line option. For example, to list all available time zones in Europe, type:
[subs="macros, attributes"]
----
~]#{nbsp}timedatectl list-timezones | grep Europe
Europe/Amsterdam
Europe/Andorra
Europe/Athens
Europe/Belgrade
Europe/Berlin
Europe/Bratislava
pass:quotes[_…_]
----
To change the time zone to `Europe/Prague`, type as `root`:
[subs="attributes"]
----
~]#{nbsp}timedatectl set-timezone Europe/Prague
----
====
[[sect-Configuring_the_Date_and_Time-timedatectl-NTP]]
===== Synchronizing the System Clock with a Remote Server
As opposed to the manual adjustments described in the previous sections, the [command]#timedatectl# command also allows you to enable automatic synchronization of your system clock with a group of remote servers using the `NTP` protocol. Enabling NTP enables the `chronyd` or `ntpd` service, depending on which of them is installed.
The `NTP` service can be enabled and disabled using a command as follows:
[subs="quotes, macros"]
----
[command]#timedatectl# [option]`set-ntp` _boolean_
----
To enable your system to synchronize the system clock with a remote `NTP` server, replace _boolean_ with `yes` (the default option). To disable this feature, replace _boolean_ with `no`.
[[exam-Configuring_the_Date_and_Time-timedatectl-NTP]]
.Synchronizing the System Clock with a Remote Server
====
To enable automatic synchronization of the system clock with a remote server, type:
[subs="attributes"]
----
~]#{nbsp}timedatectl set-ntp yes
----
The command will fail if an `NTP` service is not installed. See <<sect-Installing_chrony>> for more information.
====
[[sect-Configuring_the_Date_and_Time-date]]
==== Using the date Command
The [command]#date# utility is available on all Linux systems and allows you to display and configure the current date and time. It is frequently used in scripts to display detailed information about the system clock in a custom format.
For information on how to change the time zone or enable automatic synchronization of the system clock with a remote server, see <<sect-Configuring_the_Date_and_Time-timedatectl>>.
[[sect-Configuring_the_Date_and_Time-date-Display]]
===== Displaying the Current Date and Time
To display the current date and time, run the [command]#date# command with no additional command line options:
[subs="quotes, macros"]
----
[command]#date#
----
This displays the day of the week followed by the current date, local time, abbreviated time zone, and year.
By default, the [command]#date# command displays the local time. To display the time in UTC, run the command with the [option]`--utc` or [option]`-u` command line option:
[subs="quotes, macros"]
----
[command]#date# [option]`--utc`
----
You can also customize the format of the displayed information by providing the [option]`+"pass:attributes[{blank}]_format_pass:attributes[{blank}]"` option on the command line:
----
date +"format"
----
Replace _format_ with one or more supported control sequences as illustrated in <<exam-Configuring_the_Date_and_Time-date-Display>>. See <<tabl-Configuring_the_Date_and_Time-date-Format>> for a list of the most frequently used formatting options, or the `date`(1) manual page for a complete list of these options.
[[tabl-Configuring_the_Date_and_Time-date-Format]]
.Commonly Used Control Sequences
[options="header"]
|===
|Control Sequence|Description
|[option]`%H`|The hour in the _HH_ format (for example, `17`).
|[option]`%M`|The minute in the _MM_ format (for example, `30`).
|[option]`%S`|The second in the _SS_ format (for example, `24`).
|[option]`%d`|The day of the month in the _DD_ format (for example, `16`).
|[option]`%m`|The month in the _MM_ format (for example, `09`).
|[option]`%Y`|The year in the _YYYY_ format (for example, `2013`).
|`%Z`|The time zone abbreviation (for example, `CEST`).
|[option]`%F`|The full date in the _YYYY-MM-DD_ format (for example, `2013-09-16`). This option is equal to [option]`%Y-%m-%d`.
|[option]`%T`|The full time in the _HH:MM:SS_ format (for example, 17:30:24). This option is equal to [option]`%H:%M:%S`
|===
[[exam-Configuring_the_Date_and_Time-date-Display]]
.Displaying the Current Date and Time
====
To display the current date and local time, type the following at a shell prompt:
[subs="quotes, macros, attributes"]
----
~]${nbsp}pass:attributes[{blank}][command]#date#
Mon Sep 16 17:30:24 CEST 2013
----
To display the current date and time in UTC, type the following at a shell prompt:
[subs="quotes, macros, attributes"]
----
~]${nbsp}pass:attributes[{blank}][command]#date --utc#
Mon Sep 16 15:30:34 UTC 2013
----
To customize the output of the [command]#date# command, type:
[subs="attributes"]
----
~]${nbsp}date +"%Y-%m-%d %H:%M"
2013-09-16 17:30
----
====
[[sect-Configuring_the_Date_and_Time-date-Time]]
===== Changing the Current Time
To change the current time, run the [command]#date# command with the [option]`--set` or [option]`-s` option as `root`:
[subs="quotes, macros"]
----
[command]#date# [option]`--set` _HH:MM:SS_
----
Replace _HH_ with an hour, _MM_ with a minute, and _SS_ with a second, all typed in two-digit form.
By default, the [command]#date# command sets the system clock to the local time. To set the system clock in UTC, run the command with the [option]`--utc` or [option]`-u` command line option:
[subs="quotes, macros"]
----
[command]#date# [option]`--set` _HH:MM:SS_ [option]`--utc`
----
[[exam-Configuring_the_Date_and_Time-date-Time]]
.Changing the Current Time
====
To change the current time to 11:26 p.m., run the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}date --set 23:26:00
----
====
[[sect-Configuring_the_Date_and_Time-date-Date]]
===== Changing the Current Date
To change the current date, run the [command]#date# command with the [option]`--set` or [option]`-s` option as `root`:
[subs="quotes, macros"]
----
[command]#date# [option]`--set` _YYYY-MM-DD_
----
Replace _YYYY_ with a four-digit year, _MM_ with a two-digit month, and _DD_ with a two-digit day of the month.
Note that changing the date without specifying the current time results in setting the time to 00:00:00.
[[exam-Configuring_the_Date_and_Time-date-Date]]
.Changing the Current Date
====
To change the current date to 2 June 2013 and keep the current time (11:26 p.m.), run the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}date --set 2013-06-02 23:26:00
----
====
[[sect-Configuring_the_Date_and_Time-hwclock]]
==== Using the hwclock Command
`hwclock` is a utility for accessing the hardware clock, also referred to as the Real Time Clock (RTC). The hardware clock is independent of the operating system you use and works even when the machine is shut down. This utility is used for displaying the time from the hardware clock. `hwclock` also contains facilities for compensating for systematic drift in the hardware clock.
The hardware clock stores the values of: year, month, day, hour, minute, and second. It is not able to store the time standard, local time or Coordinated Universal Time (UTC), nor set the Daylight Saving Time (DST).
The `hwclock` utility saves its settings in the `/etc/adjtime` file, which is created with the first change you make, for example, when you set the time manually or synchronize the hardware clock with the system time.
[NOTE]
====
In {MAJOROS}{nbsp}6, the [command]#hwclock# command was run automatically on every system shutdown or reboot, but it is not in {MAJOROSVER}. When the system clock is synchronized by the Network Time Protocol (NTP) or
Precision Time Protocol (PTP), the kernel automatically synchronizes the hardware clock to the system clock every 11 minutes.
====
For details about NTP, see <<ch-Configuring_NTP_Using_the_chrony_Suite>> and <<ch-Configuring_NTP_Using_ntpd>>. For information about PTP, see <<ch-Configuring_PTP_Using_ptp4l>>. For information about setting the hardware clock after executing [application]*ntpdate*, see <<s1-Configuring_the_Hardware_Clock_update>>.
[[sect2-displaying-time-hwclock]]
===== Displaying the Current Date and Time
Running [command]#hwclock# with no command line options as the `root` user returns the date and time in local time to standard output.
[subs="quotes, macros"]
----
[command]#hwclock#
----
Note that using the [option]`--utc` or [option]`--localtime` options with the [command]#hwclock# command does not mean you are displaying the hardware clock time in UTC or local time. These options are used for setting the hardware clock to keep time in either of them. The time is always displayed in local time. Additionally, using the [command]#hwclock --utc# or [command]#hwclock --local# commands does not change the record in the `/etc/adjtime` file. This command can be useful when you know that the setting saved in `/etc/adjtime` is incorrect but you do not want to change the setting. On the other hand, you may receive misleading information if you use the command an incorrect way. See the `hwclock`(8) manual page for more details.
[[exam-sect3-displaying-time-hwclock]]
.Displaying the Current Date and Time
====
To display the current date and the current local time from the hardware clock, run as `root`:
[subs="attributes"]
----
~]#{nbsp}hwclock
Tue 15 Apr 2014 04:23:46 PM CEST -0.329272 seconds
----
CEST is a time zone abbreviation and stands for Central European Summer Time.
====
For information on how to change the time zone, see <<sect-Configuring_the_Date_and_Time-timedatectl-Time_Zone>>.
[[sect3-changing-date-time-hwclock]]
===== Setting the Date and Time
Besides displaying the date and time, you can manually set the hardware clock to a specific time.
When you need to change the hardware clock date and time, you can do so by appending the [option]`--set` and [option]`--date` options along with your specification:
[subs="quotes, macros"]
----
[command]#hwclock --set --date _"dd mmm yyyy HH:MM"_pass:attributes[{blank}]#
----
Replace _dd_ with a day (a two-digit number), _mmm_ with a month (a three-letter abbreviation), _yyyy_ with a year (a four-digit number), _HH_ with an hour (a two-digit number), _MM_ with a minute (a two-digit number).
At the same time, you can also set the hardware clock to keep the time in either UTC or local time by adding the [option]`--utc` or [option]`--localtime` options, respectively. In this case, `UTC` or `LOCAL` is recorded in the `/etc/adjtime` file.
[[exam6-sect3-setting-time-hwclock]]
.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:
[subs="attributes"]
----
~]#{nbsp}hwclock --set --date "21 Oct 2014 21:17" --utc
----
====
[[sect4-synchronizing-date-time-hwclock]]
===== Synchronizing the Date and Time
You can synchronize the hardware clock and the current system time in both directions.
* Either you can set the hardware clock to the current system time by using this command:
+
[subs="quotes, macros"]
----
[command]#hwclock --systohc#
----
+
Note that if you use NTP, the hardware clock is automatically synchronized to the system clock every 11 minutes, and this command is useful only at boot time to get a reasonable initial system time.
* Or, you can set the system time from the hardware clock by using the following command:
+
[subs="quotes, macros"]
----
[command]#hwclock --hctosys#
----
When you synchronize the hardware clock and the system time, you can also specify whether you want to keep the hardware clock in local time or UTC by adding the [option]`--utc` or [option]`--localtime` option. Similarly to using [option]`--set`, `UTC` or `LOCAL` is recorded in the `/etc/adjtime` file.
The [command]#hwclock --systohc --utc# command is functionally similar to [command]#timedatectl set-local-rtc false# and the [command]#hwclock --systohc --local# command is an alternative to [command]#timedatectl set-local-rtc true#.
[[exam4-sect4-synchornizing-systohc-hwclock]]
.Synchronizing the Hardware Clock with System Time
====
To set the hardware clock to the current system time and keep the hardware clock in local time, run the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}hwclock --systohc --localtime
----
To avoid problems with time zone and DST switching, it is recommended to keep the hardware clock in UTC. The shown <<exam4-sect4-synchornizing-systohc-hwclock>> is useful, for example, in case of a multi boot with a Windows system, which assumes the hardware clock runs in local time by default, and all other systems need to accommodate to it by using local time as well. It may also be needed with a virtual machine; if the virtual hardware clock provided by the host is running in local time, the guest system needs to be configured to use local time, too.
====
[[sect-Date_and_Time-Resources]]
==== Additional Resources
For more information on how to configure the date and time in {MAJOROSVER}, see the resources listed below.
.Installed Documentation
* `timedatectl`(1) — The manual page for the [command]#timedatectl# command line utility documents how to use this tool to query and change the system clock and its settings.
* `date`(1) — The manual page for the [command]#date# command provides a complete list of supported command line options.
* `hwclock`(8) — The manual page for the [command]#hwclock# command provides a complete list of supported command line options.
.See Also
* <<ch-System_Locale_and_Keyboard_Configuration>> documents how to configure the keyboard layout.

157
en-US/basic-system-configuration/Gaining_Privileges.adoc Normal file
View file

@ -0,0 +1,157 @@
:experimental:
include::en-US/entities.adoc[]
[[chap-Gaining_Privileges]]
=== Gaining Privileges
System administrators, and in some cases users, need to perform certain tasks with administrative access. Accessing the system as the `root` user is potentially dangerous and can lead to widespread damage to the system and data. This chapter covers ways to gain administrative privileges using setuid programs such as [command]#su# and [command]#sudo#. These programs allow specific users to perform tasks which would normally be available only to the `root` user while maintaining a higher level of control and system security.
See the link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/++[Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Security Guide] for more information on administrative controls, potential dangers, and ways to prevent data loss resulting from improper use of privileged access.
[[sect-Gaining_Privileges-The_su_Command]]
==== The su Command
When a user executes the [command]#su# command, they are prompted for the `root` password and, after authentication, are given a `root` shell prompt.
Once logged in using the [command]#su# command, the user *is* the `root` user and has absolute administrative access to the system. Note that this access is still subject to the restrictions imposed by SELinux, if it is enabled. In addition, once a user has become `root`, it is possible for them to use the [command]#su# command to change to any other user on the system without being prompted for a password.
Because this program is so powerful, administrators within an organization may want to limit who has access to the command.
One of the simplest ways to do this is to add users to the special administrative group called _wheel_. To do this, type the following command as `root`:
[subs="macros"]
----
~]# usermod -a -G wheel pass:quotes[_username_]
----
In the previous command, replace _username_ with the user name you want to add to the `wheel` group.
You can also use the [application]*Users* settings tool to modify group memberships, as follows. Note that you need administrator privileges to perform this procedure.
. Press the kbd:[Super] key to enter the Activities Overview, type [command]#Users# and then press kbd:[Enter]. The [application]*Users* settings tool appears. The kbd:[Super] key appears in a variety of guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the kbd:[Spacebar].
. To enable making changes, click the btn:[Unlock] button, and enter a valid administrator password.
. Click a user icon in the left column to display the user's properties in the right-hand pane.
. Change the Account Type from `Standard` to `Administrator`. This will add the user to the `wheel` group.
See <<s1-users-configui>> for more information about the [application]*Users* tool.
After you add the desired users to the `wheel` group, it is advisable to only allow these specific users to use the [command]#su# command. To do this, edit the PAM configuration file for [command]#su#, `/etc/pam.d/su`. Open this file in a text editor and uncomment the following line by removing the `#` character:
----
#auth required pam_wheel.so use_uid
----
This change means that only members of the administrative group `wheel` can switch to another user using the [command]#su# command.
.Note
[NOTE]
====
The `root` user is part of the `wheel` group by default.
====
[[sect-Gaining_Privileges-The_sudo_Command]]
==== The sudo Command
The [command]#sudo# command offers another approach to giving users administrative access. When trusted users precede an administrative command with [command]#sudo#, they are prompted for *their own* password. Then, when they have been authenticated and assuming that the command is permitted, the administrative command is executed as if they were the `root` user.
The basic format of the [command]#sudo# command is as follows:
[subs="quotes, macros"]
----
[command]#sudo# _command_
----
In the above example, _command_ would be replaced by a command normally reserved for the `root` user, such as [command]#mount#.
The [command]#sudo# command allows for a high degree of flexibility. For instance, only users listed in the `/etc/sudoers` configuration file are allowed to use the [command]#sudo# command and the command is executed in *the user's* shell, not a `root` shell. This means the `root` shell can be completely disabled as shown in the link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/++[Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Security Guide].
Each successful authentication using the [command]#sudo# command is logged to the file `/var/log/messages` and the command issued along with the issuer's user name is logged to the file `/var/log/secure`. If additional logging is required, use the `pam_tty_audit` module to enable TTY auditing for specified users by adding the following line to your `/etc/pam.d/system-auth` file:
[subs="macros"]
----
session required pam_tty_audit.so disable=pass:quotes[_pattern_] enable=pass:quotes[_pattern_]
----
where _pattern_ represents a comma-separated listing of users with an optional use of globs. For example, the following configuration will enable TTY auditing for the `root` user and disable it for all other users:
----
session required pam_tty_audit.so disable=* enable=root
----
Another advantage of the [command]#sudo# command is that an administrator can allow different users access to specific commands based on their needs.
Administrators wanting to edit the [command]#sudo# configuration file, `/etc/sudoers`, should use the [command]#visudo# command.
To give someone full administrative privileges, type [command]#visudo# and add a line similar to the following in the user privilege specification section:
[subs="quotes"]
----
juan ALL=(ALL) ALL
----
This example states that the user, `juan`, can use [command]#sudo# from any host and execute any command.
The example below illustrates the granularity possible when configuring [command]#sudo#:
[subs="quotes"]
----
%users localhost=/sbin/shutdown -h now
----
This example states that any member of the `users` system group can issue the command [command]#/sbin/shutdown -h now# as long as it is issued from the console.
The man page for `sudoers` has a detailed listing of options for this file.
.Important
[IMPORTANT]
====
There are several potential risks to keep in mind when using the [command]#sudo# command. You can avoid them by editing the `/etc/sudoers` configuration file using [command]#visudo# as described above. Leaving the `/etc/sudoers` file in its default state gives every user in the `wheel` group unlimited `root` access.
* By default, [command]#sudo# stores the sudoer's password for a five minute timeout period. Any subsequent uses of the command during this period will not prompt the user for a password. This could be exploited by an attacker if the user leaves their workstation unattended and unlocked while still being logged in. This behavior can be changed by adding the following line to the `/etc/sudoers` file:
+
[subs="macros"]
----
Defaults timestamp_timeout=pass:quotes[_value_]
----
+
where _value_ is the desired timeout length in minutes. Setting the _value_ to 0 causes [command]#sudo# to require a password every time.
* If a sudoer's account is compromised, an attacker can use [command]#sudo# to open a new shell with administrative privileges:
+
[subs="quotes, macros"]
----
[command]#sudo /bin/bash#
----
+
Opening a new shell as `root` in this or similar fashion gives the attacker administrative access for a theoretically unlimited amount of time, bypassing the timeout period specified in the `/etc/sudoers` file and never requiring the attacker to input a password for [command]#sudo# again until the newly opened session is closed.
====
[[sect-Gaining_Privileges-Additional_Resources]]
==== Additional Resources
While programs allowing users to gain administrative privileges are a potential security risk, security itself is beyond the scope of this particular book. You should therefore refer to the resources listed below for more information regarding security and privileged access.
.Installed Documentation
* `su`(1) — The manual page for [command]#su# provides information regarding the options available with this command.
* `sudo`(8) — The manual page for [command]#sudo# includes a detailed description of this command and lists options available for customizing its behavior.
* `pam`(8) — The manual page describing the use of Pluggable Authentication Modules (PAM) for Linux.
.Online Documentation
* The link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/++[Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Security Guide] provides a more in-depth look at potential security issues pertaining to setuid programs as well as techniques used to alleviate these risks.
.See Also
* <<ch-Managing_Users_and_Groups>> documents how to manage system users and groups in the graphical user interface and on the command line.

487
en-US/basic-system-configuration/Managing_Users_and_Groups.adoc Normal file
View file

@ -0,0 +1,487 @@
:experimental:
include::en-US/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]]
==== Introduction to Users and Groups
While users can be either people (meaning accounts tied to physical users) or accounts which exist for specific applications to use, groups are logical expressions of organization, tying users together for a common purpose. Users within a group share the same permissions to read, write, or execute files owned by that group.
Each user is associated with a unique numerical identification number called a _user ID_ (*UID*). Likewise, each group is associated with a _group ID_ (*GID*). A user who creates a file is also the owner and group owner of that file. The file is assigned separate read, write, and execute permissions for the owner, the group, and everyone else. The file owner can be changed only by `root`, and access permissions can be changed by both the `root` user and file owner.
Additionally, {MAJOROS} supports _access control lists_ (*ACLs*) for files and directories which allow permissions for specific users outside of the owner to be set. For more information about this feature, see the [citetitle]_link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/ch-Access_Control_Lists.html++[Access Control Lists]_ chapter of the [citetitle]_link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/index.html++[Red Hat Enterprise Linux 7 System Administrators Guide]_.
[[s2-users-groups-private-groups]]
===== User Private Groups
indexterm:[groups,user private]indexterm:[user private groups,groups]indexterm:[groups,tools for management of,groupadd]
{MAJOROS} uses a _user private group_ (_UPG_) scheme, which makes UNIX groups easier to manage. A user private group is created whenever a new user is added to the system. It has the same name as the user for which it was created and that user is the only member of the user private group.
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.
A list of all groups is stored in the `/etc/group` configuration file.
[[s2-users-groups-shadow-utilities]]
===== Shadow Passwords
indexterm:[passwords,shadow]indexterm:[shadow passwords,overview of]
In environments with multiple users, it is very important to use _shadow passwords_ provided by the [package]*shadow-utils* package to enhance the security of system authentication files. For this reason, the installation program enables shadow passwords by default.
The following is a list of the advantages shadow passwords have over the traditional way of storing passwords on UNIX-based systems:
* Shadow passwords improve system security by moving encrypted password hashes from the world-readable `/etc/passwd` file to `/etc/shadow`, which is readable only by the `root` user.
* Shadow passwords store information about password aging.
* Shadow passwords allow the `/etc/login.defs` file to enforce security policies.
Most utilities provided by the [package]*shadow-utils* package work properly whether or not shadow passwords are enabled. However, since password aging information is stored exclusively in the `/etc/shadow` file, some utilities and commands do not work without first enabling shadow passwords:
* The [command]#chage# utility for setting password-aging parameters. For details, see the link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/chap-Hardening_Your_System_with_Tools_and_Services.html#sec-Password_Security++[Password Security] section in the [citetitle]_Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Security Guide_.
* The [command]#gpasswd# utility for administrating the `/etc/group` file.
* The [command]#usermod# command with the [option]`-e, --expiredate` or [option]`-f, --inactive` option.
* The [command]#useradd# command with the [option]`-e, --expiredate` or [option]`-f, --inactive` option.
[[s1-users-configui]]
==== Managing Users in a Graphical Environment
indexterm:[users,user configuration]indexterm:[groups,group configuration]indexterm:[user configuration,viewing list of users]indexterm:[group configuration,viewing list of groups]indexterm:[the Users settings tool,user configuration]
The [application]*Users* utility allows you to view, modify, add, and delete local users in the graphical user interface.
[[s2-redhat-config-users-list]]
===== Using the Users Settings Tool
Press the kbd:[Super] key to enter the Activities Overview, type [command]#Users# and then press kbd:[Enter]. The [application]*Users* settings tool appears. The kbd:[Super] key appears in a variety of guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar.
To make changes to the user accounts, first select the btn:[Unlock] button and authenticate yourself as indicated by the dialog box that appears. Note that unless you have superuser privileges, the application will prompt you to authenticate as `root`. To add and remove users, select the btn:[+] and btn:[-] button respectively. To add a user to the administrative group `wheel`, change the Account Type from `Standard` to `Administrator`. To edit a user's language setting, select the language and a drop-down menu appears.
[[fig-managing-users]]
.The Users Settings Tool
image::managing_users.png[The Users settings tool]
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]]
==== Using Command Line Tools
indexterm:[users,tools for management of,useradd]indexterm:[users,tools for management of,the Users setting tool]indexterm:[groups,tools for management of,groupadd]
Apart from the [application]*Users* settings tool described in <<s1-users-configui>>, which is designed for basic managing of users, you can use command line tools for managing users and groups that are listed in <<table-users-tools>>.
[[table-users-tools]]
.Command line utilities for managing users and groups
[options="header"]
|===
|Utilities|Description
|[command]#id#|Displays user and group IDs.
|[command]#useradd#, [command]#usermod#, [command]#userdel#|Standard utilities for adding, modifying, and deleting user accounts.
|[command]#groupadd#, [command]#groupmod#, [command]#groupdel#|Standard utilities for adding, modifying, and deleting groups.
|[command]#gpasswd#|Standard utility for administering the `/etc/group` configuration file.
|[command]#pwck#, [command]#grpck#|Utilities that can be used for verification of the password, group, and associated shadow files.
|[command]#pwconv#, [command]#pwunconv#|Utilities that can be used for the conversion of passwords to shadow passwords, or back from shadow passwords to standard passwords.
|[command]#grpconv#, [command]#grpunconv#|Similar to the previous, these utilities can be used for conversion of shadowed information for group accounts.
|===
[[s2-users-tools-users-add]]
===== Adding a New User
indexterm:[useradd command,user account creation using]indexterm:[adding,user]indexterm:[user configuration,command line configuration,useradd]
To add a new user to the system, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#useradd# _options_ _username_
----
…where _options_ are command-line options as described in <<table-useradd-options>>.
indexterm:[user configuration,command line configuration,passwd]
By default, the [command]#useradd# command creates a locked user account. To unlock the account, run the following command as `root` to assign a password:
[subs="quotes, macros"]
----
[command]#passwd# _username_
----
Optionally, you can set a password aging policy. See <<s2-users-tools-password-aging>> for information on how to enable password aging.
[[table-useradd-options]]
.Common useradd command-line options
[options="header"]
|===
|Option|Description
|[option]`-c`pass:attributes[{blank}] 'pass:attributes[{blank}]_comment_pass:attributes[{blank}]'|_comment_ can be replaced with any string. This option is generally used to specify the full name of a user.
|[option]`-d`pass:attributes[{blank}] pass:attributes[{blank}]_home_directory_|Home directory to be used instead of default `/home/pass:attributes[{blank}]_username_pass:attributes[{blank}]/`.
|[option]`-e`pass:attributes[{blank}] pass:attributes[{blank}]_date_|Date for the account to be disabled in the format YYYY-MM-DD.
|[option]`-f`pass:attributes[{blank}] pass:attributes[{blank}]_days_|Number of days after the password expires until the account is disabled. If `0` is specified, the account is disabled immediately after the password expires. If `-1` is specified, the account is not disabled after the password expires.
|[option]`-g`pass:attributes[{blank}] pass:attributes[{blank}]_group_name_|Group name or group number for the user's default (primary) group. The group must exist prior to being specified here.
|[option]`-G`pass:attributes[{blank}] pass:attributes[{blank}]_group_list_|List of additional (supplementary, other than default) group names or group numbers, separated by commas, of which the user is a member. The groups must exist prior to being specified here.
|[option]`-m`|Create the home directory if it does not exist.
|[option]`-M`|Do not create the home directory.
|[option]`-N`|Do not create a user private group for the user.
|[option]`-p`pass:attributes[{blank}] pass:attributes[{blank}]_password_|The password encrypted with [command]#crypt#.
|[option]`-r`|Create a system account with a UID less than 1000 and without a home directory.
|[option]`-s`|User's login shell, which defaults to [command]#/bin/bash#.
|[option]`-u`pass:attributes[{blank}] pass:attributes[{blank}]_uid_|User ID for the user, which must be unique and greater than 999.
|===
The command-line options associated with the [command]#usermod# command are essentially the same. Note that if you want to add a user to another supplementary group, you need to use the [option]`-a, --append` option with the [option]`-G` option. Otherwise the list of supplementary groups for the user will be overwritten by those specified with the [command]#usermod -G# command.
.Explaining the Process
The following steps illustrate what happens if the command [command]#useradd juan# is issued on a system that has shadow passwords enabled:
. A new line for `juan` is created in `/etc/passwd`:
+
[subs="quotes"]
----
juan:x:1001:1001::/home/juan:/bin/bash
----
+
The line has the following characteristics:
+
** It begins with the user name `juan`.
+
** There is an `x` for the password field indicating that the system is using shadow passwords.
+
** A UID greater than 999 is created. Under {MAJOROS}, UIDs below 1000 are reserved for system use and should not be assigned to users.
+
** A GID greater than 999 is created. Under {MAJOROS}, GIDs below 1000 are reserved for system use and should not be assigned to users.
+
** The optional _GECOS_ information is left blank. The GECOS field can be used to provide additional information about the user, such as their full name or phone number.
+
** The home directory for `juan` is set to `/home/juan/`.
+
** The default shell is set to [command]#/bin/bash#.
. A new line for `juan` is created in `/etc/shadow`:
+
[subs="quotes"]
----
juan:!!:14798:0:99999:7:::
----
+
The line has the following characteristics:
+
** It begins with the username `juan`.
+
** Two exclamation marks (`!!`) appear in the password field of the `/etc/shadow` file, which locks the account.
+
.Note
[NOTE]
====
If an encrypted password is passed using the [option]`-p` flag, it is placed in the `/etc/shadow` file on the new line for the user.
====
+
** The password is set to never expire.
. A new line for a group named `juan` is created in `/etc/group`:
+
[subs="quotes"]
----
juan:x:1001:
----
+
A group with the same name as a user is called a _user private group_. For more information on user private groups, see <<s2-users-groups-private-groups>>.
+
The line created in `/etc/group` has the following characteristics:
+
** It begins with the group name `juan`.
+
** An `x` appears in the password field indicating that the system is using shadow group passwords.
+
** The GID matches the one listed for `juan`pass:attributes[{blank}]'s primary group in `/etc/passwd`.
. A new line for a group named `juan` is created in `/etc/gshadow`:
+
[subs="quotes"]
----
juan:!::
----
+
The line has the following characteristics:
+
** It begins with the group name `juan`.
+
** An exclamation mark (`!`) appears in the password field of the `/etc/gshadow` file, which locks the group.
+
** All other fields are blank.
. A directory for user `juan` is created in the `/home/` directory:
+
[subs="attributes"]
----
~]#{nbsp}ls -ld /home/juan
drwx------. 4 juan juan 4096 Mar 3 18:23 /home/juan
----
+
This directory is owned by user `juan` and group `juan`. It has _read_, _write_, and _execute_ privileges *only* for the user `juan`. All other permissions are denied.
. The files within the `/etc/skel/` directory (which contain default user settings) are copied into the new `/home/juan/` directory. The contents of `/etc/skel/` may vary depending on installed applications:
+
----
~]# ls -la /home/juan
total 24
drwx------. 4 juan juan 4096 Mar 3 18:23 .
drwxr-xr-x. 5 root root 4096 Mar 3 18:23 ..
-rw-r--r--. 1 juan juan 18 Jul 09 08:43 .bash_logout
-rw-r--r--. 1 juan juan 176 Jul 09 08:43 .bash_profile
-rw-r--r--. 1 juan juan 124 Jul 09 08:43 .bashrc
drwxr-xr-x. 4 juan juan 4096 Jul 09 08:43 .mozilla
----
At this point, a locked account called `juan` exists on the system. To activate it, the administrator must next assign a password to the account using the [command]#passwd# command and, optionally, set password aging guidelines.
[[s2-users-tools-groups-add]]
===== Adding a New Group
indexterm:[group configuration,groupadd]indexterm:[adding,group]
To add a new group to the system, type the following at a shell prompt as `root`:
[subs="macros"]
----
groupadd pass:quotes[_options_] pass:quotes[_group_name_]
----
…where _options_ are command-line options as described in <<table-groupadd-options>>.
[[table-groupadd-options]]
.Common groupadd command-line options
[options="header"]
|===
|Option|Description
|[option]`-f`, [option]`--force`|When used with [option]`-g`pass:attributes[{blank}] pass:attributes[{blank}]_gid_ and _gid_ already exists, [command]#groupadd# will choose another unique _gid_ for the group.
|[option]`-g`pass:attributes[{blank}] pass:attributes[{blank}]_gid_|Group ID for the group, which must be unique and greater than 999.
|[option]`-K`, [option]`--key`pass:attributes[{blank}] pass:attributes[{blank}]_key_pass:attributes[{blank}]=pass:attributes[{blank}]_value_|Override `/etc/login.defs` defaults.
|[option]`-o`, [option]`--non-unique`|Allows creating groups with duplicate GID.
|[option]`-p`, [option]`--password`pass:attributes[{blank}] pass:attributes[{blank}]_password_|Use this encrypted password for the new group.
|[option]`-r`|Create a system group with a GID less than 1000.
|===
[[s2-users-tools-password-aging]]
===== Enabling Password Aging
indexterm:[password,expire]indexterm:[password,aging]indexterm:[expiration of password, forcing]indexterm:[chage command,forcing password expiration with]indexterm:[user configuration,password,forcing expiration of]
For security reasons, it is advisable to require users to change their passwords periodically. This can be done by using the [command]#chage# command.
.Shadow passwords must be enabled to use chage
[IMPORTANT]
====
Shadow passwords must be enabled to use the [command]#chage# command. For more information, see <<s2-users-groups-shadow-utilities>>.
====
indexterm:[user configuration,command line configuration,chage]
To configure password expiration for a user from a shell prompt, run the following command as `root`:
[subs="quotes, macros"]
----
[command]#chage# _options_ _username_
----
…where _options_ are command line options as described in <<table-chage-options>>. When the [command]#chage# command is followed directly by a username (that is, when no command line options are specified), it displays the specified users current password aging values and allows you to change these values interactively.
[[table-chage-options]]
.chage command line options
[options="header"]
|===
|Option|Description
|[option]`-d`pass:attributes[{blank}] pass:attributes[{blank}]_days_|Specifies the number of days since January 1, 1970 the password was changed.
|[option]`-E`pass:attributes[{blank}] pass:attributes[{blank}]_date_|Specifies the date on which the account is locked, in the format YYYY-MM-DD. Instead of the date, the number of days since January 1, 1970 can also be used.
|[option]`-I`pass:attributes[{blank}] pass:attributes[{blank}]_days_|Specifies the number of inactive days after the password expiration before locking the account. If the value is `0`, the account is not locked after the password expires.
|[option]`-l`|Lists current account aging settings.
|[option]`-m`pass:attributes[{blank}] pass:attributes[{blank}]_days_|Specify the minimum number of days after which the user must change passwords. If the value is `0`, the password does not expire.
|[option]`-M`pass:attributes[{blank}] pass:attributes[{blank}]_days_|Specify the maximum number of days for which the password is valid. When the number of days specified by this option plus the number of days specified with the [option]`-d` option is less than the current day, the user must change passwords before using the account.
|[option]`-W`pass:attributes[{blank}] pass:attributes[{blank}]_days_|Specifies the number of days before the password expiration date to warn the user.
|===
You can configure a password to expire the first time a user logs in. This forces users to change passwords immediately.
. Set up an initial password. There are two common approaches to this step: you can either assign a default password, or you can use a null password.
+
To assign a default password, type the following at a shell prompt as `root`:
+
[subs="quotes, macros"]
----
[command]#passwd# _username_
----
+
To assign a null password instead, use the following command:
+
[subs="quotes, macros"]
----
[command]#passwd# [option]`-d` _username_
----
+
.Avoid using null passwords whenever possible
[WARNING]
====
Using a null password, while convenient, is a highly insecure practice, as any third party can log in first and access the system using the insecure username. Always make sure that the user is ready to log in before unlocking an account with a null password.
====
. Force immediate password expiration by running the following command as `root`:
+
[subs="quotes, macros"]
----
[command]#chage# [option]`-d` [option]`0` _username_
----
+
This command sets the value for the date the password was last changed to the epoch (January 1, 1970). This value forces immediate password expiration no matter what password aging policy, if any, is in place.
Upon the initial log in, the user is now prompted for a new password.
[[s2-users-tools-users-logout]]
===== Enabling Automatic Logouts
Especially when the user is logged in as `root`, an unattended login session may pose a significant security risk. To reduce this risk, you can configure the system to automatically log out idle users after a fixed period of time:
. Make sure the [package]*screen* package is installed. You can do so by running the following command as `root`:
+
[subs="quotes, macros"]
----
[command]#dnf# [option]`install` [option]`screen`
----
+
For more information on how to install packages in {MAJOROS}, refer to <<sec-Installing>>.
. As `root`, add the following line at the beginning of the `/etc/profile` file to make sure the processing of this file cannot be interrupted:
+
[subs="quotes"]
----
trap "" 1 2 3 15
----
. Add the following lines at the end of the `/etc/profile` file to start a [command]#screen# session each time a user logs in to a virtual console or remotely:
+
[subs="quotes"]
----
SCREENEXEC="screen"
if [ -w $(tty) ]; then
trap "exec $SCREENEXEC" 1 2 3 15
echo -n 'Starting session in 10 seconds'
sleep 10
exec $SCREENEXEC
fi
----
+
Note that each time a new session starts, a message will be displayed and the user will have to wait ten seconds. To adjust the time to wait before starting a session, change the value after the [command]#sleep# command.
. Add the following lines to the `/etc/screenrc` configuration file to close the [command]#screen# session after a given period of inactivity:
+
[subs="quotes"]
----
idle 120 quit
autodetach off
----
+
This will set the time limit to 120 seconds. To adjust this limit, change the value after the [option]`idle` directive.
+
Alternatively, you can configure the system to only lock the session by using the following lines instead:
+
[subs="quotes"]
----
idle 120 lockscreen
autodetach off
----
+
This way, a password will be required to unlock the session.
The changes take effect the next time a user logs in to the system.
[[s2-users-tools-groups-directories]]
===== Creating Group Directories
indexterm:[groups,shared directories]indexterm:[user private groups,and shared directories]
System administrators usually like to create a group for each major project and assign people to the group when they need to access that project's files. With this traditional scheme, file management is difficult; when someone creates a file, it is associated with the primary group to which they belong. When a single person works on multiple projects, it becomes difficult to associate the right files with the right group. However, with the UPG scheme, groups are automatically assigned to files created within a directory with the _setgid_ bit set. The setgid bit makes managing group projects that share a common directory very simple because any files a user creates within the directory are owned by the group that owns the directory.
For example, a group of people need to work on files in the `/opt/myproject/` directory. Some people are trusted to modify the contents of this directory, but not everyone.
. As `root`, create the `/opt/myproject/` directory by typing the following at a shell prompt:
+
[subs="quotes, macros"]
----
[command]#mkdir /opt/myproject#
----
. Add the `myproject` group to the system:
+
[subs="quotes, macros"]
----
[command]#groupadd myproject#
----
. Associate the contents of the `/opt/myproject/` directory with the `myproject` group:
+
[subs="quotes, macros"]
----
[command]#chown root:myproject /opt/myproject#
----
. Allow users in the group to create files within the directory and set the setgid bit:
+
[subs="quotes, macros"]
----
[command]#chmod 2775 /opt/myproject#
----
+
At this point, all members of the `myproject` group can create and edit files in the `/opt/myproject/` directory without the administrator having to change file permissions every time users write new files. To verify that the permissions have been set correctly, run the following command:
+
[subs="attributes"]
----
~]#{nbsp}ls -ld /opt/myproject
drwxrwsr-x. 3 root myproject 4096 Mar 3 18:31 /opt/myproject
----
. Add users to the `myproject` group:
+
[subs="quotes, macros"]
----
[command]#usermod -aG myproject _username_pass:attributes[{blank}]#
----
[[sect-Users_and_Groups-Resources]]
==== Additional Resources
indexterm:[groups,additional resources]indexterm:[users,additional resources]
For more information on how to manage users and groups on Fedora, see the resources listed below.
.Installed Documentationindexterm:[groups,additional resources,installed documentation]indexterm:[users,additional resources,installed documentation]
For information about various utilities for managing users and groups, see the following manual pages:
* `useradd`(8) — The manual page for the [command]#useradd# command documents how to use it to create new users.
* `userdel`(8) — The manual page for the [command]#userdel# command documents how to use it to delete users.
* `usermod`(8) — The manual page for the [command]#usermod# command documents how to use it to modify users.
* `groupadd`(8) — The manual page for the [command]#groupadd# command documents how to use it to create new groups.
* `groupdel`(8) — The manual page for the [command]#groupdel# command documents how to use it to delete groups.
* `groupmod`(8) — The manual page for the [command]#groupmod# command documents how to use it to modify group membership.
* `gpasswd`(1) — The manual page for the [command]#gpasswd# command documents how to manage the `/etc/group` file.
* `grpck`(8) — The manual page for the [command]#grpck# command documents how to use it to verify the integrity of the `/etc/group` file.
* `pwck`(8) — The manual page for the [command]#pwck# command documents how to use it to verify the integrity of the `/etc/passwd` and `/etc/shadow` files.
* `pwconv`(8) — The manual page for the [command]#pwconv#, [command]#pwunconv#, [command]#grpconv#, and [command]#grpunconv# commands documents how to convert shadowed information for passwords and groups.
* `id`(1) — The manual page for the [command]#id# command documents how to display user and group IDs.
For information about related configuration files, see:
* `group`(5) — The manual page for the `/etc/group` file documents how to use this file to define system groups.
* `passwd`(5) — The manual page for the `/etc/passwd` file documents how to use this file to define user information.
* `shadow`(5) — The manual page for the `/etc/shadow` file documents how to use this file to set passwords and account expiration information for the system.

199
en-US/basic-system-configuration/Opening_GUI_Applications.adoc Normal file
View file

@ -0,0 +1,199 @@
:experimental:
include::en-US/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]]
==== Opening graphical applications from the command line
Graphical applications can be launched from a terminal window or console session by simply typing the name of the application.
[subs="quotes, macros"]
----
[fedorauser@localhost]$ [command]#firefox#
----
.File names vs Application names
[NOTE]
====
Programs are opened from the command line using the name of the executable file provided in the program's package. An entry in the desktop menu will often be named differently from the file it executes. For example, the GNOME disk management utility appears in the menu as [application]*Disks*, and the file it executes is `/usr/bin/gnome-disks`.
====
When a program is executed on the command line, the terminal is occupied until the program completes. When a graphical application is executed from the command line, the program's error output, or `STDERR`, is sent to the terminal window. This can be especially useful when troubleshooting.
.Viewing errors by launching graphical applications from the command line
====
----
[fedorauser@localhost]$ astromenace-wrapper
AstroMenace 1.3.1 121212
Open XML file: /home/fedorauser/.config/astromenace/amconfig.xml
VFS file was opened /usr/share/astromenace/gamedata.vfs
Vendor : OpenAL Community
Renderer : OpenAL Soft
Version : 1.1 ALSOFT 1.15.1
ALut ver : 1.1
Font initialized: DATA/FONT/LiberationMono-Bold.ttf
Current Video Mode: 3200x1080 32bit
Xinerama/TwinView detected.
Screen count: 2
Screen #0: (0, 0) x (1920, 1080)
Screen #1: (1920, 0) x (1280, 1024)
Supported resolutions list:
640x480 16bit
640x480 32bit
640x480 0bit
768x480 16bit
<output truncated>
----
====
To launch a graphical application, but fork the additional output into the background and return the terminal for immediate use, use the shell's `job control` feature.
[subs="quotes, macros"]
----
[fedorauser@localhost]$ [command]#emacs foo.txt &#
----
.Ending a session
[IMPORTANT]
====
Applications that hold the command line prompt until they complete will close when the terminal session ends, even if they are forked into the background.
====
GUI programs can also be launched on one `TTY` and displayed on another by specifying the `DISPLAY` variable. This can be useful when running multiple graphical sessions, or for troubleshooting problems with a desktop session.
. Switch to another TTY using the key combination kbd:[Ctrl + Alt + F2] and log in. Note that consoles are available by default with kbd:[F2] through kbd:[F6].
. Identify the X session you want to target. The `DISPLAY` variable is always an integer preceded by a colon, and will be *:0* in most cases. Check the arguments of the currently running [application]*X* process to verify the value. The command below shows both the `DISPLAY` variable as well as the TTY that [application]*X* is running on, `tty1`.
+
[subs="macros"]
----
[fedorauser@localhost]$ ps aux|grep /usr/bin/X
root 1498 7.1 1.0 521396 353984 pass:quotes[`tty1`] Ss+ 00:04 66:34 /usr/bin/X pass:quotes[`:0`] vt1 -background none -nolisten tcp -auth /var/run/kdm/A:0-22Degc
root 23874 0.0 0.0 109184 900 pts/21 S+ 15:35 0:00 grep --color=auto /usr/bin/X
----
. Specify the `DISPLAY` variable when executing the program.
+
[subs="quotes, macros"]
----
[fedorauser@localhost]$ [command]#DISPLAY=:0 gnome-shell --replace &#
----
. Switch back to the TTY the graphical session is running on. Since the example above shows [application]*X* running on `vt1`, pressing kbd:[Ctrl + Alt + F1] will return to the desktop environment.
[[gui-alt_f2]]
==== Launching Applications with kbd:[Alt + F2]
Most desktop environments follow the convention of using the key combination kbd:[Alt + F2] for opening new applications. Pressing kbd:[Alt + F2] brings up a prompt for a command to be entered into.
Commands entered into this dialog box function much as they would if entered in a terminal. Applications are known by their file name, and can accept arguments.
[[fig-alt_f2-gnome]]
.Using kbd:[Alt + F2] with [application]*GNOME*
image::alt-f2_GNOME.png[GNOME command entry dialog box]
[[fig-alt-f2_kde]]
.Using kbd:[Alt + F2] with [application]*KDE*
image::alt-f2_KDE.png[KDE command entry dialog box, which also searches menu items, command history, and open applications.]
[[fig-alt-f2_lxde]]
.Using kbd:[Alt + F2] with [application]*LXDE*
image::alt-f2_LXDE.png[LXDE command entry dialog box.]
[[fig-alt-f2_mate]]
.Using kbd:[Alt + F2] with [application]*MATE*
image::alt-f2_MATE.png[MATE command entry dialog box.]
[[fig-alt-f2_xfce]]
.Using kbd:[Alt + F2] with [application]*XFCE*
image::alt-f2_XFCE.png[XFCE command entry dialog box.]
[[gui-from_menu]]
==== Launching applications from the Desktop Menu
Applications can also be opened from the menu system provided by the desktop environment in use. While the presentation may vary between desktop environments, the menu entries and their categories are provided by the individual application and standardized by the link:++http://standards.freedesktop.org/menu-spec/menu-spec-latest.html++[freedesktop.org Desktop Menu Specification]. Some desktop environments also provide search functionality in their menu system to allow quick and easy access to applications.
[[gui-from_menu-gnome]]
===== Using GNOME menus
The GNOME menu, called the `overview`, can be accessed by either clicking the `Activities` button in the top left of the primary display, by moving the mouse past the top left `hot corner`, or by pressing the kbd:[Super] ( kbd:[Windows] ) key. The `overview` presents documents in addition to applications.
Selecting an item from the menu is best accomplished using the `search box`. Simply bring up the `overview`, and begin typing the name of the application you want to launch. Pressing enter will launch the highlighted application, or you can use the arrow keys or mouse to choose an alternative.
[[fig-searchmenu-gnome]]
.Using the GNOME search box
image::searchmenu_GNOME.png[Typing the name of an application into the overview search box will display matching menu entries. The search also matches descriptions, so that typing browser will display installed browsers.]
The `overview` can also be browsed. The bar on the left, called the `dash`, shows frequently used applications and a grid icon. Clicking on the grid icon brings up a grid in the center of the window that displays frequently used applications. The grid will display all available applications if selected using the `All` button at the bottom of the screen.
[[fig-menu-gnome]]
.Browsing GNOME menu entries
image::menu_GNOME.png[The GNOME menu has a bar on the left for frequently used applications, which includes a grid icon that brings up a grid in the center of the window. Users can then use the buttons at the bottom of the screen to display either a larger list of frequently used applications, or to view all available applications.]
To learn more about using [application]*GNOME shell*, visit link:++https://wiki.gnome.org/GnomeShell/CheatSheet++[]
[[gui-from_menu-kde]]
===== Using KDE menus
The KDE menu is opened by clicking the {MAJOROS} button at the bottom left corner of the screen. The menu initially displays favorite applications, which can be added to by right clicking any menu entry. Hovering over the icons in the lower portion of the menu will display applications, file systems, recently used applications, or options for logging out of the system.
[[fig-menu_kde]]
.The KDE desktop menu.
image::menu_KDE.png[The KDE menu displays applications in categories. The contents of the categories are displayed when clicked.]
Search functionality is also available in the KDE menu system. To search for applications, open the menu and begin typing. The menu will display matching entries.
[[fig-searchmenu_kde]]
.Searching with the KDE menu.
image::searchmenu_KDE.png[The KDE menu will search for matching applications if you type into the search box. For example, typing browser will display installed browsers and other matching entries.]
===== Using menus in LXDE, MATE, and XFCE
Menus in LXDE, MATE, and XFCE have a varied appearance but a very similar structure. They categorize applications, and the contents of a category are displayed by hovering the cursor over the entry. Applications are launched by clicking on an entry.
[[fig-menu_lxde]]
.The LXDE menu
image::menu_LXDE.png[LXDE Menu]
[[fig-menu_mate]]
.MATE menu
image::menu_MATE.png[MATE menu]
[[fig-menu_xfce]]
.XFCE Menu
image::menu_XFCE.png[XFCE Menu]

261
en-US/basic-system-configuration/System_Locale_and_Keyboard_Configuration.adoc Normal file
View file

@ -0,0 +1,261 @@
:experimental:
include::en-US/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. Also, you can use the graphical user interface to perform the task; for a description of this method, see link:++http://docs.fedoraproject.org/install-guide++[{MAJOROS} Installation Guide].
[[s1-Setting_the_System_Locale]]
==== Setting the System Locale
System-wide locale settings are stored in the `/etc/locale.conf` file, which is read at early boot by the `systemd` daemon. The locale settings configured in `/etc/locale.conf` are inherited by every service or user, unless individual programs or individual users override them.
The basic file format of `/etc/locale.conf` is a newline-separated list of variable assignments. For example, German locale with English messages in `/etc/locale.conf` looks as follows:
----
LANG=de_DE.UTF-8
LC_MESSAGES=C
----
Here, the LC_MESSAGES option determines the locale used for diagnostic messages written to the standard error output. To further specify locale settings in `/etc/locale.conf`, you can use several other options, the most relevant are summarized in <<tab-locale_options>>. See the `locale(7)` manual page for detailed information on these options. Note that the LC_ALL option, which represents all possible options, should not be configured in `/etc/locale.conf`.
[[tab-locale_options]]
.Options configurable in /etc/locale.conf
[options="header"]
|===
|Option|Description
|LANG|Provides a default value for the system locale.
|LC_COLLATE|Changes the behavior of functions which compare strings in the local alphabet.
|LC_CTYPE|Changes the behavior of the character handling and classification functions and the multibyte character functions.
|LC_NUMERIC|Describes the way numbers are usually printed, with details such as decimal point versus decimal comma.
|LC_TIME|Changes the display of the current time, 24-hour versus 12-hour clock.
|LC_MESSAGES|Determines the locale used for diagnostic messages written to the standard error output.
|===
[[s2-Displaying_the_Current_Status]]
===== Displaying the Current Status
The [command]#localectl# command can be used to query and change the system locale and keyboard layout settings. To show the current settings, use the [option]`status` option:
[subs="quotes, macros"]
----
[command]#localectl# [option]`status`
----
.Displaying the Current Status
====
The output of the previous command lists the currently set locale, keyboard layout configured for the console and for the X11 window system.
[subs="attributes"]
----
~]${nbsp}localectl status
System Locale: LANG=en_US.UTF-8
VC Keymap: us
X11 Layout: n/a
----
====
[[s2-Listing_Available_Locales]]
===== Listing Available Locales
To list all locales available for your system, type:
[subs="quotes, macros"]
----
[command]#localectl# [option]`list-locales`
----
.Listing Locales
====
Imagine you want to select a specific English locale, but you are not sure if it is available on the system. You can check that by listing all English locales with the following command:
[subs="macros, attributes"]
----
~]${nbsp}localectl list-locales | grep pass:quotes[`en_`]
en_AG
en_AG.utf8
en_AU
en_AU.iso88591
en_AU.utf8
en_BW
en_BW.iso88591
en_BW.utf8
pass:quotes[*output truncated*]
----
====
[[s2-Setting_the_Locale]]
===== Setting the Locale
To set the default system locale, use the following command as `root`:
[subs="quotes, macros"]
----
[command]#localectl# [option]`set-locale` [option]`LANG`pass:attributes[{blank}]=pass:attributes[{blank}]_locale_
----
Replace _locale_ with the locale name, found with the [command]#localectl# [option]`list-locales` command. The above syntax can also be used to configure parameters from <<tab-locale_options>>.
.Changing the Default Locale
====
For example, if you want to set British English as your default locale, first find the name of this locale by using [option]`list-locales`. Then, as `root`, type the command in the following form:
[subs="macros, attributes"]
----
~]#{nbsp}localectl set-locale LANG=pass:quotes[`en_GB.utf8`]
----
====
[[s1-Changing_the_Keyboard_Layout]]
==== Changing the Keyboard Layout
indexterm:[localectl,keyboard configuration]indexterm:[keyboard configuration,layout]
The keyboard layout settings enable the user to control the layout used on the text console and graphical user interfaces.
[[s2-Displaying_the_Current_Settings]]
===== Displaying the Current Settings
As mentioned before, you can check your current keyboard layout configuration with the following command:
[subs="quotes, macros"]
----
[command]#localectl# [option]`status`
----
.Displaying the Keyboard Settings
====
In the following output, you can see the keyboard layout configured for the virtual console and for the X11 window system.
[subs="attributes"]
----
~]${nbsp}localectl status
System Locale: LANG=en_US.utf8
VC Keymap: us
X11 Layout: us
----
====
[[s2-Listing_Available_Keymaps]]
===== Listing Available Keymaps
To list all available keyboard layouts that can be configured on your system, type:
[subs="quotes, macros"]
----
[command]#localectl# [option]`list-keymaps`
----
.Searching for a Particular Keymap
====
You can use [command]#grep# to search the output of the previous command for a specific keymap name. There are often multiple keymaps compatible with your currently set locale. For example, to find available Czech keyboard layouts, type:
[subs="quotes, macros, attributes"]
----
~]${nbsp}pass:attributes[{blank}][command]#localectl# [option]`list-keymaps` | [command]#grep# `cz`
cz
cz-cp1250
cz-lat2
cz-lat2-prog
cz-qwerty
cz-us-qwertz
sunt5-cz-us
sunt5-us-cz
----
====
[[s2-Setting_the_Keymap]]
===== Setting the Keymap
To set the default keyboard layout for your system, use the following command as `root`:
[subs="quotes, macros"]
----
[command]#localectl# [option]`set-keymap` _map_
----
Replace _map_ with the name of the keymap taken from the output of the [command]#localectl# [option]`list-keymaps` command. Unless the [option]`--no-convert` option is passed, the selected setting is also applied to the default keyboard mapping of the X11 window system, after converting it to the closest matching X11 keyboard mapping. This also applies in reverse, you can specify both keymaps with the following command as `root`:
[subs="quotes, macros"]
----
[command]#localectl# [option]`set-x11-keymap` _map_
----
If you want your X11 layout to differ from the console layout, use the [option]`--no-convert` option.
[subs="quotes, macros"]
----
[command]#localectl# [option]`--no-convert` [option]`set-x11-keymap` _map_
----
With this option, the X11 keymap is specified without changing the previous console layout setting.
.Setting the X11 Keymap Separately
====
Imagine you want to use German keyboard layout in the graphical interface, but for console operations you want to retain the US keymap. To do so, type as `root`:
[subs="macros, attributes"]
----
~]#{nbsp}localectl --no-convert set-x11-keymap pass:quotes[_de_]
----
Then you can verify if your setting was successful by checking the current status:
[subs="attributes"]
----
~]${nbsp}localectl status
System Locale: LANG=de_DE.UTF-8
VC Keymap: us
X11 Layout: de
----
====
Apart from keyboard layout (_map_), three other options can be specified:
[subs="quotes, macros"]
----
[command]#localectl# [option]`set-x11-keymap` _map_ _model_ _variant_ _options_
----
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.
[[sect-Keyboard_Configuration-Resources]]
==== Additional Resources
For more information on how to configure the keyboard layout on Fedora, see the resources listed below:
.Installed Documentation
* `localectl`(1) — The manual page for the [command]#localectl# command line utility documents how to use this tool to configure the system locale and keyboard layout.
* `loadkeys`(1) — The manual page for the [command]#loadkeys# command provides more information on how to use this tool to change the keyboard layout in a virtual console.

BIN
en-US/basic-system-configuration/images/alt-f2_GNOME.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 163 KiB

BIN
en-US/basic-system-configuration/images/alt-f2_KDE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 196 KiB

BIN
en-US/basic-system-configuration/images/alt-f2_LXDE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 176 KiB

BIN
en-US/basic-system-configuration/images/alt-f2_MATE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 177 KiB

BIN
en-US/basic-system-configuration/images/alt-f2_XFCE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 200 KiB

BIN
en-US/basic-system-configuration/images/managing_users.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
en-US/basic-system-configuration/images/menu_GNOME.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 880 KiB

BIN
en-US/basic-system-configuration/images/menu_KDE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 936 KiB

BIN
en-US/basic-system-configuration/images/menu_LXDE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 241 KiB

BIN
en-US/basic-system-configuration/images/menu_MATE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 250 KiB

BIN
en-US/basic-system-configuration/images/menu_XFCE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 477 KiB

BIN
en-US/basic-system-configuration/images/searchmenu_GNOME.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 796 KiB

BIN
en-US/basic-system-configuration/images/searchmenu_KDE.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 900 KiB

3
en-US/basic-system-configuration/intro-basic-system-configuration.adoc Normal file
View file

@ -0,0 +1,3 @@
== Basic System Configuration
This part covers basic system administration tasks such as keyboard configuration, date and time configuration, managing users and groups, and gaining privileges.

22
en-US/entities.adoc Normal file
View file

@ -0,0 +1,22 @@
:BOOKID: system-administrator's-guide
:BZURL: link:++https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora%20Documentation&component=system-administrator's-guide++[http://bugzilla.redhat.com/]
:HOLDER: Red Hat, Inc. and others
:MAJOROS: Fedora
:MAJOROSVER: Fedora Rawhide
:OSORG: The Fedora Project
:PKGOS: fcRawhide
:PRODUCT: Fedora Documentation
:PRODVER: Rawhide
:YEAR: 2017
:nbsp: pass:q[&nbsp;]

1339
en-US/infrastructure-services/OpenSSH.adoc Normal file
View file

File diff suppressed because it is too large Load diff

276
en-US/infrastructure-services/Services_and_Daemons.adoc Normal file
View file

@ -0,0 +1,276 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-Services_and_Daemons]]
=== Services and Daemons
indexterm:[services configuration]
Maintaining security on your system is extremely important, and one approach for this task is to manage access to system services carefully. Your system may need to provide open access to particular services (for example, `httpd` if you are running a web server). However, if you do not need to provide a service, you should turn it off to minimize your exposure to possible bug exploits.
This chapter covers the configuration of the services to be run when a system is started, and provides information on how to start, stop, and restart the services on the command line using the [application]*systemctl* utility.
.Keep the system secure
[IMPORTANT]
====
When you allow access for new services, always remember that both the firewall and [application]*SELinux* need to be configured as well. One of the most common mistakes committed when configuring a new service is neglecting to implement the necessary firewall configuration and SELinux policies to allow access for it. For more information, refer to the {MAJOROSVER} [citetitle]_Security Guide_.
====
[[s1-services-configuring]]
==== Configuring Services
indexterm:[systemctl,services configuration]indexterm:[services configuration,systemctl]
To allow you to configure which services are started at boot time, {MAJOROS} is shipped with the [application]*systemctl* command line tool.
.Do not use the ntsysv and chkconfig utilities
[NOTE]
====
Although it is still possible to use the [application]*ntsysv* and [application]*chkconfig* utilities to manage services that have init scripts installed in the `/etc/rc.d/init.d/` directory, it is advised that you use the [application]*systemctl* utility.
====
.Enabling the irqbalance service
[IMPORTANT]
====
To ensure optimal performance on POWER architecture, it is recommended that the `irqbalance` service is enabled. In most cases, this service is installed and configured to run during the {MAJOROSVER} installation. To verify that `irqbalance` is running, type the following at a shell prompt:
[subs="quotes, macros"]
----
[command]#systemctl status irqbalance.service#
----
====
[[s3-services-configuration-enabling]]
===== Enabling the Service
To configure a service to be automatically started at boot time, use the [command]#systemctl# command in the following form:
----
systemctl enable service_name.service
----
The service will be started the next time you boot the system. For information on how to start the service immediately, refer to <<s3-services-running-running>>.
[[exam-services-configuration-enabling]]
.Enabling the httpd service
====
Imagine you want to run the Apache HTTP Server on your system. Provided that you have the [package]*httpd* package installed, you can enable the `httpd` service by typing the following at a shell prompt as `root`:
----
~]# systemctl enable httpd.service
----
====
[[s3-services-configuration-disabling]]
===== Disabling the Service
To disable starting a service at boot time, use the [command]#systemctl# command in the following form:
----
systemctl disable service_name.service
----
The next time you boot the system, the service will *not* be started. For information on how to stop the service immediately, refer to <<s3-services-running-stopping>>.
[[exam-services-configuration-disabling]]
.Disabling the telnet service
====
In order to secure the system, users are advised to disable insecure connection protocols such as Telnet. You can make sure that the `telnet` service is disabled by running the following command as `root`:
----
~]# systemctl disable telnet.service
----
====
[[s1-services-running]]
==== Running Services
indexterm:[systemctl,services configuration]indexterm:[services configuration,ssystemctl]
The [application]*systemctl* utility also allows you to determine the status of a particular service, as well as to start, stop, or restart a service.
.Do not use the service utility
[NOTE]
====
Although it is still possible to use the [application]*service* utility to manage services that have init scripts installed in the `/etc/rc.d/init.d/` directory, it is advised that you use the [application]*systemctl* utility.
====
[[s3-services-running-checking]]
===== Checking the Service Status
To determine the status of a particular service, use the [command]#systemctl# command in the following form:
----
systemctl status service_name.service
----
This command provides detailed information on the service's status. However, if you merely need to verify that a service is running, you can use the [command]#systemctl# command in the following form instead:
----
systemctl is-active service_name.service
----
[[exam-services-running-checking]]
.Checking the status of the httpd service
====
<<exam-services-configuration-enabling>> illustrated how to enable starting the `httpd` service at boot time. Imagine that the system has been restarted and you need to verify that the service is really running. You can do so by typing the following at a shell prompt:
[subs="quotes, macros"]
----
~]$ [command]#systemctl is-active httpd.service#
active
----
You can also display detailed information about the service by running the following command:
----
~]$ systemctl status httpd.service
httpd.service - LSB: start and stop Apache HTTP Server
Loaded: loaded (/etc/rc.d/init.d/httpd)
Active: active (running) since Mon, 23 May 2011 21:38:57 +0200; 27s ago
Process: 2997 ExecStart=/etc/rc.d/init.d/httpd start (code=exited, status=0/SUCCESS)
Main PID: 3002 (httpd)
CGroup: name=systemd:/system/httpd.service
├ 3002 /usr/sbin/httpd
├ 3004 /usr/sbin/httpd
├ 3005 /usr/sbin/httpd
├ 3006 /usr/sbin/httpd
├ 3007 /usr/sbin/httpd
├ 3008 /usr/sbin/httpd
├ 3009 /usr/sbin/httpd
├ 3010 /usr/sbin/httpd
└ 3011 /usr/sbin/httpd
----
====
To display a list of all active system services, use the following command:
[subs="quotes, macros"]
----
[command]#systemctl list-units --type=service#
----
This command provides a tabular output with each line consisting of the following columns:
* `UNIT` — A `systemd` unit name. In this case, a service name.
* `LOAD` — Information whether the `systemd` unit was properly loaded.
* `ACTIVE` — A high-level unit activation state.
* `SUB` — A low-level unit activation state.
* `JOB` — A pending job for the unit.
* `DESCRIPTION` — A brief description of the unit.
[[exam-services-running-checking-all]]
.Listing all active services
====
You can list all active services by using the following command:
[subs="quotes, macros"]
----
~]$ [command]#systemctl list-units --type=service#
UNIT LOAD ACTIVE SUB JOB DESCRIPTION
abrt-ccpp.service loaded active exited LSB: Installs coredump handler which saves segfault data
abrt-oops.service loaded active running LSB: Watches system log for oops messages, creates ABRT dump directories for each oops
abrtd.service loaded active running ABRT Automated Bug Reporting Tool
accounts-daemon.service loaded active running Accounts Service
atd.service loaded active running Job spooling tools
_[output truncated]_
----
In the example above, the `abrtd` service is loaded, active, and running, and it does not have any pending jobs.
====
[[s3-services-running-running]]
===== Running the Service
To run a service, use the [command]#systemctl# command in the following form:
----
systemctl start service_name.service
----
This will start the service in the current session. To configure the service to be started at boot time, refer to <<s3-services-configuration-enabling>>.
[[exam-services-running-running]]
.Running the httpd service
====
<<exam-services-configuration-enabling>> illustrated how to run the `httpd` service at boot time. You can start the service immediately by typing the following at a shell prompt as `root`:
----
~]# systemctl start httpd.service
----
====
[[s3-services-running-stopping]]
===== Stopping the Service
To stop a service, use the [command]#systemctl# command in the following form:
----
systemctl stop service_name.service
----
This will stop the service in the current session. To disable starting the service at boot time, refer to <<s3-services-configuration-enabling>>.
[[exam-services-running-stopping]]
.Stopping the telnet service
====
<<exam-services-configuration-disabling>> illustrated how to disable starting the `telnet` service at boot time. You can stop the service immediately by running the following command as `root`:
----
~]# systemctl stop telnet.service
----
====
[[s3-services-running-restarting]]
===== Restarting the Service
To restart a service, use the [command]#systemctl# command in the following form:
----
systemctl restart service_name.service
----
[[exam-services-running-restarting]]
.Restarting the sshd service
====
For any changes in the `/etc/ssh/sshd_config` configuration file to take effect, it is required that you restart the `sshd` service. You can do so by typing the following at a shell prompt as `root`:
----
~]# systemctl restart sshd.service
----
====
[[s1-services-additional-resources]]
==== Additional Resources
[[s2-services-additional-resources-installed]]
===== Installed Documentation
* `systemctl`(1) — The manual page for the [application]*systemctl* utility.
[[s2-services-additional-resources-books]]
===== Related Books
[citetitle]_{MAJOROSVER} Security Guide_:: A guide to securing {MAJOROS}. It contains valuable information on how to set up the firewall, as well as the configuration of [application]*SELinux*.

385
en-US/infrastructure-services/TigerVNC.adoc Normal file
View file

@ -0,0 +1,385 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-TigerVNC]]
=== TigerVNC
`TigerVNC` (Tiger Virtual Network Computing) is a system
for graphical desktop sharing which allows you to remotely control other computers.
`TigerVNC` works on the client-server network: a
*server* shares its output (`vncserver`) and a
*client* (`vncviewer`) connects to the server.
[NOTE]
====
Unlike in Fedora 15 and Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}6, `TigerVNC` in {MAJOROS} uses the `systemd` system management daemon for its configuration.
The `/etc/sysconfig/vncserver` configuration file has been replaced
by `/etc/systemd/system/vncserver@.service`.
====
[[s1-vnc-server]]
==== VNC Server
`vncserver` is a utility which starts a VNC (Virtual
Network Computing) desktop. It runs [application]*Xvnc* with appropriate options and starts a window
manager on the VNC desktop. `vncserver` allows users to run
separate sessions in parallel on a machine which can then be accessed by any number of clients
from anywhere.
[[s2-vnc-installation]]
===== Installing VNC Server
To install the [application]*TigerVNC* server, issue the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}dnf install tigervnc-server
----
[[s3-configuring-vnc-server]]
===== Configuring VNC Server
[[configuring-vncserver]]
.Configuring the first VNC connection
. A configuration file named `/etc/systemd/system/vncserver@.service` is required. To create this file, copy the `/lib/systemd/system/vncserver@.service` file as `root`:
+
[subs="macros, attributes"]
----
~]#{nbsp}pass:quotes[`cp /lib/systemd/system/vncserver@.service /etc/systemd/system/vncserver@.service`]
----
+
There is no need to include the display number in the file name because `systemd` automatically creates the appropriately named instance in memory on demand, replacing `'%i'` in the service file by the display number. For a single user it is not necessary to rename the file. For multiple users, a uniquely named service file for each user is required, for example, by adding the user name to the file name in some way. See <<configuring-vncserver-2users>> for details.
. Edit `/etc/systemd/system/vncserver@.service`,
replacing _USER_ with the actual user name.
Leave the remaining lines of the file unmodified.
The [option]`-geometry` argument specifies the size of the VNC desktop to
be created; by default, it is set to `1024x768`.
+
[subs="quotes, macros"]
----
ExecStart=/sbin/runuser -l _USER_ -c "/usr/bin/vncserver %i -geometry 1280x1024"
PIDFile=/home/pass:attributes[{blank}]_USER_pass:attributes[{blank}]/.vnc/%H%i.pid
----
. Save the changes.
. To make the changes take effect immediately, issue the following command:
+
[subs="macros, attributes"]
----
~]#{nbsp}pass:quotes[`systemctl daemon-reload`]
----
. Set the password for the user or users defined in the configuration file. Note
that you need to switch from `root` to _USER_ first.
+
[subs="macros, attributes"]
----
~]#{nbsp}su - pass:quotes[_USER_]
~]${nbsp}pass:quotes[`vncpasswd`]
Password:
Verify:
----
+
[IMPORTANT]
====
The stored password is not encrypted; anyone who has access to the password
file can find the plain-text password.
====
Proceed to <<s4-starting-vncserver>>.
[[configuring-vncserver-2users]]
====== Configuring VNC Server for Two Users
If you want to configure more than one user on the same machine,
create different template-type service files, one for each user.
. Create two service files, for example `vncserver-_USER_1_pass:attributes[{blank}]@.service`
and `vncserver-_USER_2_pass:attributes[{blank}]@.service`.
In both these files substitute _USER_ with the correct user name.
. Set passwords for both users:
+
[subs="macros, attributes"]
----
~]${nbsp}su - USER_1
~]${nbsp}pass:quotes[`vncpasswd`]
Password:
Verify:
~]${nbsp}su - USER_2
~]${nbsp}pass:quotes[`vncpasswd`]
Password:
Verify:
----
[[s4-starting-vncserver]]
===== Starting VNC Server
To start or enable the service, specify the display number directly in the command.
The file configured above in <<configuring-vncserver>> works as a template, in which `%i` is substituted with
the display number by `systemd`.
With a valid display number, execute the following command:
[subs="attributes"]
----
~]#{nbsp}systemctl start vncserver@:display_number.service
----
You can also enable the service to start automatically at system start. Then, when you log in, `vncserver` is automatically started. As `root`, issue a command as follows:
[subs="attributes"]
----
~]#{nbsp}systemctl enable vncserver@:display_number.service
----
At this point, other users are able to use a VNC viewer program to connect to the VNC server using the display number and password defined. Provided a graphical desktop is installed, an instance of that desktop will be displayed. It will not be the same instance as that currently displayed on the target machine.
[[starting-vncserver-2displays]]
====== Configuring VNC Server for Two Users and Two Different Displays
For the two configured VNC servers, vncserver-USER_1@.service and vncserver-USER_2@.service,
you can enable different display numbers. For example, the following commands will cause a VNC server for USER_1 to
start on display 3, and a VNC server for USER_2 to start on display 5:
[subs="attributes"]
----
~]#{nbsp}systemctl start vncserver-USER_1@:3.service
~]#{nbsp}systemctl start vncserver-USER_2@:5.service
----
[[terminating-vnc-session]]
===== Terminating a VNC Session
Similarly to enabling the `vncserver` service, you can disable
the automatic start of the service at system start:
[subs="attributes"]
----
~]#{nbsp}systemctl disable vncserver@:display_number.service
----
Or, when your system is running, you can stop the service by issuing the following
command as `root`:
[subs="attributes"]
----
~]#{nbsp}systemctl stop vncserver@:display_number.service
----
[[s5-vnc-viewer]]
==== VNC Viewer
`vncviewer` is the program which shows the shared graphical
user interfaces and controls the server.
For operating the `vncviewer`, there is a pop-up menu
containing entries which perform various actions such as switching in and out of
full-screen mode or quitting the viewer. Alternatively, you can operate `vncviewer`
through the terminal. Enter [command]#vncviewer -h# on the command line to list `vncviewer`pass:attributes[{blank}]'s parameters.
[[installing-vncviewer]]
===== Installing VNC Viewer
To install the [application]*TigerVNC* client, [command]#vncviewer#pass:attributes[{blank}]>, issue the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}dnf install tigervnc
----
[[s6-connecting-vnc-viewer]]
===== Connecting to VNC Server
Once the VNC server is configured, you can connect to it from any VNC viewer.
In order to do so, issue the [command]#vncviewer# command in the following format:
[subs="macros"]
----
vncviewer pass:quotes[_address_]:pass:quotes[_port_number_]
----
Where _address_ is an `IP` or host name.
[[connecting-to-vncserver]]
.One Client Connecting to VNC Server
====
With the `IP` address `192.168.0.4` and display number *3*
the command looks as follows:
[subs="quotes, macros, attributes"]
----
[command]#~]${nbsp}vncviewer 192.168.0.4:3#
----
====
[[sec-Configuring_the_Firewall_for_VNC]]
====== Configuring the Firewall for VNC
When using a non-encrypted connection, `firewalld` might
block the connection. To allow `firewalld` to pass the VNC packets, you can open specific ports to `TCP` traffic. When using the [option]`-via` option, traffic is redirected over `SSH` which is enabled by default in `firewalld`.
[NOTE]
====
The default port of VNC server is 5900. To reach the port through which a remote
desktop will be accessible, sum the default port and the user's
assigned display number. For example, for the second port: 2 + 5900 = 5902.
====
For displays `0` to `3`, make use of `firewalld`pass:attributes[{blank}]'s support for the VNC service by means of the [option]`service` option as described below. Note that for display numbers greater than `3`, the corresponding ports will have to be opened specifically as explained in <<proc-Opening-Ports_in_firewalld>>.
[[proc-Enabling_VNC_Service_in_firewalld]]
.Enabling VNC Service in firewalld
. Run the following command to see the information concerning `firewalld`
settings:
+
[subs="quotes, macros, attributes"]
----
[command]#~]${nbsp}firewall-cmd --list-all#
----
. To allow all VNC connections from a specific address, use a command as follows:
+
[subs="attributes"]
----
~]#{nbsp}firewall-cmd --add-rich-rule='rule family="ipv4" source address="192.168.122.116" service name=vnc-server accept'
success
----
+
See the link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/++[Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Security Guide] for more information on the use of firewall rich language commands.
. To verify the above settings, use a command as follows:
+
[subs="attributes"]
----
~]#{nbsp}firewall-cmd --list-all
public (default, active)
interfaces: bond0 bond0.192
sources:
services: dhcpv6-client ssh
ports:
masquerade: no
forward-ports:
icmp-blocks:
rich rules:
rule family="ipv4" source address="192.168.122.116" service name="vnc-server" accept
----
To open a specific port or range of ports make use of the [option]`--add-port` option to the [command]#firewall-cmd# command Line tool. For example, VNC display `4` requires port `5904` to be opened for `TCP` traffic.
[[proc-Opening-Ports_in_firewalld]]
.Opening Ports in firewalld
. To open a port for `TCP` traffic in the public zone, issue a command as `root` as follows:
+
[subs="attributes"]
----
~]#{nbsp}firewall-cmd --zone=public --add-port=5904/tcp
success
----
. To view the ports that are currently open for the public zone, issue a command as follows:
+
[subs="attributes"]
----
~]#{nbsp}firewall-cmd --zone=public --list-ports
5904/tcp
----
A port can be removed using the [command]#firewall-cmd --zone=pass:attributes[{blank}]_zone_ --remove-port=pass:attributes[{blank}]_number/protocol_pass:attributes[{blank}]# command.
For more information on opening and closing ports in `firewalld`, see the link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/++[Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Security Guide].
[[s1-using_ssh]]
===== Connecting to VNC Server Using SSH
*VNC* is a clear text network protocol with no security against possible attacks on the communication. To make the communication secure, you can encrypt your server-client connection by using the [option]`-via` option. This will create an `SSH` tunnel between the VNC server and the client.
The format of the command to encrypt a VNC server-client connection is as follows:
[subs="attributes"]
----
~]${nbsp}vncviewer -via user@host:display_number
----
[[using-via]]
.Using the -via Option
====
. To connect to a VNC server using `SSH`, enter a command as follows:
+
[subs="attributes"]
----
~]${nbsp}vncviewer -via USER_2@192.168.2.101:3
----
. When you are prompted to, type the password, and confirm by pressing kbd:[Enter].
. A window with a remote desktop appears on your screen.
====
.Restricting VNC Access
If you prefer only encrypted connections, you can prevent unencrypted connections
altogether by using the [option]`-localhost` option in the `systemd.service`
file, the ExecStart line:
[subs="quotes, macros"]
----
ExecStart=/sbin/runuser -l _user_ -c "/usr/bin/vncserver -localhost %i"
----
This will stop `vncserver` from accepting connections from anything but the local host and port-forwarded connections sent using `SSH` as a result of the [option]`-via` option.
For more information on using `SSH`, see <<ch-OpenSSH>>.
[[s9-additional-sources]]
==== Additional Resources
For more information about TigerVNC, see the resources listed below.
.Installed Documentation
* `vncserver(1)` — The *VNC* server manual pages.
* `vncviewer(1)` — The *VNC* viewer manual pages.
* `vncpasswd(1)` — The *VNC* password manual pages.

3
en-US/infrastructure-services/intro-infrastructure-services.adoc Normal file
View file

@ -0,0 +1,3 @@
== Infrastructure Services
This part provides information on how to configure services and daemons, configure authentication, and enable remote logins.

401
en-US/kernel-module-driver-configuration/Manually_Upgrading_the_Kernel.adoc Normal file
View file

@ -0,0 +1,401 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-Manually_Upgrading_the_Kernel]]
=== Manually Upgrading the Kernel
indexterm:[kernel,upgrading the kernel]indexterm:[kernel,package]indexterm:[kernel,RPM package]indexterm:[package,kernel RPM]
The {MAJOROS} kernel is custom-built by the {MAJOROS} kernel team to ensure its integrity and compatibility with supported hardware. Before a kernel is released, it must first pass a rigorous set of quality assurance tests.
{MAJOROS} kernels are packaged in the RPM format so that they are easy to upgrade and verify using the [application]*DNF* or [application]*PackageKit* package managers. [application]*PackageKit* automatically queries the DNF repositories and informs you of packages with available updates, including kernel packages.
This chapter is therefore *only* useful for users who need to manually update a kernel package using the [command]#rpm# command instead of [command]#dnf#.
indexterm:[kernel,installing kernel packages]indexterm:[installing the kernel]
.Use DNF to install kernels whenever possible
[WARNING]
====
Whenever possible, use either the [application]*DNF* or [application]*PackageKit* package manager to install a new kernel because they always *install* a new kernel instead of replacing the current one, which could potentially leave your system unable to boot.
====
indexterm:[kernel,installing kernel packages]
For more information on installing kernel packages with [application]*DNF*, see <<sec-Updating_Packages>>.
[[s1-kernel-packages]]
==== Overview of Kernel Packages
indexterm:[kernel,kernel packages]indexterm:[kernel package,kernel,for single, multicore and multiprocessor systems]indexterm:[packages,kernel,for single, multicore and multiprocessor systems]indexterm:[kernel package,kernel-devel,kernel headers and makefiles]indexterm:[packages,kernel-devel,kernel headers and makefiles]indexterm:[kernel package,kernel-headers,C header files files]indexterm:[packages,kernel-headers,C header files files]indexterm:[kernel package,linux-firmware,firmware files]indexterm:[packages,linux-firmware,firmware files]indexterm:[kernel package,perf,firmware files]indexterm:[packages,perf,firmware files]
{MAJOROS} contains the following kernel packages:
* [package]*kernel* — Contains the kernel for single, multicore and multiprocessor systems.
* [package]*kernel-debug* — Contains a kernel with numerous debugging options enabled for kernel diagnosis, at the expense of reduced performance.
* [package]*kernel-devel* — Contains the kernel headers and makefiles sufficient to build modules against the [package]*kernel* package.
* [package]*kernel-debug-devel* — Contains the development version of the kernel with numerous debugging options enabled for kernel diagnosis, at the expense of reduced performance.
* [package]*kernel-headers* — Includes the C header files that specify the interface between the Linux kernel and user-space libraries and programs. The header files define structures and constants that are needed for building most standard programs.
* [package]*linux-firmware* — Contains all of the firmware files that are required by various devices to operate.
* [package]*perf* — This package contains supporting scripts and documentation for the [application]*perf* tool shipped in each kernel image subpackage.
* [package]*kernel-abi-whitelists* — Contains information pertaining to the {MAJOROS} kernel ABI, including a lists of kernel symbols that are needed by external Linux kernel modules and a [package]*dnf* plug-in to aid enforcement.
* [package]*kernel-tools* — Contains tools for manipulating the Linux kernel and supporting documentation.
[[s1-kernel-preparing]]
==== Preparing to Upgrade
indexterm:[boot media]indexterm:[kernel,upgrading,preparing]indexterm:[kernel upgrading,preparing]indexterm:[kernel,upgrading,working boot media]
Before upgrading the kernel, it is recommended that you take some precautionary steps.
First, ensure that working boot media exists for the system in case a problem occurs. If the boot loader is not configured properly to boot the new kernel, you can use this media to boot into {MAJOROS}.
USB media often comes in the form of flash devices sometimes called _pen drives_, _thumb disks_, or _keys_, or as an externally-connected hard disk device. Almost all media of this type is formatted as a `VFAT` file system. You can create bootable USB media on media formatted as `ext2`, `ext3`, `ext4`, or `VFAT`.
You can transfer a distribution image file or a minimal boot media image file to USB media. Make sure that sufficient free space is available on the device. Around 4 GB is required for a distribution DVD image, around 700 MB for a distribution CD image, or around 10 MB for a minimal boot media image.
You must have a copy of the `boot.iso` file from a {MAJOROS} installation DVD, or installation CD-ROM#1, and you need a USB storage device formatted with the `VFAT` file system and around 16 MB of free space. The following procedure will not affect existing files on the USB storage device unless they have the same path names as the files that you copy onto it. To create USB boot media, perform the following commands as the `root` user:
. Install the [application]*SYSLINUX* bootloader on the USB storage device:
+
[subs="attributes"]
----
~]#{nbsp}syslinux /dev/sdX1
----
+
...where _sdX_ is the device name.
. Create mount points for `boot.iso` and the USB storage device:
+
[subs="attributes"]
----
~]#{nbsp}mkdir /mnt/isoboot /mnt/diskboot
----
. Mount `boot.iso`:
+
[subs="attributes"]
----
~]#{nbsp}mount -o loop boot.iso /mnt/isoboot
----
. Mount the USB storage device:
+
[subs="attributes"]
----
~]#{nbsp}mount /dev/sdX1 /mnt/diskboot
----
. Copy the [application]*ISOLINUX* files from the `boot.iso` to the USB storage device:
+
[subs="attributes"]
----
~]#{nbsp}cp /mnt/isoboot/isolinux/* /mnt/diskboot
----
. Use the `isolinux.cfg` file from `boot.iso` as the `syslinux.cfg` file for the USB device:
+
[subs="attributes"]
----
~]#{nbsp}grep -v local /mnt/isoboot/isolinux/isolinux.cfg > /mnt/diskboot/syslinux.cfg
----
. Unmount `boot.iso` and the USB storage device:
+
[subs="attributes"]
----
~]#{nbsp}umount /mnt/isoboot /mnt/diskboot
----
. You should reboot the machine with the boot media and verify that you are able to boot with it before continuing.
Alternatively, on systems with a floppy drive, you can create a boot diskette by installing the [package]*mkbootdisk* package and running the [command]#mkbootdisk# command as `root`. See [command]#man mkbootdisk# man page after installing the package for usage information.
To determine which kernel packages are installed, execute the command [command]#dnf list installed "kernel-*"# at a shell prompt. The output will comprise some or all of the following packages, depending on the system's architecture, and the version numbers might differ:
----
~]# dnf list installed "kernel-*"
Last metadata expiration check performed 0:28:51 ago on Tue May 26 21:22:39 2015.
Installed Packages
kernel-core.x86_64 4.0.3-300.fc22 @System
kernel-core.x86_64 4.0.4-300.fc22 @System
kernel-core.x86_64 4.0.4-301.fc22 @System
kernel-headers.x86_64 4.0.4-301.fc22 @System
kernel-modules.x86_64 4.0.3-300.fc22 @System
kernel-modules.x86_64 4.0.4-300.fc22 @System
kernel-modules.x86_64 4.0.4-301.fc22 @System
----
From the output, determine which packages need to be downloaded for the kernel upgrade. For a single processor system, the only required package is the [package]*kernel* package. See <<s1-kernel-packages>> for descriptions of the different packages.
[[s1-kernel-download]]
==== Downloading the Upgraded Kernel
indexterm:[kernel,downloading]indexterm:[kernel,upgrade kernel available]indexterm:[kernel,upgrade kernel available,via Fedora Update System]indexterm:[kernel,upgrade kernel available,Security Advisories]
There are several ways to determine if an updated kernel is available for the system.
* Via Fedora Update System — Download and install the kernel RPM packages. For more information, refer to link:++http://bodhi.fedoraproject.org/++[].
* Via `_DNF_` using check-update:
----
dnf check-update --enablerepo=updates-testing
----
To install the kernel manually, continue to <<s1-kernel-perform-upgrade>>.
[[s1-kernel-perform-upgrade]]
==== Performing the Upgrade
indexterm:[kernel,performing kernel upgrade]
After retrieving all of the necessary packages, it is time to upgrade the existing kernel.
.Keep the old kernel when performing the upgrade
[IMPORTANT]
====
It is strongly recommended that you keep the old kernel in case there are problems with the new kernel.
====
At a shell prompt, change to the directory that contains the kernel RPM packages. Use [option]`-i` argument with the [command]#rpm# command to keep the old kernel. Do *not* use the [option]`-U` option, since it overwrites the currently installed kernel, which creates boot loader problems. For example:
[subs="attributes"]
----
~]#{nbsp}rpm -ivh kernel-kernel_version.arch.rpm
----
The next step is to verify that the initial RAM disk image has been created. See <<sec-Verifying_the_Initial_RAM_Disk_Image>> for details.
[[sec-Verifying_the_Initial_RAM_Disk_Image]]
==== Verifying the Initial RAM Disk Image
indexterm:[initial RAM disk image,verifying]
The job of the initial RAM disk image is to preload the block device modules, such as for IDE, SCSI or RAID, so that the root file system, on which those modules normally reside, can then be accessed and mounted. On {MAJOROSVER} systems, whenever a new kernel is installed using either the [application]*DNF*, [application]*PackageKit*, or [application]*RPM* package manager, the [application]*Dracut* utility is always called by the installation scripts to create an _initramfs_ (initial RAM disk image).
On all architectures other than IBM eServer System i (see <<bh-Verifying_the_Initial_RAM_Disk_Image_and_Kernel_on_IBM_eServer_System_i>>), you can create an `initramfs` by running the [command]#dracut# command. However, you usually don't need to create an `initramfs` manually: this step is automatically performed if the kernel and its associated packages are installed or upgraded from RPM packages distributed by {OSORG}.
On architectures that use the GRUB 2 boot loader, you can verify that an `initramfs` corresponding to your current kernel version exists and is specified correctly in the `/boot/grub2/grub.cfg` configuration file by following this procedure:
[[procedure-Verifying_the_Initial_RAM_Disk_Image]]
.Verifying the Initial RAM Disk Image
. As `root`, list the contents in the `/boot/` directory and find the kernel (`vmlinuz-_kernel_version_pass:attributes[{blank}]`) and `initramfs-_kernel_version_pass:attributes[{blank}]` with the latest (most recent) version number:
+
[[ex-Ensuring_that_the_kernel_and_initramfs_versions_match]]
.Ensuring that the kernel and initramfs versions match
====
----
~]# ls /boot/
config-3.17.4-302.fc21.x86_64
config-3.17.6-300.fc21.x86_64
config-3.17.7-300.fc21.x86_64
efi
elf-memtest86+-5.01
extlinux
grub2
initramfs-0-rescue-db90b4e3715b42daa871351439343ca4.img
initramfs-3.17.4-302.fc21.x86_64.img
initramfs-3.17.6-300.fc21.x86_64.img
initramfs-3.17.7-300.fc21.x86_64.img
initrd-plymouth.img
lost+found
memtest86+-5.01
System.map-3.17.4-302.fc21.x86_64
System.map-3.17.6-300.fc21.x86_64
System.map-3.17.7-300.fc21.x86_64
vmlinuz-0-rescue-db90b4e3715b42daa871351439343ca4
vmlinuz-3.17.4-302.fc21.x86_64
vmlinuz-3.17.6-300.fc21.x86_64
vmlinuz-3.17.7-300.fc21.x86_64
----
====
+
<<ex-Ensuring_that_the_kernel_and_initramfs_versions_match>> shows that:
+
** we have three kernels installed (or, more correctly, three kernel files are present in the `/boot/` directory),
+
** the latest kernel is `vmlinuz-3.17.7-300.fc21.x86_64`, and
+
** an `initramfs` file matching our kernel version, `initramfs-3.17.7-300.fc21.x86_64.img`, also exists.
+
[[important-initrd_files_in_the__boot_directory_are_not_the_same_as_initramfs_files]]
.initrd files in the /boot/ directory are not the same as initramfs files
[IMPORTANT]
====
In the `/boot/` directory you might find several `initrd-_kernel_version_pass:attributes[{blank}]kdump.img` files. These are special files created by the `kdump` mechanism for kernel debugging purposes, are not used to boot the system, and can safely be ignored. For more information on `kdump`, see the link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Kernel_Crash_Dump_Guide/++[Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7 Kernel Crash Dump Guide].
====
. (Optional) If your `initramfs-_kernel_version_pass:attributes[{blank}]` file does not match the version of the latest kernel in `/boot`, or, in certain other situations, you might need to generate an `initramfs` file with the [application]*Dracut* utility. Simply invoking [command]#dracut# as `root` without options causes it to generate an `initramfs` file in the `/boot/` directory for the latest kernel present in that directory:
+
----
~]# dracut
----
+
You must use the [option]`--force` option if you want [command]#dracut# to overwrite an existing `initramfs` (for example, if your `initramfs` has become corrupt). Otherwise [command]#dracut# will refuse to overwrite the existing `initramfs` file:
+
----
~]# dracut
F: Will not override existing initramfs (/boot/initramfs-3.17.7-300.fc21.x86_64.img) without --force
----
+
You can create an initramfs in the current directory by calling [command]#dracut _initramfs_name_ _kernel_version_pass:attributes[{blank}]#, for example:
+
----
~]# dracut "initramfs-$(uname -r).img" $(uname -r)
----
+
If you need to specify specific kernel modules to be preloaded, add the names of those modules (minus any file name suffixes such as `.ko`) inside the parentheses of the `add_dracutmodules="pass:attributes[{blank}]_module_ _more_modules_pass:attributes[{blank}]"` directive of the `/etc/dracut.conf` configuration file. You can list the file contents of an `initramfs` image file created by dracut by using the [command]#lsinitrd _initramfs_file_pass:attributes[{blank}]# command:
+
----
~]# lsinitrd /boot/initramfs-3.17.7-300.fc21.x86_64.img
Image: /boot/initramfs-3.17.7-300.fc21.x86_64.img: 18M
========================================================================
Version: dracut-038-31.git20141204.fc21
[output truncated]
----
+
See [command]#man dracut# and [command]#man dracut.conf# for more information on options and usage.
. Examine the `/boot/grub2/grub.cfg` configuration file to ensure that an `initramfs-_kernel_version_.img` file exists for the kernel version you are booting. For example:
+
----
~]# grep initramfs /boot/grub2/grub.cfg
initrd16 /initramfs-3.17.7-300.fc21.x86_64.img
initrd16 /initramfs-3.17.6-300.fc21.x86_64.img
initrd16 /initramfs-3.17.4-302.fc21.x86_64.img
initrd16 /initramfs-0-rescue-db90b4e3715b42daa871351439343ca4.img
----
+
See <<s1-kernel-boot-loader>> for more information on how to read and update the `/boot/grub2/grub.cfg` file.
.Verifying the Initial RAM Disk Image and Kernel on IBM eServer System iindexterm:[initial RAM disk image,verifying,IBM eServer System i]
On IBM eServer System i machines, the initial RAM disk and kernel files are combined into a single file, which is created with the [command]#addRamDisk# command. This step is performed automatically if the kernel and its associated packages are installed or upgraded from the RPM packages distributed by {OSORG}; thus, it does not need to be executed manually. To verify that it was created, run the following command as `root` to make sure the `/boot/vmlinitrd-_kernel_version_pass:attributes[{blank}]` file already exists:
[subs="quotes, macros"]
----
[command]#ls -l /boot/#
----
The _kernel_version_ should match the version of the kernel just installed.
[[s1-kernel-boot-loader]]
==== Verifying the Boot Loader
indexterm:[boot loader,verifying]
When you install a kernel using [command]#rpm#, the kernel package creates an entry in the boot loader configuration file for that new kernel. However, [command]#rpm# does *not* configure the new kernel to boot as the default kernel. You must do this manually when installing a new kernel with [command]#rpm#.
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.
[[tb-grub-arch-loaders]]
.Boot loaders by architecture
[options="header"]
|===
|Architecture|Boot Loader|See
|x86|GRUB 2|<<s3-kernel-boot-loader-grub>>
|AMD AMD64 *or* Intel 64|GRUB 2|<<s3-kernel-boot-loader-grub>>
|IBM eServer System i|OS/400|<<s2-kernel-boot-loader-iseries>>
|IBM eServer System p|YABOOT|<<s2-kernel-boot-loader-pseries>>
|IBM System z|z/IPL|&mdash;
|===
[[s3-kernel-boot-loader-grub]]
===== Configuring the GRUB 2 Boot Loader
indexterm:[GRUB 2 boot loader,configuring]indexterm:[GRUB 2 boot loader,configuration file]
{MAJOROSVER} is distributed with GRUB 2, which reads its configuration from the `/boot/grub2/grub.cfg` file. This file is generated by the [application]*grub2-mkconfig* utility based on Linux kernels located in the `/boot` directory, template files located in `/etc/grub.d/`, and custom settings in the `/etc/default/grub` file and is automatically updated each time you install a new kernel from an RPM package. To update this configuration file manually, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#grub2-mkconfig# [option]`-o` [option]`/boot/grub2/grub.cfg`
----
Among various code snippets and directives, the `/boot/grub2/grub.cfg` configuration file contains one or more `menuentry` blocks, each representing a single GRUB 2 boot menu entry. These blocks always start with the `menuentry` keyword followed by a title, list of options, and opening curly bracket, and end with a closing curly bracket. Anything between the opening and closing bracket should be indented. For example, the following is a sample `menuentry` block for Fedora 21 with Linux kernel 3.17.6-300.fc21.x86_64:
----
menuentry 'Fedora (3.17.6-300.fc21.x86_64) 21 (Twenty One)' --class fedora --class gnu-linux --class gnu --class os --unrestricted $menuentry_id_option 'gnulinux-3.17.4-301.fc21.x86_64-advanced-effee860-8d55-4e4a-995e-b4c88f9ac9f0' {
load_video
set gfxpayload=keep
insmod gzio
insmod part_msdos
insmod ext2
set root='hd0,msdos1'
if [ x$feature_platform_search_hint = xy ]; then
search --no-floppy --fs-uuid --set=root --hint='hd0,msdos1' f19c92f4-9ead-4207-b46a-723b7a2c51c8
else
search --no-floppy --fs-uuid --set=root f19c92f4-9ead-4207-b46a-723b7a2c51c8
fi
linux16 /vmlinuz-3.17.6-300.fc21.x86_64 root=/dev/mapper/fedora-root ro rd.lvm.lv=fedora/swap rd.lvm.lv=fedora/root rhgb quiet LANG=en_US.UTF-8
initrd16 /initramfs-3.17.6-300.fc21.x86_64.img
}
----
Each `menuentry` block that represents an installed Linux kernel contains `linux` and `initrd` directives followed by the path to the kernel and the `initramfs` image respectively. If a separate `/boot` partition was created, the paths to the kernel and the `initramfs` image are relative to `/boot`. In the example above, the `initrd16 /initramfs-3.17.6-300.fc21.x86_64.img` line means that the `initramfs` image is actually located at `/boot/initramfs-3.17.6-300.fc21.x86_64.img` when the root file system is mounted, and likewise for the kernel path.
The kernel version number as given on the `linux /vmlinuz-_kernel_version_pass:attributes[{blank}]` line must match the version number of the `initramfs` image given on the `initrd /initramfs-_kernel_version_.img` line of each `menuentry` block. For more information on how to verify the initial RAM disk image, refer to <<procedure-Verifying_the_Initial_RAM_Disk_Image>>.
[[note-The_initrd_directive_in_grub.cfg_refers_to_an_initramfs_image]]
.The initrd directive in grub.cfg refers to an initramfs image
[NOTE]
====
In `menuentry` blocks, the `initrd` directive must point to the location (relative to the `/boot` directory if it is on a separate partition) of the `initramfs` file corresponding to the same kernel version. This directive is called `initrd` because the previous tool which created initial RAM disk images, [command]#mkinitrd#, created what were known as `initrd` files. The `grub.cfg` directive remains `initrd` to maintain compatibility with other tools. The file-naming convention of systems using the [command]#dracut# utility to create the initial RAM disk image is `initramfs-_kernel_version_.img`.
For information on using [application]*Dracut*, refer to <<sec-Verifying_the_Initial_RAM_Disk_Image>>.
====
After installing a new kernel with [command]#rpm#, verify that `/boot/grub2/grub.cfg` is correct and reboot the computer into the new kernel. Ensure your hardware is detected by watching the boot process output. If GRUB 2 presents an error and is unable to boot into the new kernel, it is often easiest to try to boot into an alternative or older kernel so that you can fix the problem. Alternatively, use the boot media you created earlier to boot the system.
.Causing the GRUB 2 boot menu to display
[IMPORTANT]
====
If you set the [option]`GRUB_TIMEOUT` option in the `/etc/default/grub` file to 0, GRUB 2 will not display its list of bootable kernels when the system starts up. In order to display this list when booting, press and hold any alphanumeric key while and immediately after BIOS information is displayed, and GRUB 2 will present you with the GRUB menu.
====
[[s2-kernel-boot-loader-iseries]]
===== Configuring the OS/400 Boot Loader
indexterm:[OS/400 boot loader,configuring]indexterm:[OS/400 boot loader,configuration file]
The `/boot/vmlinitrd-_kernel-version_pass:attributes[{blank}]` file is installed when you upgrade the kernel. However, you must use the [command]#dd# command to configure the system to boot the new kernel.
. As `root`, issue the command [command]#cat /proc/iSeries/mf/side# to determine the default side (either A, B, or C).
. As `root`, issue the following command, where _kernel-version_ is the version of the new kernel and _side_ is the side from the previous command:
+
[subs="quotes, macros"]
----
[command]#dd if=/boot/vmlinitrd-_kernel-version_ of=/proc/iSeries/mf/pass:attributes[{blank}]_side_pass:attributes[{blank}]/vmlinux bs=8k#
----
Begin testing the new kernel by rebooting the computer and watching the messages to ensure that the hardware is detected properly.
[[s2-kernel-boot-loader-pseries]]
===== Configuring the YABOOT Boot Loader
IBM eServer System p uses YABOOT as its boot loader. YABOOT uses `/etc/aboot.conf` as its configuration file. Confirm that the file contains an `image` section with the same version as the [package]*kernel* package just installed, and likewise for the `initramfs` image:
[subs="quotes, attributes"]
----
boot=/dev/sda1 init-message=Welcome to {MAJOROS}! Hit &lt;TAB&gt; for boot options
partition=2 timeout=30 install=/usr/lib/yaboot/yaboot delay=10 nonvram
image=/vmlinuz-2.6.32-17.EL
label=old
read-only
initrd=/initramfs-2.6.32-17.EL.img
append="root=LABEL=/"
image=/vmlinuz-2.6.32-19.EL
label=linux
read-only
initrd=/initramfs-2.6.32-19.EL.img
append="root=LABEL=/"
----
Notice that the default is not set to the new kernel. The kernel in the first image is booted by default. To change the default kernel to boot either move its image stanza so that it is the first one listed or add the directive `default` and set it to the `label` of the image stanza that contains the new kernel.
Begin testing the new kernel by rebooting the computer and watching the messages to ensure that the hardware is detected properly.

682
en-US/kernel-module-driver-configuration/Working_with_Kernel_Modules.adoc Normal file
View file

@ -0,0 +1,682 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-Working_with_Kernel_Modules]]
=== Working with Kernel Modules
indexterm:[kernel module,definition]indexterm:[module,kernel module]indexterm:[drivers,kernel module]
The Linux kernel is modular, which means it can extend its capabilities through the use of dynamically-loaded _kernel modules_. A kernel module can provide:
* a device driver which adds support for new hardware; or,
* support for a file system such as `btrfs` or `NFS`.
Like the kernel itself, modules can take parameters that customize their behavior, though the default parameters work well in most cases. User-space tools can list the modules currently loaded into a running kernel; query all available modules for available parameters and module-specific information; and load or unload (remove) modules dynamically into or from a running kernel. Many of these utilities, which are provided by the [package]*kmod* package, take module dependencies into account when performing operations so that manual dependency-tracking is rarely necessary.
On modern systems, kernel modules are automatically loaded by various mechanisms when the conditions call for it. However, there are occasions when it is necessary to load or unload modules manually, such as when one module is preferred over another although either could provide basic functionality, or when a module is misbehaving.
This chapter explains how to:
* use the user-space [application]*kmod* utilities to display, query, load and unload kernel modules and their dependencies;
* set module parameters both dynamically on the command line and permanently so that you can customize the behavior of your kernel modules; and,
* load modules at boot time.
.Installing the kmod package
[NOTE]
====
In order to use the kernel module utilities described in this chapter, first ensure the [package]*kmod* package is installed on your system by running, as root:
[subs="attributes"]
----
~]#{nbsp}dnf install kmod
----
For more information on installing packages with DNF, see <<sec-Installing>>.
====
[[sec-Listing_Currently-Loaded_Modules]]
==== Listing Currently-Loaded Modules
indexterm:[kernel module,listing,currently loaded modules]indexterm:[kernel module,utilities,lsmod]indexterm:[lsmod,kernel module]
You can list all kernel modules that are currently loaded into the kernel by running the [command]#lsmod# command, for example:
----
~]$ lsmod
Module Size Used by
tcp_lp 12663 0
bnep 19704 2
bluetooth 372662 7 bnep
rfkill 26536 3 bluetooth
fuse 87661 3
ip6t_rpfilter 12546 1
ip6t_REJECT 12939 2
ipt_REJECT 12541 2
xt_conntrack 12760 7
ebtable_nat 12807 0
ebtable_broute 12731 0
bridge 110196 1 ebtable_broute
stp 12976 1 bridge
llc 14552 2 stp,bridge
ebtable_filter 12827 0
ebtables 30913 3 ebtable_broute,ebtable_nat,ebtable_filter
ip6table_nat 13015 1
nf_conntrack_ipv6 18738 5
nf_defrag_ipv6 34651 1 nf_conntrack_ipv6
nf_nat_ipv6 13279 1 ip6table_nat
ip6table_mangle 12700 1
ip6table_security 12710 1
ip6table_raw 12683 1
ip6table_filter 12815 1
ip6_tables 27025 5 ip6table_filter,ip6table_mangle,ip6table_security,ip6table_nat,ip6table_raw
iptable_nat 13011 1
nf_conntrack_ipv4 14862 4
nf_defrag_ipv4 12729 1 nf_conntrack_ipv4
nf_nat_ipv4 13263 1 iptable_nat
nf_nat 21798 4 nf_nat_ipv4,nf_nat_ipv6,ip6table_nat,iptable_nat
[output truncated]
----
Each row of [command]#lsmod# output specifies:
* the name of a kernel module currently loaded in memory;
* the amount of memory it uses; and,
* the sum total of processes that are using the module and other modules which depend on it, followed by a list of the names of those modules, if there are any. Using this list, you can first unload all the modules depending the module you want to unload. For more information, see <<sec-Unloading_a_Module>>.
indexterm:[kernel module,files,/proc/modules]
Finally, note that [command]#lsmod# output is less verbose and considerably easier to read than the content of the `/proc/modules` pseudo-file.
[[sec-Displaying_Information_About_a_Module]]
==== Displaying Information About a Module
indexterm:[kernel module,listing,module information]indexterm:[kernel module,utilities,modinfo]indexterm:[modinfo,kernel module]
You can display detailed information about a kernel module by running the [command]#modinfo{nbsp}pass:attributes[{blank}]_module_name_pass:attributes[{blank}]# command.
[[note-Module_names_do_not_end_in_.ko]]
.Module names do not end in .ko
[NOTE]
====
When entering the name of a kernel module as an argument to one of the [application]*kmod* utilities, do not append a `.ko` extension to the end of the name. Kernel module names do not have extensions; their corresponding files do.
====
[[ex-Listing_information_about_a_kernel_module_with_lsmod]]
.Listing information about a kernel module with lsmod
====
To display information about the `e1000e` module, which is the Intel PRO/1000 network driver, run:
----
~]# modinfo e1000e
filename: /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
version: 2.3.2-k
license: GPL
description: Intel(R) PRO/1000 Network Driver
author: Intel Corporation, <linux.nics@intel.com>
srcversion: 2FBED3F5E2EF40112284D95
alias: pci:v00008086d00001503sv*sd*bc*sc*i*
alias: pci:v00008086d00001502sv*sd*bc*sc*i*
[some alias lines omitted]
alias: pci:v00008086d0000105Esv*sd*bc*sc*i*
depends: ptp
intree: Y
vermagic: 3.17.4-302.fc21.x86_64 SMP mod_unload
signer: Fedora kernel signing key
sig_key: 1F:C9:E6:8F:74:19:55:63:48:FD:EE:2F:DE:B7:FF:9D:A6:33:7B:BF
sig_hashalgo: sha256
parm: debug:Debug level (0=none,...,16=all) (int)
parm: copybreak:Maximum size of packet that is copied to a new buffer on receive (uint)
parm: TxIntDelay:Transmit Interrupt Delay (array of int)
parm: TxAbsIntDelay:Transmit Absolute Interrupt Delay (array of int)
parm: RxIntDelay:Receive Interrupt Delay (array of int)
parm: RxAbsIntDelay:Receive Absolute Interrupt Delay (array of int)
parm: InterruptThrottleRate:Interrupt Throttling Rate (array of int)
parm: IntMode:Interrupt Mode (array of int)
parm: SmartPowerDownEnable:Enable PHY smart power down (array of int)
parm: KumeranLockLoss:Enable Kumeran lock loss workaround (array of int)
parm: WriteProtectNVM:Write-protect NVM [WARNING: disabling this can lead to corrupted NVM] (array of int)
parm: CrcStripping:Enable CRC Stripping, disable if your BMC needs the CRC (array of int)
----
====
Here are descriptions of a few of the fields in [command]#modinfo# output:
filename:: The absolute path to the `.ko` kernel object file. You can use [command]#modinfo -n# as a shortcut command for printing only the `filename` field.
description:: A short description of the module. You can use [command]#modinfo -d# as a shortcut command for printing only the description field.
alias:: The `alias` field appears as many times as there are aliases for a module, or is omitted entirely if there are none.
depends:: This field contains a comma-separated list of all the modules this module depends on.
+
[[note-Omitted_depends_field]]
.Omitting the depends field
[NOTE]
====
If a module has no dependencies, the `depends` field may be omitted from the output.
====
parm:: Each `parm` field presents one module parameter in the form `pass:attributes[{blank}]_parameter_name_:pass:attributes[{blank}]_description_pass:attributes[{blank}]`, where:
+
** _parameter_name_ is the exact syntax you should use when using it as a module parameter on the command line, or in an option line in a `.conf` file in the `/etc/modprobe.d/` directory; and,
+
** _description_ is a brief explanation of what the parameter does, along with an expectation for the type of value the parameter accepts (such as `int`, `unit` or `array of int`) in parentheses.
+
[[ex-Listing_module_parameters]]
.Listing module parameters
====
You can list all parameters that the module supports by using the [option]`-p` option. However, because useful value type information is omitted from [command]#modinfo -p# output, it is more useful to run:
----
~]# modinfo e1000e | grep "^parm" | sort
parm: copybreak:Maximum size of packet that is copied to a new buffer on receive (uint)
parm: CrcStripping:Enable CRC Stripping, disable if your BMC needs the CRC (array of int)
parm: debug:Debug level (0=none,...,16=all) (int)
parm: InterruptThrottleRate:Interrupt Throttling Rate (array of int)
parm: IntMode:Interrupt Mode (array of int)
parm: KumeranLockLoss:Enable Kumeran lock loss workaround (array of int)
parm: RxAbsIntDelay:Receive Absolute Interrupt Delay (array of int)
parm: RxIntDelay:Receive Interrupt Delay (array of int)
parm: SmartPowerDownEnable:Enable PHY smart power down (array of int)
parm: TxAbsIntDelay:Transmit Absolute Interrupt Delay (array of int)
parm: TxIntDelay:Transmit Interrupt Delay (array of int)
parm: WriteProtectNVM:Write-protect NVM [WARNING: disabling this can lead to corrupted NVM] (array of int)
----
====
[[sec-Loading_a_Module]]
==== Loading a Module
indexterm:[kernel module,loading,for the current session]indexterm:[kernel module,utilities,modprobe]indexterm:[modprobe,kernel module]
To load a kernel module, run [command]#modprobe _module_name_pass:attributes[{blank}]# as `root`. For example, to load the `wacom` module, run:
----
~]# modprobe wacom
----
indexterm:[kernel module,directories,/lib/modules/kernel_version/kernel/drivers/]
By default, [command]#modprobe# attempts to load the module from `/lib/modules/pass:attributes[{blank}]_kernel_version_pass:attributes[{blank}]/kernel/drivers/`. In this directory, each type of module has its own subdirectory, such as `net/` and `scsi/`, for network and SCSI interface drivers respectively.
Some modules have dependencies, which are other kernel modules that must be loaded before the module in question can be loaded. The [command]#modprobe# command always takes dependencies into account when performing operations. When you ask [command]#modprobe# to load a specific kernel module, it first examines the dependencies of that module, if there are any, and loads them if they are not already loaded into the kernel. [command]#modprobe# resolves dependencies recursively: it will load all dependencies of dependencies, and so on, if necessary, thus ensuring that all dependencies are always met.
You can use the [option]`-v` (or [option]`--verbose`) option to cause [command]#modprobe# to display detailed information about what it is doing, which can include loading module dependencies.
[[ex-modprobe_-v_shows_module_dependencies_as_they_are_loaded]]
.modprobe -v shows module dependencies as they are loaded
====
You can load the `Fibre Channel over Ethernet` module verbosely by typing the following at a shell prompt:
----
~]# modprobe -v fcoe
insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/scsi_transport_fc.ko.xz
insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/libfc/libfc.ko.xz
insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/fcoe/libfcoe.ko.xz
insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/fcoe/fcoe.ko.xz
----
In this example, you can see that [command]#modprobe# loaded the `scsi_tgt`, `scsi_transport_fc`, `libfc` and `libfcoe` modules as dependencies before finally loading `fcoe`. Also note that [command]#modprobe# used the more primitive [command]#insmod# command to insert the modules into the running kernel.
====
indexterm:[kernel module,utilities,insmod]indexterm:[insmod,kernel module]
[[important-Always_use_modprobe_instead_of_insmod]]
.Always use modprobe instead of insmod!
[IMPORTANT]
====
Although the [command]#insmod# command can also be used to load kernel modules, it does not resolve dependencies. Because of this, you should *always* load modules using [command]#modprobe# instead.
====
[[sec-Unloading_a_Module]]
==== Unloading a Module
indexterm:[kernel module,unloading]indexterm:[kernel module,utilities,modprobe]indexterm:[modprobe,kernel module]
You can unload a kernel module by running [command]#modprobe -r _module_name_pass:attributes[{blank}]# as `root`. For example, assuming that the `wacom` module is already loaded into the kernel, you can unload it by running:
----
~]# modprobe -r wacom
----
However, this command will fail if a process is using:
* the `wacom` module;
* a module that `wacom` directly depends on, or;
* any module that `wacom`, through the dependency tree, depends on indirectly.
See <<sec-Listing_Currently-Loaded_Modules>> for more information about using [command]#lsmod# to obtain the names of the modules which are preventing you from unloading a certain module.
[[ex-unloading_a_kernel_module]]
.Unloading a kernel module
====
For example, if you want to unload the `firewire_ohci` module, your terminal session might look similar to this:
----
~]# modinfo -F depends firewire_ohci
firewire-core
~]# modinfo -F depends firewire_core
crc-itu-t
~]# modinfo -F depends crc-itu-t
----
You have figured out the dependency tree (which does not branch in this example) for the loaded Firewire modules: `firewire_ohci` depends on `firewire_core`, which itself depends on `crc-itu-t`.
You can unload `firewire_ohci` using the [command]#modprobe -v -r _module_name_pass:attributes[{blank}]# command, where [option]`-r` is short for [option]`--remove` and [option]`-v` for [option]`--verbose`:
----
~]# modprobe -r -v firewire_ohci
rmmod firewire_ohci
rmmod firewire_core
rmmod crc_itu_t
----
The output shows that modules are unloaded in the reverse order that they are loaded, given that no processes depend on any of the modules being unloaded.
====
indexterm:[kernel module,utilities,rmmod]indexterm:[rmmod,kernel module]
[[important-Do_not_use_rmmod_directly]]
.Do not use rmmod directly!
[IMPORTANT]
====
Although the [command]#rmmod# command can be used to unload kernel modules, it is recommended to use [command]#modprobe -r# instead.
====
[[sec-Setting_Module_Parameters]]
==== Setting Module Parameters
indexterm:[module parameters,kernel module]indexterm:[kernel module,module parameters,supplying]
Like the kernel itself, modules can also take parameters that change their behavior. Most of the time, the default ones work well, but occasionally it is necessary or desirable to set custom parameters for a module. Because parameters cannot be dynamically set for a module that is already loaded into a running kernel, there are two different methods for setting them.
. You can unload all dependencies of the module you want to set parameters for, unload the module using [command]#modprobe -r#, and then load it with [command]#modprobe# along with a list of customized parameters. This method is often used when the module does not have many dependencies, or to test different combinations of parameters without making them persistent, and is the method covered in this section.
. Alternatively, you can list the new parameters in an existing or newly created file in the `/etc/modprobe.d/` directory. This method makes the module parameters persistent by ensuring that they are set each time the module is loaded, such as after every reboot or [command]#modprobe# command. This method is covered in <<sec-Persistent_Module_Loading>>, though the following information is a prerequisite.
[[ex-Supplying_optional_parameters_when_loading_a_kernel_module]]
.Supplying optional parameters when loading a kernel module
====
You can use [command]#modprobe# to load a kernel module with custom parameters using the following command line format:
[subs="attributes"]
----
~]#{nbsp}modprobe{nbsp}module_name{nbsp}parameter=value
----
====
When loading a module with custom parameters on the command line, be aware of the following:
* You can enter multiple parameters and values by separating them with spaces.
* Some module parameters expect a list of comma-separated values as their argument. When entering the list of values, do *not* insert a space after each comma, or [command]#modprobe# will incorrectly interpret the values following spaces as additional parameters.
* The [command]#modprobe# command silently succeeds with an exit status of 0 if:
+
** it successfully loads the module, *or*
+
** the module is *already* loaded into the kernel.
+
Thus, you must ensure that the module is not already loaded before attempting to load it with custom parameters. The [command]#modprobe# command does not automatically reload the module, or alert you that it is already loaded.
Here are the recommended steps for setting custom parameters and then loading a kernel module. This procedure illustrates the steps using the `e1000e` module, which is the network driver for Intel PRO/1000 network adapters, as an example:
[[proc-Loading_a_Kernel_Module_with_Custom_Parameters]]
.Loading a Kernel Module with Custom Parameters
. First, ensure the module is not already loaded into the kernel:
+
[subs="attributes"]
----
~]#{nbsp}lsmod |grep e1000e
~]#{nbsp}
----
+
Output would indicate that the module is already loaded into the kernel, in which case you must first unload it before proceeding. See <<sec-Unloading_a_Module>> for instructions on safely unloading it.
. Load the module and list all custom parameters after the module name. For example, if you wanted to load the Intel PRO/1000 network driver with the interrupt throttle rate set to 3000 interrupts per second for the first, second, and third instances of the driver, and turn on debug, you would run, as `root`:
+
[subs="attributes"]
----
~]#{nbsp}modprobe e1000e InterruptThrottleRate=3000,3000,3000 debug=1
----
+
This example illustrates passing multiple values to a single parameter by separating them with commas and omitting any spaces between them.
[[sec-Persistent_Module_Loading]]
==== Persistent Module Loading
indexterm:[kernel module,loading,at the boot time]indexterm:[kernel module,directories,/etc/modules-load.d/]
As shown in <<ex-Listing_information_about_a_kernel_module_with_lsmod>>, many kernel modules are loaded automatically at boot time. You can specify additional modules to be loaded by the `systemd-modules-load.service` daemon by creating a `pass:attributes[{blank}]_program_.conf` file in the `/etc/modules-load.d/` directory, where _program_ is any descriptive name of your choice. The files in `/etc/modules-load.d/` are text files that list the modules to be loaded, one per line.
[[ex-A_Text_File_to_Load_a_Module]]
.A Text File to Load a Module
====
To create a file to load the `virtio-net.ko` module, create a file `/etc/modules-load.d/virtio-net.conf` with the following content:
----
# Load virtio-net.ko at boot
virtio-net
----
====
See the `modules-load.d(5)` and `systemd-modules-load.service(8)` man pages for more information.
[[sect-signing-kernel-modules-for-secure-boot]]
==== Signing Kernel Modules for Secure Boot
Fedora includes support for the UEFI Secure Boot feature, which means that Fedora can be installed and run on systems where UEFI Secure Boot is enabled. footnote:[Fedora does not require the use of Secure Boot on UEFI systems.] When Secure Boot is enabled, the EFI operating system boot loaders, the Fedora kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The Fedora distribution includes signed boot loaders, signed kernels, and signed kernel modules. In addition, the signed first-stage boot loader and the signed kernel include embedded Fedora public keys. These signed executable binaries and embedded keys enable Fedora to install, boot, and run with the Microsoft UEFI Secure Boot CA keys that are provided by the UEFI firmware on systems that support UEFI Secure Boot.footnote:[Not all UEFI-based systems include support for Secure Boot.]
The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with Fedora on UEFI-based systems where Secure Boot is enabled. These sections also provide an overview of available options for getting your public key onto the target system where you want to deploy your kernel module.
[[sect-prerequisites]]
===== Prerequisites
In order to enable signing of externally built modules, the tools listed in the following table are required to be installed on the system.
[[table-required-tools]]
.Required Tools
[options="header"]
|===
|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|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
|===
[NOTE]
====
Note that the build system, where you build and sign your kernel module, does not need to have UEFI Secure Boot enabled and does not even need to be a UEFI-based system.
====
[[sect-kernel-module-authentication]]
===== Kernel Module Authentication
In Fedora, when a kernel module is loaded, the module's signature is checked using the public X.509 keys on the kernel's system key ring, excluding those keys that are on the kernel's system black list key ring.
[[sect-sources-for-public-keys-used-to-authenticate-kernel-modules]]
====== Sources For Public Keys Used To Authenticate Kernel Modules
During boot, the kernel loads X.509 keys into the system key ring or the system black list key ring from a set of persistent key stores as shown in <<table-sources-for-system-key-rings>>
[[table-sources-for-system-key-rings]]
.Sources For System Key Rings
[options="header"]
|===
|Source of X.509 Keys|User Ability to Add Keys|UEFI Secure Boot State|Keys Loaded During Boot
|Embedded in kernel|No|-|`.system_keyring`
|UEFI Secure Boot "db"|Limited|Not enabled|No
|Enabled|`.system_keyring`
|UEFI Secure Boot "dbx"|Limited|Not enabled|No
|Enabled|`.system_keyring`
|Embedded in `shim.efi` boot loader|No|Not enabled|No
|Enabled|`.system_keyring`
|Machine Owner Key (MOK) list|Yes|Not enabled|No
|Enabled|`.system_keyring`
|===
Note that if the system is not UEFI-based or if UEFI Secure Boot is not enabled, then only the keys that are embedded in the kernel are loaded onto the system key ring and you have no ability to augment that set of keys without rebuilding the kernel. The system black list key ring is a list of X.509 keys which have been revoked. If your module is signed by a key on the black list then it will fail authentication even if your public key is in the system key ring.
To confirm if Secure Boot is enabled, enter a command as follows:
[subs="quotes, macros"]
----
~]$ [command]#mokutil --sb-state#
SecureBoot enabled
----
If Secure Boot is not enabled then the message `Failed to read SecureBoot` is displayed.
You can display information about the keys on the system key rings using the [command]#keyctl# utility. The following is abbreviated example output from a Fedora system where UEFI Secure Boot is not enabled.
[subs="attributes"]
----
~]#{nbsp}keyctl list %:.system_keyring
1 key in keyring:
265061799: ---lswrv 0 0 asymmetric: Fedora kernel signing key: ba8e2919f98f3f8e2e27541cde0d1f...
----
The following is abbreviated example output from a Fedora system where UEFI Secure Boot is enabled.
[subs="attributes"]
----
~]#{nbsp}keyctl list %:.system_keyring
5 keys in keyring:
...asymmetric: Microsoft Windows Production PCA 2011: a92902398e16c497...
...asymmetric: Fedora kernel signing key: ba8e2919f98f3f8e2e27541cde0d...
...asymmetric: Fedora Secure Boot CA: fde32599c2d61db1bf5807335d7b20e4...
...asymmetric: Red Hat Test Certifying CA: 08a0ef5800cb02fb587c12b4032...
...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.
[[sect-kernel-module-authentication-requirements]]
====== Kernel Module Authentication Requirements
If UEFI Secure Boot is enabled or if the [option]`module.sig_enforce` kernel parameter has been specified, then only signed kernel modules that are authenticated using a key on the system key ring can be successfully loaded.footnote:[Provided that the public key is not on the system black list key ring.] If UEFI Secure Boot is disabled and if the [option]`module.sig_enforce` kernel parameter has not been specified, then unsigned kernel modules and signed kernel modules without a public key can be successfully loaded. This is summarized in <<table-kernel-module-authentication-requirements-for-loading>>.
[[table-kernel-module-authentication-requirements-for-loading]]
.Kernel Module Authentication Requirements for Loading
[options="header"]
|===
|Module Signed|Public Key Found and Signature Valid|UEFI Secure Boot State|module.sig_enforce|Module Load|Kernel Tainted
|Unsigned|-|Not enabled|Not enabled|Succeeds|Yes
|Not enabled|Enabled|Fails|
|Enabled|-|Fails|-
|Signed|No|Not enabled|Not enabled|Succeeds|Yes
|Not enabled|Enabled|Fails|-
|Enabled|-|Fails|-
|Signed|Yes|Not enabled|Not enabled|Succeeds|No
|Not enabled|Enabled|Succeeds|No
|Enabled|-|Succeeds|No
|===
Subsequent sections will describe how to generate a public and private X.509 key pair, how to use the private key to sign a kernel module, and how to enroll the public key into a source for the system key ring.
[[sect-generating-a-public-private-x509-key-pair]]
===== Generating a Public and Private X.509 Key Pair
You need to generate a public and private X.509 key pair that will be used to sign a kernel module after it has been built. The corresponding public key will be used to authenticate the kernel module when it is loaded.
. The [command]#openssl# tool can be used to generate a key pair that satisfies the requirements for kernel module signing in Fedora. Some of the parameters for this key generation request are best specified with a configuration file; follow the example below to create your own configuration file.
+
[subs="macros, attributes"]
----
~]#{nbsp}cat &lt;&lt; EOF &gt; configuration_file.config
[ req ]
default_bits = 4096
distinguished_name = req_distinguished_name
prompt = no
string_mask = utf8only
x509_extensions = myexts
[ req_distinguished_name ]
O = pass:quotes[_Organization_]
CN = pass:quotes[_Organization signing key_]
emailAddress = pass:quotes[_E-mail address_]
[ myexts ]
basicConstraints=critical,CA:FALSE
keyUsage=digitalSignature
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid
EOF
----
. After you have created the configuration file, you can create an X.509 public and private key pair. The public key will be written to the `pass:attributes[{blank}]_public_key_.der` file and the private key will be written to the `pass:attributes[{blank}]_private_key_.priv` file.
+
[subs="attributes"]
----
~]#{nbsp}openssl req -x509 -new -nodes -utf8 -sha256 -days 36500 \
> -batch -config configuration_file.config -outform DER \
> -out public_key.der \
> -keyout private_key.priv
----
. Enroll your public key on all systems where you want to authenticate and load your kernel module.
[WARNING]
====
Take proper care to guard the contents of your private key. In the wrong hands, the key could be used to compromise any system which has your public key.
====
[[sect-enrolling-public-key-on-target-system]]
===== Enrolling Public Key on Target System
When Fedora boots on a UEFI-based system with Secure Boot enabled, all keys that are in the Secure Boot db key database, but not in the dbx database of revoked keys, are loaded onto the system keyring by the kernel. The system keyring is used to authenticate kernel modules.
[[sect-factory-firmware-image-including-public-key]]
====== Factory Firmware Image Including Public Key
To facilitate authentication of your kernel module on your systems, consider requesting your system vendor to incorporate your public key into the UEFI Secure Boot key database in their factory firmware image.
[[sect-executable-key-enrollment-image-adding-public-key]]
====== Executable Key Enrollment Image Adding Public Key
It is possible to add a key to an existing populated and active Secure Boot key database. This can be done by writing and providing an EFI executable *enrollment* image. Such an enrollment image contains a properly formed request to append a key to the Secure Boot key database. This request must include data that is properly signed by the private key that corresponds to a public key that is already in the system's Secure Boot Key Exchange Key (KEK) database. Additionally, this EFI image must be signed by a private key that corresponds to a public key that is already in the key database.
It is also possible to write an enrollment image that runs under Fedora. However, the Fedora image must be properly signed by a private key that corresponds to a public key that is already in the KEK database.
The construction of either type of key enrollment images requires assistance from the platform vendor.
[[sect-system-administrator-manually-adding-public-key-to-the-mok-list]]
====== System Administrator Manually Adding Public Key to the MOK List
The Machine Owner Key (MOK) facility is a feature that is supported by Fedora and can be used to augment the UEFI Secure Boot key database. When Fedora boots on a UEFI-enabled system with Secure Boot enabled, the keys on the MOK list are also added to the system keyring in addition to the keys from the key database. The MOK list keys are also stored persistently and securely in the same fashion as the Secure Boot key database keys, but these are two separate facilities. The MOK facility is supported by shim.efi, MokManager.efi, grubx64.efi, and the Fedora [command]#mokutil# utility.
The major capability provided by the MOK facility is the ability to add public keys to the MOK list without needing to have the key chain back to another key that is already in the KEK database. However, enrolling a MOK key requires manual interaction by a *physically present* user at the UEFI system console on each target system. Nevertheless, the MOK facility provides an excellent method for testing newly generated key pairs and testing kernel modules signed with them.
Follow these steps to add your public key to the MOK list:
. Request addition of your public key to the MOK list using a Fedora userspace utility:
+
[subs="attributes"]
----
~]#{nbsp}mokutil --import my_signing_key_pub.der
----
+
You will be asked to enter and confirm a password for this MOK enrollment request.
. Reboot the machine.
. The pending MOK key enrollment request will be noticed by `shim.efi` and it will launch `MokManager.efi` to allow you to complete the enrollment from the UEFI console. You will need to enter the password you previously associated with this request and confirm the enrollment. Your public key is added to the MOK list, which is persistent.
Once a key is on the MOK list, it will be automatically propagated to the system key ring on this and subsequent boots when UEFI Secure Boot is enabled.
[[sect-signing-kernel-module-with-the-private-key]]
===== Signing Kernel Module with the Private Key
There are no extra steps required to prepare your kernel module for signing. You build your kernel module normally. Assuming an appropriate Makefile and corresponding sources, follow these steps to build your module and sign it:
. Build your `my_module.ko` module the standard way:
+
[subs="attributes"]
----
~]#{nbsp}make -C /usr/src/kernels/$(uname -r) M=$PWD modules
----
. 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}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 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 <<sec-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.
Your kernel module is now ready for loading. Note that your signed kernel module is also loadable on systems where UEFI Secure Boot is disabled or on a non-UEFI system. That means you do not need to provide both a signed and unsigned version of your kernel module.
[[sect-loading-signed-kernel-module]]
===== Loading Signed Kernel Module
Once your public key is enrolled and is in the system keyring, the normal kernel module loading mechanisms will work transparently. In the following example, you will use [command]#mokutil# to add your public key to the MOK list and you will manually load your kernel module with [command]#modprobe#.
. Optionally, you can verify that your kernel module will not load before you have enrolled your public key. First, verify what keys have been added to the system key ring on the current boot by running the [command]#keyctl list %:.system_keyring# as root. Since your public key has not been enrolled yet, it should not be displayed in the output of the command.
. Request enrollment of your public key.
+
[subs="attributes"]
----
~]#{nbsp}mokutil --import my_signing_key_pub.der
----
. Reboot, and complete the enrollment at the UEFI console.
+
[subs="attributes"]
----
~]#{nbsp}reboot
----
. After the system reboots, verify the keys on the system key ring again.
+
[subs="attributes"]
----
~]#{nbsp}keyctl list %:.system_keyring
----
. You should now be able to load your kernel module successfully.
+
[subs="macros, attributes"]
----
~]#{nbsp}modprobe -v my_module
insmod /lib/modules/3.17.4-302.fc21.x86_64/extra/pass:quotes[_my_module_].ko
~]#{nbsp}lsmod | grep my_module
pass:quotes[_my_module_] 12425 0
----
[[s1-kernel-modules-additional-resources]]
==== Additional Resources
For more information on kernel modules and their utilities, see the following resources.
.Manual Page Documentation
* `lsmod(8)` — The manual page for the [command]#lsmod# command.
* `modinfo(8)` — The manual page for the [command]#modinfo# command.
* `modprobe(8)` — The manual page for the [command]#modprobe# command.
* `rmmod(8)` — The manual page for the [command]#rmmod# command.
* `ethtool(8)` — The manual page for the [command]#ethtool# command.
* `mii-tool(8)` — The manual page for the [command]#mii-tool# command.
.Installable and External Documentation
* link:++http://tldp.org/HOWTO/Module-HOWTO/++[Linux Loadable Kernel Module HOWTO] — The [citetitle]_Linux Loadable Kernel Module HOWTO_ from the Linux Documentation Project contains further information on working with kernel modules.

954
en-US/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc Normal file
View file

@ -0,0 +1,954 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-Working_with_the_GRUB_2_Boot_Loader]]
=== Working with the GRUB 2 Boot Loader
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 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 <<sec-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.
.Menu Entries in grub.cfg
Among various code snippets and directives, the `grub.cfg` configuration file contains one or more `menuentry` blocks, each representing a single GRUB 2 boot menu entry. These blocks always start with the `menuentry` keyword followed by a title, list of options, and an opening curly bracket, and end with a closing curly bracket. Anything between the opening and closing bracket should be indented. For example, the following is a sample `menuentry` block for {MAJOROSVER} with Linux kernel 3.17.4-301.fc21.x86_64:
----
menuentry 'Fedora, with Linux 3.17.4-301.fc21.x86_64' --class fedora --class gnu-linux --class gnu --class os --unrestricted $menuentry_id_option 'gnulinux-3.17.4-301.fc21.x86_64-advanced-effee860-8d55-4e4a-995e-b4c88f9ac9f0' {
load_video
set gfxpayload=keep
insmod gzio
insmod part_msdos
insmod ext2
set root='hd0,msdos1'
if [ x$feature_platform_search_hint = xy ]; then
search --no-floppy --fs-uuid --set=root --hint='hd0,msdos1' f19c92f4-9ead-4207-b46a-723b7a2c51c8
else
search --no-floppy --fs-uuid --set=root f19c92f4-9ead-4207-b46a-723b7a2c51c8
fi
linux16 /vmlinuz-3.17.4-301.fc21.x86_64 root=/dev/mapper/fedora-root ro rd.lvm.lv=fedora/swap rd.lvm.lv=fedora/root rhgb quiet LANG=en_US.UTF-8
initrd16 /initramfs-3.17.4-301.fc21.x86_64.img
}
----
Each `menuentry` block that represents an installed Linux kernel contains `linux` on 64-bit IBM POWER Series, `linux16` on x86_64 BIOS-based systems, and `linuxefi` on UEFI-based systems. Then the `initrd` directives followed by the path to the kernel and the `initramfs` image respectively. If a separate `/boot` partition was created, the paths to the kernel and the `initramfs` image are relative to `/boot`. In the example above, the `initrd /initramfs-3.17.4-301.fc21.x86_64.img` line means that the `initramfs` image is actually located at `/boot/initramfs-3.17.4-301.fc21.x86_64.img` when the `root` file system is mounted, and likewise for the kernel path.
The kernel version number as given on the `linux16 /vmlinuz-kernel_version` line must match the version number of the `initramfs` image given on the `initrd /initramfs-kernel_version.img` line of each `menuentry` block. For more information on how to verify the initial RAM disk image, see <<sec-Verifying_the_Initial_RAM_Disk_Image>>.
[NOTE]
====
In `menuentry` blocks, the `initrd` directive must point to the location (relative to the `/boot/` directory if it is on a separate partition) of the `initramfs` file corresponding to the same kernel version. This directive is called `initrd` because the previous tool which created initial RAM disk images, [command]#mkinitrd#, created what were known as `initrd` files. The `grub.cfg` directive remains `initrd` to maintain compatibility with other tools. The file-naming convention of systems using the [command]#dracut# utility to create the initial RAM disk image is `initramfs-_kernel_version_.img`.
For information on using [application]*Dracut*, see <<sec-Verifying_the_Initial_RAM_Disk_Image>>.
====
[[sec-Configuring_the_GRUB_2_Boot_Loader]]
==== Configuring the GRUB 2 Boot Loader
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 <<sec-Making_Temporary_Changes_to_a_GRUB_2_Menu>>.
* To make persistent changes to a running system, see <<sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool>>.
* For information on making and customizing a GRUB 2 configuration file, see <<sec-Customizing_the_GRUB_2_Configuration_File>>.
[[sec-Making_Temporary_Changes_to_a_GRUB_2_Menu]]
==== Making Temporary Changes to a GRUB 2 Menu
[[proc-Making_Temporary_Changes_to_Kernel_Menu_Entry]]
.Making Temporary Changes to a Kernel Menu Entry
To change kernel parameters only during a single boot process, proceed as follows:
. Start the system and, on the GRUB 2 boot screen, move the cursor to the menu entry you want to edit, and press the kbd:[e] key for edit.
. Move the cursor down to find the kernel command line. The kernel command line starts with `linux` on 64-Bit IBM Power Series, `linux16` on x86-64 BIOS-based systems, or `linuxefi` on UEFI systems.
. Move the cursor to the end of the line.
Press kbd:[Ctrl + a] and kbd:[Ctrl + e] to jump to the start and end of the line, respectively. On some systems, kbd:[Home] and kbd:[End] might also work.
. Edit the kernel parameters as required. For example, to run the system in emergency mode, add the *emergency* parameter at the end of the `linux16` line:
[subs="macros"]
----
linux16 /vmlinuz-4.2.0-1.fc23.x86_64 root=/dev/mapper/fedora-root ro rd.md=0 rd.dm=0 rd.lvm.lv=fedora/swap crashkernel=auto rd.luks=0 vconsole.keymap=us rd.lvm.lv=fedora/root rhgb quiet pass:quotes[*emergency*]
----
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 <<bh-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
The [command]#grubby# tool can be used to read information from, and make persistent changes to, the `grub.cfg` file. It enables, for example, changing GRUB menu entries to specify what arguments to pass to a kernel on system start and changing the default kernel.
In Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}7, if [command]#grubby# is invoked manually without specifying a GRUB configuration file, it defaults to searching for `/etc/grub2.cfg`, which is a symbolic link to the `grub.cfg` file, whose location is architecture dependent. If that file cannot be found it will search for an architecture dependent default.
.Listing the Default Kernel
To find out the file name of the default kernel, enter a command as follows:
----
~]# grubby --default-kernel
/boot/vmlinuz-4.2.0-1.fc23.x86_64
----
To find out the index number of the default kernel, enter a command as follows:
----
~]# grubby --default-index
0
----
.Changing the Default Boot Entry
To make a persistent change in the kernel designated as the default kernel, use the [command]#grubby# command as follows:
----
~]# grubby --set-default /boot/vmlinuz-4.2.0-1.fc23.x86_64
----
.Viewing the GRUB Menu Entry for a Kernel
To list all the kernel menu entries, enter a command as follows:
[subs="quotes, macros"]
----
~]$ [command]#grubby --info=ALL#
----
On UEFI systems, all [command]#grubby# commands must be entered as `root`.
To view the GRUB menu entry for a specific kernel, enter a command as follows:
----
~]$ grubby --info /boot/vmlinuz-4.2.0-1.fc23.x86_64
index=0
kernel=/boot/vmlinuz-4.2.0-1.fc23.x86_64
args="ro rd.lvm.lv=fedora/root rd.lvm.lv=fedora/swap rhgb quiet LANG=en_US.UTF-8"
root=/dev/mapper/fedora-root
initrd=/boot/initramfs-4.2.0-1.fc23.x86_64.img
title=Fedora (4.2.0-1.fc23.x86_64) 23 (Workstation Edition)
----
Try tab completion to see the available kernels within the `/boot/` directory.
[[bh-Adding_and_Removing_Arguments_from_a_GRUB_Menu_Entry]]
.Adding and Removing Arguments from a GRUB Menu Entry
The [option]`--update-kernel` option can be used to update a menu entry when used in combination with [option]`--args` to add new arguments and [option]`--remove-arguments` to remove existing arguments. These options accept a quoted space-separated list. The command to simultaneously add and remove arguments a from GRUB menu entry has the follow format:
[subs="quotes, macros"]
----
grubby --remove-args="pass:attributes[{blank}]_argX argY_pass:attributes[{blank}]" --args="pass:attributes[{blank}]_argA argB_pass:attributes[{blank}]" --update-kernel /boot/pass:attributes[{blank}]_kernel_
----
To add and remove arguments from a kernel's GRUB menu entry, use a command as follows:
----
~]# grubby --remove-args="rhgb quiet" --args=console=ttyS0,115200 --update-kernel /boot/vmlinuz-4.2.0-1.fc23.x86_64
----
This command removes the Red Hat graphical boot argument, enables boot message to be seen, and adds a serial console. As the console arguments will be added at the end of the line, the new console will take precedence over any other consoles configured.
To review the changes, use the [option]`--info` command option as follows:
[subs="macros"]
----
~]# grubby --info /boot/vmlinuz-4.2.0-1.fc23.x86_64
index=0
kernel=/boot/vmlinuz-4.2.0-1.fc23.x86_64
args="ro rd.lvm.lv=fedora/root rd.lvm.lv=fedora/swap LANG=en_US.UTF-8 pass:quotes[*console=ttyS0,115200*]"
root=/dev/mapper/fedora-root
initrd=/boot/initramfs-4.2.0-1.fc23.x86_64.img
title=Fedora (4.2.0-1.fc23.x86_64) 23 (Workstation Edition)
----
.Updating All Kernel Menus with the Same Arguments
To add the same kernel boot arguments to all the kernel menu entries, enter a command as follows:
----
~]# grubby --update-kernel=ALL --args=console=ttyS0,115200
----
The [option]`--update-kernel` parameter also accepts DEFAULT or a comma separated list of kernel index numbers.
.Changing a Kernel Argument
To change a value in an existing kernel argument, specify the argument again, changing the value as required. For example, if the virtual console font size has been set to `latarcyrheb-sun16` and you want to change the virtual console font size to `32`, use a command as follows:
[subs="macros"]
----
~]# grubby --args=vconsole.font=latarcyrheb-sun32 --update-kernel /boot/vmlinuz-4.2.0-1.fc23.x86_64
index=0
kernel=/boot/vmlinuz-4.2.0-1.fc23.x86_64
args="ro rd.lvm.lv=fedora/root crashkernel=auto rd.lvm.lv=fedora/swap vconsole.font=pass:quotes[*latarcyrheb-sun32*] vconsole.keymap=us LANG=en_US.UTF-8"
root=/dev/mapper/fedora-root
initrd=/boot/initramfs-4.2.0-1.fc23.x86_64.img
title=Fedora (4.2.0-1.fc23.x86_64) 23 (Workstation Edition)
----
See the `grubby(8)` manual page for more command options.
[[sec-Customizing_the_GRUB_2_Configuration_File]]
==== Customizing the GRUB 2 Configuration File
GRUB 2 scripts search the user's computer and build a boot menu based on what operating systems the scripts find. To reflect the latest system boot options, the boot menu is rebuilt automatically when the kernel is updated or a new kernel is added.
However, users may want to build a menu containing specific entries or to have the entries in a specific order. GRUB 2 allows basic customization of the boot menu to give users control of what actually appears on the screen.
GRUB 2 uses a series of scripts to build the menu; these are located in the `/etc/grub.d/` directory. The following files are included:
* `00_header`, which loads GRUB 2 settings from the `/etc/default/grub` file.
* `01_users`, which is created only when a boot loader password is assigned in a [application]*kickstart* file.
* `10_linux`, which locates kernels in the default partition of Fedora.
* `30_os-prober`, which builds entries for operating systems found on other partitions.
* `40_custom`, a template, which can be used to create additional menu entries.
Scripts from the `/etc/grub.d/` directory are read in alphabetical order and can be therefore renamed to change the boot order of specific menu entries.
[IMPORTANT]
====
With the [option]`GRUB_TIMEOUT` key set to `0` in the `/etc/default/grub` file, GRUB 2 does not display the list of bootable kernels when the system starts up. In order to display this list when booting, press and hold any alphanumeric key when the BIOS information is displayed; GRUB 2 will present you with the GRUB menu.
====
[[sec-Changing_the_Default_Boot_Entry]]
===== Changing the Default Boot Entry
By default, the key for the `GRUB_DEFAULT` directive in the `/etc/default/grub` file is the word `saved`. This instructs GRUB 2 to load the kernel specified by the [option]`saved_entry` directive in the GRUB 2 environment file, located at `/boot/grub2/grubenv`. You can set another GRUB record to be the default, using the [command]#grub2-set-default# command, which will update the GRUB 2 environment file.
By default, the [option]`saved_entry` value is set to the name of latest installed kernel of package type [package]*kernel*. This is defined in `/etc/sysconfig/kernel` by the `UPDATEDEFAULT` and `DEFAULTKERNEL` directives. The file can be viewed by the `root` user as follows:
[subs="attributes"]
----
~]#{nbsp}cat /etc/sysconfig/kernel
# UPDATEDEFAULT specifies if new-kernel-pkg should make
# new kernels the default
UPDATEDEFAULT=yes
# DEFAULTKERNEL specifies the default kernel package type
DEFAULTKERNEL=kernel-core
----
The `DEFAULTKERNEL` directive specifies what package type will be used as the default. Installing a package of type [package]*kernel-debug* will not change the default kernel while the `DEFAULTKERNEL` is set to package type [package]*kernel*.
GRUB 2 supports using a numeric value as the key for the [option]`saved_entry` directive to change the default order in which the operating systems are loaded. To specify which operating system should be loaded first, pass its number to the [command]#grub2-set-default# command. For example:
[subs="macros, attributes"]
----
~]#{nbsp}grub2-set-default pass:quotes[`2`]
----
Note that the position of a menu entry in the list is denoted by a number starting with zero; therefore, in the example above, the third entry will be loaded. This value will be overwritten by the name of the next kernel to be installed.
To force a system to always use a particular menu entry, use the menu entry name as the key to the `GRUB_DEFAULT` directive in the `/etc/default/grub` file. To list the available menu entries, run the following command as `root`:
[subs="attributes"]
----
~]#{nbsp}awk -F\' '$1=="menuentry " {print $2}' /etc/grub2.cfg
----
The file name `/etc/grub2.cfg` is a symlink to the `grub.cfg` file, whose location is architecture dependent. For reliability reasons, the symlink is not used in other examples in this chapter. It is better to use absolute paths when writing to a file, especially when repairing a system.
Changes to `/etc/default/grub` require rebuilding the `grub.cfg` file as follows:
* 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
If required to prepare a new GRUB 2 file with different parameters, edit the values of the `GRUB_CMDLINE_LINUX` key in the `/etc/default/grub` file. Note that you can specify multiple parameters for the `GRUB_CMDLINE_LINUX` key. For example:
----
GRUB_CMDLINE_LINUX="console=tty0 console=ttyS0,9600n8"
----
Where [option]`console=tty0` is the first virtual terminal and [option]`console=ttyS0` is the serial terminal to be used.
Changes to `/etc/default/grub` require rebuilding the `grub.cfg` file as follows:
* 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
When executing the [command]#grub2-mkconfig# command, GRUB 2 searches for Linux kernels and other operating systems based on the files located in the `/etc/grub.d/` directory. The `/etc/grub.d/10_linux` script searches for installed Linux kernels on the same partition. The `/etc/grub.d/30_os-prober` script searches for other operating systems. Menu entries are also automatically added to the boot menu when updating the kernel.
The `40_custom` file located in the `/etc/grub.d/` directory is a template for custom entries and looks as follows:
----
#!/bin/sh
exec tail -n +3 $0
# This file provides an easy way to add custom menu entries. Simply type the
# menu entries you want to add after this comment. Be careful not to change
# the 'exec tail' line above.
----
This file can be edited or copied. Note that as a minimum, a valid menu entry must include at least the following:
[subs="quotes, macros"]
----
*menuentry* "&lt;Title&gt;"pass:attributes[{blank}]*{*
&lt;Data&gt;
*}*
----
[[sec-Using_only_a_Custom_Menu]]
===== Creating a Custom Menu
If you do not want menu entries to be updated automatically, you can create a custom menu.
[IMPORTANT]
====
Before proceeding, back up the contents of the `/etc/grub.d/` directory in case you need to revert the changes later.
====
[NOTE]
====
Note that modifying the `/etc/default/grub` file does not have any effect on creating custom menus.
====
. 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` 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:
----
#!/bin/sh
exec tail -n +3 $0
# This file provides an easy way to add custom menu entries. Simply type the
# menu entries you want to add after this comment. Be careful not to change
# the 'exec tail' line above.
menuentry 'First custom entry' --class red --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-4.2.0-1.fc23.x86_64-advanced-32782dd0-4b47-4d56-a740-2076ab5e5976' {
load_video
set gfxpayload=keep
insmod gzio
insmod part_msdos
insmod xfs
set root='hd0,msdos1'
if [ x$feature_platform_search_hint = xy ]; then
search --no-floppy --fs-uuid --set=root --hint='hd0,msdos1' 7885bba1-8aa7-4e5d-a7ad-821f4f52170a
else
search --no-floppy --fs-uuid --set=root 7885bba1-8aa7-4e5d-a7ad-821f4f52170a
fi
linux16 /vmlinuz-4.2.0-1.fc23.x86_64 root=/dev/mapper/fedora-root ro rd.lvm.lv=fedora/root vconsole.font=latarcyrheb-sun16 rd.lvm.lv=fedora/swap vconsole.keymap=us crashkernel=auto rhgb quiet LANG=en_US.UTF-8
initrd16 /initramfs-4.2.0-1.fc23.x86_64.img
}
menuentry 'Second custom entry' --class red --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-0-rescue-07f43f20a54c4ce8ada8b70d33fd001c-advanced-32782dd0-4b47-4d56-a740-2076ab5e5976' {
load_video
insmod gzio
insmod part_msdos
insmod xfs
set root='hd0,msdos1'
if [ x$feature_platform_search_hint = xy ]; then
search --no-floppy --fs-uuid --set=root --hint='hd0,msdos1' 7885bba1-8aa7-4e5d-a7ad-821f4f52170a
else
search --no-floppy --fs-uuid --set=root 7885bba1-8aa7-4e5d-a7ad-821f4f52170a
fi
linux16 /vmlinuz-0-rescue-07f43f20a54c4ce8ada8b70d33fd001c root=/dev/mapper/fedora-root ro rd.lvm.lv=fedora/root vconsole.font=latarcyrheb-sun16 rd.lvm.lv=fedora/swap vconsole.keymap=us crashkernel=auto rhgb quiet
initrd16 /initramfs-0-rescue-07f43f20a54c4ce8ada8b70d33fd001c.img
}
----
. Remove all files from the `/etc/grub.d` directory except the following:
** `00_header`,
** `40_custom`,
** `01_users` (if it exists),
** and `README`.
Alternatively, if you want to keep the files in the `/etc/grub2.d/` directory, make them unexecutable by running the [command]#chmod a-x <file_name># command.
. Edit, add, or remove menu entries in the `40_custom` file as desired.
. Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows:
** 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 <<sec-Setting_Up_Users_and_Password_Protection_Specifying_Menu_Entries>>. To use encrypted passwords, see <<sec-Password_Encryption>>.
[WARNING]
====
If you do not use the correct format for the menu, or modify the configuration in an incorrect way, you might be unable to boot your system.
====
All menu entries can be password-protected against changes by setting superusers, which can be done in the `/etc/grub.d/00_header` or the `/etc/grub.d/01_users` file. The `00_header` file is very complicated and, if possible, avoid making modifications in this file. Menu entries should be placed in the `/etc/grub.d/40_custom` and users in the `/etc/grub.d/01_users` file. The `01_users` file is generated by the installation application [application]*anaconda* when a grub boot loader password is used in a [application]*kickstart* template (but it should be created and used it if it does not exist). Examples in this section adopt this policy.
[[sec-Setting_Up_Users_and_Password_Protection_Specifying_Menu_Entries]]
===== Setting Up Users and Password Protection, Specifying Menu Entries
. To specify a superuser, add the following lines in the `/etc/grub.d/01_users` file, where `john` is the name of the user designated as the superuser, and `johnspassword` is the superuser's password:
[subs="quotes"]
----
cat &lt;&lt;EOF
set superusers="john"
password john johnspassword
EOF
----
. To allow other users to access the menu entries, add additional lines per user at the end of the `/etc/grub.d/01_users` file.
[subs="quotes"]
----
cat &lt;&lt;EOF
set superusers="john"
password john johnspassword
password jane janespassword
EOF
----
. When the users and passwords are set up, specify the menu entries that should be password-protected in the `/etc/grub.d/40_custom` file in a similar fashion to the following:
[subs="quotes, attributes"]
----
menuentry 'Red{nbsp}Hat Enterprise{nbsp}Linux Server' --unrestricted {
set root=(hd0,msdos1)
linux /vmlinuz
}
menuentry 'Fedora' --users jane {
set root=(hd0,msdos2)
linux /vmlinuz
}
menuentry 'Red{nbsp}Hat Enterprise{nbsp}Linux Workstation' {
set root=(hd0,msdos3)
linux /vmlinuz
}
----
In the above example:
* `john` is the `superuser` and can therefore boot any menu entry, use the GRUB 2 command line, and edit items of the GRUB 2 menu during boot. In this case, `john` can access both Red{nbsp}Hat Enterprise{nbsp}Linux Server, Fedora, and Red{nbsp}Hat Enterprise{nbsp}Linux Workstation. Note that only `john` can access Red{nbsp}Hat Enterprise{nbsp}Linux Workstation because neither the [option]`--users` nor [option]`--unrestricted` options have been used.
* User `jane` can boot Fedora since she was granted the permission in the configuration.
* Anyone can boot Red{nbsp}Hat Enterprise{nbsp}Linux Server, because of the [option]`--unrestricted` option, but only `john` can edit the menu entry as a superuser has been defined. When a superuser is defined then all records are protected against unauthorized changes and all records are protected for booting if they do *not* have the [option]`--unrestricted` parameter
If you do not specify a user for a menu entry, or make use of the [option]`--unrestricted` option, then only the superuser will have access to the system.
After you have made changes in the template file the GRUB 2 configuration file must be updated.
Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows:
* 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
By default, passwords are saved in plain text in GRUB 2 scripts. Although the files cannot be accessed on boot without the correct password, security can be improved by encrypting the password using the [command]#grub2-mkpasswd-pbkdf2# command. This command converts a desired password into a long hash, which is placed in the GRUB 2 scripts instead of the plain-text password.
. To generate an encrypted password, run the [command]#grub2-mkpasswd-pbkdf2# command on the command line as `root`.
. Enter the desired password when prompted and repeat it. The command then outputs your password in an encrypted form.
. Copy the hash, and paste it in the template file where you configured the users, that is, either in `/etc/grub.d/01_users` or `/etc/grub.d/40_custom`.
The following format applies for the `01_users` file:
----
cat <<EOF
set superusers="john"
password_pbkdf2 john grub.pbkdf2.sha512.10000.19074739ED80F115963D984BDCB35AA671C24325755377C3E9B014D862DA6ACC77BC110EED41822800A87FD3700C037320E51E9326188D53247EC0722DDF15FC.C56EC0738911AD86CEA55546139FEBC366A393DF9785A8F44D3E51BF09DB980BAFEF85281CBBC56778D8B19DC94833EA8342F7D73E3A1AA30B205091F1015A85
EOF
----
The following format applies for the `40_custom` file:
----
set superusers="john"
password_pbkdf2 john grub.pbkdf2.sha512.10000.19074739ED80F115963D984BDCB35AA671C24325755377C3E9B014D862DA6ACC77BC110EED41822800A87FD3700C037320E51E9326188D53247EC0722DDF15FC.C56EC0738911AD86CEA55546139FEBC366A393DF9785A8F44D3E51BF09DB980BAFEF85281CBBC56778D8B19DC94833EA8342F7D73E3A1AA30B205091F1015A85
----
[[sec-Reinstalling_GRUB_2]]
==== Reinstalling GRUB 2
Reinstalling GRUB 2 is a convenient way to fix certain problems usually caused by an incorrect installation of GRUB 2, missing files, or a broken system. Other reasons to reinstall GRUB 2 include the following:
* Upgrading from the previous version of GRUB.
* The user requires the GRUB 2 boot loader to control installed operating systems. However, some operating systems are installed with their own boot loaders. Reinstalling GRUB 2 returns control to the desired operating system.
* Adding the boot information to another drive.
[[sec-grub2-reinstall_on_BIOS-Based_Machines]]
===== Reinstalling GRUB 2 on BIOS-Based Machines
When using the [command]#grub2-install# command, the boot information is updated and missing files are restored. Note that the files are restored only if they are not corrupted.
Use the [command]#grub2-install _device_pass:attributes[{blank}]# command to reinstall GRUB 2 if the system is operating normally. For example, if `sda` is your _device_:
[subs="macros, attributes"]
----
~]#{nbsp}grub2-install pass:quotes[`/dev/sda`]
----
[[sec-grub2-reinstall_on_UEFI-Based_Machines]]
===== Reinstalling GRUB 2 on UEFI-Based Machines
When using the [command]#dnf reinstall grub2-efi shim# command, the boot information is updated and missing files are restored. Note that the files are restored only if they are not corrupted.
Use the [command]#dnf reinstall grub2-efi shim# command to reinstall GRUB 2 if the system is operating normally. For example:
[subs="attributes"]
----
~]#{nbsp}dnf reinstall grub2-efi shim
----
[[sec-Resetting_and_Reinstalling_GRUB_2]]
===== Resetting and Reinstalling GRUB 2
This method completely removes all GRUB 2 configuration files and system settings. Apply this method to reset all configuration settings to their default values. Removing of the configuration files and subsequent reinstalling of GRUB 2 fixes failures caused by corrupted files and incorrect configuration. To do so, as `root`, follow these steps:
. Run the [command]#rm /etc/grub.d/*# command;
. Run the [command]#rm /etc/sysconfig/grub# command;
. For EFI systems *only*, run the following command:
[subs="attributes"]
----
~]#{nbsp}dnf reinstall grub2-efi shim grub2-tools
----
. Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows:
** 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
----
. Now follow the procedure in <<sec-Reinstalling_GRUB_2>> to restore GRUB2 on the `/boot/` partition.
[[sec-GRUB_2_over_a_Serial_Console]]
==== GRUB 2 over a Serial Console
If you use computers with no display or keyboard, it can be very useful to control the machines through serial communications.
[[sec-Configuring_the_GRUB_2_Menu]]
===== Configuring the GRUB 2 Menu
To set the system to use a serial terminal only during a single boot process, when the GRUB 2 boot menu appears, move the cursor to the kernel you want to start, and press the kbd:[e] key to edit the kernel parameters. Remove the `rhgb` and `quit` parameters and add console parameters at the end of the `linux16` line as follows:
[subs="macros"]
----
linux16 /vmlinuz-4.2.0-1.fc23.x86_64 root=/dev/mapper/fedora-root ro rd.md=0 rd.dm=0 rd.lvm.lv=fedora/swap crashkernel=auto rd.luks=0 vconsole.keymap=us rd.lvm.lv=fedora/root pass:quotes[*console=ttyS0,115200*]
----
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. For example, to update the entry for the default kernel, enter a command as follows:
----
~]# 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 <<bh-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:
----
GRUB_TERMINAL="serial"
GRUB_SERIAL_COMMAND="serial --speed=9600 --unit=0 --word=8 --parity=no --stop=1"
----
The first line disables the graphical terminal. Note that specifying the `GRUB_TERMINAL` key overrides values of `GRUB_TERMINAL_INPUT` and `GRUB_TERMINAL_OUTPUT`. On the second line, adjust the baud rate, parity, and other values to fit your environment and hardware. A much higher baud rate, for example `115200`, is preferable for tasks such as following log files. Once you have completed the changes in the `/etc/default/grub` file, it is necessary to update the GRUB 2 configuration file.
Rebuild the `grub.cfg` file by running the [command]#grub2-mkconfig -o# command as follows:
* 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]
====
In order to access the grub terminal over a serial connection an additional option must be added to a kernel definition to make that particular kernel monitor a serial connection. For example:
[subs="quotes, macros"]
----
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 <<bh-Installable_and_External_Documentation>>
====
[[sec-Using_screen_to_Connect_to_the_Serial_Console]]
===== Using screen to Connect to the Serial Console
The [application]*screen* tool serves as a capable serial terminal. To install it, run as `root`:
[subs="attributes"]
----
~]#{nbsp}dnf install screen
----
To connect to your machine using the serial console, use a command in the follow format:
[subs="macros"]
----
screen /dev/pass:quotes[_console_port_] pass:quotes[_baud_rate_]
----
By default, if no option is specified, [application]*screen* uses the standard 9600 baud rate. To set a higher baud rate, enter:
[subs="macros, attributes"]
----
~]${nbsp}screen pass:quotes[`/dev/console_port`] 115200
----
Where _console_port_ is `ttyS0`, or `ttyUSB0`, and so on.
To end the session in [application]*screen*, press kbd:[Ctrl]+kbd:[a], type `:quit` and press kbd:[Enter].
See the `screen(1)` manual page for additional options and detailed information.
[[sec-Terminal_Menu_Editing_During_Boot]]
==== Terminal Menu Editing During Boot
Menu entries can be modified and arguments passed to the kernel on boot. This is done using the menu entry editor interface, which is triggered when pressing the kbd:[e] key on a selected menu entry in the boot loader menu. The kbd:[Esc] key discards any changes and reloads the standard menu interface. The kbd:[c] key loads the command line interface.
The command line interface is the most basic GRUB interface, but it is also the one that grants the most control. The command line makes it possible to type any relevant GRUB commands followed by the kbd:[Enter] key to execute them. This interface features some advanced features similar to [application]*shell*, including kbd:[Tab] key completion based on context, and kbd:[Ctrl + a] to move to the beginning of a line and kbd:[Ctrl + e] to move to the end of a line. In addition, the kbd:[arrow], kbd:[Home], kbd:[End], and kbd:[Delete] keys work as they do in the bash shell.
[[sec-Booting_to_Rescue_Mode]]
===== Booting to Rescue Mode
Rescue mode provides a convenient single-user environment and allows you to repair your system in situations when it is unable to complete a normal booting process. In rescue mode, the system attempts to mount all local file systems and start some important system services, but it does not activate network interfaces or allow more users to be logged into the system at the same time. In Fedora, rescue mode is equivalent to single user mode and requires the `root` password.
. To enter rescue mode during boot, on the GRUB 2 boot screen, press the kbd:[e] key for edit.
. Add the following parameter at the end of the `linux` line on 64-Bit IBM Power Series, the `linux16` line on x86-64 BIOS-based systems, or the `linuxefi` line on UEFI systems:
[subs="quotes"]
----
systemd.unit=rescue.target
----
Press kbd:[Ctrl + a] and kbd:[Ctrl + e] to jump to the start and end of the line, respectively. On some systems, kbd:[Home] and kbd:[End] might also work.
Note that equivalent parameters, `1`, `s`, and `single`, can be passed to the kernel as well.
. Press kbd:[Ctrl + x] to boot the system with the parameter.
[[sec-Booting_to_Emergency_Mode]]
===== Booting to Emergency Mode
Emergency mode provides the most minimal environment possible and allows you to repair your system even in situations when the system is unable to enter rescue mode. In emergency mode, the system mounts the `root` file system only for reading, does not attempt to mount any other local file systems, does not activate network interfaces, and only starts few essential services. In Fedora, emergency mode requires the `root` password.
. To enter emergency mode, on the GRUB 2 boot screen, press the kbd:[e] key for edit.
. Add the following parameter at the end of the `linux` line on 64-Bit IBM Power Series, the `linux16` line on x86-64 BIOS-based systems, or the `linuxefi` line on UEFI systems:
[subs="quotes"]
----
systemd.unit=emergency.target
----
Press kbd:[Ctrl + a] and kbd:[Ctrl + e] to jump to the start and end of the line, respectively. On some systems, kbd:[Home] and kbd:[End] might also work.
Note that equivalent parameters, `emergency` and `-b`, can be passed to the kernel as well.
. Press kbd:[Ctrl + x] to boot the system with the parameter.
[[sec-Changing_and_Resetting_the_Root_Password]]
===== Changing and Resetting the Root Password
Setting up the `root` password is a mandatory part of the Fedora installation. If you forget or lose the `root` password it is possible to reset it, however users who are members of the wheel group can change the `root` password as follows:
[subs="quotes, macros"]
----
~]$ [command]#sudo passwd root#
----
Note that in GRUB 2, resetting the password is no longer performed in single-user mode as it was in GRUB included in Fedora 15 and Red{nbsp}Hat Enterprise{nbsp}Linux{nbsp}6. The `root` password is now required to operate in `single-user` mode as well as in `emergency` mode.
Two procedures for resetting the `root` password are shown here:
* <<proc-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.
* <<proc-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
. Start the system and when BIOS information is displayed, select the option for a boot menu and select to boot from the installation disk.
. Choose `Troubleshooting`.
. Choose `Rescue a Fedora-Server System`.
. Choose `Continue` which is the default option. At this point you will be promoted for a passphrase if an encrypted file system is found.
. Press kbd:[OK] to acknowledge the information displayed until the shell prompt appears.
. Change the file system `root` as follows:
[subs="attributes"]
----
sh-4.2#{nbsp}chroot /mnt/sysimage
----
. Enter the [command]#passwd# command and follow the instructions displayed on the command line to change the `root` password.
. Remove the `autorelable` file to prevent a time consuming SELinux relabel of the disk:
[subs="attributes"]
----
sh-4.2#{nbsp}rm -f /.autorelabel
----
. Enter the [command]#exit# command to exit the [command]#chroot# environment.
. Enter the [command]#exit# command again to resume the initialization and finish the system boot.
[[proc-Resetting_the_Root_Password_Using_rd.break]]
.Resetting the Root Password Using rd.break
. Start the system and, on the GRUB 2 boot screen, press the kbd:[e] key for edit.
. Remove the [option]`rhgb` and [option]`quiet` parameters from the end, or near the end, of the `linux16` line, or `linuxefi` on UEFI systems.
Press kbd:[Ctrl + a] and kbd:[Ctrl + e] to jump to the start and end of the line, respectively. On some systems, kbd:[Home] and kbd:[End] might also work.
[IMPORTANT]
====
The [option]`rhgb` and [option]`quiet` parameters must be removed in order to enable system messages.
====
. Add the following parameters at the end of the `linux` line on 64-Bit IBM Power Series, the `linux16` line on x86-64 BIOS-based systems, or the `linuxefi` line on UEFI systems:
[subs="quotes"]
----
rd.break enforcing=0
----
Adding the [option]`enforcing=0` option enables omitting the time consuming SELinux relabeling process.
The `initramfs` will stop before passing control to the Linux [package]*kernel*, enabling you to work with the `root` file system.
Note that the `initramfs` prompt will appear on the last console specified on the Linux line.
. Press kbd:[Ctrl + x] to boot the system with the changed parameters.
With an encrypted file system, a password is required at this point. However the password prompt might not appear as it is obscured by logging messages. You can press the kbd:[Backspace] key to see the prompt. Release the key and enter the password for the encrypted file system, while ignoring the logging messages.
The `initramfs` `switch_root` prompt appears.
. The file system is mounted read-only on `/sysroot/`. You will not be allowed to change the password if the file system is not writable.
Remount the file system as writable:
[subs="attributes"]
----
switch_root:/#{nbsp}mount -o remount,rw /sysroot
----
. The file system is remounted with write enabled.
Change the file system's `root` as follows:
[subs="attributes"]
----
switch_root:/#{nbsp}chroot /sysroot
----
The prompt changes to `sh-4.2#`.
. Enter the [command]#passwd# command and follow the instructions displayed on the command line to change the `root` password.
Note that if the system is not writable, the [application]*passwd* tool fails with the following error:
[subs="quotes"]
----
Authentication token manipulation error
----
. Updating the password file results in a file with the incorrect SELinux security context. To relabel all files on next system boot, enter the following command:
[subs="attributes"]
----
sh-4.2#{nbsp}touch /.autorelabel
----
Alternatively, to save the time it takes to relabel a large disk, you can omit this step provided you included the [option]`enforcing=0` option in step 3.
. Remount the file system as read only:
[subs="attributes"]
----
sh-4.2#{nbsp}mount -o remount,ro /
----
. Enter the [command]#exit# command to exit the [command]#chroot# environment.
. Enter the [command]#exit# command again to resume the initialization and finish the system boot.
With an encrypted file system, a pass word or phrase is required at this point. However the password prompt might not appear as it is obscured by logging messages. You can press and hold the kbd:[Backspace] key to see the prompt. Release the key and enter the password for the encrypted file system, while ignoring the logging messages.
[NOTE]
====
Note that the SELinux relabeling process can take a long time. A system reboot will occur automatically when the process is complete.
====
. If you added the [option]`enforcing=0` option in step 3 and omitted the [command]#touch /.autorelabel# command in step 8, enter the following command to restore the `/etc/shadow` file's SELinux security context:
----
~]# restorcon /etc/shadow
----
Enter the following commands to turn SELinux policy enforcement back on and verify that it is on:
----
~]# setenforce 1
~]# getenforce
Enforcing
----
[[sec-UEFI_Secure_Boot]]
==== UEFI Secure Boot
The Secure Boot technology ensures that the system firmware checks whether the system boot loader is signed with a cryptographic key authorized by a database contained in the firmware. With signature verification in the next-stage boot loader, kernel, and, potentially, user space, it is possible to prevent the execution of unsigned code.
Secure Boot is the boot path validation component of the Unified Extensible Firmware Interface (UEFI) specification. The specification defines:
* a programming interface for cryptographically protected UEFI variables in non-volatile storage,
* how the trusted X.509 root certificates are stored in UEFI variables,
* validation of UEFI applications like boot loaders and drivers,
* procedures to revoke known-bad certificates and application hashes.
UEFI Secure Boot does not prevent the installation or removal of second-stage boot loaders, nor require explicit user confirmation of such changes. Signatures are verified during booting, not when the boot loader is installed or updated. Therefore, UEFI Secure Boot does not stop boot path manipulations, it simplifies the detection of changes and prevents the system from executing a modified boot path once such a modification has occurred.
[[sec-UEFI_Secure_Boot_Support_in_Fedora]]
===== UEFI Secure Boot Support in Fedora
{MAJOROS} includes support for the UEFI Secure Boot feature, which means that {MAJOROS} can be installed and run on systems where UEFI Secure Boot is enabled. On UEFI-based systems with the Secure Boot technology enabled, all drivers that are loaded must be signed with a valid certificate, otherwise the system will not accept them. All drivers provided by Red{nbsp}Hat are signed by the UEFI CA certificate.
If you want to load externally built drivers &mdash; drivers that are not provided on the {MAJOROS}{nbsp}Linux DVD &mdash; you must make sure these drivers are signed as well.
[[sec-Working_with_the_GRUB_2_Boot_Loader-Additional_Resources]]
==== Additional Resources
Please see the following resources for more information on the GRUB 2 boot loader:
[[bh-Installable_and_External_Documentation]]
.Installed Documentation
* `/usr/share/doc/grub2-tools-<version-number>` &mdash; This directory contains information about using and configuring GRUB 2. `<version-number>` corresponds to the version of the GRUB 2 package installed.
* [command]#info grub2# &mdash; The GRUB 2 info page contains a tutorial, a user reference manual, a programmer reference manual, and a FAQ document about GRUB 2 and its usage.
* `grubby(8)` — The manual page for the command-line tool for configuring GRUB and GRUB 2.
* `new-kernel-pkg(8)` — The manual page for the tool to script kernel installation.
.External Documentation
* link:++http://docs.fedoraproject.org/install-guide++[ {MAJOROS} Installation Guide] &mdash; The Installation Guide provides basic information on GRUB 2, for example, installation, terminology, interfaces, and commands.

3
en-US/kernel-module-driver-configuration/intro-kernel-module-driver-configuration.adoc Normal file
View file

@ -0,0 +1,3 @@
== Kernel, Module and Driver Configuration
This part covers various tools that assist administrators with kernel customization.

541
en-US/monitoring-and-automation/Automating_System_Tasks.adoc Normal file
View file

@ -0,0 +1,541 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-Automating_System_Tasks]]
=== Automating System Tasks
indexterm:[Automated Tasks]
Tasks, also known as _jobs_, can be configured to run automatically within a specified period of time, on a specified date, or when the system load average decreases below 0.8.
{MAJOROS} is pre-configured to run important system tasks to keep the system updated. For example, the slocate database used by the [command]#locate# command is updated daily. A system administrator can use automated tasks to perform periodic backups, monitor the system, run custom scripts, and so on.
{MAJOROS} comes with the following automated task utilities: [command]#cron#, [command]#anacron#, [command]#at#, and [command]#batch#.
Every utility is intended for scheduling a different job type: while Cron and Anacron schedule recurring jobs, At and Batch schedule one-time jobs (refer to <<s1-autotasks-cron-anacron>> and <<s1-autotasks-at-batch>> respectively).
{MAJOROS} supports the use of `systemd.timer` for executing a job at a specific time. See man `systemd.timer(5)` for more information.
[[s1-autotasks-cron-anacron]]
==== Cron and Anacron
indexterm:[anacron]indexterm:[cron]
Both Cron and Anacron are daemons that can schedule execution of recurring tasks to a certain point in time defined by the exact time, day of the month, month, day of the week, and week.
Cron jobs can run as often as every minute. However, the utility assumes that the system is running continuously and if the system is not on at the time when a job is scheduled, the job is not executed.
On the other hand, Anacron remembers the scheduled jobs if the system is not running at the time when the job is scheduled. The job is then executed as soon as the system is up. However, Anacron can only run a job once a day.
[[sect-Cron-Installing]]
===== Installing Cron and Anacron
To install Cron and Anacron, you need to install the [package]*cronie* package with Cron and the [package]*cronie-anacron* package with Anacron ([package]*cronie-anacron* is a sub-package of [package]*cronie*).
To determine if the packages are already installed on your system, issue the following command:
[subs="quotes, macros"]
----
[command]#rpm -q cronie cronie-anacron#
----
The command returns full names of the [package]*cronie* and [package]*cronie-anacron* packages if already installed, or notifies you that the packages are not available.
To install these packages, use the [command]#dnf# command in the following form as `root`:
[subs="quotes, macros"]
----
[command]#dnf install _package_pass:attributes[{blank}]#
----
For example, to install both Cron and Anacron, type the following at a shell prompt:
[subs="attributes"]
----
~]#{nbsp}dnf install cronie cronie-anacron
----
For more information on how to install new packages in {MAJOROS}, see <<sec-Installing>>.
[[sect-Cron-Running]]
===== Running the Crond Service
The cron and anacron jobs are both picked by the `crond` service. This section provides information on how to start, stop, and restart the `crond` service, and shows how to configure it to start automatically at boot time.
[[sect-Cron-service]]
====== Starting and Stopping the Cron Service
To determine if the service is running, use the following command:
[subs="quotes, macros"]
----
[command]#systemctl status crond.service#
----
To run the `crond` service in the current session, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#systemctl start crond.service#
----
To configure the service to start automatically at boot time, use the following command as `root`:
[subs="quotes, macros"]
----
[command]#systemctl enable crond.service#
----
[[sect-Crond_Stopping]]
====== Stopping the Cron Service
To stop the `crond` service in the current session, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#systemctl stop crond.service#
----
To prevent the service from starting automatically at boot time, use the following command as `root`:
[subs="quotes, macros"]
----
[command]#systemctl disable crond.service#
----
[[sect-Crond_Restarting]]
====== Restarting the Cron Service
To restart the `crond` service, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#systemctl restart crond.service#
----
This command stops the service and starts it again in quick succession.
[[s2-configuring-anacron-jobs]]
===== Configuring Anacron Jobs
indexterm:[anacron,anacron configuration file]indexterm:[anacrontab]indexterm:[anacron,user-defined tasks]indexterm:[/var/spool/anacron]
The main configuration file to schedule jobs is the `/etc/anacrontab` file, which can be only accessed by the `root` user. The file contains the following:
----
SHELL=/bin/sh
PATH=/sbin:/bin:/usr/sbin:/usr/bin
MAILTO=root
# the maximal random delay added to the base delay of the jobs
RANDOM_DELAY=45
# the jobs will be started during the following hours only
START_HOURS_RANGE=3-22
#period in days delay in minutes job-identifier command
1 5 cron.daily nice run-parts /etc/cron.daily
7 25 cron.weekly nice run-parts /etc/cron.weekly
@monthly 45 cron.monthly nice run-parts /etc/cron.monthly
----
The first three lines define the variables that configure the environment in which the anacron tasks run:
* `SHELL` &mdash; shell environment used for running jobs (in the example, the Bash shell)
* `PATH` &mdash; paths to executable programs
* `MAILTO` &mdash; username of the user who receives the output of the anacron jobs by email
+
If the `MAILTO` variable is not defined (`MAILTO=`), the email is not sent.
The next two variables modify the scheduled time for the defined jobs:
* `RANDOM_DELAY` &mdash; maximum number of minutes that will be added to the `delay in minutes` variable which is specified for each job
+
The minimum delay value is set, by default, to 6 minutes.
+
If `RANDOM_DELAY` is, for example, set to `12`, then between 6 and 12 minutes are added to the `delay in minutes` for each job in that particular anacrontab. `RANDOM_DELAY` can also be set to a value below `6`, including `0`. When set to `0`, no random delay is added. This proves to be useful when, for example, more computers that share one network connection need to download the same data every day.
* `START_HOURS_RANGE` &mdash; interval, when scheduled jobs can be run, in hours
+
In case the time interval is missed, for example due to a power failure, the scheduled jobs are not executed that day.
The remaining lines in the `/etc/anacrontab` file represent scheduled jobs and follow this format:
[subs="quotes"]
----
period in days delay in minutes job-identifier command
----
* `period in days` &mdash; frequency of job execution in days
+
The property value can be defined as an integer or a macro (`@daily`, `@weekly`, `@monthly`), where `@daily` denotes the same value as integer 1, `@weekly` the same as 7, and `@monthly` specifies that the job is run once a month regardless of the length of the month.
* `delay in minutes` &mdash; number of minutes anacron waits before executing the job
+
The property value is defined as an integer. If the value is set to `0`, no delay applies.
* `job-identifier` &mdash; unique name referring to a particular job used in the log files
* `command` &mdash; command to be executed
+
The command can be either a command such as [command]#ls /proc >> /tmp/proc# or a command which executes a custom script.
Any lines that begin with a hash sign (#) are comments and are not processed.
[[s3-anacron-examples]]
====== Examples of Anacron Jobs
The following example shows a simple `/etc/anacrontab` file:
----
SHELL=/bin/sh
PATH=/sbin:/bin:/usr/sbin:/usr/bin
MAILTO=root
# the maximal random delay added to the base delay of the jobs
RANDOM_DELAY=30
# the jobs will be started during the following hours only
START_HOURS_RANGE=16-20
#period in days delay in minutes job-identifier command
1 20 dailyjob nice run-parts /etc/cron.daily
7 25 weeklyjob /etc/weeklyjob.bash
@monthly 45 monthlyjob ls /proc >> /tmp/proc
----
All jobs defined in this `anacrontab` file are randomly delayed by 6-30 minutes and can be executed between 16:00 and 20:00.
The first defined job is triggered daily between 16:26 and 16:50 (RANDOM_DELAY is between 6 and 30 minutes; the `delay in minutes` property adds 20 minutes). The command specified for this job executes all present programs in the `/etc/cron.daily/` directory using the [command]#run-parts# script (the [command]#run-parts# scripts accepts a directory as a command-line argument and sequentially executes every program in the directory). See the `run-parts` man page for more information on the [command]#run-parts# script.
The second job executes the `weeklyjob.bash` script in the `/etc/` directory once a week.
The third job runs a command, which writes the contents of `/proc` to the `/tmp/proc` file ([command]#ls /proc >> /tmp/proc#) once a month.
[[s2-configuring-cron-jobs]]
===== Configuring Cron Jobs
indexterm:[cron,user-defined tasks]indexterm:[/var/spool/cron]indexterm:[cron,cron configuration file]indexterm:[crontab]
The configuration file for cron jobs is `/etc/crontab`, which can be only modified by the `root` user. The file contains the following:
----
SHELL=/bin/bash
PATH=/sbin:/bin:/usr/sbin:/usr/bin
MAILTO=root
HOME=/
# For details see man 4 crontabs
# Example of job definition:
# .---------------- minute (0 - 59)
# | .------------- hour (0 - 23)
# | | .---------- day of month (1 - 31)
# | | | .------- month (1 - 12) OR jan,feb,mar,apr ...
# | | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
# | | | | |
# * * * * * user-name command to be executed
----
The first three lines contain the same variable definitions as an `anacrontab` file: `SHELL`, `PATH`, and `MAILTO`. For more information about these variables, see <<s2-configuring-anacron-jobs>>.
In addition, the file can define the `HOME` variable. The `HOME` variable defines the directory, which will be used as the home directory when executing commands or scripts run by the job.
The remaining lines in the `/etc/crontab` file represent scheduled jobs and have the following format:
[subs="quotes"]
----
minute hour day month day of week username command
----
The following define the time when the job is to be run:
* `minute` &mdash; any integer from 0 to 59
* `hour` &mdash; any integer from 0 to 23
* `day` &mdash; any integer from 1 to 31 (must be a valid day if a month is specified)
* `month` &mdash; any integer from 1 to 12 (or the short name of the month such as jan or feb)
* `day of week` &mdash; any integer from 0 to 7, where 0 or 7 represents Sunday (or the short name of the week such as sun or mon)
The following define other job properties:
* `username` &mdash; specifies the user under which the jobs are run.
* `command` &mdash; the command to be executed.
+
The command can be either a command such as [command]#ls /proc /tmp/proc# or a command which executes a custom script.
For any of the above values, an asterisk (*) can be used to specify all valid values. If you, for example, define the month value as an asterisk, the job will be executed every month within the constraints of the other values.
A hyphen (-) between integers specifies a range of integers. For example, `1-4` means the integers 1, 2, 3, and 4.
A list of values separated by commas (,) specifies a list. For example, `3,4,6,8` indicates exactly these four integers.
The forward slash (/) can be used to specify step values. The value of an integer will be skipped within a range following the range with `/pass:attributes[{blank}]_integer_pass:attributes[{blank}]`. For example, the minute value defined as `0-59/2` denotes every other minute in the minute field. Step values can also be used with an asterisk. For instance, if the month value is defined as `*/3`, the task will run every third month.
Any lines that begin with a hash sign (#) are comments and are not processed.
Users other than `root` can configure cron tasks with the [command]#crontab# utility. The user-defined crontabs are stored in the `/var/spool/cron/` directory and executed as if run by the users that created them.
To create a crontab as a specific user, login as that user and type the command [command]#crontab -e# to edit the user's crontab with the editor specified in the `VISUAL` or `EDITOR` environment variable. The file uses the same format as `/etc/crontab`. When the changes to the crontab are saved, the crontab is stored according to the user name and written to the file `/var/spool/cron/pass:attributes[{blank}]_username_pass:attributes[{blank}]`. To list the contents of the current user's crontab file, use the [command]#crontab -l# command.
The `/etc/cron.d/` directory contains files that have the same syntax as the `/etc/crontab` file. Only `root` is allowed to create and modify files in this directory.
.Do not restart the daemon to apply the changes
[NOTE]
====
The cron daemon checks the `/etc/anacrontab` file, the `/etc/crontab` file, the `/etc/cron.d/` directory, and the `/var/spool/cron/` directory every minute for changes and the detected changes are loaded into memory. It is therefore not necessary to restart the daemon after an anacrontab or a crontab file have been changed.
====
[[s2-autotasks-cron-access]]
===== Controlling Access to Cron
To restrict the access to Cron, you can use the `/etc/cron.allow` and `/etc/cron.deny` files. These access control files use the same format with one user name on each line. Mind that no whitespace characters are permitted in either file.
If the `cron.allow` file exists, only users listed in the file are allowed to use cron, and the `cron.deny` file is ignored.
If the `cron.allow` file does not exist, users listed in the `cron.deny` file are not allowed to use Cron.
The Cron daemon (`crond`) does not have to be restarted if the access control files are modified. The access control files are checked each time a user tries to add or delete a cron job.
The `root` user can always use cron, regardless of the user names listed in the access control files.
You can control the access also through Pluggable Authentication Modules (PAM). The settings are stored in the `/etc/security/access.conf` file. For example, after adding the following line to the file, no other user but the `root` user can create crontabs:
[subs="quotes"]
----
-:ALL EXCEPT root :cron
----
The forbidden jobs are logged in an appropriate log file or, when using [command]#crontab -e#, returned to the standard output. For more information, see the `access.conf.5` manual page.
[[s2-black-white-listing-of-cron-jobs]]
===== Black and White Listing of Cron Jobs
Black and white listing of jobs is used to define parts of a job that do not need to be executed. This is useful when calling the [application]*run-parts* script on a Cron directory, such as `/etc/cron.daily/`: if the user adds programs located in the directory to the job black list, the [application]*run-parts* script will not execute these programs.
To define a black list, create a `jobs.deny` file in the directory that [command]#run-parts# scripts will be executing from. For example, if you need to omit a particular program from `/etc/cron.daily/`, create the `/etc/cron.daily/jobs.deny` file. In this file, specify the names of the programs to be omitted from execution (only programs located in the same directory can be enlisted). If a job runs a command which runs the programs from the `/etc/cron.daily/` directory, such as [command]#run-parts /etc/cron.daily#, the programs defined in the `jobs.deny` file will not be executed.
To define a white list, create a `jobs.allow` file.
The principles of `jobs.deny` and `jobs.allow` are the same as those of `cron.deny` and `cron.allow` described in section <<s2-autotasks-cron-access>>.
[[s1-autotasks-at-batch]]
==== At and Batch
indexterm:[at]indexterm:[batch]
While Cron is used to schedule recurring tasks, the [application]*At* utility is used to schedule a one-time task at a specific time and the [application]*Batch* utility is used to schedule a one-time task to be executed when the system load average drops below 0.8.
[[sect-At_and_Batch_Installation]]
===== Installing At and Batch
To determine if the [package]*at* package is already installed on your system, issue the following command:
[subs="quotes, macros"]
----
[command]#rpm -q at#
----
The command returns the full name of the [package]*at* package if already installed or notifies you that the package is not available.
To install the packages, use the [command]#dnf# command in the following form as `root`:
[subs="quotes, macros"]
----
[command]#dnf install _package_pass:attributes[{blank}]#
----
For example, to install both At and Batch, type the following at a shell prompt:
[subs="attributes"]
----
~]#{nbsp}dnf install at
----
For more information on how to install new packages in {MAJOROS}, see <<sec-Installing>>.
[[sect-Atd-Running]]
===== Running the At Service
The At and Batch jobs are both picked by the `atd` service. This section provides information on how to start, stop, and restart the `atd` service, and shows how to configure it to start automatically at boot time.
[[sect-Atd-service]]
====== Starting and Stopping the At Service
To determine if the service is running, use the following command:
[subs="quotes, macros"]
----
[command]#systemctl status atd.service#
----
To run the `atd` service in the current session, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#systemctl start atd.service#
----
To configure the service to start automatically at boot time, use the following command as `root`:
[subs="quotes, macros"]
----
[command]#systemctl enable atd.service#
----
[NOTE]
====
It is recommended that you configure your system to start the `atd` service automatically at boot time.
====
[[sect-Atd_Stopping]]
====== Stopping the At Service
To stop the `atd` service, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#systemctl stop atd.service#
----
To prevent the service from starting automatically at boot time, use the following command as `root`:
[subs="quotes, macros"]
----
[command]#systemctl disable atd.service#
----
[[sect-Atd_Restarting]]
====== Restarting the At Service
To restart the `atd` service, type the following at a shell prompt as `root`:
[subs="quotes, macros"]
----
[command]#systemctl restart atd.service#
----
This command stops the service and starts it again in quick succession.
[[s2-autotasks-at-configuring]]
===== Configuring an At Job
To schedule a one-time job for a specific time with the [application]*At* utility, do the following:
. On the command line, type the command [command]#at _TIME_pass:attributes[{blank}]#, where [command]#pass:attributes[{blank}]_TIME_pass:attributes[{blank}]# is the time when the command is to be executed.
+
The _TIME_ argument can be defined in any of the following formats:
+
** `pass:attributes[{blank}]_HH_:pass:attributes[{blank}]_MM_pass:attributes[{blank}]` specifies the exact hour and minute; For example, `04:00` specifies 4:00 a.m.
+
** `midnight` specifies 12:00 a.m.
+
** `noon` specifies 12:00 p.m.
+
** `teatime` specifies 4:00 p.m.
+
** `pass:attributes[{blank}]_MONTH_pass:attributes[{blank}]pass:attributes[{blank}]_DAY_pass:attributes[{blank}]pass:attributes[{blank}]_YEAR_pass:attributes[{blank}]` format; For example, `January 15 2012` specifies the 15th day of January in the year 2012. The year value is optional.
+
** `pass:attributes[{blank}]_MMDDYY_pass:attributes[{blank}]`, `pass:attributes[{blank}]_MM_pass:attributes[{blank}]/pass:attributes[{blank}]_DD_pass:attributes[{blank}]/pass:attributes[{blank}]_YY_pass:attributes[{blank}]`, or `pass:attributes[{blank}]_MM_._DD_._YY_pass:attributes[{blank}]` formats; For example, `011512` for the 15th day of January in the year 2012.
+
** `now + _TIME_pass:attributes[{blank}]` where _TIME_ is defined as an integer and the value type: minutes, hours, days, or weeks. For example, `now + 5 days` specifies that the command will be executed at the same time five days from now.
+
The time must be specified first, followed by the optional date. For more information about the time format, see the `/usr/share/doc/at-_<version>_pass:attributes[{blank}]/timespec` text file.
+
If the specified time has past, the job is executed at the time the next day.
. In the displayed `at>` prompt, define the job commands:
+
.. Type the command the job should execute and press kbd:[Enter]. Optionally, repeat the step to provide multiple commands.
+
.. Enter a shell script at the prompt and press kbd:[Enter] after each line in the script.
+
The job will use the shell set in the user's `SHELL` environment, the user's login shell, or [command]#/bin/sh# (whichever is found first).
. Once finished, press kbd:[Ctrl + D] on an empty line to exit the prompt.
If the set of commands or the script tries to display information to standard output, the output is emailed to the user.
To view the list of pending jobs, use the [command]#atq# command. See <<s2-autotasks-at-batch-viewing>> for more information.
You can also restrict the usage of the [command]#at# command. For more information, see <<s2-autotasks-at-batch-controlling-access>> for details.
[[s2-autotasks-batch-configuring]]
===== Configuring a Batch Job
The [application]*Batch* application executes the defined one-time tasks when the system load average decreases below 0.8.
To define a Batch job, do the following:
. On the command line, type the command [command]#batch#.
. In the displayed `at>` prompt, define the job commands:
+
.. Type the command the job should execute and press kbd:[Enter]. Optionally, repeat the step to provide multiple commands.
+
.. Enter a shell script at the prompt and press kbd:[Enter] after each line in the script.
+
If a script is entered, the job uses the shell set in the user's `SHELL` environment, the user's login shell, or [command]#/bin/sh# (whichever is found first).
. Once finished, press kbd:[Ctrl + D] on an empty line to exit the prompt.
If the set of commands or the script tries to display information to standard output, the output is emailed to the user.
To view the list of pending jobs, use the [command]#atq# command. See <<s2-autotasks-at-batch-viewing>> for more information.
You can also restrict the usage of the [command]#batch# command. For more information, see <<s2-autotasks-at-batch-controlling-access>> for details.
[[s2-autotasks-at-batch-viewing]]
===== Viewing Pending Jobs
To view the pending [command]#At# and [command]#Batch# jobs, run the [command]#atq# command. The [command]#atq# command displays a list of pending jobs, with each job on a separate line. Each line follows the job number, date, hour, job class, and user name format. Users can only view their own jobs. If the `root` user executes the [command]#atq# command, all jobs for all users are displayed.
[[s2-autotasks-commandline-options]]
===== Additional Command Line Options
Additional command line options for [command]#at# and [command]#batch# include the following:
[[tb-at-command-line-options]]
.[command]#at# and [command]#batch# Command Line Options
[options="header"]
|===
|Option|Description
|[option]`-f`|Read the commands or shell script from a file instead of specifying them at the prompt.
|[option]`-m`|Send email to the user when the job has been completed.
|[option]`-v`|Display the time that the job is executed.
|===
[[s2-autotasks-at-batch-controlling-access]]
===== Controlling Access to At and Batch
You can restrict the access to the [command]#at# and [command]#batch# commands using the `/etc/at.allow` and `/etc/at.deny` files. These access control files use the same format defining one user name on each line. Mind that no whitespace are permitted in either file.
If the file `at.allow` exists, only users listed in the file are allowed to use [command]#at# or [command]#batch#, and the `at.deny` file is ignored.
If `at.allow` does not exist, users listed in `at.deny` are not allowed to use [command]#at# or [command]#batch#.
The [command]#at# daemon ([command]#atd#) does not have to be restarted if the access control files are modified. The access control files are read each time a user tries to execute the [command]#at# or [command]#batch# commands.
The `root` user can always execute [command]#at# and [command]#batch# commands, regardless of the content of the access control files.
[[s1-autotasks-additional-resources]]
==== Additional Resources
indexterm:[cron,additional resources]indexterm:[at,additional resources]indexterm:[batch,additional resources]
To learn more about configuring automated tasks, see the following installed documentation:
* `cron(8)` man page contains an overview of cron.
* `crontab` man pages in sections 1 and 5:
+
** The manual page in section 1 contains an overview of the `crontab` file.
+
** The man page in section 5 contains the format for the file and some example entries.
* `anacron(8)` manual page contains an overview of anacron.
* `anacrontab(5)` manual page contains an overview of the `anacrontab` file.
* `run-parts(4)` manual page contains an overview of the [command]#run-parts# script.
* `/usr/share/doc/at/timespec` contains detailed information about the time values that can be used in cron job definitions.
* `at` manual page contains descriptions of [command]#at# and [command]#batch# and their command line options.

883
en-US/monitoring-and-automation/OProfile.adoc Normal file
View file

@ -0,0 +1,883 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-OProfile]]
=== OProfile
indexterm:[system analysis,OProfile,OProfile]indexterm:[OProfile]
OProfile is a low overhead, system-wide performance monitoring tool. It uses the performance monitoring hardware on the processor to retrieve information about the kernel and executables on the system, such as when memory is referenced, the number of L2 cache requests, and the number of hardware interrupts received. On a {MAJOROS} system, the `oprofile` package must be installed to use this tool.
Many processors include dedicated performance monitoring hardware. This hardware makes it possible to detect when certain events happen (such as the requested data not being in cache). The hardware normally takes the form of one or more _counters_ that are incremented each time an event takes place. When the counter value increments, an interrupt is generated, making it possible to control the amount of detail (and therefore, overhead) produced by performance monitoring.
OProfile uses this hardware (or a timer-based substitute in cases where performance monitoring hardware is not present) to collect _samples_ of performance-related data each time a counter generates an interrupt. These samples are periodically written out to disk; later, the data contained in these samples can then be used to generate reports on system-level and application-level performance.
Be aware of the following limitations when using OProfile:
* *Use of shared libraries* — Samples for code in shared libraries are not attributed to the particular application unless the [option]`--separate=library` option is used.
* *Performance monitoring samples are inexact* — When a performance monitoring register triggers a sample, the interrupt handling is not precise like a divide by zero exception. Due to the out-of-order execution of instructions by the processor, the sample may be recorded on a nearby instruction.
* *pass:attributes[{blank}][command]#opreport# does not associate samples for inline functions properly* — [command]#opreport# uses a simple address range mechanism to determine which function an address is in. Inline function samples are not attributed to the inline function but rather to the function the inline function was inserted into.
* *OProfile accumulates data from multiple runs* — OProfile is a system-wide profiler and expects processes to start up and shut down multiple times. Thus, samples from multiple runs accumulate. Use the command [command]#opcontrol --reset# to clear out the samples from previous runs.
* *Hardware performance counters do not work on guest virtual machines* — Because the hardware performance counters are not available on virtual systems, you need to use the `timer` mode. Enter the command [command]#opcontrol --deinit#, and then execute [command]#modprobe oprofile timer=1# to enable the `timer` mode.
* *Non-CPU-limited performance problems* — OProfile is oriented to finding problems with CPU-limited processes. OProfile does not identify processes that are asleep because they are waiting on locks or for some other event to occur (for example an I/O device to finish an operation).
[[s1-oprofile-overview-tools]]
==== Overview of Tools
indexterm:[OProfile,overview of tools]
<<tb-oprofile-tools>> provides a brief overview of the most commonly used tools provided with the `oprofile` package.
[[tb-oprofile-tools]]
.OProfile Commands
[options="header"]
|===
|Command|Description
|[command]#ophelp#|Displays available events for the system's processor along with a brief description of each.
|[command]#opimport#|Converts sample database files from a foreign binary format to the native format for the system. Only use this option when analyzing a sample database from a different architecture.
|[command]#opannotate#|Creates annotated source for an executable if the application was compiled with debugging symbols. See <<s2-oprofile-reading-opannotate>> for details.
|[command]#opcontrol#|Configures what data is collected. See <<s1-oprofile-configuring>> for details.
|[command]#operf#|Recommended tool to be used in place of [command]#opcontrol# for profiling. See <<s1-using-operf>> for details.
For differences between [command]#operf# and [command]#opcontrol# see <<s2-operf_vs_opcontrol>>.
|[command]#opreport#|Retrieves profile data. See <<s2-oprofile-reading-opreport>> for details.
|[command]#oprofiled#|Runs as a daemon to periodically write sample data to disk.
|===
[[s2-operf_vs_opcontrol]]
===== operf vs. opcontrol
There are two mutually exclusive methods for collecting profiling data with OProfile. You can either use the newer and preferred [command]#operf# or the [command]#opcontrol# tool.
.operf
This is the recommended mode for profiling. The [command]#operf# tool uses the Linux Performance Events Subsystem, and therefore does not require the *oprofile* kernel driver. The [command]#operf# tool allows you to target your profiling more precisely, as a single process or system-wide, and also allows OProfile to co-exist better with other tools using the performance monitoring hardware on your system. Unlike [command]#opcontrol#, it can be used without the `root` privileges. However, [command]#operf# is also capable of system-wide operations with use of the [option]`--system-wide` option, where root authority is required.
With [command]#operf#, there is no initial setup needed. You can invoke [command]#operf# with command-line options to specify your profiling settings. After that, you can run the OProfile post-processing tools described in <<s1-oprofile-analyzing-data>>. See <<s1-using-operf>> for further information.
.opcontrol
This mode consists of the [command]#opcontrol# shell script, the `oprofiled` daemon, and several post-processing tools. The [command]#opcontrol# command is used for configuring, starting, and stopping a profiling session. An OProfile kernel driver, usually built as a kernel module, is used for collecting samples, which are then recorded into sample files by `oprofiled`. You can use legacy mode only if you have `root` privileges. In certain cases, such as when you need to sample areas with disabled interrupt request (IRQ), this is a better alternative.
Before OProfile can be run in legacy mode, it must be configured as shown in <<s1-oprofile-configuring>>. These settings are then applied when starting OProfile (<<s1-oprofile-starting>>).
[[s1-using-operf]]
==== Using operf
[command]#operf# is the recommended profiling mode that does not require initial setup before starting. All settings are specified as command-line options and there is no separate command to start the profiling process. To stop [command]#operf#, press Ctrl+C. The typical [command]#operf# command syntax looks as follows:
[subs="quotes, macros"]
----
[command]#operf# _options_ _range_ _command_ _args_
----
Replace _options_ with the desired command-line options to specify your profiling settings. Full set of options is described in `operf(1)` manual page. Replace _range_ with one of the following:
[option]`--system-wide` - this setting allows for global profiling, see <<using_operf_system-wide>>
[option]`--pid=pass:attributes[{blank}]_PID_pass:attributes[{blank}]` - this is to profile a running application, where _PID_ is the process ID of the process you want to profile.
With _command_ and _args_, you can define a specific command or application to be profiled, and also the input arguments that this command or application requires. Either _command_, [option]`--pid` or [option]`--system-wide` is required, but these cannot be used simultaneously.
When you invoke [command]#operf# on a command line without setting the _range_ option, data will be collected for the children processes.
[[using_operf_system-wide]]
.Using [command]#operf# in System-wide Mode
[NOTE]
====
To run [command]#operf# [option]`--system-wide`, you need `root` authority. When finished profiling, you can stop [command]#operf# with `Ctrl+C`.
If you run [command]#operf# [option]`--system-wide` as a background process (with `&`), stop it in a controlled manner in order to process the collected profile data. For this purpose, use:
[subs="quotes, macros"]
----
[command]#kill -SIGINT operf-PID#
----
When running [command]#operf# [option]`--system-wide`, it is recommended that your current working directory is `/root` or a subdirectory of `/root` so that sample data files are not stored in locations accessible by regular users.
====
[[s2-operf-kernel]]
===== Specifying the Kernel
To monitor the kernel, execute the following command:
[subs="macros"]
----
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".
[[s2-operf-events]]
===== Setting Events to Monitor
Most processors contain counters, which are used by OProfile to monitor specific events. As shown in <<tb-oprofile-processors>>, the number of counters available depends on the processor.
The events for each counter can be configured via the command line or with a graphical interface. For more information on the graphical interface, see <<s1-oprofile-gui>>. If the counter cannot be set to a specific event, an error message is displayed.
.Older Processors and operf
[NOTE]
====
Some older processor models are not supported by the underlying Linux Performance Events Subsystem kernel and therefore are not supported by [command]#operf#. If you receive this message:
[subs="quotes"]
----
Your kernel's Performance Events Subsystem does not support your processor type
----
when attempting to use [command]#operf#, try profiling with [command]#opcontrol# to see if your processor type may be supported by OProfile's legacy mode.
====
.Using operf on Virtual Systems
[NOTE]
====
Since hardware performance counters are not available on guest virtual machines, you have to enable *timer* mode to use [application]*operf* on virtual systems. To do so, type as `root`:
[subs="quotes, macros"]
----
[command]#opcontrol# [option]`--deinit`
----
[subs="quotes, macros"]
----
[command]#modprobe# [command]#oprofile# [option]`timer=1`
----
====
To set the event for each configurable counter via the command line, use:
[subs="quotes, macros"]
----
[command]#operf# [option]`--events`pass:attributes[{blank}]=pass:attributes[{blank}]_event1_,_event2_pass:attributes[{blank}]&hellip;
----
Here, pass a comma-separated list of event specifications for profiling. Each event specification is a colon-separated list of attributes in the following form:
[subs="quotes, macros"]
----
_event-name_:pass:attributes[{blank}]_sample-rate_:pass:attributes[{blank}]_unit-mask_:pass:attributes[{blank}]_kernel_:pass:attributes[{blank}]_user_
----
<<tab_event_specifications>> summarizes these options. The last three values are optional, if you omit them, they will be set to their default values. Note that certain events do require a unit mask.
[[tab_event_specifications]]
.Event Specifications
[options="header"]
|===
|Specification|Description
|_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.
|_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))
|===
The events available vary depending on the processor type. When no event specification is given, the default event for the running processor type will be used for profiling. See <<tb-oprofile-default-events>> for a list of these default events. To determine the events available for profiling, use the [command]#ophelp# command.
[subs="quotes, macros"]
----
[command]#ophelp#
----
[[s2-operf-categorization]]
===== Categorization of Samples
The [option]`--separate-thread` option categorizes samples by thread group ID (tgid) and thread ID (tid). This is useful for seeing per-thread samples in multi-threaded applications. When used in conjunction with the [option]`--system-wide` option, [option]`--separate-thread` is also useful for seeing per-process (i.e., per-thread group) samples for the case where multiple processes are executing the same program during a profiling run.
The [option]`--separate-cpu` option categorizes samples by CPU.
[[s1-oprofile-configuring]]
==== Configuring OProfile Using Legacy Mode
indexterm:[OProfile,configuring]indexterm:[OProfile,opcontrol]indexterm:[opcontrol,OProfile]
Before OProfile can be run in legacy mode, it must be configured. At a minimum, selecting to monitor the kernel (or selecting not to monitor the kernel) is required. The following sections describe how to use the [command]#opcontrol# utility to configure OProfile. As the [command]#opcontrol# commands are executed, the setup options are saved to the `/root/.oprofile/daemonrc` file.
[[s2-oprofile-kernel]]
===== Specifying the Kernel
indexterm:[OProfile,monitoring the kernel]
First, configure whether OProfile should monitor the kernel. This is the only configuration option that is required before starting OProfile. All others are optional.
To monitor the kernel, execute the following command as `root`:
indexterm:[OProfile,opcontrol,--vmlinux=]
----
~]# opcontrol --setup --vmlinux=/usr/lib/debug/lib/modules/`uname -r`/vmlinux
----
.Install the debuginfo package
[IMPORTANT]
====
In order to monitor the kernel, the [package]*debuginfo* package which contains the uncompressed kernel must be installed.
====
To configure OProfile not to monitor the kernel, execute the following command as `root`:
indexterm:[OProfile,opcontrol,--no-vmlinux]
----
~]# opcontrol --setup --no-vmlinux
----
This command also loads the `oprofile` kernel module, if it is not already loaded, and creates the `/dev/oprofile/` directory, if it does not already exist. See <<s1-oprofile-dev-oprofile>> for details about this directory.
Setting whether samples should be collected within the kernel only changes what data is collected, not how or where the collected data is stored. To generate different sample files for the kernel and application libraries, see <<s2-oprofile-starting-separate>>.
[[s2-oprofile-events]]
===== Setting Events to Monitor
indexterm:[OProfile,events,setting]
Most processors contain _counters_, which are used by OProfile to monitor specific events. As shown in <<tb-oprofile-processors>>, the number of counters available depends on the processor.
[[tb-oprofile-processors]]
.OProfile Processors and Counters
[options="header"]
|===
|Processor|[command]#cpu_type#|Number of Counters
|AMD64|x86-64/hammer|4
|AMD Family 10h|x86-64/family10|4
|AMD Family 11h|x86-64/family11|4
|AMD Family 12h|x86-64/family12|4
|AMD Family 14h|x86-64/family14|4
|AMD Family 15h|x86-64/family15|6
|Applied Micro X-Gene|arm/armv8-xgene|4
|ARM Cortex A53|arm/armv8-ca53|6
|ARM Cortex A57|arm/armv8-ca57|6
|IBM eServer System i and IBM eServer System p|timer|1
|IBM POWER4|ppc64/power4|8
|IBM POWER5|ppc64/power5|6
|IBM PowerPC 970|ppc64/970|8
|IBM PowerPC 970MP|ppc64/970MP|8
|IBM POWER5+|ppc64/power5+|6
|IBM POWER5++|ppc64/power5++|6
|IBM POWER56|ppc64/power6|6
|IBM POWER7|ppc64/power7|6
|IBM POWER8|ppc64/power7|8
|IBM S/390 and IBM System z|timer|1
|Intel Core i7|i386/core_i7|4
|Intel Nehalem microarchitecture|i386/nehalem|4
|Intel Westmere microarchitecture|i386/westmere|4
|Intel Haswell microarchitecture (non-hyper-threaded)|i386/haswell|8
|Intel Haswell microarchitecture (hyper-threaded)|i386/haswell-ht|4
|Intel Ivy Bridge microarchitecture (non-hyper-threaded)|i386/ivybridge|8
|Intel Ivy Bridge microarchitecture (hyper-threaded)|i386/ivybridge-ht|4
|Intel Sandy Bridge microarchitecture (non-hyper-threaded)|i386/sandybridge|8
|Intel Sandy Bridge microarchitecture|i386/sandybridge-ht|4
|Intel Broadwell microarchitecture (non-hyper-threaded)|i386/broadwell|8
|Intel Broadwell microarchitecture (hyper-threaded)|i386/broadwell-ht|4
|Intel Silvermont microarchitecture|i386/silvermont|2
|TIMER_INT|timer|1
|===
Use <<tb-oprofile-processors>> to determine the number of events that can be monitored simultaneously for your CPU type. If the processor does not have supported performance monitoring hardware, the `timer` is used as the processor type.
If `timer` is used, events cannot be set for any processor because the hardware does not have support for hardware performance counters. Instead, the timer interrupt is used for profiling.
If `timer` is not used as the processor type, the events monitored can be changed, and counter 0 for the processor is set to a time-based event by default. If more than one counter exists on the processor, the counters other than 0 are not set to an event by default. The default events monitored are shown in <<tb-oprofile-default-events>>.
[[tb-oprofile-default-events]]
.Default Events
[options="header"]
|===
|Processor|Default Event for Counter|Description
|AMD Athlon and AMD64|CPU_CLK_UNHALTED|The processor's clock is not halted
|AMD Family 10h, AMD Family 11h, AMD Family 12h|CPU_CLK_UNHALTED|The processor's clock is not halted
|AMD Family 14h, AMD Family 15h|CPU_CLK_UNHALTED|The processor's clock is not halted
|Applied Micro X-Gene|CPU_CYCLES|Processor Cycles
|ARM Cortex A53|CPU_CYCLES|Processor Cycles
|ARM Cortex A57|CPU_CYCLES|Processor Cycles
|IBM POWER4|CYCLES|Processor Cycles
|IBM POWER5|CYCLES|Processor Cycles
|IBM POWER8|CYCLES|Processor Cycles
|IBM PowerPC 970|CYCLES|Processor Cycles
|Intel Core i7|CPU_CLK_UNHALTED|The processor's clock is not halted
|Intel Nehalem microarchitecture|CPU_CLK_UNHALTED|The processor's clock is not halted
|Intel Pentium 4 (hyper-threaded and non-hyper-threaded)|GLOBAL_POWER_EVENTS|The time during which the processor is not stopped
|Intel Westmere microarchitecture|CPU_CLK_UNHALTED|The processor's clock is not halted
|Intel Broadwell microarchitecture|CPU_CLK_UNHALTED|The processor's clock is not halted
|Intel Silvermont microarchitecture|CPU_CLK_UNHALTED|The processor's clock is not halted
|TIMER_INT|(none)|Sample for each timer interrupt
|===
The number of events that can be monitored at one time is determined by the number of counters for the processor. However, it is not a one-to-one correlation; on some processors, certain events must be mapped to specific counters. To determine the number of counters available, execute the following command:
----
~]# ls -d /dev/oprofile/[0-9]*
----
The events available vary depending on the processor type. To determine the events available for profiling, execute the following command as root (the list is specific to the system's processor type):
indexterm:[OProfile,ophelp]indexterm:[ophelp]
----
~]# ophelp
----
.Make sure that OProfile is configured
[NOTE]
====
Unless OProfile is properly configured, [command]#ophelp# fails with the following error message:
----
Unable to open cpu_type file for reading
Make sure you have done opcontrol --init
cpu_type 'unset' is not valid
you should upgrade oprofile or force the use of timer mode
----
To configure OProfile, follow the instructions in <<s1-oprofile-configuring>>.
====
The events for each counter can be configured via the command line or with a graphical interface. For more information on the graphical interface, see <<s1-oprofile-gui>>. If the counter cannot be set to a specific event, an error message is displayed.
To set the event for each configurable counter via the command line, use [command]#opcontrol#:
----
~]# opcontrol --event=event-name:sample-rate
----
Replace _event-name_ with the exact name of the event from [command]#ophelp#, and replace _sample-rate_ with the number of events between samples.
[[s3-oprofile-events-sampling]]
====== Sampling Rate
indexterm:[OProfile,events,sampling rate]
By default, a time-based event set is selected. It creates a sample every 100,000 clock cycles per processor. If the timer interrupt is used, the timer is set to the respective rate and is not user-settable. If the `cpu_type` is not `timer`, each event can have a _sampling rate_ set for it. The sampling rate is the number of events between each sample snapshot.
When setting the event for the counter, a sample rate can also be specified:
----
~]# opcontrol --event=event-name:sample-rate
----
Replace _sample-rate_ with 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 the event instances.
.Sampling too frequently can overload the system
[WARNING]
====
Be extremely careful when setting sampling rates. Sampling too frequently can overload the system, causing the system to appear frozen or causing the system to actually freeze.
====
[[s3-oprofile-events-unit-masks]]
====== Unit Masks
indexterm:[OProfile,unit mask]
Some user performance monitoring events may also require unit masks to further define the event.
Unit masks for each event are listed with the [command]#ophelp# command. The values for each unit mask are listed in hexadecimal format. To specify more than one unit mask, the hexadecimal values must be combined using a bitwise _or_ operation.
----
~]# opcontrol --event=event-name:sample-rate:unit-mask
----
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.
[[s2-oprofile-starting-separate]]
===== Separating Kernel and User-space Profiles
indexterm:[OProfile,configuring,separating profiles]
By default, kernel mode and user mode information is gathered for each event. To configure OProfile to ignore events in kernel mode for a specific counter, execute the following command:
----
~]# opcontrol --event=event-name:sample-rate:unit-mask:0
----
Execute the following command to start profiling kernel mode for the counter again:
----
~]# opcontrol --event=event-name:sample-rate:unit-mask:1
----
To configure OProfile to ignore events in user mode for a specific counter, execute the following command:
----
~]# opcontrol --event=event-name:sample-rate:unit-mask:1:0
----
Execute the following command to start profiling user mode for the counter again:
----
~]# opcontrol --event=event-name:sample-rate:unit-mask:1:1
----
When the OProfile daemon writes the profile data to sample files, it can separate the kernel and library profile data into separate sample files. To configure how the daemon writes to sample files, execute the following command as root:
----
~]# opcontrol --separate=choice
----
The _choice_ argument can be one of the following:
* `none` — Do not separate the profiles (default).
* [command]#library# — Generate per-application profiles for libraries.
* [command]#kernel# — Generate per-application profiles for the kernel and kernel modules.
* [command]#all# — Generate per-application profiles for libraries and per-application profiles for the kernel and kernel modules.
If [option]`--separate=library` is used, the sample file name includes the name of the executable as well as the name of the library.
.Restart the OProfile profiler
[NOTE]
====
These configuration changes will take effect when the OProfile profiler is restarted.
====
[[s1-oprofile-starting]]
==== Starting and Stopping OProfile Using Legacy Mode
indexterm:[OProfile,starting]
To start monitoring the system with OProfile, execute the following command as root:
indexterm:[OProfile,opcontrol,--start]
----
~]# opcontrol --start
----
Output similar to the following is displayed:
[subs="quotes"]
----
Using log file /var/lib/oprofile/oprofiled.log Daemon started. Profiler running.
----
The settings in `/root/.oprofile/daemonrc` are used.
indexterm:[OProfile,oprofiled]indexterm:[oprofiled,OProfile]indexterm:[OProfile,oprofiled,log file]
The OProfile daemon, [command]#oprofiled#, is started; it periodically writes the sample data to the `/var/lib/oprofile/samples/` directory. The log file for the daemon is located at `/var/lib/oprofile/oprofiled.log`.
.Disable the nmi_watchdog registers
[IMPORTANT]
====
On a {MAJOROSVER} system, the `nmi_watchdog` registers with the `perf` subsystem. Due to this, the `perf` subsystem grabs control of the performance counter registers at boot time, blocking OProfile from working.
To resolve this, either boot with the [command]#nmi_watchdog=0# kernel parameter set, or run the following command as `root` to disable `nmi_watchdog` at run time:
----
~]# echo 0 > /proc/sys/kernel/nmi_watchdog
----
To re-enable `nmi_watchdog`, use the following command as `root`:
----
~]# echo 1 > /proc/sys/kernel/nmi_watchdog
----
====
To stop the profiler, execute the following command as root:
----
~]# opcontrol --shutdown
----
[[s1-oprofile-saving-data]]
==== Saving Data in Legacy Mode
indexterm:[OProfile,saving data]
Sometimes it is useful to save samples at a specific time. For example, when profiling an executable, it may be useful to gather different samples based on different input data sets. If the number of events to be monitored exceeds the number of counters available for the processor, multiple runs of OProfile can be used to collect data, saving the sample data to different files each time.
To save the current set of sample files, execute the following command, replacing _name_ with a unique descriptive name for the current session:
----
~]# opcontrol --save=name
----
The command creates the directory `/var/lib/oprofile/samples/pass:attributes[{blank}]_name_pass:attributes[{blank}]/` and the current sample files are copied to it.
To specify the session directory to hold the sample data, use the [option]`--session-dir` option. If not specified, the data is saved in the `oprofile_data/` directory on the current path.
[[s1-oprofile-analyzing-data]]
==== Analyzing the Data
indexterm:[OProfile,reading data]
The same OProfile post-processing tools are used whether you collect your profile with [command]#operf# or [command]#opcontrol# in legacy mode.
By default, [command]#operf# stores the profiling data in the `pass:attributes[{blank}]_current_dir_pass:attributes[{blank}]/oprofile_data/` directory. You can change to a different location with the [option]`--session-dir` option. The usual post-profiling analysis tools such as [command]#opreport# and [command]#opannotate# can be used to generate profile reports. These tools search for samples in `pass:attributes[{blank}]_current_dir_pass:attributes[{blank}]/oprofile_data/` first. If this directory does not exist, the analysis tools use the standard session directory of `/var/lib/oprofile/`. Statistics, such as total samples received and lost samples, are written to the `pass:attributes[{blank}]_session_dir_pass:attributes[{blank}]/samples/operf.log` file.
When using legacy mode, the OProfile daemon, [command]#oprofiled#, periodically collects the samples and writes them to the `/var/lib/oprofile/samples/` directory. Before reading the data, make sure all data has been written to this directory by executing the following command as root:
----
~]# opcontrol --dump
----
Each sample file name is based on the name of the executable. For example, the samples for the default event on a Pentium III processor for [command]#/bin/bash# becomes:
----
\{root\}/bin/bash/\{dep\}/\{root\}/bin/bash/CPU_CLK_UNHALTED.100000
----
The following tools are available to profile the sample data once it has been collected:
* [command]#opreport#
* [command]#opannotate#
Use these tools, along with the binaries profiled, to generate reports that can be further analyzed.
.Back up the executable and the sample files
[WARNING]
====
The executable being profiled must be used with these tools to analyze the data. If it must change after the data is collected, back up the executable used to create the samples as well as the sample files. Note that the names of the sample file and the binary have to agree. You cannot make a backup if these names do not match. As an alternative, [command]#oparchive# can be used to address this problem.
====
Samples for each executable are written to a single sample file. Samples from each dynamically linked library are also written to a single sample file. While OProfile is running, if the executable being monitored changes and a sample file for the executable exists, the existing sample file is automatically deleted. Thus, if the existing sample file is needed, it must be backed up, along with the executable used to create it before replacing the executable with a new version. The OProfile analysis tools use the executable file that created the samples during analysis. If the executable changes, the analysis tools will be unable to analyze the associated samples. See <<s1-oprofile-saving-data>> for details on how to back up the sample file.
[[s2-oprofile-reading-opreport]]
===== Using [command]#opreport#
indexterm:[OProfile,opreport]indexterm:[opreport,OProfile]
The [command]#opreport# tool provides an overview of all the executables being profiled. The following is part of a sample output from the [command]#opreport# command:
[subs="quotes, macros, attributes"]
----
~]${nbsp}pass:attributes[{blank}][command]#opreport#
Profiling through timer interrupt
TIMER:0|
samples| %|
------------------
25926 97.5212 no-vmlinux
359 1.3504 pi
65 0.2445 Xorg
62 0.2332 libvte.so.4.4.0
56 0.2106 libc-2.3.4.so
34 0.1279 libglib-2.0.so.0.400.7
19 0.0715 libXft.so.2.1.2
17 0.0639 bash
8 0.0301 ld-2.3.4.so
8 0.0301 libgdk-x11-2.0.so.0.400.13
6 0.0226 libgobject-2.0.so.0.400.7
5 0.0188 oprofiled
4 0.0150 libpthread-2.3.4.so
4 0.0150 libgtk-x11-2.0.so.0.400.13
3 0.0113 libXrender.so.1.2.2
3 0.0113 du
1 0.0038 libcrypto.so.0.9.7a
1 0.0038 libpam.so.0.77
1 0.0038 libtermcap.so.2.0.8
1 0.0038 libX11.so.6.2
1 0.0038 libgthread-2.0.so.0.400.7
1 0.0038 libwnck-1.so.4.9.0
----
Each executable is listed on its own line. The first column is the number of samples recorded for the executable. The second column is the percentage of samples relative to the total number of samples. The third column is the name of the executable.
See the `opreport(1)` manual page for a list of available command-line options, such as the [option]`-r` option used to sort the output from the executable with the smallest number of samples to the one with the largest number of samples. You can also use the [option]`-t` or [option]`--threshold` option to trim the output of [command]#opcontrol#.
[[s2-oprofile-reading-opreport-single]]
===== Using opreport on a Single Executable
indexterm:[OProfile,opreport,on a single executable]indexterm:[opreport,OProfile]
To retrieve more detailed profiled information about a specific executable, use the [command]#opreport# command:
----
~]# opreport mode
executable
----
Replace _executable_ with the full path to the executable to be analyzed. _mode_ stands for one of the following options:
[option]`-l`:: This option is used to list sample data by symbols. For example, running this command:
+
[subs="attributes"]
----
~]#{nbsp}opreport -l /lib/tls/libc-version.so
----
+
produces the following output:
+
----
samples % symbol name
12 21.4286 __gconv_transform_utf8_internal
5 8.9286 _int_malloc 4 7.1429 malloc
3 5.3571 __i686.get_pc_thunk.bx
3 5.3571 _dl_mcount_wrapper_check
3 5.3571 mbrtowc
3 5.3571 memcpy
2 3.5714 _int_realloc
2 3.5714 _nl_intern_locale_data
2 3.5714 free
2 3.5714 strcmp
1 1.7857 __ctype_get_mb_cur_max
1 1.7857 __unregister_atfork
1 1.7857 __write_nocancel
1 1.7857 _dl_addr
1 1.7857 _int_free
1 1.7857 _itoa_word
1 1.7857 calc_eclosure_iter
1 1.7857 fopen@@GLIBC_2.1
1 1.7857 getpid
1 1.7857 memmove
1 1.7857 msort_with_tmp
1 1.7857 strcpy
1 1.7857 strlen
1 1.7857 vfprintf
1 1.7857 write
----
+
The first column is the number of samples for the symbol, the second column is the percentage of samples for this symbol relative to the overall samples for the executable, and the third column is the symbol name.
+
To sort the output from the largest number of samples to the smallest (reverse order), use [option]`-r` in conjunction with the [option]`-l` option.
[option]`-i _symbol-name_pass:attributes[{blank}]`:: List sample data specific to a symbol name. For example, running:
+
[subs="attributes"]
----
~]#{nbsp}opreport -l -i __gconv_transform_utf8_internal /lib/tls/libc-version.so
----
+
returns the following output:
+
----
samples % symbol name
12 100.000 __gconv_transform_utf8_internal
----
+
The first line is a summary for the symbol/executable combination.
+
The first column is the number of samples for the memory symbol. The second column is the percentage of samples for the memory address relative to the total number of samples for the symbol. The third column is the symbol name.
[option]`-d`:: This option lists sample data by symbols with more detail than the [option]`-l` option. For example, with the following command:
+
[subs="attributes"]
----
~]#{nbsp}opreport -d -i __gconv_transform_utf8_internal /lib/tls/libc-version.so
----
+
this output is returned:
+
----
vma samples % symbol name
00a98640 12 100.000 __gconv_transform_utf8_internal
00a98640 1 8.3333
00a9868c 2 16.6667
00a9869a 1 8.3333
00a986c1 1 8.3333
00a98720 1 8.3333
00a98749 1 8.3333
00a98753 1 8.3333
00a98789 1 8.3333
00a98864 1 8.3333
00a98869 1 8.3333
00a98b08 1 8.3333
----
+
The data is the same as the [option]`-l` option except that for each symbol, each virtual memory address used is shown. For each virtual memory address, the number of samples and percentage of samples relative to the number of samples for the symbol is displayed.
[option]`-e` _symbol-name_pass:attributes[{blank}]&hellip;:: With this option, you can exclude some symbols from the output. Replace _symbol-name_ with the comma-separated list of symbols you want to exclude.
[option]`session`:pass:attributes[{blank}]_name_:: Here, you can specify the full path to the session, a directory relative to the `/var/lib/oprofile/samples/` directory, or if you are using [command]#operf#, a directory relative to `./oprofile_data/samples/`.
[[s2-oprofile-module-output]]
===== Getting More Detailed Output on the Modules
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.
Find out which kernel is running with the [command]#uname -a# command, obtain the appropriate [package]*debuginfo* package and install it on the machine.
Then proceed with clearing out the samples from previous runs with the following command:
----
~]# opcontrol --reset
----
To start the monitoring process, for example, on a machine with Westmere processor, run the following command:
----
~]# opcontrol --setup --vmlinux=/usr/lib/debug/lib/modules/`uname -r`/vmlinux \
--event=CPU_CLK_UNHALTED:500000
----
Then the detailed information, for instance, for the ext4 module can be obtained with:
----
~]# opreport /ext4 -l --image-path /lib/modules/`uname -r`/kernel
CPU: Intel Westmere microarchitecture, speed 2.667e+06 MHz (estimated)
Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 500000
warning: could not check that the binary file /lib/modules/2.6.32-191.el6.x86_64/kernel/fs/ext4/ext4.ko has not been modified since the profile was taken. Results may be inaccurate.
samples % symbol name
1622 9.8381 ext4_iget
1591 9.6500 ext4_find_entry
1231 7.4665 __ext4_get_inode_loc
783 4.7492 ext4_ext_get_blocks
752 4.5612 ext4_check_dir_entry
644 3.9061 ext4_mark_iloc_dirty
583 3.5361 ext4_get_blocks
583 3.5361 ext4_xattr_get
479 2.9053 ext4_htree_store_dirent
469 2.8447 ext4_get_group_desc
414 2.5111 ext4_dx_find_entry
----
[[s2-oprofile-reading-opannotate]]
===== Using [command]#opannotate#
indexterm:[OProfile,opannotate]indexterm:[opannotate,OProfile]
The [command]#opannotate# tool tries to match the samples for particular instructions to the corresponding lines in the source code. The resulting generated files should have the samples for the lines at the left. It also puts in a comment at the beginning of each function listing the total samples for the function.
For this utility to work, the appropriate [package]*debuginfo* package for the executable must be installed on the system. On {MAJOROS}, the [package]*debuginfo* packages are not automatically installed with the corresponding packages that contain the executable. You have to obtain and install them separately.
The general syntax for [command]#opannotate# is as follows:
----
~]# opannotate --search-dirs src-dir --source executable
----
These command-line options are mandatory. Replace _src-dir_ with a path to the directory containing the source code and specify the executable to be analyzed. See the `opannotate(1)` manual page for a list of additional command line options.
[[s1-oprofile-dev-oprofile]]
==== Understanding the /dev/oprofile/ directory
indexterm:[OProfile,/dev/oprofile/]indexterm:[/dev/oprofile/]
When using OProfile in legacy mode, the `/dev/oprofile/` directory is used to store the file system for OProfile. On the other hand, [command]#operf# does not require `/dev/oprofile/`. Use the [command]#cat# command to display the values of the virtual files in this file system. For example, the following command displays the type of processor OProfile detected:
----
~]# cat /dev/oprofile/cpu_type
----
A directory exists in `/dev/oprofile/` for each counter. For example, if there are 2 counters, the directories `/dev/oprofile/0/` and `/dev/oprofile/1/` exist.
Each directory for a counter contains the following files:
* `count` — The interval between samples.
* `enabled` — If 0, the counter is off and no samples are collected for it; if 1, the counter is on and samples are being collected for it.
* `event` — The event to monitor.
* `extra` — Used on machines with Nehalem processors to further specify the event to monitor.
* `kernel` — If 0, samples are not collected for this counter event when the processor is in kernel-space; if 1, samples are collected even if the processor is in kernel-space.
* `unit_mask` — Defines which unit masks are enabled for the counter.
* `user` — If 0, samples are not collected for the counter event when the processor is in user-space; if 1, samples are collected even if the processor is in user-space.
The values of these files can be retrieved with the [command]#cat# command. For example:
----
~]# cat /dev/oprofile/0/count
----
[[s1-oprofile-example-usage]]
==== Example Usage
While OProfile can be used by developers to analyze application performance, it can also be used by system administrators to perform system analysis. For example:
* *Determine which applications and services are used the most on a system* — [command]#opreport# can be used to determine how much processor time an application or service uses. If the system is used for multiple services but is underperforming, the services consuming the most processor time can be moved to dedicated systems.
* *Determine processor usage* — The `CPU_CLK_UNHALTED` event can be monitored to determine the processor load over a given period of time. This data can then be used to determine if additional processors or a faster processor might improve system performance.
[[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.
[[s1-oprofile-java-profiling]]
===== Profiling Java Code
To profile JIT code from the Java Virtual Machine with the JVMTI agent, add the following to the JVM startup parameters:
[subs="macros"]
----
-agentlib:pass:quotes[_jvmti_oprofile_]
----
Where _jvmti_oprofile_ is a path to the OProfile agent. For 64-bit JVM, the path looks as follows:
----
-agentlib:/usr/lib64/oprofile/libjvmti_oprofile.so
----
Currently, you can add one command-line option: [option]`--debug`, which enables debugging mode.
.Install the oprofile-jit package
[NOTE]
====
The [package]*oprofile-jit* package must be installed on the system in order to profile JIT code with OProfile. With this package, you gain the capability to show method-level information.
====
Depending on the JVM that you are using, you may have to install the *debuginfo* package for the JVM. For OpenJDK, this package is required, there is no debuginfo package for Oracle JDK. To keep the debug information packages synchronized with their respective non-debug packages, you also need to install the *yum-plugin-auto-update-debug-info* plug-in. This plug-in searches the debug information repository for corresponding updates.
After successful setup, you can apply the standard profiling and analyzing tools described in previous sections
To learn more about Java support in OProfile, see the OProfile Manual, which is linked from <<s1-oprofile_additional_resources>>.
[[s1-oprofile-gui]]
==== Graphical Interface
indexterm:[oprof_start]
Some OProfile preferences can be set with a graphical interface. Make sure you have the `oprofile-gui` package that provides the OProfile GUI installed on your system. To start the interface, execute the [command]#oprof_start# command as root at a shell prompt.
After changing any of the options, save them by clicking the btn:[Save and quit] button. The preferences are written to `/root/.oprofile/daemonrc`, and the application exits. Exiting the application does not stop OProfile from sampling.
On the `Setup` tab, to set events for the processor counters as discussed in <<s2-oprofile-events>>, select the counter from the pulldown menu and select the event from the list. A brief description of the event appears in the text box below the list. Only events available for the specific counter and the specific architecture are displayed. The interface also displays whether the profiler is running and some brief statistics about it.
[[fig-oprofile-setup]]
.OProfile Setup
image::oprof-start-setup.png[oprof_start interface]
On the right side of the tab, select the `Profile kernel` option to count events in kernel mode for the currently selected event, as discussed in <<s2-oprofile-starting-separate>>. If this option is not selected, no samples are collected for the kernel.
Select the `Profile user binaries` option to count events in user mode for the currently selected event, as discussed in <<s2-oprofile-starting-separate>>. If this option is not selected, no samples are collected for user applications.
Use the `Count` text field to set the sampling rate for the currently selected event as discussed in <<s3-oprofile-events-sampling>>.
If any unit masks are available for the currently selected event, as discussed in <<s3-oprofile-events-unit-masks>>, they are displayed in the `Unit Masks` area on the right side of the `Setup` tab. Select the check box beside the unit mask to enable it for the event.
On the `Configuration` tab, to profile the kernel, enter the name and location of the `vmlinux` file for the kernel to monitor in the `Kernel image file` text field. To configure OProfile not to monitor the kernel, select `No kernel image`.
[[fig-oprofile-configuration]]
.OProfile Configuration
image::oprof-start-config.png[OProfile Configuration]
If the `Verbose` option is selected, the [command]#oprofiled# daemon log includes more detailed information.
If `Per-application profiles` is selected, OProfile generates per-application profiles for libraries. This is equivalent to the [command]#opcontrol --separate=library# command. If `Per-application profiles, including kernel` is selected, OProfile generates per-application profiles for the kernel and kernel modules as discussed in <<s2-oprofile-starting-separate>>. This is equivalent to the [command]#opcontrol --separate=kernel# command.
To force data to be written to samples files as discussed in <<s1-oprofile-analyzing-data>>, click the btn:[Flush] button. This is equivalent to the [command]#opcontrol --dump# command.
To start OProfile from the graphical interface, click btn:[Start]. To stop the profiler, click btn:[Stop]. Exiting the application does not stop OProfile from sampling.
[[s1-oprofile-and-systemtap]]
==== OProfile and SystemTap
indexterm:[OProfile,SystemTap]
SystemTap is a tracing and probing tool that allows users to study and monitor the activities of the operating system in fine detail. It provides information similar to the output of tools like [command]#netstat#, [command]#ps#, [command]#top#, and [command]#iostat#pass:attributes[{blank}]; however, SystemTap is designed to provide more filtering and analysis options for the collected information.
While using OProfile is suggested in cases of collecting data on where and why the processor spends time in a particular area of code, it is less usable when finding out why the processor stays idle.
You might want to use SystemTap when instrumenting specific places in code. Because SystemTap allows you to run the code instrumentation without having to stop and restart the instrumented code, it is particularly useful for instrumenting the kernel and daemons.
For more information on SystemTap, see <<br-oprofile_online_documentation>> for the relevant SystemTap documentation.
[[s1-oprofile_additional_resources]]
==== Additional Resources
indexterm:[OProfile,additional resources]
To learn more about OProfile and how to configure it, see the following resources.
.Installed Documentation
* `/usr/share/doc/oprofile/oprofile.html` — [citetitle]_OProfile Manual_
* `oprofile(1)` manual page — Discusses [command]#opcontrol#, [command]#opreport#, [command]#opannotate#, and [command]#ophelp#
* `operf(1)` manual page
[[br-oprofile_online_documentation]]
.Online Documentation
* link:++http://oprofile.sourceforge.net/++[http://oprofile.sourceforge.net/] — Contains the latest upstream documentation, mailing lists, IRC channels, and more.
.See Also
* link:++https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SystemTap_Beginners_Guide/index.html++[SystemTap Beginners Guide] — Provides basic instructions on how to use SystemTap to monitor different subsystems of {MAJOROS} in finer detail.

1497
en-US/monitoring-and-automation/System_Monitoring_Tools.adoc Normal file
View file

File diff suppressed because it is too large Load diff

2134
en-US/monitoring-and-automation/Viewing_and_Managing_Log_Files.adoc Normal file
View file

File diff suppressed because it is too large Load diff

BIN
en-US/monitoring-and-automation/images/oprof-start-config.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
en-US/monitoring-and-automation/images/oprof-start-setup.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
en-US/monitoring-and-automation/images/redhat-filter-enable.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 945 KiB

BIN
en-US/monitoring-and-automation/images/redhat-filter-sample.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 350 KiB

BIN
en-US/monitoring-and-automation/images/redhat-filters.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 302 KiB

BIN
en-US/monitoring-and-automation/images/redhat-logviewer-add.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 943 KiB

BIN
en-US/monitoring-and-automation/images/redhat-logviewer-monitoring.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 945 KiB

BIN
en-US/monitoring-and-automation/images/redhat-logviewer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 943 KiB

BIN
en-US/monitoring-and-automation/images/rsyslog_message_flow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 72 KiB

BIN
en-US/monitoring-and-automation/images/system-monitor-file-systems.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
en-US/monitoring-and-automation/images/system-monitor-processes.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 62 KiB

BIN
en-US/monitoring-and-automation/images/system-monitor-resources.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 47 KiB

3
en-US/monitoring-and-automation/intro-monitoring-and-automation.adoc Normal file
View file

@ -0,0 +1,3 @@
== Monitoring and Automation
This part describes various tools that allow system administrators to monitor system performance, automate system tasks, and report bugs.

911
en-US/package-management/DNF.adoc Normal file
View file

@ -0,0 +1,911 @@
:experimental:
include::en-US/entities.adoc[]
[[ch-DNF]]
=== DNF
[application]*DNF* is the {OSORG} package manager that is able to query for information about packages, fetch packages from repositories, install and uninstall packages using automatic dependency resolution, and update an entire system to the latest available packages. DNF performs automatic dependency resolution on packages you are updating, installing or removing, and thus is able to automatically determine, fetch and install all available dependent packages. DNF can be configured with new, additional repositories, or _package sources_, and also provides many plug-ins which enhance and extend its capabilities. DNF is able to perform many of the same tasks that [application]*RPM* can; additionally, many of the command line options are similar. DNF enables easy and simple package management on a single machine or on groups of them.
[[important-Secure_Package_Management_with_GPG-Signed_Packages]]
.Secure package management with GPG-signed packages
[IMPORTANT]
====
DNF provides secure package management by enabling GPG (Gnu Privacy Guard; also known as GnuPG) signature verification on GPG-signed packages to be turned on for all package repositories (package sources), or for individual repositories. When signature verification is enabled, DNF will refuse to install any packages not GPG-signed with the correct key for that repository. This means that you can trust that the [application]*RPM* packages you download and install on your system are from a trusted source, such as {OSORG}, and were not modified during transfer. See <<sec-Configuring_DNF_and_DNF_Repositories>> for details on enabling signature-checking with DNF, or <<s1-check-rpm-sig>> for information on working with and verifying GPG-signed [application]*RPM* packages in general.
====
DNF also enables you to easily set up your own repositories of [application]*RPM* packages for download and installation on other machines.
Learning DNF is a worthwhile investment because it is often the fastest way to perform system administration tasks, and it provides capabilities beyond those provided by the [application]*PackageKit* graphical package management tools.
[[note-Note_DNF_and_Superuser_Privileges]]
.DNF and superuser privileges
[NOTE]
====
You must have superuser privileges in order to use the [command]#dnf# command to install, update or remove packages on your system. All examples in this chapter assume that you have already obtained superuser privileges by using either the [command]#su# or [command]#sudo# command.
====
[[sec-Checking_For_and_Updating_Packages]]
==== Checking For and Updating Packages
[[sec-Checking_For_Updates]]
===== Checking For Updates
indexterm:[DNF Updates,checking for updates]
The quickest way to check for updates is to attempt to install any available updates by using the [command]#dnf upgrade# command as follows:
----
~]# dnf upgrade
Last metadata expiration check performed 1:24:32 ago on Thu May 14 23:23:51 2015.
Dependencies resolved.
Nothing to do.
Complete!
----
Note that [command]#dnf upgrade# installs only those updates that can be installed. If a package cannot be updated, because of dependency problems for example, it is skipped.
The [command]#dnf check-update# command can be used see which installed packages on your system have new versions available, however it does not mean that they can be successfully installed. This command is therefore mostly useful in scripts and for checking for updated packages that were not installed after running [command]#dnf upgrade#.
// See http://pastebin.test.redhat.com/pastebin.php?diff=283438 I cannot see the difference.
For example:
----
~]# dnf check-update
Using metadata from Mon Apr 20 16:34:10 2015 (2:42:10 hours old)
python.x86_64 2.7.9-6.fc22 updates
python-cryptography.x86_64 0.8.2-1.fc22 updates
python-libs.x86_64 2.7.9-6.fc22 updates
----
The packages in the above output are listed as having updated versions. The line in the example output tells us:
* `python` — the name of the package,
* `x86_64` — the CPU architecture the package was built for,
* `2.7.9` — the version of the updated package,
* `6.fc22` — the release of the updated package,
* `updates-testing` — the repository in which the updated package is located.
[[sec-Updating_Packages]]
===== Updating Packages
indexterm:[DNF Updates,updating packages]
You can choose to update a single package, multiple packages, or all packages at once. If any dependencies of the package, or packages, you update have updates available themselves, then they are updated too.
.Updating a Single Packageindexterm:[DNF Updates,updating a single package]
To update a single package, run the following command as `root`:
[subs="macros"]
----
dnf upgrade pass:quotes[_package_name_]
----
For example, to update the [package]*python* package, type:
----
~]# dnf upgrade python
Using metadata from Mon Apr 20 16:38:16 2015 (2:42:14 hours old)
Dependencies resolved.
==================================================================
Package Arch Version Repository Size
==================================================================
Upgrading:
python x86_64 2.7.9-6.fc22 updates 92 k
python-libs x86_64 2.7.9-6.fc22 updates 5.8 M
Transaction Summary
==================================================================
Upgrade 2 Packages
Total download size: 5.9 M
Is this ok [y/N]:
----
This output contains:
. `python.x86_64` — you can download and install new [package]*python* package.
. `python-libs.x86_64` — DNF has resolved that the [package]*python-libs-2.7.9-6.fc22.x86_64* package is a required dependency of the [package]*python* package.
. DNF presents the update information and then prompts you as to whether you want it to perform the update; DNF runs interactively by default. If you already know which transactions DNF plans to perform, you can use the [option]`-y` option to automatically answer [command]#yes# to any questions DNF may ask (in which case it runs non-interactively). However, you should always examine which changes DNF plans to make to the system so that you can easily troubleshoot any problems that might arise.
+
If a transaction does go awry, you can view DNF's transaction history by using the [command]#dnf history# command as described in <<sec-DNF-Transaction_History>>.
[[important-Important-Updating_and_Installing_Kernels_with_DNF]]
.Updating and installing kernels with DNF
[IMPORTANT]
====
DNF always *installs* a new kernel in the same sense that [application]*RPM* installs a new kernel when you use the command [command]#rpm -i kernel#. Therefore, you do not need to worry about the distinction between *installing* and *upgrading* a kernel package when you use the [command]#dnf# command: it will do the right thing, regardless of whether you are using the [command]#dnf upgrade# or [command]#dnf install# command.
When using [application]*RPM*, on the other hand, it is important to use the [command]#rpm -i kernel# command (which installs a new kernel) instead of [command]#rpm -u kernel# (which *replaces* the current kernel). See <<sec-Installing_and_Upgrading>> for more information on installing and updating kernels with [application]*RPM*.
====
.Updating All Packages and Their Dependenciesindexterm:[DNF Updates,updating all packages and dependencies]
To update all packages and their dependencies, enter [command]#dnf upgrade# without any arguments:
[subs="quotes, macros"]
----
[command]#dnf upgrade#
----
[[sec-Preserving_Configuration_File_Changes]]
===== Preserving Configuration File Changes
indexterm:[Configuration File Changes]
You will inevitably make changes to the configuration files installed by packages as you use your {MAJOROS} system. [application]*RPM*, which DNF uses to perform changes to the system, provides a mechanism for ensuring their integrity. See <<sec-Installing_and_Upgrading>> for details on how to manage changes to configuration files across package upgrades.
[[sec-Packages_and_Package_Groups]]
==== Packages and Package Groups
indexterm:[packages,packages and package groups]indexterm:[DNF,packages and package groups]
[[sec-Searching_Packages]]
===== Searching Packages
indexterm:[packages,searching packages with DNF,dnf search]indexterm:[DNF,searching packages with DNF,dnf search]
You can search all *RPM* package names and summaries by using the following command:
[subs="quotes, macros"]
----
[command]#dnf# [option]`search` _term_pass:attributes[{blank}]…
----
Add the [option]`all` to match against descriptions and URLs.
[subs="quotes, macros"]
----
[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:
----
~]# dnf search meld kompare
Loaded plugins: langpacks, presto, refresh-packagekit
============================== N/S Matched: meld ===============================
meld.noarch : Visual diff and merge tool
python-meld3.x86_64 : HTML/XML templating system for Python
============================= N/S Matched: kompare =============================
komparator.x86_64 : Kompare and merge two folders
Name and summary matches only, use "search all" for everything.
----
indexterm:[packages,searching for packages with DNF,dnf search]indexterm:[DNF,searching for packages with DNF,dnf search]
[[sec-Listing_Packages]]
===== Listing Packages
indexterm:[packages,listing packages with DNF,dnf search]indexterm:[DNF,listing packages with DNF,dnf list]
[command]#dnf list# and related commands provide information about packages, package groups, and repositories.
All of DNF's list commands allow you to filter the results by appending one or more _glob expressions_ as arguments. Glob expressions are normal strings of characters which contain one or more of the wildcard characters [command]#*# (which expands to match any character multiple times) and [command]#?# (which expands to match any one character).
[[note-Tip-Filtering_Results_with_Glob_Expressions]]
.Filtering results with glob expressions
[NOTE]
====
indexterm:[packages,listing packages with DNF,Glob expressions]indexterm:[DNF,listing packages with DNF,Glob expressions]
Be careful to escape the glob expressions when passing them as arguments to a [command]#dnf# command, otherwise the Bash shell will interpret these expressions as _pathname expansions_, and potentially pass all files in the current directory that match the globs to DNF. To make sure the glob expressions are passed to DNF as intended, either:
* escape the wildcard characters by preceding them with a backslash character; or,
* double-quote or single-quote the entire glob expression.
DNF searches only package names when using glob expressions. To search for a version of a package, include a dash and part of the version number as follows:
----
~]# dnf search kernel*-4*
Last metadata expiration check performed 2:46:09 ago on Thu May 14 23:23:51 2015.
Installed Packages
kernel.x86_64 4.0.0-1.fc22 @System
kernel.x86_64 4.0.2-300.fc22 @System
kernel-core.x86_64 4.0.0-1.fc22 @System
kernel-core.x86_64 4.0.2-300.fc22 @System
[output truncated]
----
See <<ex-Listing_all_ABRT_addons_and_plugins_using_glob_expressions>> and <<ex-Listing_available_packages_using_a_single_glob_expression_with_escaped_wildcards>> for an example usage of both these methods.
====
[command]#dnf list _glob_expression_pass:attributes[{blank}]…#:: Lists information on installed and available packages matching all glob expressions.
+
[[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:
----
~]# dnf list abrt-addon\* abrt-plugin\*
Last metadata expiration check performed 0:14:36 ago on Mon May 25 23:38:13 2015.
Installed Packages
abrt-addon-ccpp.x86_64 2.5.1-2.fc22 @System
abrt-addon-coredump-helper.x86_64 2.5.1-2.fc22 @System
abrt-addon-kerneloops.x86_64 2.5.1-2.fc22 @System
abrt-addon-pstoreoops.x86_64 2.5.1-2.fc22 @System
abrt-addon-python.x86_64 2.5.1-2.fc22 @System
abrt-addon-python3.x86_64 2.5.1-2.fc22 @System
abrt-addon-vmcore.x86_64 2.5.1-2.fc22 @System
abrt-addon-xorg.x86_64 2.5.1-2.fc22 @System
abrt-plugin-bodhi.x86_64 2.5.1-2.fc22 @System
Available Packages
abrt-addon-upload-watch.x86_64 2.5.1-2.fc22 fedora
----
====
indexterm:[packages,listing packages with DNF,dnf list all] indexterm:[DNF,listing packages with DNF,dnf list all] [command]#dnf list all#:: Lists all installed *and* available packages.
+
[[ex-Listing_all_installed_and_available_packages]]
.Listing all installed and available packages
====
----
~]# dnf list all
Last metadata expiration check performed 0:21:11 ago on Mon May 25 23:38:13 2015.
Installed Packages
NetworkManager.x86_64 1:1.0.2-1.fc22 @System
NetworkManager-libnm.x86_64 1:1.0.2-1.fc22 @System
PackageKit.x86_64 1.0.6-4.fc22 @System
PackageKit-glib.x86_64 1.0.6-4.fc22 @System
aajohan-comfortaa-fonts.noarch 2.004-4.fc22 @System
abrt.x86_64 2.5.1-2.fc22 @System
[output truncated]
----
====
indexterm:[packages,listing packages with DNF,dnf list installed] indexterm:[DNF,listing packages with DNF,dnf list installed] [command]#dnf list installed#:: Lists all packages installed on your system. The rightmost column in the output lists the repository from which the package was retrieved.
+
[[ex-Listing_installed_packages_using_a_double-quoted_glob_expression]]
.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:
----
~]# dnf list installed "krb?-*"
Last metadata expiration check performed 0:34:45 ago on Mon May 25 23:38:13 2015.
Installed Packages
krb5-libs.x86_64 1.13.1-3.fc22 @System
krb5-workstation.x86_64 1.13.1-3.fc22 @System
----
====
indexterm:[packages,listing packages with DNF,dnf list available] indexterm:[DNF,listing packages with DNF,dnf list available] [command]#dnf list available#:: Lists all available packages in all enabled repositories.
+
[[ex-Listing_available_packages_using_a_single_glob_expression_with_escaped_wildcards]]
.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:
----
~]# dnf list available gstreamer\*plugin\*
Last metadata expiration check performed 0:42:15 ago on Mon May 25 23:38:13 2015.
Available Packages
gstreamer-plugin-crystalhd.i686 3.10.0-8.fc22 fedora
gstreamer-plugin-crystalhd.x86_64 3.10.0-8.fc22 fedora
gstreamer-plugins-bad-free.i686 0.10.23-24.fc22 fedora
gstreamer-plugins-bad-free.x86_64 0.10.23-24.fc22 fedora
gstreamer-plugins-bad-free-devel.i686 0.10.23-24.fc22 fedora
gstreamer-plugins-bad-free-devel.x86_64 0.10.23-24.fc22 fedora
[output truncated]
----
====
indexterm:[packages,listing packages with DNF,dnf group list] indexterm:[DNF,listing packages with DNF,dnf group list] [command]#dnf group list#:: Lists all package groups.
+
[[ex-Listing_all_package_groups]]
.Listing all package groups
====
----
~]# dnf group list
Loaded plugins: langpacks, presto, refresh-packagekit
Setting up Group Process
Installed Groups:
Administration Tools
Design Suite
Dial-up Networking Support
Fonts
GNOME Desktop Environment
[output truncated]
----
====
indexterm:[packages,listing packages with DNF,dnf repolist] indexterm:[DNF,listing packages with DNF,dnf repolist] [command]#dnf repolist#:: Lists the repository ID, name, and number of packages it provides for each *enabled* repository.
+
[[ex-Listing_enabled_repositories]]
.Listing enabled repositories
====
----
~]# dnf repolist
Last metadata expiration check performed 0:48:29 ago on Mon May 25 23:38:13 2015.
repo id repo name status
*fedora Fedora 22 - x86_64 44,762
*updates Fedora 22 - x86_64 - Updates 0
----
====
indexterm:[packages,listing packages from a single repository with DNF,dnf repository-packages] indexterm:[DNF,listing packages from a single repository with DNF,dnf repository-packages] [command]#dnf repository-packages _repo_id_ list#:: Lists the packages from the specified repository.
+
[[ex-Listing_packages_from_a_single_repositories]]
.Listing packages from a single repository
====
----
~]# dnf repository-packages fedora list [option]
Last metadata expiration check performed 1:38:25 ago on Wed May 20 22:16:16 2015.
Installed Packages
PackageKit.x86_64 1.0.6-3.fc22 @System
PackageKit-glib.x86_64 1.0.6-3.fc22 @System
aajohan-comfortaa-fonts.noarch 2.004-4.fc22 @System
[output truncated]
----
The default action is to list all packages available and installed from the repository specified. Add the [option]`available` or [option]`installed` option to list only those packages available or installed from the specified repository.
====
[[sec-Displaying_Package_Information]]
===== Displaying Package Information
indexterm:[packages,displaying packages with DNF,dnf info]indexterm:[DNF,displaying packages with DNF,dnf info]
To display information about one or more packages, use a command as follows:
[subs="macros"]
----
dnf info pass:quotes[_package_name_]…
----
For example, to display information about the [package]*abrt* package, type:
----
~]# dnf info abrt
Last metadata expiration check: 1:09:44 ago on Tue May 31 06:51:51 2016.
Installed Packages
Name : abrt
Arch : x86_64
Epoch : 0
Version : 2.8.1
Release : 1.fc24
Size : 2.2 M
Repo : @System
From repo : updates-testing
Summary : Automatic bug detection and reporting tool
URL : https://abrt.readthedocs.org/
License : GPLv2+
Description : abrt is a tool to help users to detect defects in applications and
: to create a bug report with all information needed by maintainer to fix it.
: It uses plugin system to extend its functionality.
----
indexterm:[packages,displaying packages,dnf info]indexterm:[DNF,displaying packages,dnf info]
The [command]#dnf info _package_name_pass:attributes[{blank}]# command is similar to the [command]#rpm -q --info _package_name_pass:attributes[{blank}]# command, but provides as additional information the name of the DNF repository the RPM package was installed from (look for the `From repo:` line in the output). The [command]#dnf info# command shows only the newest available package if there is a newer version available than the one installed. The [command]#dnf repoquery# command can show *all* installed and available packages.
To display information about all available packages, both installed and available from a repository, use a command as follows:
[subs="macros"]
----
dnf repoquery pass:quotes[_package_name_] --info
----
For example, to display information about the [package]*abrt* package, type:
----
~]# dnf repoquery abrt --info
Last metadata expiration check: 1:01:44 ago on Tue May 31 06:51:51 2016.
Name : abrt
Version : 2.8.1
Release : 1.fc24
Architecture: x86_64
Size : 2318452
License : GPLv2+
Source RPM : abrt-2.8.1-1.fc24.src.rpm
Build Date : 2016-05-25 08:54
Packager : Fedora Project
URL : https://abrt.readthedocs.org/
Summary : Automatic bug detection and reporting tool
Description :
abrt is a tool to help users to detect defects in applications and
to create a bug report with all information needed by maintainer to fix it.
It uses plugin system to extend its functionality.
----
See the [command]#dnf repoquery# usage statement for more options:
[subs="quotes, macros"]
----
~]$ [command]#dnf repoquery -h#
usage: dnf [options] COMMAND
_output truncated_
----
[[sec-Installing]]
===== Installing Packages
indexterm:[packages,installing with DNF]indexterm:[DNF,installing with DNF]
DNF allows you to install both a single package and multiple packages, as well as a package group of your choice.
.Installing Individual Packages
To install a single package and all of its non-installed dependencies, enter a command in the following form:
[subs="macros"]
----
dnf install pass:quotes[_package_name_]
----
You can also install multiple packages simultaneously by appending their names as arguments:
[subs="macros"]
----
dnf install pass:quotes[_package_name_] pass:quotes[_package_name_]…
----
If you are installing packages on a _multilib_ system, such as an AMD64 or Intel64 machine, you can specify the architecture of the package, as long as it is available in an enabled repository, by appending _.arch_ to the package name. For example, to install the [package]*sqlite2* package for `i586`, type:
----
~]# dnf install sqlite2.i586
----
You can use glob expressions to quickly install multiple similarly-named packages:
----
~]# dnf install audacious-plugins-\*
----
In addition to package names and glob expressions, you can also provide file names to [command]#dnf install#. If you know the name of the binary you want to install, but not its package name, you can give [command]#dnf install# the path name:
----
~]# dnf install /usr/sbin/named
----
[command]#dnf# then searches through its package lists, finds the package which provides `/usr/sbin/named`, if any, and prompts you as to whether you want to install it.
[[note-Finding_which_package_owns_a_file]]
.Finding which package owns a file
[NOTE]
====
If you know you want to install the package that contains the `named` binary, but you do not know in which `/usr/bin` or `/usr/sbin` directory the file is installed, use the [command]#dnf provides# command with a glob expression:
----
~]# dnf provides "*bin/named"
Using metadata from Thu Apr 16 13:41:45 2015 (4:23:50 hours old)
bind-32:9.10.2-1.fc22.x86_64 : The Berkeley Internet Name Domain (BIND) DNS (Domain Name System) server
Repo : @System
----
[command]#dnf provides "*/pass:attributes[{blank}]_file_name_pass:attributes[{blank}]"# will find all the packages that contain _file_name_.
====
.Installing a Package Groupindexterm:[packages,installing a package group with DNF]indexterm:[DNF,installing a package group with DNF]
A package group is similar to a package: it is not useful by itself, but installing one pulls a group of dependent packages that serve a common purpose. A package group has a name and a _groupid_ (*GID*). The [command]#dnf group list -v# command lists the names of all package groups, and, next to each of them, their groupid in parentheses. The groupid is always the term in the last pair of parentheses, such as `kde-desktop-environment` in the following example:
----
~]# dnf -v group list kde\*
cachedir: /var/cache/dnf/x86_64/22
Loaded plugins: builddep, config-manager, copr, playground, debuginfo-install, download, generate_completion_cache, kickstart, needs-restarting, noroot, protected_packages, Query, reposync, langpacks
initialized Langpacks plugin
DNF version: 0.6.5
repo: using cache for: fedora
not found deltainfo for: Fedora 22 - x86_64
not found updateinfo for: Fedora 22 - x86_64
repo: using cache for: updates-testing
repo: using cache for: updates
not found updateinfo for: Fedora 22 - x86_64 - Updates
Using metadata from Thu Apr 16 13:41:45 2015 (4:37:51 hours old)
Available environment groups:
KDE Plasma Workspaces (kde-desktop-environment)
----
You can install a package group by passing its full group name (without the groupid part) to [command]#group install#:
[subs="macros"]
----
dnf group install pass:quotes[_group_name_]
----
Multi-word names must be quoted.
You can also install by groupid:
[subs="quotes, macros"]
----
[command]#dnf# [option]`group install` _groupid_
----
You can even pass the groupid, or quoted name, to the [command]#install# command if you prepend it with an @-symbol (which tells [command]#dnf# that you want to perform a [command]#group install#):
[subs="quotes, macros"]
----
[command]#dnf# [option]`install` @pass:attributes[{blank}]_group_
----
For example, the following are alternative but equivalent ways of installing the `KDE Plasma Workspaces` group:
----
~]# dnf group install "KDE Plasma Workspaces"
~]# dnf group install kde-desktop-environment
~]# dnf install @kde-desktop-environment
----
[[sec-Removing]]
===== Removing Packages
indexterm:[packages,uninstalling packages with DNF]indexterm:[DNF,uninstalling packages with DNF]
Similarly to package installation, DNF allows you to uninstall (remove in [application]*RPM* and DNF terminology) both individual packages and a package group.
.Removing Individual Packagesindexterm:[packages,uninstalling packages with DNF,dnf remove package_name]indexterm:[DNF,uninstalling packages with DNF,dnf remove package_name]
To uninstall a particular package, as well as any packages that depend on it, run the following command as `root`:
[subs="macros"]
----
dnf remove pass:quotes[_package_name_]…
----
As when you install multiple packages, you can remove several at once by adding more package names to the command. For example, to remove [package]*totem*, [package]*rhythmbox*, and [package]*sound-juicer*, type the following at a shell prompt:
----
~]# dnf remove totem rhythmbox sound-juicer
----
Similar to [command]#install#, [command]#remove# can take these arguments:
* package names
* glob expressions
* file lists
* package provides
[[warning-WarningRemoving_a_Package_when_Other_Packages_Depend_On_It]]
.Removing a package when other packages depend on it
[WARNING]
====
DNF is not able to remove a package without also removing packages which depend on it. This type of operation can only be performed by [application]*RPM*, is not advised, and can potentially leave your system in a non-functioning state or cause applications to misbehave and terminate unexpectedly. For further information, refer to <<s2-rpm-uninstalling>> in the [application]*RPM* chapter.
====
.Removing a Package Group
You can remove a package group using syntax congruent with the [command]#install# syntax:
[subs="quotes, macros"]
----
[command]#dnf# [option]`group remove` _group_
----
[subs="quotes, macros"]
----
[command]#dnf# [option]`remove` @pass:attributes[{blank}]_group_
----
The following are alternative but equivalent ways of removing the `KDE Plasma Workspaces` group:
----
~]# dnf group remove "KDE Plasma Workspaces"
~]# dnf group remove kde-desktop-environment
~]# dnf remove @kde-desktop-environment
----
[[sec-DNF-Transaction_History]]
===== Working with Transaction History
The [command]#dnf history# command allows users to review information about a timeline of DNF transactions, the dates and times on when they occurred, the number of packages affected, whether transactions succeeded or were aborted, and if the RPM database was changed between transactions. Additionally, this command can be used to undo or redo certain transactions.
.Listing Transactions
To display a list of all transactions, as `root`, either run [command]#dnf history# with no additional arguments, or enter the following command:
[subs="quotes, macros"]
----
[command]#dnf# [option]`history` [option]`list`
----
To display only transactions in a given range, use the command in the following form:
[subs="macros"]
----
dnf history list pass:quotes[_start_id_]..pass:quotes[_end_id_]
----
You can also list only transactions regarding a particular package or packages. To do so, use the command with a package name or a glob expression:
[subs="macros"]
----
dnf history list pass:quotes[_glob_expression_]…
----
For example, the list of first five transactions may look as follows:
----
~]# dnf history list 1..4
Using metadata from Thu Apr 16 13:41:45 2015 (5:47:31 hours old)
ID | Login user | Date a | Action | Altere
-------------------------------------------------------------------------------
4 | root <root> | 2015-04-16 18:35 | Erase | 1
3 | root <root> | 2015-04-16 18:34 | Install | 1
2 | root <root> | 2015-04-16 17:53 | Install | 1
1 | System <unset> | 2015-04-16 14:14 | Install | 668 E
----
The [command]#dnf history list# command produces tabular output with each row consisting of the following columns:
* `ID` &mdash; an integer value that identifies a particular transaction.
* `Login user` &mdash; the name of the user whose login session was used to initiate a transaction. This information is typically presented in the `pass:attributes[{blank}]_Full Name_ <pass:attributes[{blank}]_username>_pass:attributes[{blank}]` form, however sometimes the command used to perform the transaction is displayed. For transactions that were not issued by a user (such as an automatic system update), `System <unset>` is used instead.
* `Date and time` &mdash; the date and time when a transaction was issued.
* `Action(s)` &mdash; a list of actions that were performed during a transaction as described in <<tabl-DNF-Transaction_History-Actions>>.
* `Altered` &mdash; the number of packages that were affected by a transaction, possibly followed by additional information.
[[tabl-DNF-Transaction_History-Actions]]
.Possible values of the Action(s) field
[options="header"]
|===
|Action|Abbreviation|Description
|`Downgrade`|`D`|At least one package has been downgraded to an older version.
|`Erase`|`E`|At least one package has been removed.
|`Install`|`I`|At least one new package has been installed.