January 2015 - docs-commits - Fedora Mailing-Lists

[networking-guide] master: Update entities to 21 and year to 2015 (1c7a9c9)

by stephenw

Repository : http://git.fedorahosted.org/cgit/docs/networking-guide.git On branch : master >--------------------------------------------------------------- commit 1c7a9c9768574aa36597533e0323d7774e214d48 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Sun Jan 18 15:59:04 2015 +0100 Update entities to 21 and year to 2015 >--------------------------------------------------------------- en-US/Networking_Guide.ent | 8 ++++---- 1 files changed, 4 insertions(+), 4 deletions(-) diff --git a/en-US/Networking_Guide.ent b/en-US/Networking_Guide.ent index b961ceb..7971cc0 100644 --- a/en-US/Networking_Guide.ent +++ b/en-US/Networking_Guide.ent @@ -1,13 +1,13 @@  <!ENTITY PRODUCT "Fedora Documentation"> <!ENTITY BOOKID "networking-guide"> -<!ENTITY YEAR "2014"> +<!ENTITY YEAR "2015"> <!ENTITY HOLDER "Red Hat, Inc. and others"> <!ENTITY BUGZILLA '<ulink url="https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&component...;" />'> <!ENTITY BZURL 'https://bugzilla.redhat.com/enter_bug.cgi?product=&PRODUCT;&component...;'>  <!ENTITY MAJOROS "Fedora"> -<!ENTITY MAJOROSVER "Fedora 20"> +<!ENTITY MAJOROSVER "Fedora 21"> <!ENTITY OSORG "The Fedora Project"> -<!ENTITY PKGOS "fc20"> -<!ENTITY PRODVER "20"> +<!ENTITY PKGOS "fc21"> +<!ENTITY PRODVER "21">

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Change wrong entity to "Fedora"

by stephenw

commit 5ed371de0c83e56fd5531d6f47db06076d732ef0 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Sat Dec 13 09:18:26 2014 +0100 Change wrong entity to "Fedora" en-US/Working_with_Kernel_Modules.xml | 20 ++++++++++---------- 1 files changed, 10 insertions(+), 10 deletions(-) --- diff --git a/en-US/Working_with_Kernel_Modules.xml b/en-US/Working_with_Kernel_Modules.xml index 1af0060..214f01c 100644 --- a/en-US/Working_with_Kernel_Modules.xml +++ b/en-US/Working_with_Kernel_Modules.xml @@ -478,10 +478,10 @@ virtio-net</screen> <section id="sect-signing-kernel-modules-for-secure-boot"> <title>Signing Kernel Modules for Secure Boot</title> <para> - &PRODUCT; includes support for the UEFI Secure Boot feature, which means that &PRODUCT; can be installed and run on systems where UEFI Secure Boot is enabled. <footnote><para>&PRODUCT; does not require the use of Secure Boot on UEFI systems.</para></footnote> When Secure Boot is enabled, the EFI operating system boot loaders, the &PRODUCT; kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The &PRODUCT; 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 &PRODUCT; public keys. These signed executable binaries and embedded keys enable &PRODUCT; 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><para>Not all UEFI-based systems include support for Secure Boot.</para></footnote> + 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><para>Fedora does not require the use of Secure Boot on UEFI systems.</para></footnote> 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><para>Not all UEFI-based systems include support for Secure Boot.</para></footnote> </para> <para> - The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with &PRODUCT; 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. + 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. </para> <section id="sect-prerequisites"> @@ -544,7 +544,7 @@ virtio-net</screen> <section id="sect-kernel-module-authentication"> <title>Kernel Module Authentication</title> <para> - In &PRODUCT;, 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. + 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. </para> <section id="sect-sources-for-public-keys-used-to-authenticate-kernel-modules"> @@ -618,13 +618,13 @@ virtio-net</screen> 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. </para> <para> - You can display information about the keys on the system key rings using the <command>keyctl</command> utility. The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is not enabled. + You can display information about the keys on the system key rings using the <command>keyctl</command> utility. The following is abbreviated example output from a Fedora system where UEFI Secure Boot is not enabled. </para> <screen>~]# <command>keyctl list %:.system_keyring</command> 1 key in keyring: 61139991: ---lswrv 0 0 asymmetric: Fedora kernel signing key: 1fc9e68f7419556348fdee2fdeb7ff9da6337b</screen> <para> - The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is enabled. + The following is abbreviated example output from a Fedora system where UEFI Secure Boot is enabled. </para> <screen>~]# <command>keyctl list %:.system_keyring</command> 6 keys in keyring: @@ -743,7 +743,7 @@ virtio-net</screen> <procedure> <step> <para> - The <command>openssl</command> tool can be used to generate a key pair that satisfies the requirements for kernel module signing in &PRODUCT;. 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.</para> + The <command>openssl</command> 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.</para> <screen>~]# <command>cat << EOF > <replaceable>configuration_file</replaceable>.config</command> [ req ] default_bits = 4096 @@ -789,7 +789,7 @@ EOF</screen> <section id="sect-enrolling-public-key-on-target-system"><title>Enrolling Public Key on Target System</title> <para> - When &PRODUCT; 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. + 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. </para> <section id="sect-factory-firmware-image-including-public-key"><title>Factory Firmware Image Including Public Key</title> <para> @@ -801,7 +801,7 @@ EOF</screen> 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 <emphasis>enrollment</emphasis> 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. </para> <para> - It is also possible to write an enrollment image that runs under &PRODUCT;. However, the &PRODUCT; image must be properly signed by a private key that corresponds to a public key that is already in the KEK 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. </para> <para> The construction of either type of key enrollment images requires assistance from the platform vendor. @@ -809,7 +809,7 @@ EOF</screen> </section> <section id="sect-system-administrator-manually-adding-public-key-to-the-mok-list"><title>System Administrator Manually Adding Public Key to the MOK List</title> <para> - The Machine Owner Key (MOK) facility is a feature that is supported by &PRODUCT; and can be used to augment the UEFI Secure Boot key database. When &PRODUCT; 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 &PRODUCT; <command>mokutil</command> utility. + 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</command> utility. </para> <para> 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 <emphasis>physically present</emphasis> 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. @@ -820,7 +820,7 @@ EOF</screen> <procedure> <step> <para> - Request addition of your public key to the MOK list using a &PRODUCT; userspace utility: + Request addition of your public key to the MOK list using a Fedora userspace utility: </para> <screen>~]# <command>mokutil <option>--import</option> <filename>my_signing_key_pub.der</filename></command></screen> <para>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Signing Kernel Modules for Secure Boot

by stephenw

commit f480d5b3e589693d4515fd634b20ef252a6e64f8 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Sat Dec 13 09:08:27 2014 +0100 Signing Kernel Modules for Secure Boot en-US/Working_with_Kernel_Modules.xml | 445 +++++++++++++++++++++++++++++++++ 1 files changed, 445 insertions(+), 0 deletions(-) --- diff --git a/en-US/Working_with_Kernel_Modules.xml b/en-US/Working_with_Kernel_Modules.xml index fe84be1..1af0060 100644 --- a/en-US/Working_with_Kernel_Modules.xml +++ b/en-US/Working_with_Kernel_Modules.xml @@ -475,6 +475,451 @@ virtio-net</screen> </section> + <section id="sect-signing-kernel-modules-for-secure-boot"> + <title>Signing Kernel Modules for Secure Boot</title> + <para> + &PRODUCT; includes support for the UEFI Secure Boot feature, which means that &PRODUCT; can be installed and run on systems where UEFI Secure Boot is enabled. <footnote><para>&PRODUCT; does not require the use of Secure Boot on UEFI systems.</para></footnote> When Secure Boot is enabled, the EFI operating system boot loaders, the &PRODUCT; kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The &PRODUCT; 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 &PRODUCT; public keys. These signed executable binaries and embedded keys enable &PRODUCT; 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><para>Not all UEFI-based systems include support for Secure Boot.</para></footnote> + </para> + <para> + The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with &PRODUCT; 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. + </para> + + <section id="sect-prerequisites"> + <title>Prerequisites</title> + <para> + In order to enable signing of externally built modules, the tools listed in the following table are required to be installed on the system. + </para> + + <table frame='all' id="table-required-tools"><title>Required Tools</title> + <tgroup cols='4' align='left'> + <thead> + <row> + <entry>Tool</entry> + <entry>Provided by Package</entry> + <entry>Used on</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>openssl</command></entry> + <entry><package>openssl</package></entry> + <entry>Build system</entry> + <entry>Generates public and private X.509 key pair</entry> + </row> + <row> + <entry><command>sign-file</command></entry> + <entry><package>kernel-devel</package></entry> + <entry>Build system</entry> + <entry>Perl script used to sign kernel modules</entry> + </row> + <row> + <entry><command>perl</command></entry> + <entry><package>perl</package></entry> + <entry>Build system</entry> + <entry>Perl interpreter used to run the signing script</entry> + </row> + <row> + <entry><command>mokutil</command></entry> + <entry><package>mokutil</package></entry> + <entry>Target system</entry> + <entry>Optional tool used to manually enroll the public key</entry> + </row> + <row> + <entry><command>keyctl</command></entry> + <entry><package>keyutils</package></entry> + <entry>Target system</entry> + <entry>Optional tool used to display public keys in the system key ring</entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + 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. + </para> + </note> + </section> + + <section id="sect-kernel-module-authentication"> + <title>Kernel Module Authentication</title> + <para> + In &PRODUCT;, 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. + </para> + + <section id="sect-sources-for-public-keys-used-to-authenticate-kernel-modules"> + <title>Sources For Public Keys Used To Authenticate Kernel Modules</title> + <para> + 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 <xref linkend="table-sources-for-system-key-rings" /> + </para> + + <table frame='all' id="table-sources-for-system-key-rings"><title>Sources For System Key Rings</title> + <tgroup cols='4' align='left'> + <thead> + <row> + <entry>Source of X.509 Keys</entry> + <entry>User Ability to Add Keys</entry> + <entry>UEFI Secure Boot State</entry> + <entry>Keys Loaded During Boot</entry> + </row> + </thead> + <tbody> + <row> + <entry>Embedded in kernel</entry> + <entry>No</entry> + <entry>-</entry> + <entry><systemitem>.system_keyring</systemitem></entry> + </row> + <row> + <entry morerows="1">UEFI Secure Boot "db"</entry> + <entry morerows="1">Limited</entry> + <entry>Not enabled</entry> + <entry>No</entry> + </row> + <row> + <entry>Enabled</entry> + <entry><systemitem>.system_keyring</systemitem></entry> + </row> + <row> + <entry morerows="1">UEFI Secure Boot "dbx"</entry> + <entry morerows="1">Limited</entry> + <entry>Not enabled</entry> + <entry>No</entry> + </row> + <row> + <entry>Enabled</entry> + <entry><systemitem>.system_keyring</systemitem></entry> + </row> + <row> + <entry morerows="1">Embedded in <systemitem>shim.efi</systemitem> boot loader</entry> + <entry morerows="1">No</entry> + <entry>Not enabled</entry> + <entry>No</entry> + </row> + <row> + <entry>Enabled</entry> + <entry><systemitem>.system_keyring</systemitem></entry> + </row> + <row> + <entry morerows="1">Machine Owner Key (MOK) list</entry> + <entry morerows="1">Yes</entry> + <entry>Not enabled</entry> + <entry>No</entry> + </row> + <row> + <entry>Enabled</entry> + <entry><systemitem>.system_keyring</systemitem></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + 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. + </para> + <para> + You can display information about the keys on the system key rings using the <command>keyctl</command> utility. The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is not enabled. + </para> +<screen>~]# <command>keyctl list %:.system_keyring</command> +1 key in keyring: + 61139991: ---lswrv 0 0 asymmetric: Fedora kernel signing key: 1fc9e68f7419556348fdee2fdeb7ff9da6337b</screen> + <para> + The following is abbreviated example output from a &PRODUCT; system where UEFI Secure Boot is enabled. + </para> +<screen>~]# <command>keyctl list %:.system_keyring</command> +6 keys in keyring: +...asymmetric: Red Hat Enterprise Linux Driver Update Program (key 3): bf57f3e87... +...asymmetric: Red Hat Secure Boot (CA key 1): 4016841644ce3a810408050766e8f8a29... +...asymmetric: Microsoft Corporation UEFI CA 2011: 13adbf4309bd82709c8cd54f316ed... +...asymmetric: Microsoft Windows Production PCA 2011: a92902398e16c49778cd90f99e... +...asymmetric: Red Hat Enterprise Linux kernel signing key: 4249689eefc77e95880b... +...asymmetric: Red Hat Enterprise Linux kpatch signing key: 4d38fd864ebe18c5f0b7...</screen> + <para> + The above output shows the addition of two keys from the UEFI Secure Boot "db" keys plus the <computeroutput>Red Hat Secure Boot (CA key 1)</computeroutput> which is embedded in the <systemitem>shim.efi</systemitem> boot loader. You can also look for the kernel console messages that identify the keys with an UEFI Secure Boot related source, that is UEFI Secure Boot db, embedded shim, and MOK list. + </para> +<screen>~]# <command>dmesg | grep 'EFI: Loaded cert'</command> +[5.160660] EFI: Loaded cert 'Microsoft Windows Production PCA 2011: a9290239... +[5.160674] EFI: Loaded cert 'Microsoft Corporation UEFI CA 2011: 13adbf4309b... +[5.165794] EFI: Loaded cert 'Red Hat Secure Boot (CA key 1): 4016841644ce3a8...</screen> + </section> + <section id="sect-kernel-module-authentication-requirements"> + <title> + Kernel Module Authentication Requirements + </title> + <para> + If UEFI Secure Boot is enabled or if the <option>module.sig_enforce</option> 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><para>Provided that the public key is not on the system black list key ring.</para></footnote> If UEFI Secure Boot is disabled and if the <option>module.sig_enforce</option> 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 <xref linkend="table-kernel-module-authentication-requirements-for-loading"/>. + </para> + + <table frame='all' id="table-kernel-module-authentication-requirements-for-loading"><title>Kernel Module Authentication Requirements for Loading</title> + <tgroup cols='6' align='left'> + <thead> + <row> + <entry>Module Signed</entry> + <entry>Public Key Found and Signature Valid</entry> + <entry>UEFI Secure Boot State</entry> + <entry>module.sig_enforce</entry> + <entry>Module Load</entry> + <entry>Kernel Tainted</entry> + </row> + </thead> + <tbody> + <row> + <entry morerows="2">Unsigned</entry> + <entry morerows="2">-</entry> + <entry>Not enabled</entry> + <entry>Not enabled</entry> + <entry>Succeeds</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Not enabled</entry> + <entry>Enabled</entry> + <entry>Fails</entry> + <entry></entry> + </row> + <row> + <entry>Enabled</entry> + <entry>-</entry> + <entry>Fails</entry> + <entry>-</entry> + </row> + + <row> + <entry morerows="2">Signed</entry> + <entry morerows="2">No</entry> + <entry>Not enabled</entry> + <entry>Not enabled</entry> + <entry>Succeeds</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Not enabled</entry> + <entry>Enabled</entry> + <entry>Fails</entry> + <entry>-</entry> + </row> + <row> + <entry>Enabled</entry> + <entry>-</entry> + <entry>Fails</entry> + <entry>-</entry> + </row> + + <row> + <entry morerows="2">Signed</entry> + <entry morerows="2">Yes</entry> + <entry>Not enabled</entry> + <entry>Not enabled</entry> + <entry>Succeeds</entry> + <entry>No</entry> + </row> + <row> + <entry>Not enabled</entry> + <entry>Enabled</entry> + <entry>Succeeds</entry> + <entry>No</entry> + </row> + <row> + <entry>Enabled</entry> + <entry>-</entry> + <entry>Succeeds</entry> + <entry>No</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + 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. + </para> + </section> + </section> + + <section id="sect-generating-a-public-private-x509-key-pair"> + <title>Generating a Public and Private X.509 Key Pair</title> + <para> + 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. + </para> + <procedure> + <step> + <para> + The <command>openssl</command> tool can be used to generate a key pair that satisfies the requirements for kernel module signing in &PRODUCT;. 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.</para> +<screen>~]# <command>cat << EOF > <replaceable>configuration_file</replaceable>.config</command> +[ req ] +default_bits = 4096 +distinguished_name = req_distinguished_name +prompt = no +string_mask = utf8only +x509_extensions = myexts + +[ req_distinguished_name ] +O = <replaceable>Organization</replaceable> +CN = <replaceable>Organization signing key</replaceable> +emailAddress = <replaceable>E-mail address</replaceable> + +[ myexts ] +basicConstraints=critical,CA:FALSE +keyUsage=digitalSignature +subjectKeyIdentifier=hash +authorityKeyIdentifier=keyid +EOF</screen> + </step> + <step> + <para> + 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 <filename><replaceable>public_key</replaceable>.der</filename> file and the private key will be written to the <filename><replaceable>private_key</replaceable>.priv</filename> file. + </para> + +<screen>~]# <command>openssl req -x509 -new -nodes -utf8 -sha256 -days 36500 \ +> -batch -config <replaceable>configuration_file</replaceable>.config -outform DER \ +> -out <replaceable>public_key</replaceable>.der \ +> -keyout <replaceable>private_key</replaceable>.priv</command></screen> + </step> + <step> + <para> + Enroll your public key on all systems where you want to authenticate and load your kernel module. + </para> + </step> + </procedure> +<warning> + <para> + 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. + </para> +</warning> + </section> + + <section id="sect-enrolling-public-key-on-target-system"><title>Enrolling Public Key on Target System</title> + <para> + When &PRODUCT; 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. + </para> + <section id="sect-factory-firmware-image-including-public-key"><title>Factory Firmware Image Including Public Key</title> + <para> + 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. + </para> + </section> + <section id="sect-executable-key-enrollment-image-adding-public-key"><title>Executable Key Enrollment Image Adding Public Key</title> + <para> + 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 <emphasis>enrollment</emphasis> 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. + </para> + <para> + It is also possible to write an enrollment image that runs under &PRODUCT;. However, the &PRODUCT; image must be properly signed by a private key that corresponds to a public key that is already in the KEK database. + </para> + <para> + The construction of either type of key enrollment images requires assistance from the platform vendor. + </para> + </section> + <section id="sect-system-administrator-manually-adding-public-key-to-the-mok-list"><title>System Administrator Manually Adding Public Key to the MOK List</title> + <para> + The Machine Owner Key (MOK) facility is a feature that is supported by &PRODUCT; and can be used to augment the UEFI Secure Boot key database. When &PRODUCT; 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 &PRODUCT; <command>mokutil</command> utility. + </para> + <para> + 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 <emphasis>physically present</emphasis> 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. + </para> + <para> + Follow these steps to add your public key to the MOK list: + </para> + <procedure> + <step> + <para> + Request addition of your public key to the MOK list using a &PRODUCT; userspace utility: + </para> +<screen>~]# <command>mokutil <option>--import</option> <filename>my_signing_key_pub.der</filename></command></screen> + <para> + You will be asked to enter and confirm a password for this MOK enrollment request. + </para> + </step> + <step> + <para> + Reboot the machine. + </para> + </step> + <step> + <para> + The pending MOK key enrollment request will be noticed by <systemitem>shim.efi</systemitem> and it will launch <systemitem>MokManager.efi</systemitem> 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. + </para> + </step> + </procedure> + <para> + 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. + </para> + </section> + </section> + <section id="sect-signing-kernel-module-with-the-private-key"> + <title>Signing Kernel Module with the Private Key</title> + <para> + 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: + </para> + + <procedure> + <step> + <para> + Build your <filename>my_module.ko</filename> module the standard way: + </para> +<screen>~]# <command>make -C /usr/src/kernels/$(uname -r) M=$PWD modules</command></screen> + </step> + <step> + <para> + 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. + </para> +<screen>~]# <command>perl /usr/src/kernels/$(uname -r)/scripts/sign-file \ +> sha256 \ +> my_signing_key.priv \ +> my_signing_key_pub.der \ +> my_module.ko</command></screen> + </step> + </procedure> + <para> + Your kernel module is in ELF image format and this script computes and appends the signature directly to the ELF image in your <filename>my_module.ko</filename> file. The <command>modinfo</command> utility can be used to display information about the kernel module's signature, if it is present. For information on using the utility, see <xref linkend="sec-Displaying_Information_About_a_Module" />. + </para> + <para> + 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</command> will not be able to display the signature on your kernel module. + </para> + <para> + 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. + </para> + </section> + <section id="sect-loading-signed-kernel-module"> + <title>Loading Signed Kernel Module</title> + <para> + 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</command> to add your public key to the MOK list and you will manually load your kernel module with <command>modprobe</command>. + </para> + <procedure> + <step> + <para> + 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</command> as root. Since your public key has not been enrolled yet, it should not be displayed in the output of the command. + </para> + </step> + <step> + <para> + Request enrollment of your public key. + </para> +<screen>~]# <command>mokutil --import <replaceable>my_signing_key_pub</replaceable>.der</command></screen> + </step> + <step> + <para> + Reboot, and complete the enrollment at the UEFI console. + </para> +<screen>~]# <command>reboot</command></screen> + </step> + + <step> + <para> + After the system reboots, verify the keys on the system key ring again. + </para> +<screen>~]# <command>keyctl list %:.system_keyring</command></screen> + </step> + <step> + <para> + You should now be able to load your kernel module successfully. + </para> +<screen>~]# <command>modprobe -v <replaceable>my_module</replaceable></command> +insmod /lib/modules/3.17.4-302.fc21.x86_64/extra/<replaceable>my_module</replaceable>.ko +~]# <command>lsmod | grep <replaceable>my_module</replaceable></command> +<replaceable>my_module</replaceable> 12425 0</screen> + </step> + </procedure> + </section> + </section> + <section id="s1-kernel-modules-additional-resources"> <title>Additional Resources</title>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Changing entities

by stephenw

commit e2b502e857d5d291783794833703ae6ee4592b7a Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Sat Dec 13 09:52:39 2014 +0100 Changing entities en-US/Working_with_the_GRUB_2_Boot_Loader.xml | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) --- diff --git a/en-US/Working_with_the_GRUB_2_Boot_Loader.xml b/en-US/Working_with_the_GRUB_2_Boot_Loader.xml index d465e8c..7185dec 100644 --- a/en-US/Working_with_the_GRUB_2_Boot_Loader.xml +++ b/en-US/Working_with_the_GRUB_2_Boot_Loader.xml @@ -952,10 +952,10 @@ Updating the password file results in a file with the incorrect SELinux security <section id="sec-UEFI_Secure_Boot_Support_in_Fedora"> <title>UEFI Secure Boot Support in Fedora</title> <para> - &PRODUCT; includes support for the UEFI Secure Boot feature, which means that &PRODUCT; 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 Hat are signed by the UEFI CA certificate. + &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 Hat are signed by the UEFI CA certificate. </para> - <para> - If you want to load externally built drivers — drivers that are not provided on the &PRODUCT; Linux DVD — you must make sure these drivers are signed as well. + <para> + If you want to load externally built drivers — drivers that are not provided on the &MAJOROS; Linux DVD — you must make sure these drivers are signed as well. </para> <para>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Applying improvements to OProfile

by stephenw

commit e5ce3acf8b54c8807b1e02af377ea60ac51be200 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Sat Dec 13 14:58:01 2014 +0100 Applying improvements to OProfile from upstream version, after proofreading and SME feedback en-US/OProfile.xml | 1082 +++++++++++++++++++++++++++++++++------------------- 1 files changed, 694 insertions(+), 388 deletions(-) --- diff --git a/en-US/OProfile.xml b/en-US/OProfile.xml index dd9f724..e5e2ffa 100644 --- a/en-US/OProfile.xml +++ b/en-US/OProfile.xml @@ -4,20 +4,18 @@ <chapter id="ch-OProfile"> <title>OProfile</title> - <indexterm - significance="normal"> + <indexterm> <primary>system analysis</primary> <secondary>OProfile</secondary> <see>OProfile</see> </indexterm> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> </indexterm> <para>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 <filename>oprofile</filename> package must be installed to use this tool.</para> - <para>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 <firstterm>counters</firstterm> that are incremented each time an event takes place. When the counter value, essentially rolls over, an interrupt is generated, making it possible to control the amount of detail (and therefore, overhead) produced by performance monitoring.</para> + <para>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 <firstterm>counters</firstterm> 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.</para> <para>OProfile uses this hardware (or a timer-based substitute in cases where performance monitoring hardware is not present) to collect <firstterm>samples</firstterm> 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.</para> - <para>OProfile is a useful tool, but be aware of some limitations when using it:</para> + <para>Be aware of the following limitations when using OProfile:</para> <itemizedlist> <listitem> <para> @@ -38,7 +36,7 @@ </listitem> <listitem> <para> - <emphasis>Hardware performance counters do not work on guest virtual machines</emphasis> — Because the hardware performance counters are not available on virtual systems, you need to use the <computeroutput>timer</computeroutput> mode. Run the command <command>opcontrol --deinit</command>, and then execute <command>modprobe oprofile timer=1</command> to enable the <computeroutput>timer</computeroutput> mode.</para> + <emphasis>Hardware performance counters do not work on guest virtual machines</emphasis> — Because the hardware performance counters are not available on virtual systems, you need to use the <computeroutput>timer</computeroutput> mode. Enter the command <command>opcontrol --deinit</command>, and then execute <command>modprobe oprofile timer=1</command> to enable the <computeroutput>timer</computeroutput> mode.</para> </listitem> <listitem> <para> @@ -48,14 +46,13 @@ <section id="s1-oprofile-overview-tools"> <title>Overview of Tools</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>overview of tools</secondary> </indexterm> <para> <xref - linkend="tb-oprofile-tools"/> provides a brief overview of the tools provided with the <filename>oprofile</filename> package.</para> + linkend="tb-oprofile-tools"/> provides a brief overview of the most commonly used tools provided with the <filename>oprofile</filename> package.</para> <table id="tb-oprofile-tools"> <title>OProfile Commands</title> @@ -116,6 +113,14 @@ </row> <row> <entry> + <command>operf</command> + </entry> + <entry> + <para>Recommended tool to be used in place of <command>opcontrol</command> for profiling. See <xref linkend="s1-using-operf"/> for details.</para> For differences between <command>operf</command> and <command>opcontrol</command> see <xref linkend="s2-operf_vs_opcontrol"/>. + </entry> + </row> + <row> + <entry> <command>opreport</command> </entry> <entry> @@ -134,59 +139,203 @@ </tbody> </tgroup> </table> + <section id="s2-operf_vs_opcontrol"> + <title>operf vs. opcontrol</title> + <para> + There are two mutually exclusive methods for collecting profiling data with OProfile. You can either use the newer and preferred <command>operf</command> or the <command>opcontrol</command> tool. + </para> + <bridgehead>operf</bridgehead> + <para> + This is the recommended mode for profiling. The <command>operf</command> tool uses the Linux Performance Events Subsystem, and therefore does not require the <emphasis>oprofile</emphasis> kernel driver. The <command>operf</command> 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</command>, it can be used without the <systemitem class="username">root</systemitem> privileges. However, <command>operf</command> is also capable of system-wide operations with use of the <option>--system-wide</option> option, where root authority is required. + </para> + <para> + With <command>operf</command>, there is no initial setup needed. You can invoke <command>operf</command> with command-line options to specify your profiling settings. After that, you can run the OProfile post-processing tools described in <xref linkend="s1-oprofile-analyzing-data"/>. See <xref linkend="s1-using-operf"/> for further information. + </para> + <bridgehead>opcontrol</bridgehead> + <para> + This mode consists of the <command>opcontrol</command> shell script, the <systemitem class="daemon">oprofiled</systemitem> daemon, and several post-processing tools. The <command>opcontrol</command> 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 <systemitem class="daemon">oprofiled</systemitem>. You can use legacy mode only if you have <systemitem class="username">root</systemitem> privileges. In certain cases, such as when you need to sample areas with disabled interrupt request (IRQ), this is a better alternative. + </para> + <para> + Before OProfile can be run in legacy mode, it must be configured as shown in <xref linkend="s1-oprofile-configuring"/>. These settings are then applied when starting OProfile (<xref linkend="s1-oprofile-starting"/>). + </para> + </section> + </section> + <section id="s1-using-operf"> + <title>Using operf</title> + <para> + <command>operf</command> 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</command>, press Ctrl+C. The typical <command>operf</command> command syntax looks as follows: + </para> + <synopsis><command>operf</command> <replaceable>options</replaceable> <replaceable>range</replaceable> <replaceable>command</replaceable> <replaceable>args</replaceable></synopsis> + <para> + Replace <replaceable>options</replaceable> with the desired command-line options to specify your profiling settings. Full set of options is described in <systemitem>operf(1)</systemitem> manual page. Replace <replaceable>range</replaceable> with one of the following: + </para> + <para> + <option>--system-wide</option> - this setting allows for global profiling, see <xref linkend="using_operf_system-wide"/> + </para> + <para> + <option>--pid=<replaceable>PID</replaceable></option> - this is to profile a running application, where <replaceable>PID</replaceable> is the process ID of the process you want to profile. + </para> + <para> + With <replaceable>command</replaceable> and <replaceable>args</replaceable>, you can define a specific command or application to be profiled, and also the input arguments that this command or application requires. Either <replaceable>command</replaceable>, <option>--pid</option> or <option>--system-wide</option> is required, but these cannot be used simultaneously. + </para> + <para> + When you invoke <command>operf</command> on a command line without setting the <replaceable>range</replaceable> option, data will be collected for the children processes. + </para> + <note id="using_operf_system-wide"> + <title>Using <command>operf</command> in System-wide Mode</title> + <para> + To run <command>operf</command> <option>--system-wide</option>, you need <systemitem class="username">root</systemitem> authority. When finished profiling, you can stop <command>operf</command> with <literal>Ctrl+C</literal>. + </para> + <para> + If you run <command>operf</command> <option>--system-wide</option> as a background process (with <literal>&</literal>), stop it in a controlled manner in order to process the collected profile data. For this purpose, use: + </para> + <synopsis><command>kill -SIGINT operf-PID </command></synopsis> + <para> + When running <command>operf</command> <option>--system-wide</option>, it is recommended that your current working directory is <filename class="directory">/root</filename> or a subdirectory of <filename class="directory">/root</filename> so that sample data files are not stored in locations accessible by regular users. + </para> + </note> + <section + id="s2-operf-kernel"> + <title>Specifying the Kernel</title> + <para> + To monitor the kernel, execute the following command: + </para> + <synopsis><command>operf</command> <option>--vmlinux</option>=<replaceable>vmlinux_path</replaceable></synopsis> + <para> + 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". + </para> + </section> + <section id="s2-operf-events"> + <title>Setting Events to Monitor</title> + <para> + Most processors contain counters, which are used by OProfile to monitor specific events. As shown in <xref linkend="tb-oprofile-processors"/>, the number of counters available depends on the processor. + </para> + <para> + 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 <xref linkend="s1-oprofile-gui"/>. If the counter cannot be set to a specific event, an error message is displayed. + </para> + <note> + <title>Older Processors and operf</title> + <para> + Some older processor models are not supported by the underlying Linux Performance Events Subsystem kernel and therefore are not supported by <command>operf</command>. If you receive this message: + <screen> +Your kernel's Performance Events Subsystem does not support your processor type + </screen> + when attempting to use <command>operf</command>, try profiling with <command>opcontrol</command> to see if your processor type may be supported by OProfile's legacy mode. + </para> + </note> + <note> + <title>Using operf on Virtual Systems</title> + <para> + Since hardware performance counters are not available on guest virtual machines, you have to enable <emphasis>timer</emphasis> mode to use <application>operf</application> on virtual systems. To do so, type as <systemitem class="username">root</systemitem>: + </para> + <synopsis><command>opcontrol</command> <option>--deinit</option></synopsis> + <synopsis><command>modprobe</command> <command>oprofile</command> <option>timer=1</option></synopsis> + </note> + + <para> + To set the event for each configurable counter via the command line, use: + </para> + <synopsis><command>operf</command> <option>--events</option>=<replaceable>event1</replaceable>,<replaceable>event2</replaceable>…</synopsis> + <para> + 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: + </para> + <synopsis><replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable>:<replaceable>kernel</replaceable>:<replaceable>user</replaceable></synopsis> + <para> + <xref linkend="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. + </para> + <table id="tab_event_specifications"> + <title>Event Specifications</title> + <tgroup cols='2' align='left'> + <thead> + <row> + <entry>Specification</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><replaceable>event-name</replaceable></entry> + <entry> The exact symbolic event name taken from <command>ophelp</command></entry> + </row> + <row> + <entry><replaceable>sample-rate</replaceable></entry> + <entry>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. </entry> + </row> + <row> + <entry><replaceable>unit-mask</replaceable></entry> + <entry> + Unit masks, which further define the event, are listed in <command>ophelp</command>. + 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</command>. Definition by name is valid only for unit masks having "extra:" parameters, as shown by the output of <command>ophelp</command>. 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. + </entry> + </row> + <row> + <entry><replaceable>kernel</replaceable></entry> + <entry>Specifies whether to profile kernel code (insert <literal>0</literal> or <literal>1</literal>(default))</entry> + </row> + <row> + <entry><replaceable>user</replaceable></entry> + <entry>Specifies whether to profile user-space code (insert <literal>0</literal> or <literal>1</literal> (default))</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + 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 <xref linkend="tb-oprofile-default-events"/> for a list of these default events. To determine the events available for profiling, use the <command>ophelp</command> command. + </para> + <synopsis><command>ophelp</command></synopsis> + </section> + <section id="s2-operf-categorization"> + <title>Categorization of Samples</title> + <para> + The <option>--separate-thread</option> 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, <option>--separate-thread</option> 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. + </para> + <para> + The <option>--separate-cpu</option> option categorizes samples by CPU. + </para> + </section> </section> <section id="s1-oprofile-configuring"> - <title>Configuring OProfile</title> - <indexterm - significance="normal"> + <title>Configuring OProfile Using Legacy Mode</title> + <indexterm> <primary>OProfile</primary> <secondary>configuring</secondary> </indexterm> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> - <secondary> - <command>opcontrol</command> - </secondary> + <secondary><command>opcontrol</command></secondary> </indexterm> - <indexterm - significance="normal"> - <primary> - <command>opcontrol</command> - </primary> + <indexterm> + <primary><command>opcontrol</command></primary> <see>OProfile</see> </indexterm> - <para>Before OProfile can be run, 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</command> utility to configure OProfile. As the <command>opcontrol</command> commands are executed, the setup options are saved to the <filename>/root/.oprofile/daemonrc</filename> file.</para> + <para> + 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</command> utility to configure OProfile. As the <command>opcontrol</command> commands are executed, the setup options are saved to the <filename>/root/.oprofile/daemonrc</filename> file. + </para> <section id="s2-oprofile-kernel"> <title>Specifying the Kernel</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>monitoring the kernel</secondary> </indexterm> <para>First, configure whether OProfile should monitor the kernel. This is the only configuration option that is required before starting OProfile. All others are optional.</para> - <para>To monitor the kernel, execute the following command as root:</para> - <indexterm - significance="normal"> + <para>To monitor the kernel, execute the following command as <systemitem class="username">root</systemitem>: + </para> + <indexterm> <primary>OProfile</primary> - <secondary> - <command>opcontrol</command> - </secondary> - <tertiary> - <option>--vmlinux=</option> - </tertiary> + <secondary><command>opcontrol</command></secondary> + <tertiary><option>--vmlinux=</option></tertiary> </indexterm>  <screen>~]# <command>opcontrol --setup --vmlinux=/usr/lib/debug/lib/modules/`uname -r`/vmlinux</command></screen> - <note> + <important> <title>Install the debuginfo package</title> - <para>The <package>debuginfo</package> package for the kernel must be installed (which contains the uncompressed kernel) in order to monitor the kernel.</para> - </note> - <para>To configure OProfile not to monitor the kernel, execute the following command as root:</para> - <indexterm - significance="normal"> + <para>In order to monitor the kernel, the <package>debuginfo</package> package which contains the uncompressed kernel must be installed. + </para> + </important> + <para>To configure OProfile not to monitor the kernel, execute the following command as <systemitem class="username">root</systemitem>:</para> + <indexterm> <primary>OProfile</primary> <secondary> <command>opcontrol</command> @@ -198,14 +347,13 @@ <screen>~]# <command>opcontrol --setup --no-vmlinux</command></screen> <para>This command also loads the <computeroutput>oprofile</computeroutput> kernel module, if it is not already loaded, and creates the <filename>/dev/oprofile/</filename> directory, if it does not already exist. See <xref linkend="s1-oprofile-dev-oprofile"/> for details about this directory.</para> - <para>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, refer to <xref + <para>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 <xref linkend="s2-oprofile-starting-separate"/>.</para> </section> <section id="s2-oprofile-events"> <title>Setting Events to Monitor</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>events</secondary> <tertiary>setting</tertiary> @@ -232,222 +380,297 @@ <thead> <row> <entry> - Processor - </entry> + Processor + </entry> <entry> <command>cpu_type</command> </entry> <entry> - Number of Counters - </entry> + Number of Counters + </entry> </row> </thead> <tbody> <row> <entry> - AMD64 - </entry> + AMD64 + </entry> <entry> - x86-64/hammer - </entry> + x86-64/hammer + </entry> <entry> - 4 - </entry> + 4 + </entry> </row> <row> <entry> - AMD Athlon - </entry> + AMD Family 10h + </entry> <entry> - i386/athlon - </entry> + x86-64/family10 + </entry> <entry> - 4 - </entry> + 4 + </entry> </row> <row> <entry> - AMD Family 10h - </entry> + AMD Family 11h + </entry> <entry> - x86-64/family10 - </entry> + x86-64/family11 + </entry> <entry> - 4 - </entry> + 4 + </entry> </row> <row> <entry> - AMD Family 11h - </entry> + AMD Family 12h + </entry> <entry> - x86-64/family11 - </entry> + x86-64/family12 + </entry> <entry> - 4 - </entry> + 4 + </entry> </row> <row> <entry> - AMD Family 12h - </entry> + AMD Family 14h + </entry> <entry> - x86-64/family12 - </entry> + x86-64/family14 + </entry> <entry> - 4 - </entry> + 4 + </entry> </row> <row> <entry> - AMD Family 14h - </entry> + AMD Family 15h + </entry> <entry> - x86-64/family14 - </entry> + x86-64/family15 + </entry> <entry> - 4 - </entry> + 6 + </entry> </row> <row> <entry> - AMD Family 15h - </entry> + Applied Micro X-Gene + </entry> <entry> - x86-64/family15 - </entry> + arm/armv8-xgene + </entry> <entry> - 6 - </entry> + 4 + </entry> </row> <row> <entry> - IBM eServer System i and IBM eServer System p - </entry> + ARM Cortex A53 + </entry> <entry> - timer - </entry> + arm/armv8-ca53 + </entry> <entry> - 1 - </entry> + 6 + </entry> </row> <row> <entry> - IBM POWER4 - </entry> + ARM Cortex A57 + </entry> <entry> - ppc64/power4 - </entry> + arm/armv8-ca57 + </entry> <entry> - 8 - </entry> + 6 + </entry> </row> <row> <entry> - IBM POWER5 - </entry> + IBM eServer System i and IBM eServer System p + </entry> <entry> - ppc64/power5 - </entry> + timer + </entry> <entry> - 6 - </entry> + 1 + </entry> </row> <row> <entry> - IBM PowerPC 970 - </entry> + IBM POWER4 + </entry> <entry> - ppc64/970 - </entry> + ppc64/power4 + </entry> <entry> - 8 - </entry> + 8 + </entry> </row> <row> <entry> - IBM S/390 and IBM System z - </entry> + IBM POWER5 + </entry> <entry> - timer - </entry> + ppc64/power5 + </entry> <entry> - 1 - </entry> + 6 + </entry> </row> <row> <entry> - Intel Core i7 - </entry> + IBM PowerPC 970 + </entry> <entry> - i386/core_i7 - </entry> + ppc64/970 + </entry> <entry> - 4 - </entry> + 8 + </entry> + </row> + <row> + <entry>IBM PowerPC 970MP</entry> + <entry> ppc64/970MP</entry> + <entry>8</entry> + </row> + <row> + <entry> IBM POWER5+</entry> + <entry>ppc64/power5+</entry> + <entry>6</entry> + </row> + <row> + <entry> IBM POWER5++</entry> + <entry>ppc64/power5++</entry> + <entry>6</entry> + </row> + <row> + <entry> IBM POWER56</entry> + <entry>ppc64/power6</entry> + <entry>6</entry> + </row> + <row> + <entry> IBM POWER7</entry> + <entry>ppc64/power7</entry> + <entry>6</entry> + </row> + <row> + <entry> IBM POWER8</entry> + <entry>ppc64/power7</entry> + <entry>8</entry> </row> <row> <entry> - Intel Nehalem microarchitecture - </entry> + IBM S/390 and IBM System z + </entry> <entry> - i386/nehalem - </entry> + timer + </entry> <entry> - 4 - </entry> + 1 + </entry> </row> <row> <entry> - Intel Pentium 4 (non-hyper-threaded) - </entry> + Intel Core i7 + </entry> <entry> - i386/p4 - </entry> + i386/core_i7 + </entry> <entry> - 8 - </entry> + 4 + </entry> </row> <row> <entry> - Intel Pentium 4 (hyper-threaded) - </entry> + Intel Nehalem microarchitecture + </entry> <entry> - i386/p4-ht - </entry> + i386/nehalem + </entry> <entry> - 4 - </entry> + 4 + </entry> </row> <row> <entry> - Intel Westmere microarchitecture - </entry> + Intel Westmere microarchitecture + </entry> <entry> - i386/westmere - </entry> + i386/westmere + </entry> <entry> - 4 - </entry> + 4 + </entry> + </row> + <row> + <entry>Intel Haswell microarchitecture (non-hyper-threaded)</entry> + <entry>i386/haswell</entry> + <entry>8</entry> + </row> + <row> + <entry>Intel Haswell microarchitecture (hyper-threaded)</entry> + <entry>i386/haswell-ht</entry> + <entry>4</entry> + </row> + <row> + <entry>Intel Ivy Bridge microarchitecture (non-hyper-threaded)</entry> + <entry>i386/ivybridge</entry> + <entry>8</entry> + </row> + <row> + <entry>Intel Ivy Bridge microarchitecture (hyper-threaded)</entry> + <entry>i386/ivybridge-ht</entry> + <entry>4</entry> + </row> + <row> + <entry>Intel Sandy Bridge microarchitecture (non-hyper-threaded)</entry> + <entry>i386/sandybridge</entry> + <entry>8</entry> + </row> + <row> + <entry>Intel Sandy Bridge microarchitecture</entry> + <entry>i386/sandybridge-ht</entry> + <entry>4</entry> + </row> + <row> + <entry>Intel Broadwell microarchitecture (non-hyper-threaded)</entry> + <entry>i386/broadwell</entry> + <entry>8</entry> + </row> + <row> + <entry>Intel Broadwell microarchitecture (hyper-threaded)</entry> + <entry>i386/broadwell-ht</entry> + <entry>4</entry> + </row> + <row> + <entry>Intel Silvermont microarchitecture</entry> + <entry>i386/silvermont</entry> + <entry>2</entry> </row> <row> <entry> - TIMER_INT - </entry> + TIMER_INT + </entry> <entry> - timer - </entry> + timer + </entry> <entry> - 1 - </entry> + 1 + </entry> </row> </tbody> </tgroup> </table> <para>Use <xref - linkend="tb-oprofile-processors"/> to verify that the correct processor type was detected and to determine the number of events that can be monitored simultaneously. <computeroutput>timer</computeroutput> is used as the processor type if the processor does not have supported performance monitoring hardware.</para> + linkend="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 <computeroutput>timer</computeroutput> is used as the processor type.</para> <para>If <computeroutput>timer</computeroutput> 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.</para> - <para>If <computeroutput>timer</computeroutput> 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 counter 0 are not set to an event by default. The default events monitored are shown in <xref + <para>If <computeroutput>timer</computeroutput> 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 <xref linkend="tb-oprofile-default-events"/>.</para> <table id="tb-oprofile-default-events"> @@ -469,141 +692,203 @@ <thead> <row> <entry> - Processor - </entry> + Processor + </entry> <entry> - Default Event for Counter - </entry> + Default Event for Counter + </entry> <entry> - Description - </entry> + Description + </entry> </row> </thead> <tbody> <row> <entry> - AMD Athlon and AMD64 - </entry> + AMD Athlon and AMD64 + </entry> <entry> - CPU_CLK_UNHALTED - </entry> + CPU_CLK_UNHALTED + </entry> <entry> - The processor's clock is not halted - </entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - AMD Family 10h, AMD Family 11h, AMD Family 12h - </entry> + AMD Family 10h, AMD Family 11h, AMD Family 12h + </entry> <entry> - CPU_CLK_UNHALTED - </entry> + CPU_CLK_UNHALTED + </entry> <entry> - The processor's clock is not halted - </entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - AMD Family 14h, AMD Family 15h - </entry> + AMD Family 14h, AMD Family 15h + </entry> <entry> - CPU_CLK_UNHALTED - </entry> + CPU_CLK_UNHALTED + </entry> <entry> - The processor's clock is not halted - </entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - IBM POWER4 - </entry> + Applied Micro X-Gene + </entry> <entry> - CYCLES - </entry> + CPU_CYCLES + </entry> <entry> - Processor Cycles - </entry> + Processor Cycles + </entry> </row> <row> <entry> - IBM POWER5 - </entry> + ARM Cortex A53 + </entry> <entry> - CYCLES - </entry> + CPU_CYCLES + </entry> <entry> - Processor Cycles - </entry> + Processor Cycles + </entry> </row> <row> <entry> - IBM PowerPC 970 - </entry> + ARM Cortex A57 + </entry> <entry> - CYCLES - </entry> + CPU_CYCLES + </entry> <entry> - Processor Cycles - </entry> + Processor Cycles + </entry> </row> - - - - <row> <entry> - Intel Core i7 - </entry> + IBM POWER4 + </entry> <entry> - CPU_CLK_UNHALTED - </entry> + CYCLES + </entry> <entry> - The processor's clock is not halted - </entry> + Processor Cycles + </entry> + </row> + <row> + <entry> + IBM POWER5 + </entry> + <entry> + CYCLES + </entry> + <entry> + Processor Cycles + </entry> + </row> + <row> + <entry> + IBM POWER8 + </entry> + <entry> + CYCLES + </entry> + <entry> + Processor Cycles + </entry> + </row> + <row> + <entry> + IBM PowerPC 970 + </entry> + <entry> + CYCLES + </entry> + <entry> + Processor Cycles + </entry> + </row> + <row> + <entry> + Intel Core i7 + </entry> + <entry> + CPU_CLK_UNHALTED + </entry> + <entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - Intel Nehalem microarchitecture - </entry> + Intel Nehalem microarchitecture + </entry> <entry> - CPU_CLK_UNHALTED - </entry> + CPU_CLK_UNHALTED + </entry> <entry> - The processor's clock is not halted - </entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - Intel Pentium 4 (hyper-threaded and non-hyper-threaded) - </entry> + Intel Pentium 4 (hyper-threaded and non-hyper-threaded) + </entry> + <entry> + GLOBAL_POWER_EVENTS + </entry> + <entry> + The time during which the processor is not stopped + </entry> + </row> + <row> + <entry> + Intel Westmere microarchitecture + </entry> + <entry> + CPU_CLK_UNHALTED + </entry> + <entry> + The processor's clock is not halted + </entry> + </row> + <row> + <entry> + Intel Broadwell microarchitecture + </entry> <entry> - GLOBAL_POWER_EVENTS - </entry> + CPU_CLK_UNHALTED + </entry> <entry> - The time during which the processor is not stopped - </entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - Intel Westmere microarchitecture - </entry> + Intel Silvermont microarchitecture + </entry> <entry> - CPU_CLK_UNHALTED - </entry> + CPU_CLK_UNHALTED + </entry> <entry> - The processor's clock is not halted - </entry> + The processor's clock is not halted + </entry> </row> <row> <entry> - TIMER_INT - </entry> + TIMER_INT + </entry> <entry> - (none) - </entry> + (none) + </entry> <entry> - Sample for each timer interrupt - </entry> + Sample for each timer interrupt + </entry> </row> </tbody> </tgroup> @@ -611,21 +896,30 @@ <para>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:</para> <screen>~]# <command>ls -d /dev/oprofile/[0-9]*</command></screen> <para>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):</para> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary> <command>ophelp</command> </secondary> </indexterm> - <indexterm - significance="normal"> - <primary> - <command>ophelp</command> - </primary> + <indexterm> + <primary><command>ophelp</command></primary> </indexterm> <screen>~]# <command>ophelp</command></screen> - <para>The events for each counter can be configured via the command line or with a graphical interface. For more information on the graphical interface, refer to <xref + <note> + <title>Make sure that OProfile is configured</title> + <para> + Unless OProfile is properly configured, <command>ophelp</command> fails with the following error message: + </para> + <screen>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</screen> + <para> + To configure OProfile, follow the instructions in <xref linkend="s1-oprofile-configuring" />. + </para> + </note> + <para>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 <xref linkend="s1-oprofile-gui"/>. If the counter cannot be set to a specific event, an error message is displayed.</para> <para>To set the event for each configurable counter via the command line, use <command>opcontrol</command>:</para> <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable></command></screen> @@ -633,39 +927,39 @@ <section id="s3-oprofile-events-sampling"> <title>Sampling Rate</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>events</secondary> <tertiary>sampling rate</tertiary> </indexterm> - <para>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 whatever the jiffy rate is and is not user-settable. If the <computeroutput>cpu_type</computeroutput> is not <computeroutput>timer</computeroutput>, each event can have a <firstterm>sampling rate</firstterm> set for it. The sampling rate is the number of events between each sample snapshot.</para> + <para>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 <computeroutput>cpu_type</computeroutput> is not <computeroutput>timer</computeroutput>, each event can have a <firstterm>sampling rate</firstterm> set for it. The sampling rate is the number of events between each sample snapshot.</para> <para>When setting the event for the counter, a sample rate can also be specified:</para> <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable></command></screen> <para>Replace <replaceable>sample-rate</replaceable> 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.</para> <warning> <title>Sampling too frequently can overload the system</title> - <para>Be extremely careful when setting sampling rates. Sampling too frequently can overload the system, causing the system to appear as if it is frozen or causing the system to actually freeze.</para> + <para>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.</para> </warning> </section> <section id="s3-oprofile-events-unit-masks"> <title>Unit Masks</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>unit mask</secondary> </indexterm> <para>Some user performance monitoring events may also require unit masks to further define the event.</para> <para>Unit masks for each event are listed with the <command>ophelp</command> 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 <firstterm>or</firstterm> operation.</para> <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable></command></screen> + <para> + 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. + </para> </section> </section> <section id="s2-oprofile-starting-separate"> <title>Separating Kernel and User-space Profiles</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>configuring</secondary> <tertiary>separating profiles</tertiary> @@ -675,29 +969,33 @@ <para>Execute the following command to start profiling kernel mode for the counter again:</para> <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable>:1</command></screen> <para>To configure OProfile to ignore events in user mode for a specific counter, execute the following command:</para> - <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable>:<replaceable>kernel</replaceable>:0</command></screen> + <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable>:1:0</command></screen> <para>Execute the following command to start profiling user mode for the counter again:</para> - <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable>:<replaceable>kernel</replaceable>:1</command></screen> + <screen>~]# <command>opcontrol --event=<replaceable>event-name</replaceable>:<replaceable>sample-rate</replaceable>:<replaceable>unit-mask</replaceable>:1:1</command></screen> <para>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:</para> <screen>~]# <command>opcontrol --separate=<replaceable>choice</replaceable></command></screen> <para> - <replaceable>choice</replaceable> can be one of the following:</para> + The <replaceable>choice</replaceable> argument can be one of the following:</para> <itemizedlist> <listitem> <para> - <computeroutput>none</computeroutput> — do not separate the profiles (default)</para> + <computeroutput>none</computeroutput> — Do not separate the profiles (default). + </para> </listitem> <listitem> <para> - <command>library</command> — generate per-application profiles for libraries</para> + <command>library</command> — Generate per-application profiles for libraries. + </para> </listitem> <listitem> <para> - <command>kernel</command> — generate per-application profiles for the kernel and kernel modules</para> + <command>kernel</command> — Generate per-application profiles for the kernel and kernel modules. + </para> </listitem> <listitem> <para> - <command>all</command> — generate per-application profiles for libraries and per-application profiles for the kernel and kernel modules</para> + <command>all</command> — Generate per-application profiles for libraries and per-application profiles for the kernel and kernel modules. + </para> </listitem> </itemizedlist> <para>If <option>--separate=library</option> is used, the sample file name includes the name of the executable as well as the name of the library.</para> @@ -709,15 +1007,13 @@ </section> <section id="s1-oprofile-starting"> - <title>Starting and Stopping OProfile</title> - <indexterm - significance="normal"> + <title>Starting and Stopping OProfile Using Legacy Mode</title> + <indexterm> <primary>OProfile</primary> <secondary>starting</secondary> </indexterm> <para>To start monitoring the system with OProfile, execute the following command as root:</para> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary> <command>opcontrol</command> @@ -730,62 +1026,65 @@ <para>Output similar to the following is displayed:</para> <screen>Using log file /var/lib/oprofile/oprofiled.log Daemon started. Profiler running.</screen> <para>The settings in <filename>/root/.oprofile/daemonrc</filename> are used.</para> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary> <command>oprofiled</command> </secondary> </indexterm> - <indexterm - significance="normal"> - <primary> - <command>oprofiled</command> - </primary> + <indexterm> + <primary><command>oprofiled</command></primary> <see>OProfile</see> </indexterm> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary> <command>oprofiled</command> </secondary> <tertiary>log file</tertiary> </indexterm> - <para>The OProfile daemon, <command>oprofiled</command>, is started; it periodically writes the sample data to the <filename>/var/lib/oprofile/samples/</filename> directory. The log file for the daemon is located at <filename>/var/lib/oprofile/oprofiled.log</filename>.</para> + <para>The OProfile daemon, <command>oprofiled</command>, is started; it periodically writes the sample data to the <filename class="directory">/var/lib/oprofile/samples/</filename> directory. The log file for the daemon is located at <filename>/var/lib/oprofile/oprofiled.log</filename>.</para> <important> <title>Disable the nmi_watchdog registers</title> <para>On a &MAJOROSVER; system, the <computeroutput>nmi_watchdog</computeroutput> registers with the <computeroutput>perf</computeroutput> subsystem. Due to this, the <computeroutput>perf</computeroutput> subsystem grabs control of the performance counter registers at boot time, blocking OProfile from working.</para> - <para>To resolve this, either boot with the <command>nmi_watchdog=0</command> kernel parameter set, or run the following command to disable <computeroutput>nmi_watchdog</computeroutput> at run time:</para> - <screen>~]# <command>echo 0 > /proc/sys/kernel/nmi_watchdog</command></screen> - <para>To re-enable <computeroutput>nmi_watchdog</computeroutput>, use the following command:</para> - <screen>~]# <command>echo 1 > /proc/sys/kernel/nmi_watchdog</command></screen> + <para>To resolve this, either boot with the <command>nmi_watchdog=0</command> kernel parameter set, or run the following command as <systemitem class="username">root</systemitem> to disable <computeroutput>nmi_watchdog</computeroutput> at run time:</para> + <screen>~]# <command>echo 0 > /proc/sys/kernel/nmi_watchdog</command></screen> + <para>To re-enable <computeroutput>nmi_watchdog</computeroutput>, use the following command as <systemitem class="username">root</systemitem>:</para> + <screen>~]# <command>echo 1 > /proc/sys/kernel/nmi_watchdog</command></screen> </important> <para>To stop the profiler, execute the following command as root:</para> <screen>~]# <command>opcontrol --shutdown</command></screen> </section> <section id="s1-oprofile-saving-data"> - <title>Saving Data</title> - <indexterm - significance="normal"> + <title>Saving Data in Legacy Mode</title> + <indexterm> <primary>OProfile</primary> <secondary>saving data</secondary> </indexterm> <para>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.</para> - <para>To save the current set of sample files, execute the following command, replacing <replaceable>name</replaceable> with a unique descriptive name for the current session.</para> + <para>To save the current set of sample files, execute the following command, replacing <replaceable>name</replaceable> with a unique descriptive name for the current session:</para> <screen>~]# <command>opcontrol --save=<replaceable>name</replaceable></command></screen> - <para>The directory <filename>/var/lib/oprofile/samples/<replaceable>name</replaceable>/</filename> is created and the current sample files are copied to it.</para> + <para>The command creates the directory <filename>/var/lib/oprofile/samples/<replaceable>name</replaceable>/</filename> and the current sample files are copied to it.</para> + <para> + To specify the session directory to hold the sample data, use the <option>--session-dir</option> option. If not specified, the data is saved in the <filename class="directory">oprofile_data/</filename> directory on the current path. + </para> </section> <section id="s1-oprofile-analyzing-data"> <title>Analyzing the Data</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>reading data</secondary> </indexterm> - <para>Periodically, the OProfile daemon, <command>oprofiled</command>, collects the samples and writes them to the <filename>/var/lib/oprofile/samples/</filename> directory. Before reading the data, make sure all data has been written to this directory by executing the following command as root:</para> + <para> + The same OProfile post-processing tools are used whether you collect your profile with <command>operf</command> or <command>opcontrol</command> in legacy mode. + </para> + <para> + By default, <command>operf</command> stores the profiling data in the <filename class="directory"><replaceable>current_dir</replaceable>/oprofile_data/</filename> directory. You can change to a different location with the <option>--session-dir</option> option. The usual post-profiling analysis tools such as <command>opreport</command> and <command>opannotate</command> can be used to generate profile reports. These tools search for samples in <filename class="directory"><replaceable>current_dir</replaceable>/oprofile_data/</filename> first. If this directory does not exist, the analysis tools use the standard session directory of <filename class="directory">/var/lib/oprofile/</filename>. Statistics, such as total samples received and lost samples, are written to the <filename><replaceable>session_dir</replaceable>/samples/operf.log</filename> file. + </para> + <para> + When using legacy mode, the OProfile daemon, <command>oprofiled</command>, periodically collects the samples and writes them to the <filename>/var/lib/oprofile/samples/</filename> directory. Before reading the data, make sure all data has been written to this directory by executing the following command as root:</para> <screen>~]# <command>opcontrol --dump</command></screen> <para>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</command> becomes:</para> <screen>\{root\}/bin/bash/\{dep\}/\{root\}/bin/bash/CPU_CLK_UNHALTED.100000</screen> @@ -805,31 +1104,26 @@ <para>Use these tools, along with the binaries profiled, to generate reports that can be further analyzed.</para> <warning> <title>Back up the executable and the sample files</title> - <para>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. Please note that the sample file and the binary have to agree. Making a backup is not going to work if they do not match. <command>oparchive</command> can be used to address this problem.</para> + <para>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</command> can be used to address this problem.</para> </warning> - <para>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 <xref + <para>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 <xref linkend="s1-oprofile-saving-data"/> for details on how to back up the sample file.</para> <section id="s2-oprofile-reading-opreport"> - <title>Using <command>opreport</command> - </title> - <indexterm - significance="normal"> + <title>Using <command>opreport</command></title> + <indexterm> <primary>OProfile</primary> <secondary> <command>opreport</command> </secondary> </indexterm> - <indexterm - significance="normal"> - <primary> - <command>opreport</command> - </primary> + <indexterm> + <primary><command>opreport</command></primary> <see>OProfile</see> </indexterm> - <para>The <command>opreport</command> tool provides an overview of all the executables being profiled.</para> - <para>The following is part of a sample output:</para> - <screen>Profiling through timer interrupt + <para>The <command>opreport</command> tool provides an overview of all the executables being profiled. The following is part of a sample output from the <command>opreport</command> command:</para> + <screen>~]$ <command>opreport</command> +Profiling through timer interrupt TIMER:0| samples| %| ------------------ @@ -855,39 +1149,42 @@ samples| %| 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</screen> - <para>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.</para> - <para>See the <command>opreport</command> man page for a list of available command line options, such as the <option>-r</option> option used to sort the output from the executable with the smallest number of samples to the one with the largest number of samples.</para> + <para> + 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. + </para> + <para> + See the <systemitem>opreport(1)</systemitem> manual page for a list of available command-line options, such as the <option>-r</option> 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</option> or <option>--threshold</option> option to trim the output of <command>opcontrol</command>. + </para> </section> <section id="s2-oprofile-reading-opreport-single"> <title>Using opreport on a Single Executable</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary> <command>opreport</command> </secondary> <tertiary>on a single executable</tertiary> </indexterm> - <indexterm - significance="normal"> - <primary> - <command>opreport</command> - </primary> + <indexterm> + <primary><command>opreport</command></primary> <see>OProfile</see> </indexterm> - <para>To retrieve more detailed profiled information about a specific executable, use <command>opreport</command>:</para> + <para>To retrieve more detailed profiled information about a specific executable, use the <command>opreport</command> command:</para> <screen>~]# <command>opreport <replaceable>mode</replaceable> <replaceable>executable</replaceable></command></screen> <para> - <replaceable>executable</replaceable> must be the full path to the executable to be analyzed. <replaceable>mode</replaceable> must be one of the following:</para> + Replace <replaceable>executable</replaceable> with the full path to the executable to be analyzed. <replaceable>mode</replaceable> stands for one of the following options:</para> <variablelist> <varlistentry> <term> <option>-l</option> </term> <listitem> - <para>List sample data by symbols. For example, the following is part of the output from running the command <command>opreport -l /lib/tls/libc-<replaceable>version</replaceable>.so</command>:</para> + <para>This option is used to list sample data by symbols. For example, running this command: + <synopsis>~]# <command>opreport -l /lib/tls/libc-<replaceable>version</replaceable>.so</command></synopsis> + </para> + <para> produces the following output:</para> <screen>samples % symbol name 12 21.4286 __gconv_transform_utf8_internal 5 8.9286 _int_malloc 4 7.1429 malloc @@ -924,7 +1221,12 @@ samples| %| </option> </term> <listitem> - <para>List sample data specific to a symbol name. For example, the following output is from the command <command>opreport -l -i __gconv_transform_utf8_internal /lib/tls/libc-<replaceable>version</replaceable>.so</command>:</para> + <para>List sample data specific to a symbol name. For example, running: + <synopsis>~]# <command>opreport -l -i __gconv_transform_utf8_internal /lib/tls/libc-<replaceable>version</replaceable>.so</command></synopsis> + </para> + <para> + returns the following output: + </para> <screen>samples % symbol name 12 100.000 __gconv_transform_utf8_internal</screen> <para>The first line is a summary for the symbol/executable combination.</para> @@ -936,7 +1238,12 @@ samples| %| <option>-d</option> </term> <listitem> - <para>List sample data by symbols with more detail than <option>-l</option>. For example, the following output is from the command <command>opreport -l -d __gconv_transform_utf8_internal /lib/tls/libc-<replaceable>version</replaceable>.so</command>:</para> + <para>This option lists sample data by symbols with more detail than the <option>-l</option> option. For example, with the following command: + <synopsis>~]# <command>opreport -d -i __gconv_transform_utf8_internal /lib/tls/libc-<replaceable>version</replaceable>.so</command></synopsis> + </para> + <para> + this output is returned: + </para> <screen>vma samples % symbol name 00a98640 12 100.000 __gconv_transform_utf8_internal 00a98640 1 8.3333 @@ -955,11 +1262,11 @@ samples| %| </varlistentry> <varlistentry> <term> - <option>-x</option> - <replaceable>symbol-name</replaceable> + <option>-e</option> + <replaceable>symbol-name</replaceable>… </term> <listitem> - <para>Exclude the comma-separated list of symbols from the output.</para> + <para>With this option, you can exclude some symbols from the output. Replace <replaceable>symbol-name</replaceable> with the comma-separated list of symbols you want to exclude.</para> </listitem> </varlistentry> <varlistentry> @@ -967,27 +1274,25 @@ samples| %| <option>session</option>:<replaceable>name</replaceable> </term> <listitem> - <para>Specify the full path to the session or a directory relative to the <filename>/var/lib/oprofile/samples/</filename> directory.</para> + <para>Here, you can specify the full path to the session, a directory relative to the <filename class="directory">/var/lib/oprofile/samples/</filename> directory, or if you are using <command>operf</command>, a directory relative to <filename class="directory">./oprofile_data/samples/</filename>.</para> </listitem> </varlistentry> </variablelist> </section> <section id="s2-oprofile-module-output"> - <title>Getting more detailed output on the modules</title> - <indexterm - significance="normal"> + <title>Getting More Detailed Output on the Modules</title> + <indexterm> <primary>OProfile</primary> <secondary> <command>opreport</command> </secondary> </indexterm> - <indexterm - significance="normal"> + <indexterm> <primary/> <see>OProfile</see> </indexterm> - <para>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 have come from the <filename>initrd</filename> file on boot up, the directory with the various kernel modules, or a locally created kernel module. As a result, when OProfile records sample 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 executable.</para> + <para>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 <filename>initrd</filename> 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.</para> <para>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> package installed for the kernel.</para> <para>Find out which kernel is running with the <command>uname -a</command> command, obtain the appropriate <package>debuginfo</package> package and install it on the machine.</para> <para>Then proceed with clearing out the samples from previous runs with the following command:</para> @@ -1015,49 +1320,40 @@ samples % symbol name </section> <section id="s2-oprofile-reading-opannotate"> - <title>Using <command>opannotate</command> - </title> - <indexterm - significance="normal"> + <title>Using <command>opannotate</command></title> + <indexterm> <primary>OProfile</primary> <secondary> <command>opannotate</command> </secondary> </indexterm> - <indexterm - significance="normal"> - <primary> - <command>opannotate</command> - </primary> + <indexterm> + <primary><command>opannotate</command></primary> <see>OProfile</see> </indexterm> - <para>The <command>opannotate</command> tool tries to match the samples for particular instructions to the corresponding lines in the source code. The resulting files generated 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.</para> - <para>For this utility to work, the appropriate <package>debuginfo</package> package for the executable must be installed on the system. By default, &MAJOROS; <package>debuginfo</package> packages are not installed together with their corresponding packages, which contain the executable, so that you have to obtain and install the <package>debuginfo</package> packages separately.</para> + <para>The <command>opannotate</command> 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.</para> + <para>For this utility to work, the appropriate <package>debuginfo</package> package for the executable must be installed on the system. On &MAJOROS;, the <package>debuginfo</package> packages are not automatically installed with the corresponding packages that contain the executable. You have to obtain and install them separately.</para> <para>The general syntax for <command>opannotate</command> is as follows:</para> <screen>~]# <command>opannotate --search-dirs <replaceable>src-dir</replaceable> --source <replaceable>executable</replaceable></command></screen> - <para>The directory containing the source code and the executable to be analyzed must be specified. See the <command>opannotate</command> man page for a list of additional command line options.</para> + <para>These command-line options are mandatory. Replace <replaceable>src-dir</replaceable> with a path to the directory containing the source code and specify the executable to be analyzed. See the <systemitem>opannotate(1)</systemitem> manual page for a list of additional command line options.</para> </section> </section> <section id="s1-oprofile-dev-oprofile"> - <title>Understanding <filename>/dev/oprofile/</filename> - </title> - <indexterm - significance="normal"> + <title>Understanding the /dev/oprofile/ directory +</title> + <indexterm> <primary>OProfile</primary> - <secondary> - <filename>/dev/oprofile/</filename> - </secondary> + <secondary><filename class="directory">/dev/oprofile/</filename></secondary> </indexterm> - <indexterm - significance="normal"> - <primary> - <filename>/dev/oprofile/</filename> - </primary> + <indexterm> + <primary><filename class="directory">/dev/oprofile/</filename></primary> </indexterm> - <para>The <filename>/dev/oprofile/</filename> directory contains the file system for OProfile. Use the <command>cat</command> 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:</para> - <screen>~]# <command>cat /dev/oprofile/cpu_type</command></screen> - <para>A directory exists in <filename>/dev/oprofile/</filename> for each counter. For example, if there are 2 counters, the directories <filename>/dev/oprofile/0/</filename> and <filename>dev/oprofile/1/</filename> exist.</para> + <para> + When using OProfile in legacy mode, the <filename class="directory">/dev/oprofile/</filename> directory is used to store the file system for OProfile. On the other hand, <command>operf</command> does not require <filename class="directory">/dev/oprofile/</filename>. Use the <command>cat</command> 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: + </para> + <screen>~]# <command>cat /dev/oprofile/cpu_type</command></screen> + <para>A directory exists in <filename class="directory">/dev/oprofile/</filename> for each counter. For example, if there are 2 counters, the directories <filename class="directory">/dev/oprofile/0/</filename> and <filename class="directory">/dev/oprofile/1/</filename> exist.</para> <para>Each directory for a counter contains the following files:</para> <itemizedlist> <listitem> @@ -1099,7 +1395,7 @@ samples % symbol name <itemizedlist> <listitem> <para> - <emphasis>Determine which applications and services are used the most on a system</emphasis> — <command>opreport</command> can be used to determine how much processor time an application or service uses. If the system is used for multiple services but is under performing, the services consuming the most processor time can be moved to dedicated systems.</para> + <emphasis>Determine which applications and services are used the most on a system</emphasis> — <command>opreport</command> 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.</para> </listitem> <listitem> <para> @@ -1110,35 +1406,44 @@ samples % symbol name <section id="s1-oprofile-java-support"> <title>OProfile Support for Java</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>Java</secondary> </indexterm> - <para>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 build-in support for the JVM Tools Interface (JVMTI) agent library, which supports Java 1.5 and higher.</para> + <para>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.</para> <section id="s1-oprofile-java-profiling"> <title>Profiling Java Code</title> <para>To profile JIT code from the Java Virtual Machine with the JVMTI agent, add the following to the JVM startup parameters:</para> - <screen><option>-agentlib:jvmti_oprofile</option></screen> + <screen><option>-agentlib:</option><replaceable>jvmti_oprofile</replaceable></screen> + <para> + Where <replaceable>jvmti_oprofile</replaceable> is a path to the OProfile agent. For 64-bit JVM, the path looks as follows: + </para> + <screen><option>-agentlib:/usr/lib64/oprofile/libjvmti_oprofile.so</option></screen> + <para> + Currently, you can add one command-line option: <option>--debug</option>, which enables debugging mode. + </para> <note> <title>Install the oprofile-jit package</title> - <para>The <package>oprofile-jit</package> package must be installed on the system in order to profile JIT code with OProfile.</para> + <para>The <package>oprofile-jit</package> 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.</para> </note> - <para>To learn more about Java support in OProfile, refer to the OProfile Manual, which is linked from <xref - linkend="s1-oprofile-additional-resources"/>.</para> + <para> + Depending on the JVM that you are using, you may have to install the <emphasis>debuginfo</emphasis> 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 <emphasis>yum-plugin-auto-update-debug-info</emphasis> plug-in. This plug-in searches the debug information repository for corresponding updates. + </para> + <para> + After successful setup, you can apply the standard profiling and analyzing tools described in previous sections + </para> + <para>To learn more about Java support in OProfile, see the OProfile Manual, which is linked from <xref + linkend="s1-oprofile_additional_resources"/>.</para> </section> </section> <section id="s1-oprofile-gui"> <title>Graphical Interface</title> - <indexterm - significance="normal"> - <primary> - <command>oprof_start</command> - </primary> + <indexterm> + <primary><command>oprof_start</command></primary> </indexterm> - <para>Some OProfile preferences can be set with a graphical interface. To start it, execute the <command>oprof_start</command> command as root at a shell prompt. To use the graphical interface, you will need to have the <filename>oprofile-gui</filename> package installed.</para> + <para>Some OProfile preferences can be set with a graphical interface. Make sure you have the <filename>oprofile-gui</filename> package that provides the OProfile GUI installed on your system. To start the interface, execute the <command>oprof_start</command> command as root at a shell prompt.</para> <para>After changing any of the options, save them by clicking the <guibutton>Save and quit</guibutton> button. The preferences are written to <filename>/root/.oprofile/daemonrc</filename>, and the application exits. Exiting the application does not stop OProfile from sampling.</para> <para>On the <guilabel>Setup</guilabel> tab, to set events for the processor counters as discussed in <xref linkend="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.</para> @@ -1160,13 +1465,13 @@ samples % symbol name </mediaobject> </figure> <para>On the right side of the tab, select the <guilabel>Profile kernel</guilabel> option to count events in kernel mode for the currently selected event, as discussed in <xref - linkend="s2-oprofile-starting-separate"/>. If this option is unselected, no samples are collected for the kernel.</para> + linkend="s2-oprofile-starting-separate"/>. If this option is not selected, no samples are collected for the kernel.</para> <para>Select the <guilabel>Profile user binaries</guilabel> option to count events in user mode for the currently selected event, as discussed in <xref - linkend="s2-oprofile-starting-separate"/>. If this option is unselected, no samples are collected for user applications.</para> + linkend="s2-oprofile-starting-separate"/>. If this option is not selected, no samples are collected for user applications.</para> <para>Use the <guilabel>Count</guilabel> text field to set the sampling rate for the currently selected event as discussed in <xref linkend="s3-oprofile-events-sampling"/>.</para> <para>If any unit masks are available for the currently selected event, as discussed in <xref - linkend="s3-oprofile-events-unit-masks"/>, they are displayed in the <guilabel>Unit Masks</guilabel> area on the right side of the <guilabel>Setup</guilabel> tab. Select the checkbox beside the unit mask to enable it for the event.</para> + linkend="s3-oprofile-events-unit-masks"/>, they are displayed in the <guilabel>Unit Masks</guilabel> area on the right side of the <guilabel>Setup</guilabel> tab. Select the check box beside the unit mask to enable it for the event.</para> <para>On the <guilabel>Configuration</guilabel> tab, to profile the kernel, enter the name and location of the <filename>vmlinux</filename> file for the kernel to monitor in the <guilabel>Kernel image file</guilabel> text field. To configure OProfile not to monitor the kernel, select <guilabel>No kernel image</guilabel>.</para> <figure float="0" @@ -1184,7 +1489,7 @@ samples % symbol name </textobject> </mediaobject> </figure> - <para>If the <guilabel>Verbose</guilabel> option is selected, the <command>oprofiled</command> daemon log includes more information.</para> + <para>If the <guilabel>Verbose</guilabel> option is selected, the <command>oprofiled</command> daemon log includes more detailed information.</para> <para>If <guilabel>Per-application profiles</guilabel> is selected, OProfile generates per-application profiles for libraries. This is equivalent to the <command>opcontrol --separate=library</command> command. If <guilabel>Per-application profiles, including kernel</guilabel> is selected, OProfile generates per-application profiles for the kernel and kernel modules as discussed in <xref linkend="s2-oprofile-starting-separate"/>. This is equivalent to the <command>opcontrol --separate=kernel</command> command.</para> <para>To force data to be written to samples files as discussed in <xref @@ -1194,29 +1499,25 @@ samples % symbol name <section id="s1-oprofile-and-systemtap"> <title>OProfile and SystemTap</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>SystemTap</secondary> </indexterm> - <para>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>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide more filtering and analysis options for collected information.</para> + <para>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>, <command>ps</command>, <command>top</command>, and <command>iostat</command>; however, SystemTap is designed to provide more filtering and analysis options for the collected information.</para> <para>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.</para> - <para>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 instrumentation, it is particularly useful for instrumenting the kernel and daemons.</para> - <para>For more information on SystemTap, refer to <xref - linkend="s2-oprofile-useful-websites"/> for the relevant SystemTap documentation.</para> + <para>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.</para> + <para>For more information on SystemTap, see <xref + linkend="br-oprofile_online_documentation"/> for the relevant SystemTap documentation.</para> </section> <section - id="s1-oprofile-additional-resources"> + id="s1-oprofile_additional_resources"> <title>Additional Resources</title> - <indexterm - significance="normal"> + <indexterm> <primary>OProfile</primary> <secondary>additional resources</secondary> </indexterm> - <para>This chapter only highlights OProfile and how to configure and use it. To learn more, refer to the following resources.</para> - <section - id="s1-oprofile-installed-docs"> - <title>Installed Docs</title> + <para>To learn more about OProfile and how to configure it, see the following resources.</para> + <bridgehead id="br-oprofile_installed_documentation">Installed Documentation</bridgehead> <itemizedlist> <listitem> <para> @@ -1225,26 +1526,31 @@ samples % symbol name </listitem> <listitem> <para> - <command>oprofile</command> man page — Discusses <command>opcontrol</command>, <command>opreport</command>, <command>opannotate</command>, and <command>ophelp</command> + <filename>oprofile(1)</filename> manual page — Discusses <command>opcontrol</command>, <command>opreport</command>, <command>opannotate</command>, and <command>ophelp</command> </para> </listitem> + <listitem> + <para> + <filename>operf(1)</filename> manual page + </para> + </listitem> </itemizedlist> - </section> - <section - id="s2-oprofile-useful-websites"> - <title>Useful Websites</title> + <bridgehead id="br-oprofile_online_documentation">Online Documentation</bridgehead> <itemizedlist> <listitem> <para> <ulink - url="http://oprofile.sourceforge.net/">http://oprofile.sourceforge.net/</ulink> — Contains the latest documentation, mailing lists, IRC channels, and more.</para> + url="http://oprofile.sourceforge.net/">http://oprofile.sourceforge.net/</ulink> — Contains the latest upstream documentation, mailing lists, IRC channels, and more.</para> </listitem> + </itemizedlist> + <bridgehead id="br-oprofile_see_also">See Also</bridgehead> + <itemizedlist> <listitem> <para> <ulink - url="http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/SystemT...">SystemTap Beginners Guide</ulink> — Provides basic instructions on how to use SystemTap to monitor different subsystems of &MAJOROS; in finer detail.</para> + url="https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/...">SystemTap Beginners Guide</ulink> — Provides basic instructions on how to use SystemTap to monitor different subsystems of &MAJOROS; in finer detail.</para> + </listitem> </itemizedlist> - </section> </section> </chapter>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] kernel-tools

by stephenw

commit d2dcb5714aa82ae252aa35cb263ba3c083f98e4b Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Sat Dec 13 09:32:38 2014 +0100 kernel-tools en-US/Manually_Upgrading_the_Kernel.xml | 5 +++++ 1 files changed, 5 insertions(+), 0 deletions(-) --- diff --git a/en-US/Manually_Upgrading_the_Kernel.xml b/en-US/Manually_Upgrading_the_Kernel.xml index 26e166f..e8c498f 100644 --- a/en-US/Manually_Upgrading_the_Kernel.xml +++ b/en-US/Manually_Upgrading_the_Kernel.xml @@ -166,6 +166,11 @@ <package>kernel-abi-whitelists</package> — 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>yum</package> plug-in to aid enforcement. </para> </listitem> + <listitem> + <para> + <package>kernel-tools</package> — Contains tools for manipulating the Linux kernel and supporting documentation. + </para> + </listitem> </itemizedlist> </section> <section id="s1-kernel-preparing">

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Updates to ptp4l

by stephenw

commit c91d9a27fa7f176479d8a8f15bd28ce42a441c03 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Tue Dec 16 21:57:41 2014 +0100 Updates to ptp4l misc. updates from upstream version en-US/Configuring_PTP_Using_ptp4l.xml | 52 ++++++++++++++++++++++++++++++-- 1 files changed, 48 insertions(+), 4 deletions(-) --- diff --git a/en-US/Configuring_PTP_Using_ptp4l.xml b/en-US/Configuring_PTP_Using_ptp4l.xml index 0f5174c..e6ad252 100644 --- a/en-US/Configuring_PTP_Using_ptp4l.xml +++ b/en-US/Configuring_PTP_Using_ptp4l.xml @@ -145,6 +145,19 @@ should include: <section id="sec-Starting_ptp4l"> <title>Starting ptp4l</title> + <para> +The <application>ptp4l</application> program can be started from the command line or it can be started as a service. When running as a service, options are specified in the <filename>/etc/sysconfig/ptp4l</filename> file. Options required for use both by the service and on the command line should be specified in the <filename>/etc/ptp4l.conf</filename> file. The <filename>/etc/sysconfig/ptp4l</filename> file includes the <command>-f /etc/ptp4l.conf</command> command line option, which causes the <systemitem class="service">ptp4l</systemitem> program to read the <filename>/etc/ptp4l.conf</filename> file and process the options it contains. The use of the <filename>/etc/ptp4l.conf</filename> is explained in <xref linkend="sec-Specifying_a_Configuration_File" />. More information on the different <application>ptp4l</application> options and the configuration file settings can be found in the <filename>ptp4l(8)</filename> man page.</para> + +<bridgehead id="bh-Starting_ptp4l_as_a_Service">Starting ptp4l as a Service</bridgehead> + +<para> +To start <application>ptp4l</application> as a service, issue the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl start ptp4l</command></screen> + +</para> + +<bridgehead id="bh-Using_ptp4l_From_The_Command_Line">Using ptp4l From The Command Line</bridgehead> + <para> The <application>ptp4l</application> program tries to use hardware time stamping by default. To use <application>ptp4l</application> with hardware time stamping capable drivers and NICs, you must provide the network interface to use with the <option>-i</option> option. Enter the following command as <systemitem class="username">root</systemitem>: <screen>~]# <command>ptp4l -i <replaceable>em3</replaceable> -m</command></screen> @@ -326,9 +339,24 @@ if <literal>gmPresent</literal> is true, the <systemitem class="protocol">PTP</s <section id="sec-Synchronizing_the_Clocks"> <title>Synchronizing the Clocks</title> <para> - The <application>phc2sys</application> program is used to synchronize the system clock to the <systemitem class="protocol">PTP</systemitem> hardware clock (<acronym>PHC</acronym>) on the NIC. To start <application>phc2sys</application>, where <replaceable>em3</replaceable> is the interface with the <systemitem class="protocol">PTP</systemitem> hardware clock, enter the following command as <systemitem class="username">root</systemitem>: + The <application>phc2sys</application> program is used to synchronize the system clock to the <systemitem class="protocol">PTP</systemitem> hardware clock (<acronym>PHC</acronym>) on the NIC. The <application>phc2sys</application> service is configured in the <filename>/etc/sysconfig/phc2sys</filename> configuration file. The default setting in the <filename>/etc/sysconfig/phc2sys</filename> file is as follows: + <synopsis>OPTIONS="-a -r"</synopsis> + The <option>-a</option> option causes <application>phc2sys</application> to read the clocks to be synchronized from the <application>ptp4l</application> application. It will follow changes in the <systemitem class="protocol">PTP</systemitem> port states, adjusting the synchronization between the NIC hardware clocks accordingly. The system clock is not synchronized, unless the <option>-r</option> option is also specified. If you want the system clock to be eligible to become a time source, specify the <option>-r</option> option twice. + </para> +<para> +After making changes to <filename>/etc/sysconfig/phc2sys</filename>, restart the <application>phc2sys</application> service from the command line by issuing a command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart phc2sys</command></screen> +Under normal circumstances, use <command>systemctl</command> commands to start, stop, and restart the <application>phc2sys</application> service. + </para> + <para> +When you do not want to start <application>phc2sys</application> as a service, you can start it from the command line. For example, enter the following command as <systemitem class="username">root</systemitem>: + <screen>~]# <command>phc2sys -a -r</command></screen> +The <option>-a</option> option causes <application>phc2sys</application> to read the clocks to be synchronized from the <application>ptp4l</application> application. If you want the system clock to be eligible to become a time source, specify the <option>-r</option> option twice. + </para> + <para> + Alternately, use the <option>-s</option> option to synchronize the system clock to a specific interface's <systemitem class="protocol">PTP</systemitem> hardware clock. For example: <screen>~]# <command>phc2sys -s <replaceable>em3</replaceable> -w</command></screen> - The <option>-w</option> option waits for the running <application>ptp4l</application> application to synchronize the <systemitem class="protocol">PTP</systemitem> clock and then retrieves the <acronym>TAI</acronym> to <acronym>UTC</acronym> offset from <application>ptp4l</application>. +The <option>-w</option> option waits for the running <application>ptp4l</application> application to synchronize the <systemitem class="protocol">PTP</systemitem> clock and then retrieves the <acronym>TAI</acronym> to <acronym>UTC</acronym> offset from <application>ptp4l</application>. </para> <para> Normally, <systemitem class="protocol">PTP</systemitem> operates in the <firstterm>International Atomic Time</firstterm> (<acronym>TAI</acronym>) timescale, while the system clock is kept in <firstterm>Coordinated Universal Time</firstterm> (<acronym>UTC</acronym>). The current offset between the TAI and UTC timescales is 35 seconds. The offset changes when leap seconds are inserted or deleted, which typically happens every few years. The <option>-O</option> option needs to be used to set this offset manually when the <option>-w</option> is not used, as follows: @@ -464,8 +492,24 @@ priority1 127 # ptp4l -f /etc/ptp4l.conf</screen> </para> <para> -With hardware time stamping, <application>phc2sys</application> needs to be used to synchronize the <systemitem class="protocol">PTP</systemitem> hardware clock to the system clock: -<screen>~]# <command>phc2sys -c <replaceable>em3</replaceable> -s CLOCK_REALTIME -w</command></screen> +With hardware time stamping, <application>phc2sys</application> needs to be used to synchronize the <systemitem class="protocol">PTP</systemitem> hardware clock to the system clock. +If running <application>phc2sys</application> as a service, edit the <filename>/etc/sysconfig/phc2sys</filename> configuration file. The default setting in the <filename>/etc/sysconfig/phc2sys</filename> file is as follows: +<synopsis>OPTIONS="-a -r"</synopsis> +As <systemitem class="username">root</systemitem>, edit that line as follows: +<screen>~]# <command>vi /etc/sysconfig/phc2sys</command> +OPTIONS="-a -r -r"</screen> +The <option>-r</option> option is used twice here to allow synchronization of the <systemitem class="protocol">PTP</systemitem> hardware clock on the NIC from the system clock. +Restart the <application>phc2sys</application> service for the changes to take effect: +<screen>~]# <command>systemctl restart phc2sys</command></screen> +</para> + + + <para> + To prevent quick changes in the <systemitem class="protocol">PTP</systemitem> clock's frequency, the synchronization to the system clock can be loosened by using smaller <option>P</option> (proportional) and <option>I</option> (integral) constants for the PI servo: +<screen>~]# <command>phc2sys -a -r -r -P 0.01 -I 0.0001</command></screen> + </para> +</section> + <section id="sec-Synchronize_to_PTP_or_NTP_Time_Using_timemaster"> <title>Synchronize to PTP or NTP Time Using timemaster</title> <para>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Updates to: Improving Accuracy (PTP)

by stephenw

commit 99b22fe17d81feca5f3676612b8bbb60afa21367 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Tue Dec 16 21:56:20 2014 +0100 Updates to: Improving Accuracy (PTP) en-US/Configuring_PTP_Using_ptp4l.xml | 14 +++++++++++++- 1 files changed, 13 insertions(+), 1 deletions(-) --- diff --git a/en-US/Configuring_PTP_Using_ptp4l.xml b/en-US/Configuring_PTP_Using_ptp4l.xml index 75e812e..0f5174c 100644 --- a/en-US/Configuring_PTP_Using_ptp4l.xml +++ b/en-US/Configuring_PTP_Using_ptp4l.xml @@ -695,8 +695,20 @@ If required to use <systemitem class="daemon">ntpd</systemitem> as the <systemit <section id="sec-Improving_Accuracy"> <title>Improving Accuracy</title> <para> - Test results indicate that disabling the tickless kernel capability can significantly improve the stability of the system clock, and thus improve the <systemitem class="protocol">PTP</systemitem> synchronization accuracy (at the cost of increased power consumption). The kernel tickless mode can be disabled by adding <option>nohz=off</option> to the kernel boot option parameters. + Previously, test results indicated that disabling the tickless kernel capability could significantly improve the stability of the system clock, and thus improve the <systemitem class="protocol">PTP</systemitem> synchronization accuracy (at the cost of increased power consumption). The kernel tickless mode can be disabled by adding <option>nohz=off</option> to the kernel boot option parameters. However, recent improvements applied to <filename>kernel-3.10.0-197.fc21</filename> have greatly improved the stability of the system clock and the difference in stability of the clock with and without <option>nohz=off</option> should be much smaller now for most users. </para> + <para> + The <application>ptp4l</application> and <application>phc2sys</application> applications can be configured to use a new adaptive servo. The advantage over the PI servo is that it does not require configuration of the PI constants to perform well. To make use of this for <application>ptp4l</application>, add the following line to the <filename>/etc/ptp4l.conf</filename> file: + <synopsis>clock_servo linreg</synopsis> + After making changes to <filename>/etc/ptp4l.conf</filename>, restart the <application>ptp4l</application> service from the command line by issuing the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart ptp4l</command></screen> +</para> +<para> +To make use of this for <application>phc2sys</application>, add the following line to the <filename>/etc/sysconfig/phc2sys</filename> file: + <synopsis>-E linreg</synopsis> +After making changes to <filename>/etc/sysconfig/phc2sys</filename>, restart the <application>phc2sys</application> service from the command line by issuing the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart phc2sys</command></screen> +</para> </section>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] Synchronize to PTP or NTP Time Using timemaster

by stephenw

commit 65c8aeb722ea1e74278dcacc26f3898c4c9c4ce4 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Tue Dec 16 21:55:31 2014 +0100 Synchronize to PTP or NTP Time Using timemaster en-US/Configuring_PTP_Using_ptp4l.xml | 229 ++++++++++++++++++++++++++++++++- 1 files changed, 227 insertions(+), 2 deletions(-) --- diff --git a/en-US/Configuring_PTP_Using_ptp4l.xml b/en-US/Configuring_PTP_Using_ptp4l.xml index ba5e354..75e812e 100644 --- a/en-US/Configuring_PTP_Using_ptp4l.xml +++ b/en-US/Configuring_PTP_Using_ptp4l.xml @@ -466,11 +466,230 @@ priority1 127 <para> With hardware time stamping, <application>phc2sys</application> needs to be used to synchronize the <systemitem class="protocol">PTP</systemitem> hardware clock to the system clock: <screen>~]# <command>phc2sys -c <replaceable>em3</replaceable> -s CLOCK_REALTIME -w</command></screen> +<section id="sec-Synchronize_to_PTP_or_NTP_Time_Using_timemaster"> +<title>Synchronize to PTP or NTP Time Using timemaster</title> +<para> +When there are multiple <systemitem class="protocol">PTP</systemitem> domains available on the network, or fallback to <systemitem class="protocol">NTP</systemitem> is needed, the <application>timemaster</application> program can be used to synchronize the system clock to all available time sources. The <systemitem class="protocol">PTP</systemitem> time is provided by <application>phc2sys</application> and <application>ptp4l</application> via <firstterm>shared memory driver</firstterm> (<acronym>SHM</acronym> reference clocks to <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem> (depending on the <systemitem class="protocol">NTP</systemitem> daemon that has been configured on the system). The <systemitem class="protocol">NTP</systemitem> daemon can then compare all time sources, both <systemitem class="protocol">PTP</systemitem> and <systemitem class="protocol">NTP</systemitem>, and use the best sources to synchronize the system c lock.</para> + <para> + On start, <application>timemaster</application> reads a configuration file that specifies the <systemitem class="protocol">NTP</systemitem> and <systemitem class="protocol">PTP</systemitem> time sources, checks which network interfaces have their own or share a <systemitem class="protocol">PTP</systemitem> hardware clock (PHC), generates configuration files for <application>ptp4l</application> and <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem>, and starts the <application>ptp4l</application>, <application>phc2sys</application>, and <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem> processes as needed. It will remove the generated configuration files on exit. It writes configuration files for <systemitem class="daemon">chronyd</systemitem>, <systemitem class="daemon">ntpd</systemitem>, and <application>ptp4l</application> to <filename class="directory">/var/run/timemaster/</filenam e>. + </para> + + <section id="sec-Starting_timemaster_as_a_Service"> + <title>Starting timemaster as a Service</title> + +<para> +To start <application>timemaster</application> as a service, issue the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl start timemaster</command></screen> +This will read the options in <filename> /etc/timemaster.conf</filename>. + +</para> + +</section> + +<section id="sec-Understanding_the_timemaster_Configuration_File"> +<title>Understanding the timemaster Configuration File</title> + +<para> + &MAJOROS; provides a default <filename>/etc/timemaster.conf</filename> file with a number of sections containing default options. The section headings are enclosed in brackets.</para> + +<para> + To view the default configuration, issue a command as follows: +<screen>~]$ <command>less /etc/timemaster.conf</command> +# Configuration file for timemaster + +#[ntp_server ntp-server.local] +#minpoll 4 +#maxpoll 4 + +#[ptp_domain 0] +#interfaces eth0 + +[timemaster] +ntp_program chronyd + +[chrony.conf] +include /etc/chrony.conf + +[ntp.conf] +includefile /etc/ntp.conf + +[ptp4l.conf] + +[chronyd] +path /usr/sbin/chronyd +options -u chrony + +[ntpd] +path /usr/sbin/ntpd +options -u ntp:ntp -g + +[phc2sys] +path /usr/sbin/phc2sys + +[ptp4l] +path /usr/sbin/ptp4l</screen> +</para> + +<para> +Notice the section named as follows: +<synopsis>[ntp_server <replaceable>address</replaceable>]</synopsis> +This is an example of an <systemitem class="protocol">NTP</systemitem> server section, <quote>ntp-server.local</quote> is an example of a host name for an <systemitem class="protocol">NTP</systemitem> server on the local LAN. Add more sections as required using a host name or <systemitem class="protocol">IP</systemitem> address as part of the section name. Note that the short polling values in that example section are not suitable for a public server, see <xref linkend="ch-Configuring_NTP_Using_ntpd" /> for an explanation of suitable <option>minpoll</option> and <option>maxpoll</option> values. +</para> + +<para> +Notice the section named as follows: + <synopsis>[ptp_domain <replaceable>number</replaceable>]</synopsis> + + A <quote>PTP domain</quote> is a group of one or more <systemitem class="protocol">PTP</systemitem> clocks that synchronize to each other. They may or may not be synchronized to clocks in another domain. Clocks that are configured with the same domain number make up the domain. This includes a <systemitem class="protocol">PTP</systemitem> grandmaster clock. The domain number in each <quote>PTP domain</quote> section needs to correspond to one of the <systemitem class="protocol">PTP</systemitem> domains configured on the network.</para> + <para> + An instance of <application>ptp4l</application> is started for every interface which has its own <systemitem class="protocol">PTP</systemitem> clock and hardware time stamping is enabled automatically. Interfaces that support hardware time stamping have a <systemitem class="protocol">PTP</systemitem> clock (PHC) attached, however it is possible for a group of interfaces on a NIC to share a PHC. A separate <application>ptp4l</application> instance will be started for each group of interfaces sharing the same PHC and for each interface that supports only software time stamping. All <application>ptp4l</application> instances are configured to run as a slave. If an interface with hardware time stamping is specified in more than one <systemitem class="protocol">PTP</systemitem> domain, then only the first <application>ptp4l</application> instance created will have hardware time stamping enabled. + </para> + + <para> + Notice the section named as follows: + <synopsis>[timemaster]</synopsis> + The default <application>timemaster</application> configuration includes the system <systemitem class="daemon">ntpd</systemitem> and chrony configuration (<filename>/etc/ntp.conf</filename> or <filename>/etc/chronyd.conf</filename>) in order to include the configuration of access restrictions and authentication keys. That means any <systemitem class="protocol">NTP</systemitem> servers specified there will be used with <application>timemaster</application> too. + </para> + +<para> + The section headings are as follows: +</para> + <itemizedlist> + <listitem> + <para> + <option>[ntp_server ntp-server.local]</option> — Specify polling intervals for this server. Create additional sections as required. Include the host name or <systemitem class="protocol">IP</systemitem> address in the section heading. + </para> + </listitem> + <listitem> + <para> + <option>[ptp_domain 0]</option> — Specify interfaces that have <systemitem class="protocol">PTP</systemitem> clocks configured for this domain. Create additional sections with, the appropriate domain number, as required. + </para> + </listitem> + <listitem> + <para> + <option>[timemaster]</option> — Specify the <systemitem class="protocol">NTP</systemitem> daemon to be used. Possible values are <systemitem class="daemon">chronyd</systemitem> and <systemitem class="daemon">ntpd</systemitem>. + </para> + </listitem> + <listitem> + <para> + <option>[chrony.conf]</option> — Specify any additional settings to be copied to the configuration file generated for <systemitem class="daemon">chronyd</systemitem>. + </para> + </listitem> + <listitem> + <para> + <option>[ntp.conf]</option> — Specify any additional settings to be copied to the configuration file generated for <systemitem class="daemon">ntpd</systemitem>. + </para> + </listitem> + <listitem> + <para> + <option>[ptp4l.conf]</option> — Specify options to be copied to the configuration file generated for <application>ptp4l</application>. + </para> + </listitem> + <listitem> + <para> + <option>[chronyd]</option> — Specify any additional settings to be passed on the command line to <systemitem class="daemon">chronyd</systemitem>. + </para> + </listitem> + <listitem> + <para> + <option>[ntpd]</option> — Specify any additional settings to be passed on the command line to <systemitem class="daemon">ntpd</systemitem>. + </para> + </listitem> + <listitem> + <para> + <option>[phc2sys]</option> — Specify any additional settings to be passed on the command line to <application>phc2sys</application>. + </para> + </listitem> + <listitem> + <para> + <option>[ptp4l]</option> — Specify any additional settings to be passed on the command line to all instances of <application>ptp4l</application>. + </para> + </listitem> + + </itemizedlist> + <para> + The section headings and there contents are explained in detail in the <filename>timemaster(8)</filename> manual page. + </para> + +</section> + +<section id="sec-Configuring_timemaster_Options"> +<title>Configuring timemaster Options</title> + +<procedure id="proc-Editing_the_timemaster_Configuration_File"> +<title>Editing the timemaster Configuration File</title> +<step> + <para> + To change the default configuration, open the <filename>/etc/timemaster.conf</filename> file for editing as <systemitem class="username">root</systemitem>: +<screen>~]# <command>vi /etc/timemaster.conf</command></screen> +</para> +</step> +<step> +<para> + For each <systemitem class="protocol">NTP</systemitem> server you want to control using <application>timemaster</application>, create <computeroutput>[ntp_server <replaceable>address</replaceable>]</computeroutput> sections . Note that the short polling values in the example section are not suitable for a public server, see <xref linkend="ch-Configuring_NTP_Using_ntpd" /> for an explanation of suitable <option>minpoll</option> and <option>maxpoll</option> values. + </para> +</step> +<step> + <para> + To add interfaces that should be used in a domain, edit the <computeroutput>#[ptp_domain 0]</computeroutput> section and add the interfaces. Create additional domains as required. For example: + <screen>[ptp_domain 0] + interfaces eth0 + + [ptp_domain 1] + interfaces eth1</screen> +</para> +</step> +<step> +<para> +If required to use <systemitem class="daemon">ntpd</systemitem> as the <systemitem class="protocol">NTP</systemitem> daemon on this system, change the default entry in the <computeroutput>[timemaster]</computeroutput> section from <systemitem class="daemon">chronyd</systemitem> to <systemitem class="daemon">ntpd</systemitem>. See <xref linkend="ch-Configuring_NTP_Using_the_chrony_Suite" /> for information on the differences between ntpd and chronyd. + </para> +</step> +<step> + <para> + If using <systemitem class="daemon">chronyd</systemitem> as the <systemitem class="protocol">NTP</systemitem> server on this system, add any additional options below the default <option>include /etc/chrony.conf</option> entry in the <computeroutput>[chrony.conf]</computeroutput> section. Edit the default <option>include</option> entry if the path to <filename>/etc/chrony.conf</filename> is known to have changed. + </para> +</step> +<step> + <para> + If using <systemitem class="daemon">ntpd</systemitem> as the <systemitem class="protocol">NTP</systemitem> server on this system, add any additional options below the default <option>include /etc/ntp.conf</option> entry in the <computeroutput>[ntp.conf]</computeroutput> section. Edit the default <option>include</option> entry if the path to <filename>/etc/ntp.conf</filename> is known to have changed. + </para> +</step> +<step> + <para> + In the <computeroutput>[ptp4l.conf]</computeroutput> section, add any options to be copied to the configuration file generated for <application>ptp4l</application>. This chapter documents common options and more information is available in the <filename>ptp4l(8)</filename> manual page. + </para> +</step> +<step> + <para> + In the <computeroutput>[chronyd]</computeroutput> section, add any command line options to be passed to <systemitem class="daemon">chronyd</systemitem> when called by <application>timemaster</application>. See <xref linkend="ch-Configuring_NTP_Using_the_chrony_Suite" /> for information on using <systemitem class="daemon">chronyd</systemitem>. + </para> +</step> +<step> + <para> + In the <computeroutput>[ntpd]</computeroutput> section, add any command line options to be passed to <systemitem class="daemon">ntpd</systemitem> when called by <application>timemaster</application>. See <xref linkend="ch-Configuring_NTP_Using_ntpd" /> for information on using <systemitem class="daemon">ntpd</systemitem>. + </para> +</step> +<step> + <para> + In the <computeroutput>[phc2sys]</computeroutput> section, add any command line options to be passed to <application>phc2sys</application> when called by <application>timemaster</application>. This chapter documents common options and more information is available in the <filename>phy2sys(8)</filename> manual page. + </para> +</step> +<step> + <para> + In the <computeroutput>[ptp4l]</computeroutput> section, add any command line options to be passed to <application>ptp4l</application> when called by <application>timemaster</application>. This chapter documents common options and more information is available in the <filename>ptp4l(8)</filename> manual page. </para> +</step> +<step> <para> - To prevent quick changes in the <systemitem class="protocol">PTP</systemitem> clock's frequency, the synchronization to the system clock can be loosened by using smaller <option>P</option> (proportional) and <option>I</option> (integral) constants of the PI servo: -<screen>~]# <command>phc2sys -c <replaceable>em3</replaceable> -s CLOCK_REALTIME -w -P 0.01 -I 0.0001</command></screen> + Save the configuration file and restart <application>timemaster</application> by issuing the following command as <systemitem class="username">root</systemitem>: +<screen>~]# <command>systemctl restart timemaster</command></screen> + </para> +</step> + +</procedure> +</section> + </section> <section id="sec-Improving_Accuracy"> @@ -505,6 +724,12 @@ With hardware time stamping, <application>phc2sys</application> needs to be used <filename>phc2sys(8)</filename> man page — Describes a tool for synchronizing the system clock to a <systemitem class="protocol">PTP</systemitem> hardware clock (PHC). </para> </listitem> + <listitem> + <para> +<filename>timemaster(8)</filename> man page — Describes a program that uses <application>ptp4l</application> and <application>phc2sys</application> to synchronize the system clock using <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem>. +</para> + </listitem> + </itemizedlist> </section>

9 years, 5 months

1
0
0 / 0

[system-administrators-guide/21] typo

by stephenw

commit 2334e30a61f8ee617b900a2d1752c140d239eb47 Author: Stephen Wadeley <swadeley(a)redhat.com> Date: Mon Dec 15 09:55:37 2014 +0100 typo en-US/Configuring_PTP_Using_ptp4l.xml | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) --- diff --git a/en-US/Configuring_PTP_Using_ptp4l.xml b/en-US/Configuring_PTP_Using_ptp4l.xml index ea6aab9..ba5e354 100644 --- a/en-US/Configuring_PTP_Using_ptp4l.xml +++ b/en-US/Configuring_PTP_Using_ptp4l.xml @@ -71,7 +71,7 @@ Hardware Transmit Timestamp Modes: Hardware Receive Filter Modes: none (HWTSTAMP_FILTER_NONE) all (HWTSTAMP_FILTER_ALL)</screen> - Where <replaceable>eth3</replaceable> is the interface you want to check. + Where <replaceable>em3</replaceable> is the interface you want to check. </para> <para> For software time stamping support, the parameters list

9 years, 5 months

1
0
0 / 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

docs-commits January 2015